Create Transaction

Search…
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.  
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. We accept maximum two decimal places.
to_amount
No
numeric
The amount to be received by the receiving user. We accept maximum two decimal places.
from_currency
Yes
String
User’s currency
to_currency
Yes
String
Receive user’s currency
exchange_rate
Yes
numeric
Exchange rate used in transaction. We accept maximum four decimal places.
fee_amount
Yes
numeric
Additional fee.
purpose
Yes
Category
The purpose of sending money. Details below.
custom_purpose
Yes, if purpose is OTHER
String
Additional details when purpose is OTHER
physical_document
No
Object
Copy of a document. This may be required for certain corridors and will be outlined in your spec sheet.
physical_document.document_type
No
Category
Enumerated value: INVOICE
physical_document.document_value
No
String
Value of the document. Documents must be encoded Base64 before being uploaded to our system.
calculation_mode
Yes
String
Enumerated value : SENDER_AMOUNT, RECEIVER_AMOUNT.
payer_id
No
numeric
Id of payer.
transaction_status
No
String
Enumerated value : INITIATED, PENDING, PROCESSING, PROCESSED, CANCELLED, FAILED, HOLD, REFUNDED, RETURNED Note: Transaction hold reasons are listed below.
delivery_status
No
String
Enumerated Value : NONE, HOLD, PENDING, DELIVERY_REQUESTED, DELIVERED, DELIVERY_FAILED, DELIVERY_AUTHORIZED, DELIVERY_PAYOUT_READY
risk_score
No
numeric
A Risk Score indicates the high or low risk of a transaction created by users. The lower the score, the less likely the event is high risk.
reference_number
No
String
A unique identification number of a transaction. This number is generated once the transaction is in PENDING status.
payout_reference_number
No
String
Reference number provided by the payout partner.
​
Purpose 
Purpose
Description
COMPUTER_SERVICES
Computer service
FAMILY_SUPPORT
Family support
EDUCATION
Education
GIFT_AND_DONATION
Gift and other donations
MEDICAL_TREATMENT
Medical treatment
MAINTENANCE_EXPENSES
Maintenance or other expenses
TRAVEL
Travel
SMALL_VALUE_REMITTANCE
Small value remittance
LIBERALIZED_REMITTANCE
Liberalized remittance
CONSTRUCTION_EXPENSES
Construction expenses
HOTEL_ACCOMMODATION
Hotel accommodation
ADVERTISING_EXPENSES
Advertising and/or public relations related expenses
ADVISORY_FEES
Fees for advisory or consulting service
BUSINESS_INSURANCE
Business related insurance payment
INSURANCE_CLAIMS
Insurance claims payment
DELIVERY_FEES
Delivery fees
EXPORTED_GOODS
Payments for exported goods
SERVICE_CHARGES
Payment for services
LOAN_PAYMENT
Payment of loans
OFFICE_EXPENSES
Office expenses
PROPERTY_PURCHASE
Residential property purchase
PROPERTY_RENTAL
Property rental payment
ROYALTY_FEES
Royalty, trademark, patent and copyright fees
SHARES_INVESTMENT
Investment in shares
FUND_INVESTMENT
Fund investment
TAX_PAYMENT
Tax payment
TRANSPORTATION_FEES
Transportation fees
UTILITY_BILLS
Utility bills
PERSONAL_TRANSFER
Personal transfer
SALARY_PAYMENT
Payment of salary
REWARD_PAYMENT
Payment of rewards
INFLUENCER_PAYMENT
Payment of Influencer
OTHER_FEES
Broker, commitment, guarantee and other fees
OTHER
Other purposes
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' \
--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' \
--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
    }
}'
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": "[email protected]",
        "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": "[email protected]",
        "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": "[email protected]",
        "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
}
Transaction Hold Reasons
Transactions may be placed on hold for specific reasons. Regardless of the reason, transactions on hold for more than 7 days are automatically cancelled. 
Code
Reason
T001
Transaction is under review by compliance. Machnet will provide further information once available.
T002
Issue processing transaction. Please contact Machnet customer support.
T003
Unable to check balance of the funding account. Please contact Machnet customer support.
T004
Transaction limit based on the current tier of the user has been exceeded. If the user is eligible to increase their limits, requested information must be submitted and verified for the transaction to be processed. Check requested information using this API. 
T005
User is not verified. All basic information must be submitted and verified for the transaction to be processed. Check KYC status using this API. 
T006
Issue processing transaction. Please contact Machnet customer support.
Transaction Cancellation Reason
Code
Reason
C001
Transaction risk is high.
C002
Platform limit exceeded.
C003
Transaction expired as it was on HOLD for more than 7 days
C004
Transaction was canceled by the user.
C005
Transaction was canceled by the admin.
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.
API References - Previous
Transaction
Get Transaction by ID
Last modified 30d ago
Copy link
On this page
Transaction Hold Reasons
Transaction Cancellation Reason
Calculation Mode