Api Documentation

Create & Execute

Overview

Create a remittance from a live quote. By default the transfer executes immediately: the wallet is debited and the payout is submitted. Set auto_execute to false to hold it in pending_approval and call execute later.

Create remittance

HTTP Method	POST
Endpoint URL	`/api/v2/remit`
Base URL	`https://base-url-here.com`
Description	Create a remittance. Executes immediately unless `auto_execute` is false.

Request Body

Field	Type	Description	Required
quote_id	uuid	Quote from POST /quotes. Must belong to this business and not be expired.	Yes
reference	string	Your unique order reference (max 64). Reuse returns HTTP 409.	Yes
rail	string	`mobile_money` or `bank`. Should match the quote.	Yes
recipient	object	Recipient details. See fields below.	Yes
recipient.other_names	string	Recipient given names.	Yes
recipient.surname	string	Recipient family name.	Yes
recipient.phone	string	Required when rail is `mobile_money`.	Conditional
recipient.account_number	string	Required when rail is `bank`.	Conditional
recipient.bank_code	string	Required when rail is `bank`.	Conditional
recipient.bank_name	string	Required when rail is `bank`.	Conditional
purpose	string	Reason for the transfer (max 255).	Yes
result_url	url	HTTPS URL that receives the merchant webhook after the provider callback.	No
auto_execute	boolean	Default `true`. Set `false` to create without debiting.	No

Success Response

Field	Type	Description
data.id	uuid	Remittance ID. Use this on execute or show.
data.reference	string	Your reference.
data.status	string	`processing`, `pending_approval`, `successful`, or `failed`.
data.status_desc	string	Provider or platform message.
data.rail	string	Payout rail.
data.purpose	string	Purpose you supplied.
data.recipient	object	Stored recipient snapshot.
data.quote	object	Quoted amounts and rates.
data.provider_reference	string	Payout provider transaction reference after submit.

Mobile money example

curl --location --request POST 'https://base-url-here.com/api/v2/remit' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--header 'X-Business-Id: 9' \
--data-raw '{
    "quote_id": "11111111-1111-1111-1111-111111111111",
    "reference": "INV-1001",
    "rail": "mobile_money",
    "recipient": {
        "other_names": "Asha",
        "surname": "Juma",
        "phone": "256712000000"
    },
    "purpose": "Supplier payment",
    "result_url": "https://merchant.example.com/webhooks/remit",
    "auto_execute": true
}'

{
    "success": true,
    "message": "Success",
    "data": {
        "id": "22222222-2222-2222-2222-222222222222",
        "reference": "INV-1001",
        "status": "processing",
        "status_desc": "Payout submitted",
        "rail": "mobile_money",
        "purpose": "Supplier payment",
        "recipient": {
            "other_names": "Asha",
            "surname": "Juma",
            "phone": "256712000000"
        },
        "quote": {
            "quote_id": "11111111-1111-1111-1111-111111111111",
            "currency_pair": "KES - UGX",
            "send_amount": "1000.00",
            "receive_amount": "28023.25",
            "debit_amount": "1000.00",
            "rail": "mobile_money"
        },
        "provider_reference": "TXN-889900"
    }
}

Bank example (hold then execute)

curl --location --request POST 'https://base-url-here.com/api/v2/remit' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--header 'X-Business-Id: 9' \
--data-raw '{
    "quote_id": "11111111-1111-1111-1111-111111111111",
    "reference": "INV-1002",
    "rail": "bank",
    "recipient": {
        "other_names": "Peter",
        "surname": "Okello",
        "account_number": "0123456789",
        "bank_code": "0001",
        "bank_name": "Example Bank"
    },
    "purpose": "Invoice 4401",
    "auto_execute": false
}'

Execute a held remittance

HTTP Method	POST
Endpoint URL	`/api/v2/remit/{id}/execute`
Base URL	`https://base-url-here.com`
Description	Debit the wallet and submit a `pending_approval` remittance. `{id}` is the remittance UUID or your reference.

curl --location --request POST 'https://base-url-here.com/api/v2/remit/INV-1002/execute' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer <token>' \
--header 'X-Business-Id: 9'

The wallet must have enough available balance for debit_amount. A reused reference returns HTTP 409. An expired quote returns HTTP 422. Execute is idempotent for an already successful remittance.

Terms of Use & Legal

By using this API, you agree to our Terms of Service and Privacy Policy. Do not share sensitive data or credentials.