Create Transaction

Read on how to create transactions in our system

A transaction can be created only after the following criteria are fulfilled.

• The Sender's KYC status is other than UNVERIFIED, IN PROGRESS, or SUSPENDED

• At least one sender funding account has been linked by the sender and is active

• At least one receive user has been added

Based on the payout_method, different information about the receive user and method is required.

• payout_method=BANK_DEPOSIT, funds are directly deposited into the receive user's account. Receive bank accounts need to be added for this transaction.

• payout_method=WALLET, funds are directly deposited to the receive user's wallet. Receive wallet accounts need to be added for this transaction.

• payout_method=CASH_PICKUP, funds can be collected at a cash pick-up location. The payer_id of the relevant location must be specified for this transaction.

• payout_method=HOME_DELIVERY, funds are directly delivered to the receive user's home. Address must be accurate and payer_id must be specified for the transaction.

POST /users/{{user_id}}/transactions

Supports Idempotency Key as part of header to avoid duplicate transaction. If you are creating a transaction with the same request and the same idempotency key again, the endpoint will consider this a duplicate request. It will not create a new transaction but will instead provide details of the initial transaction in the response. 

Response:
200 if a transaction is successfully created or transaction with the same idempotency key and request was created earlier
400 if the idempotency key is greater than 255 char
409 if the idempotency key is the same but the request is different 

Request Sample

Bank Deposit

curl --location --request POST '{{url}}/users/{{user_id}}/transactions' \
--header 'X-Client-Id: client_id' \
--header 'X-Client-Secret: client_secret' \
--header 'Content-Type: application/json' \
--header 'X-Idempotency-Key: idempotencykey' \
--data-raw '{
"from_amount":1,
"exchange_rate": 6.11,
"to_amount":6.11,
"fee_amount": 0,
"note": "Sample Note",
"to_currency":"USD",
"from_currency":"USD",
"custom_purpose":"home",
"purpose": "OTHER",
"physical_documents": [
        {
            "document_type": "INVOICE",
            "document_value": "data:image/jpg;base64,SUQsasasasas909090=="
        }
    ],
"ip_address": "10.10.10.5",
"from_fund_id": UUID,
"funding_source_type": "CARD",
"to":{
        "id": UUID,
        "fund_id" : UUID,
        "payout_method":"BANK_DEPOSIT",
        "calculation_mode":"SENDER_AMOUNT"
    } 
}'

Wallet

curl --location --request POST '{{url}}/users/{{user_id}}/transactions' \
--header 'X-Client-Id: client_id' \
--header 'X-Client-Secret: client_secret' \
--header 'Content-Type: application/json' \
--header 'X-Idempotency-Key: idempotencykey' \
--data-raw '{
"from_amount":1,
"exchange_rate": 6.11,
"to_amount":6.11,
"fee_amount": 0,
"note": "Sample Note",
"to_currency":"XAF",
"from_currency":"USD",
"remittance_purpose": "home payment",
"ip_address": "10.10.10.5",
"from_fund_id": UUID,
"funding_source_type": "CARD",
"purpose": "OTHER",
"custom_purpose":"home",
"physical_documents": [
        {
            "document_type": "INVOICE",
            "document_value": "data:image/jpg;base64,SUQsasasasas909090=="
        }
    ],
"to":{
        "id": UUID,
         "fund_id" : UUID,
        "payout_method":"WALLET",
        "calculation_mode":"SENDER_AMOUNT",
        "payer_id" :42
    } 
}'

Cash Pickup

 curl --location --request POST '{{url}}/users/{{user_id}}/transactions' \
--header 'X-Client-Id: client_id' \
--header 'X-Client-Secret: client_secret' \
--header 'Content-Type: application/json' \
--data-raw '{
    "from_amount": 2.11,
    "exchange_rate": 1,
    "to_amount": 2.11,
    "fee_amount": 0,
    "note": "Sample Note",
    "to_currency": "GHS",
    "from_currency": "USD",
    "custom_purpose": "home",
    "purpose": "OTHER",
    "physical_documents": [
        {
            "document_type": "INVOICE",
            "document_value": "data:image/jpg;base64,SUQsasasasas909090=="
        }
    ],
    "ip_address": "10.10.10.5",
    "from_fund_id": UUID,
    "funding_source_type": "CARD",
    "to": {
        "id": UUID,
        "payout_method": "CASH_PICKUP",
        "calculation_mode": "SENDER_AMOUNT",
        "payer_id": 9,
        "pickup_location": 1
    }
}'

Response Sample

Bank Deposit

{
    "bonus_amount": 0,
    "created_at": "2022-05-18T11:48:05.127065",
    "custom_purpose": "home",
    "delivery_status": "NONE",
    "exchange_rate": 6.11,
    "fee_amount": 0,
    "from_amount": 1,
    "from_currency": "USD",
    "from_fund_id": UUID,
    "funding_source_type": "CARD",
    "id": UUID,
    "ip_address": "10.10.10.5",
    "note": "Sample Note",
    "physical_documents": [
        {
            "document_type": "INVOICE",
            "id": UUID
        }
    ],
    "purpose": "OTHER",
    "status": "INITIATED",
    "to": {
        "address_line1": "500 El Camino Real Santa Clara",
        "calculation_mode": "SENDER_AMOUNT",
        "email": "[e-mail]",
        "first_name": "Tenzin",
        "fund_id": UUID,
        "id": UUID,
            "last_name": "Norgay",
        "mobile_phone": "2662030406",
        "payout_method": "BANK_DEPOSIT"
    },
    "to_amount": 6.11,
    "to_currency": "USD",
    "user_id": UUID
}

Wallet

{
    "bonus_amount": 0,
    "created_at": "2022-05-18T11:56:18.168841",
    "custom_purpose": "home",
    "delivery_status": "NONE",
    "exchange_rate": 6.11,
    "fee_amount": 0,
    "from_amount": 1,
    "from_currency": "USD",
    "from_fund_id": UUID,
    "funding_source_type": "CARD",
    "id": UUID,
    "ip_address": "10.10.10.5",
    "note": "Sample Note",
    "physical_documents": [
        {
            "document_type": "INVOICE",
            "id": UUID
        }
    ],
    "purpose": "OTHER",
    "status": "INITIATED",
    "to": {
        "address_line1": "500 El Camino Real Santa Clara",
        "calculation_mode": "SENDER_AMOUNT",
        "email": "[e-mail]",
        "first_name": "Tenzin",
        "fund_id": UUID,
        "id": UUID,
        "last_name": "Norgay",
        "mobile_phone": "237676641000",
        "payout_method": "WALLET"
    },
    "to_amount": 6.11,
    "to_currency": "XAF",
    "user_id": UUID
}

Cash Pickup

{
    "bonus_amount": 0,
    "created_at": "2022-05-18T11:37:15.710741",
    "custom_purpose": "home",
    "delivery_status": "NONE",
    "exchange_rate": 1,
    "fee_amount": 0,
    "from_amount": 2.11,
    "from_currency": "USD",
    "from_fund_id": UUID,
    "funding_source_type": "CARD",
    "id": UUID,
    "ip_address": "10.10.10.5",
    "note": "Sample Note",
    "physical_documents": [
        {
            "document_type": "INVOICE",
            "id": UUID
        }
    ],
    "purpose": "OTHER",
    "status": "INITIATED",
    "to": {
        "address_line1": "500 El Camino Real Santa Clara",
        "calculation_mode": "SENDER_AMOUNT",
        "email": "[e-mail]",
        "first_name": "Tenzin",
        "id": UUID,
        "last_name": "Norgay",
        "mobile_phone": "233541859101",
        "payer_id": 9,
        "payout_method": "CASH_PICKUP"
    },
    "to_amount": 2.11,
    "to_currency": "GHS",
    "user_id": UUID
}

Calculation Mode

There are two calculation models available for the sending and receiving amount while creating a transaction. These modes are based on which amount (sending or receiving) the system will take as a base for the calculation.

1. SENDER_AMOUNT: When a transaction is created with this calculation mode, you will pass the sending amount and exchange rate through the Transaction API. The receiving amount is calculated based on the provided sending amount and exchange rate. The default calculation mode is SENDER_AMOUNT.

2. RECEIVER_AMOUNT: When a transaction is created with this calculation mode, you will pass the total receiving amount, sending amount, and exchange rate through the Transaction API. We will then calculate the sending amount based on the provided receiving amount and exchange rate.

The calculated sending amount will then be compared with the sending amount you have provided in the request. If the difference between the calculated sending amount and the sending amount provided by you in the API request is greater than $0.01, the transaction API will provide the following error message.

{
   "status": 400,
   "code": "BAD_REQUEST",
   "message": "From amount is not equivalent with To amount."
}

For example, if the exchange rate today for USD to MEX, is 19.77 and the recipient_amount is 427, the sender amount would be 427/19.66 = 21.719. Since our API will take the difference up to $0.01, $21.72 would be accepted for a successful transaction.