Create transaction

This API can be used to initiate a transfer. A transaction can be created only after the following criteria are fulfilled.
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.  
Supports Idempotency Key as part of the header to avoid duplicate transactions.
POST /users/{{user_id}}/transactions
Details
Request Sample
Response Sample
Transaction object details 
​
Field
Required
Type
Description
id
No
UUID
ID of the transaction created.
user_id
Yes
UUID
ID of the User initiating the transaction.
from_fund_id
Yes
UUID
Account ID of the User from where the amount will be debited.
funding_source_type
Yes
String
Enumerated value: CARD, BANK_ACCOUNT
to.id
Yes if Remittance transaction
UUID
ID of the receive User who will receive the amount
to.fund_id
Yes if Remittance
UUID
ID of the receive user’s fund.
to.payout_method
Yes
String
Payout method for transaction amount delivery. Enumerated Value: BANK_DEPOSIT (Default), CASH_PICKUP, WALLET, HOME_DELIVERY.
type
No
String
Enumerated value: TRANSFER|PAYOUT or PAYOUT
from_amount
Yes
numeric
The amount entered by the user to be debited from the user’s account.
to_amount
No
numeric
The amount to be received by the receiving user.
from_currency
Yes
String
User’s currency
to_currency
Yes
String
Receive user’s currency
exchange_rate
Yes
numeric
Exchange rate used in transaction
fee_amount
Yes
numeric
Additional fee.
remittance_purpose
Yes
String
The purpose of sending money.
sku_id
Yes if to.payout_method is “BILL_PAYMENT”
numeric
Id for the service  provided by the payer.
inputs
Yes if to.payout_method is “BILL_PAYMENT”
String
Inputs are required by the payer and described for service.The details of the required inputs can be obtained from the IO Catalog
calculation_mode
Yes if to.payout_method is “BILL_PAYMENT”
String
Enumerated value : SENDER_AMOUNT, RECEIVER_AMOUNT.
The calculation for a bill payment transaction is done with respect to the receiving amount, hence the bill payment transaction requires calculation_mode to be  RECEIVER_AMOUNT.
payer_id
Yes if to.payout_method is “BILL_PAYMENT”
numeric
Id of payer.
Bank Deposit
1
curl --location --request POST '{{url}}/users/{{user_id}}/transactions' \
2
--header 'X-Client-Id: client_id' \
3
--header 'X-Client-Secret: client_secret' \
4
--header 'Content-Type: application/json' \
5
--data-raw '{
6
"from_amount":1,
7
"exchange_rate": 6.11,
8
"to_amount":6.11,
9
"fee_amount": 0,
10
"note": "Sample Note",
11
"to_currency":"NGA",
12
"from_currency":"USD",
13
"remittance_purpose": "home payment",
14
"ip_address": "10.10.10.5",
15
"from_fund_id":"d1f9eb6c-c4a2-4c6c-a590-276990995d66",
16
"funding_source_type": "CARD",
17
"to":{
18
        "id": "e2d1b7bf-4e8a-4e2d-b5a3-474525c396db",
19
        "fund_id" : "9db84704-fabc-4be2-b96b-f79f13809467",
20
        "payout_method":"BANK_DEPOSIT",
21
        "calculation_mode":"SENDER_AMOUNT"
22
    } 
23
}'
Copied!
​
Wallet
1
curl --location --request POST '{{url}}/users/{{user_id}}/transactions' \
2
--header 'X-Client-Id: client_id' \
3
--header 'X-Client-Secret: client_secret' \
4
--header 'Content-Type: application/json' \
5
--data-raw '{
6
"from_amount":1,
7
"exchange_rate": 6.11,
8
"to_amount":6.11,
9
"fee_amount": 0,
10
"note": "Sample Note",
11
"to_currency":"CMR",
12
"from_currency":"USD",
13
"remittance_purpose": "home payment",
14
"ip_address": "10.10.10.5",
15
"from_fund_id":"31679ca8-56fd-4f46-8be5-301005a6be88",
16
"funding_source_type": "CARD",
17
"to":
18
        "id": "{{receive_user_id}}",
19
         "fund_id" : "ec84726e-9a01-4e7a-8a2f-b295d288f3fb",
20
        "payout_method":"WALLET",
21
        "calculation_mode":"SENDER_AMOUNT",
22
        "payer_id" :42    
23
    } 
24
}'
Copied!
​
Cash Pickup
1
curl --location --request POST 'https://api.machpay.com/users/{{user_id}}/transactions \
2
--header 'X-Client-Id: {{client_id}}' \
3
--header 'X-Client-Secret: {{client_secret}}' \
4
--header 'Content-Type: application/json' \
5
--data-raw '{
6
    "from_amount":1,
7
    "exchange_rate": 6.11,
8
    "to_amount":6.11,
9
    "fee_amount": 0,
10
    "note": "Sample Note",
11
    "to_currency":" GHA",
12
    "from_currency":"USD",
13
    "remittance_purpose": "home payment",
14
    "ip_address": "10.10.10.5",
15
    "from_fund_id":"d1f9eb6c-c4a2-4c6c-a590-276990995d66",
16
    "funding_source_type": "CARD",
17
    "to":{
18
        "id": "e2d1b7bf-4e8a-4e2d-b5a3-474525c396db",
19
        "payout_method":"CASH_PICKUP",
20
        "calculation_mode":"SENDER_AMOUNT",  
21
        "payer_id" : 16,
22
        "pickup_location":1
23
    } 
24
}'
Copied!
Bank Deposit
1
{
2
    "bonus_amount": 0,
3
    "created_at": "2022-01-14T12:16:10.348279",
4
    "delivery_status": "NONE",
5
    "exchange_rate": 6.11,
6
    "fee_amount": 0,
7
    "from_amount": 1,
8
    "from_currency": "USD",
9
    "from_fund_id": "d1f9eb6c-c4a2-4c6c-a590-276990995d66",
10
    "id": "1cdebf3c-d5f1-438b-baf5-798095041b74",
11
    "ip_address": "10.10.10.5",
12
    "note": "Sample Note",
13
    "status": "INITIATED",
14
    "to": {
15
        "address_line1": "500 El Camino Real Santa Clara",
16
        "calculation_mode": "SENDER_AMOUNT",
17
        "email": "[email protected]",
18
        "first_name": "Prat",
19
        "fund_id": "9db84704-fabc-4be2-b96b-f79f13809467",
20
        "id": "e2d1b7bf-4e8a-4e2d-b5a3-474525c396db",
21
        "last_name": "Dul",
22
        "mobile_phone": "237676641000",
23
        "payout_method": "BANK_DEPOSIT"
24
    },
25
    "to_amount": 6.11,
26
    "to_currency": "NGA",
27
    "user_id": "2d5ea62b-0956-447f-a50d-bc70295f623f"
28
}
Copied!
​
Wallet
1
{
2
    "bonus_amount": 0,
3
    "created_at": "2022-01-18T05:58:27.576884",
4
    "delivery_status": "NONE",
5
    "exchange_rate": 6.11,
6
    "fee_amount": 0,
7
    "from_amount": 1,
8
    "from_currency": "USD",
9
    "from_fund_id": "31679ca8-56fd-4f46-8be5-301005a6be88",
10
    "id": "4619ed9f-b9e5-41e3-8b0e-d91715c01b9f",
11
    "ip_address": "10.10.10.5",
12
    "note": "Sample Note",
13
    "status": "INITIATED",
14
    "to": {
15
        "address_line1": "500 El Camino Real Santa Clara",
16
        "calculation_mode": "SENDER_AMOUNT",
17
        "email": "[email protected]",
18
        "first_name": "Prat",
19
        "fund_id": "ec84726e-9a01-4e7a-8a2f-b295d288f3fb",
20
        "id": "43fd7809-08e2-4534-8a7a-71a0b4e3faee",
21
        "last_name": "Dul",
22
        "mobile_phone": "237676641000",
23
        "payout_method": "WALLET"
24
    },
25
    "to_amount": 6.11,
26
    "to_currency": "CMR",
27
    "user_id": "eb35d451-1d9b-4cce-8f2f-85937084d277"
28
}
Copied!
​
Cash Pickup
1
{
2
    "bonus_amount": 0,
3
    "created_at": "2022-01-14T12:02:12.823098",
4
    "delivery_status": "NONE",
5
    "exchange_rate": 6.11,
6
    "fee_amount": 0,
7
    "from_amount": 1,
8
    "from_currency": "USD",
9
    "from_fund_id": "d1f9eb6c-c4a2-4c6c-a590-276990995d66",
10
    "id": "3f0b7c75-ef80-4e16-a07d-43d9e11d418a",
11
    "ip_address": "10.10.10.5",
12
    "note": "Sample Note",
13
    "status": "INITIATED",
14
    "to": {
15
        "address_line1": "500 El Camino Real Santa Clara",
16
        "calculation_mode": "SENDER_AMOUNT",
17
        "email": "[email protected]",
18
        "first_name": "Prat",
19
        "id": "e2d1b7bf-4e8a-4e2d-b5a3-474525c396db",
20
        "last_name": "Dul",
21
        "mobile_phone": "237676641000",
22
        "payer_id": 16,
23
        "payout_method": "CASH_PICKUP"
24
    },
25
    "to_amount": 6.11,
26
    "to_currency": " GHA",
27
    "user_id": "2d5ea62b-0956-447f-a50d-bc70295f623f"
28
}
Copied!
Transaction Hold Reasons
Code
Reason
T001
Transaction is under review
T002
Service limit exceeded
T003
Unable to check balance
T004
Transaction limit exceeded
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.
1
{
2
   "status": 400,
3
   "code": "BAD_REQUEST",
4
   "message": "From amount is not equivalent with To amount."
5
}
6
​
Copied!
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.
API References - Previous
Transaction
Get transaction by ID
Last modified 28d ago
Copy link
Contents
Transaction Hold Reasons
Calculation Mode