Welcome

SafeTrade Developers API V1 Docs


SafeTrade API V1 gives you access to features you would require to send and receive data on your platform from your business account. The API V1 is RESTful and mainly allows you to create and read requests using JSON format.

Index

The default response format is application/json. Requests with a message-body use plain JSON to set or update resource attributes. Successful requests will return a 200: OK HTTP status. After generating your ApiKey and ApiSecret you can call the API using POSTMAN or cURL

General information about responses:

  • Dates are returned in the following format YYYY-MM-DD HH:MM:SS
  • IDs are returned in string format
  • Any monetary amount is returned as integers with decimal numbers in certain occasions
  • Blank fields are returned as null instead of empty strings

Requirements

Follow the checklist below to make sure you have all you need before you can start integrating SafeTrade into your platform.

Pre-requisite Description
SafeTrade business account Create a SafeTrade account, confirm your details to verify your account and request to have a business account
API Key Generate your API Key from your account page after sign in.
API Secret Generate your API secret from your account page after sign in.

Authentication

Every API call should include your ApiKey in the body and the ApiSecret in the header of every request you make. You can manage your API details from your account page.

When you generate the API details for your SafeTrade business account, you will be provided with two keys: ApiKey and ApiSecret. These details verify that an API call is coming from your account and provide only relevant information linked to your account. The ApiKey is meant to be present in the body of your API call but your ApiSecret is not for public knowledge and it should not be included in the body of your API call. The ApiSecret should be included in the header of your API call.

Authentication headers should be in this format: "X-API-SECRET": "API_SECRET"

AJAX example

$.ajax({        
      type: 'GET',
      dataType: 'json',      
      headers: { "X-API-SECRET": "sORMw9yTF2PD85q1UqL8RHStUXoAPc" },
      url: endpoint',                 
      data: data
    });
    

PHP CURL header

    curl_setopt($ch, CURLOPT_HTTPHEADER, array(
        'X-API-SECRET: sORMw9yTF2PD85q1UqL8RHStUXoAPc'
)
);

Errors

Occasionally you might encounter errors when accessing the API. There are two possible types

Code Error Description
400 Bad request Invalid request to an unsupported method or directory
401 Unauthorized Authentication or permission error, e.g. incorrect API key or API secret

Error messages are sent back in with status and message.

Example

{
  "status": "400",
  "message": "Bad request"
}

Item transactions

The transactions API allows you to create, view and update item transactions.

Endpoint /v1/api/transactions/

Transaction properties

Attribute Type Description
Id string Unique identifier for the transaction
business_id string Custom business ID

List transaction

GET /v1/api/transactions/list/{business_id}

Response

The API would respond with details of the transaction of send back status message with error 400: Bad request. Below is the type of information sent back in detail:

Name Type Description
total_item_transactions integer Total number of item transactions with the business_id
item_transactions array Details of all item transactions
total_service_transactions integer Total number of service transactions with the business_id
service_transactions array Details of all service transactions

Result

{
  "total_item_transactions": 1,
  "item_transactions": [
    {
      "transaction_id": "IT957219658",
      "buyer": "534483356",
      "seller": "702586233",
      "item": "BTC",
      "amount": "500000",
      "fee": "25",
      "status": "awaiting inspection"
    }
  ],
  "total_service_transactions": 1,
  "service_transactions": [
    {
      "transaction_id": "ST1",
      "client": "847744446",
      "service_provider": "847744459",
      "service_description": "Design boat",
      "amount": "100000",
      "fee": "2350",
      "status": "awaiting confirmation"
    }
  ]
}

Retrieve transaction

GET /v1/api/transactions/{id}

Response

The API would respond with details of the transaction of send back status message with error 400: Bad request. Below is the type of information sent back in detail:

Name Type Description
transaction_id string Unique identifier for the transaction
category string Type if transaction
buyer array Information of the buyer.
seller array Information of the seller.
initiator integer Unique identifier of the user that started the transaction
item array Information of the transaction item
inspection_period integer The number of days the buyer can inspect the item
date timestamp The date the transaction was started
fee integer/decimal SafeTrade's fee
status string Current progress of the transaction
flagged string Signifier that this transaction has been flagged for broker to intervene
transaction_receipts array Information of the delivery receipts uploaded by the seller
payment array Information of payment made by the buyer to SafeTrade

Result

[
  {
    "transaction_id": "IT957219658",
    "category": "Cryptocurrency",
    "buyer": {
      "buyer_id": "534483356",
      "buyer_fee": "50%",
      "buyer_fee_amt": 12.5,
      "buyer_account_id": "4"
    },
    "seller": {
      "seller_id": "702586233",
      "seller_fee": "50%",
      "seller_fee_amt": 12.5,
      "seller_account_id": "6"
    },
    "initiator": "534483356",
    "item": {
      "item_name": "BTC",
      "item_amount": "500000",
      "item_description": "Bitcoin",
      "item_quantity": "1"
    },
    "inspection_period": "3",
    "date": "2017-07-21 00:00:00",
    "fee": "25",
    "status": "awaiting inspection",
    "flagged": "null",
    "transaction_receipts": [
      {
        "transaction_receipt_id": "2",
        "filename": "https://safetrade.ng/receipts/1504607649.png",
        "uploaded_by": "847744415",
        "date": "2017-09-05 11:34:09"
      }
    ],
    "payment": [
      {
        "payment_id": "p20domD",
        "user_id": "534483356",
        "amount": "500000",
        "date": "2017-09-25 09:33:34",
        "payment_gateway": "Paystack",
        "description": "payment",
        "status": "success"
      }
    ]
  }
]

Service transactions

The transactions API allows you to create, view and update service transactions.

Endpoint /v1/api/transactions/

Transaction properties

Attribute Type Description
Id string Unique identifier for the transaction

Retrieve transaction

GET /v1/api/transactions/{id}

Response

The API would respond with details of the transaction of send back status message with error 400: Bad request. Below is the type of information sent back in detail:

Name Type Description
transaction_id string Unique identifier for the transaction
service_description string Explanation of the service
service_amount integer Total amount to be paid for the service
initiator integer Unique identifier of the user that started the transaction
payment_method string Chosen mode of payment
initial_payment integer Amount to be paid after starting the transaction
termination_date date Final date to end the transaction
status string Current progress of the transaction
fee integer/decimal SafeTrade's fee
flagged string Signifier that this transaction has been flagged for broker to intervene
client array Information of the client
service_provider array Information of the service provider
deliverables array Milestones to be achieved by the service provider and amount to be paid
payment array Information of payment made by the buyer to SafeTrade

Result

[
  {
    "transaction_id": "ST1",
    "service_description": "Design boat",
    "service_amount": "100000",
    "initiator": "847744446",
    "payment_method": "Full payment",
    "initial_payment": "0",
    "termination_date": "2017-09-29",
    "status": "awaiting confirmation",
    "fee": "2350",
    "flagged": "null",
    "client": {
      "client_id": "847744446",
      "client_fee": "0%",
      "client_fee_amt": "0"
    },
    "service_provider": {
      "service_provider_id": "847744459",
      "service_provider_fee": "100%",
      "service_provider_fee_amt": "2350"
    },
    "deliverables": [
      {
        "deliverable": "Design quality boat",
        "status": "paid",
        "amount": "100000",
        "completion_date": "2017-09-29"
      }
    ],
    "payment": [
      {
        "payment_id": "Fio29DM",
        "user_id": "847744446",
        "amount": "100000",
        "date": "2017-09-29 09:33:34",
        "payment_gateway": "Paystack",
        "description": "payment",
        "status": "success"
      }
    ]
  }
]

Users

The users API allows you to create, view and update users.

Endpoint /v1/api/users/

User properties

Attribute Type Description
Id string Unique identifier for the user

Retrieve user

GET /v1/api/users/{id}

Result

[
  {
    "user_id": "847744446",
    "name": "Mikolo",
    "email": "eddygudom@gmail.com",
    "gender": "Male",
    "mobile": "08124698785",
    "status": "active"
  }
]

List user transactions

GET /v1/api/users/list/{id}

Response

The API would respond with details of the transaction of send back status message with error 400: Bad request. Below is the type of information sent back in detail:

Name Type Description
total_item_transactions integer Total number of item transactions for that specific user
item_transactions array Details of all item transactions
total_service_transactions integer Total number of service transactions for that specific user
service_transactions array Details of all service transactions

Result

{
  "total_item_transactions": 0,
  "item_transactions": [],
  "total_service_transactions": 1,
  "service_transactions": [
    {
      "transaction_id": "ST1",
      "client": "847744446",
      "service_provider": "847744459",
      "service_description": "Design boat",
      "amount": "100000",
      "fee": "2350",
      "status": "awaiting confirmation"
    }
  ]
}