API ReferenceTransactions
API REFERENCE

Transactions

Log, commit, track and cancel transfers. See Transaction flow for the order of calls per channel.

Log a Mobile Transfer

Log a transfer to a mobile wallet. No money moves until you call commitTransaction.

Run getMobileSubscriberDetails first and keep the tracking_id from its callback.

!

Warning: Check result.status before you commit. 409 returns the existing transaction_id (see Idempotency).

POST/transactionstransactions@logMobileTranscation

Request Body

FieldTypeRequiredDescription
request_idstringYesYour unique reference. Must never be reused.
callback_urlstringYesHTTPS URL that receives the commit result
currency_codestringYesAlways KES. Payout currency
send_amountnumberYesAmount to pay out, max 2 decimal places
sender_first_namestringYesSender's first name
sender_last_namestringYesSender's last name
sender_date_of_birthstringYesyyyymmdd
sender_nationalitystringYesISO country code
sender_id_numberstringYesSender's ID document number
sender_id_typestringNoType of the sender's ID document One of: National ID, Passport, Military ID.
sender_addressstringNoSender's address
recipient_first_namestringYesRecipient's first name
recipient_last_namestringYesRecipient's last name
recipient_msisdnstringYesRecipient phone, e.g. 254712345678
recipient_addressstringYesRecipient's address
recipient_date_of_birthstringNoyyyymmdd
recipient_nationalitystringNoISO country code
recipient_id_numberstringNoRecipient's ID document number
recipient_id_typestringNoType of the recipient's ID document
recipient_occupationstringNoRecipient's occupation
recipient_emailstringNoMust be a valid email if sent
purposestringNoPurpose of the remittance
source_of_fundsstringNoSource of the funds being sent
tracking_idstringYesFrom the mobile subscriber lookup callback
sender_phonestringYesSender phone number
sender_country_isostringYesSender's country of residence (ISO code)
sender_id_issue_placestringNoPlace where the sender's ID was issued
sender_id_issue_datestringNoyyyymmdd
sender_id_expirystringNoyyyymmdd
sender_spstringNoSender's service provider
foreign_currencystringNo"<currency>,<rate>,<original amount>", e.g. "USD,129.5,100"
occasionstringNoOccasion for the transfer

Request Body Example

json
{
  "jsonrpc": "2.0",
  "method": "transactions@logMobileTranscation",
  "params": {
    "request_id": "TXN-20261012-000184",
    "tracking_id": "AG_20261012_2030166ee8992ece3dc4",
    "callback_url": "https://partner.example.com/afrisend/payments",
    "currency_code": "KES",
    "send_amount": 12950,
    "sender_first_name": "Joseph",
    "sender_last_name": "Mwangi",
    "sender_phone": "971501234567",
    "sender_date_of_birth": "19850312",
    "sender_nationality": "KE",
    "sender_country_iso": "AE",
    "sender_id_number": "784198512345678",
    "sender_id_type": "Passport",
    "sender_address": "Al Nahda, Dubai",
    "recipient_first_name": "Wanjiru",
    "recipient_last_name": "Kamau",
    "recipient_msisdn": "254712345678",
    "recipient_address": "Kiambu",
    "foreign_currency": "USD,129.5,100",
    "purpose": "Family support",
    "source_of_funds": "Salary"
  },
  "id": "1"
}

Check result.status before committing.

Response Fields

FieldTypeDescription
resultobjectOperation result
result.transaction_idstringAfrisend transaction ID. Use it to commit, cancel and check status.
result.statusinteger200 accepted, 409 duplicate, 422 outside limits, 400 or 404 commit refused
result.messagestringOutcome description

Example Response — Logged

json
{
  "jsonrpc": "2.0",
  "result": {
    "transaction_id": "in8447D7EC98",
    "status": 200,
    "message": "transaction logged successfully"
  },
  "id": "1"
}

Example Response — Duplicate request_id

json
{
  "jsonrpc": "2.0",
  "result": {
    "transaction_id": "in8447D7EC98",
    "status": 409,
    "message": "A transaction with a similar request_id has already been recorded."
  },
  "id": "1"
}

Example Response — Similar Transaction Within the Last Hour

json
{
  "jsonrpc": "2.0",
  "result": {
    "transaction_id": "in8447D7EC98",
    "status": 409,
    "message": "A similar transaction was logged within the last hour. Please verify your transaction details before retrying."
  },
  "id": "1"
}

Example Response — Validation Error

json
{
  "jsonrpc": "2.0",
  "error": {
    "code": 400,
    "message": "{\"sender_phone\":[\"The sender phone field is required.\"]}"
  },
  "id": "1"
}

The bearer token is missing, invalid or expired. The response is plain JSON with HTTP 401, not a JSON-RPC envelope. Log in again and retry once.

Response Fields

FieldTypeDescription
statusstringAlways 401.
messagestringError message

Example Response

json
{
  "status": 401,
  "message": "Failed, Not authorized"
}

Log a Bank Transfer

Log a transfer to a bank account. Get valid bank codes from getAllBanks. Verify the account holder's name first with getBankSubscriberDetails.

!

Warning: Check result.status before you commit. 409 returns the existing transaction_id (see Idempotency).

POST/transactionstransactions@logBankTranscation

Request Body

FieldTypeRequiredDescription
request_idstringYesYour unique reference. Must never be reused.
callback_urlstringYesHTTPS URL that receives the commit result
currency_codestringYesAlways KES. Payout currency
send_amountnumberYesAmount to pay out, max 2 decimal places
sender_first_namestringYesSender's first name
sender_last_namestringYesSender's last name
sender_date_of_birthstringYesyyyymmdd
sender_nationalitystringYesISO country code
sender_id_numberstringYesSender's ID document number
sender_id_typestringNoType of the sender's ID document
sender_addressstringNoSender's address
recipient_first_namestringYesRecipient's first name
recipient_last_namestringYesRecipient's last name
recipient_msisdnstringYesRecipient phone, e.g. 254712345678
recipient_addressstringYesRecipient's address
recipient_date_of_birthstringNoyyyymmdd
recipient_nationalitystringNoISO country code
recipient_id_numberstringNoRecipient's ID document number
recipient_id_typestringNoType of the recipient's ID document
recipient_occupationstringNoRecipient's occupation
recipient_emailstringNoMust be a valid email if sent
purposestringNoPurpose of the remittance
source_of_fundsstringNoSource of the funds being sent
destination_bank_codestringYesBank code from getAllBanks
destination_accountstringYesRecipient account number
sender_msisdnstringYesSender phone number
descriptionstringNoDescription of the transfer

Request Body Example

json
{
  "jsonrpc": "2.0",
  "method": "transactions@logBankTranscation",
  "params": {
    "request_id": "TXN-20261012-000185",
    "callback_url": "https://partner.example.com/afrisend/payments",
    "currency_code": "KES",
    "send_amount": 85000,
    "destination_bank_code": "40401000",
    "destination_account": "1182736450",
    "sender_first_name": "Grace",
    "sender_last_name": "Achieng",
    "sender_msisdn": "447700900123",
    "sender_date_of_birth": "19900415",
    "sender_nationality": "KE",
    "sender_id_number": "A12345678",
    "sender_id_type": "Passport",
    "recipient_first_name": "Brian",
    "recipient_last_name": "Odhiambo",
    "recipient_msisdn": "254722334455",
    "recipient_address": "Kisumu",
    "purpose": "School fees",
    "source_of_funds": "Salary"
  },
  "id": "1"
}

Check result.status before committing.

Response Fields

FieldTypeDescription
resultobjectOperation result
result.transaction_idstringAfrisend transaction ID. Use it to commit, cancel and check status.
result.statusinteger200 accepted, 409 duplicate, 422 outside limits, 400 or 404 commit refused
result.messagestringOutcome description

Example Response — Logged

json
{
  "jsonrpc": "2.0",
  "result": {
    "transaction_id": "in8447D7EC98",
    "status": 200,
    "message": "transaction logged successfully"
  },
  "id": "1"
}

Example Response — Duplicate request_id

json
{
  "jsonrpc": "2.0",
  "result": {
    "transaction_id": "in8447D7EC98",
    "status": 409,
    "message": "A transaction with a similar request_id has already been recorded."
  },
  "id": "1"
}

Example Response — Similar Transaction Within the Last Hour

json
{
  "jsonrpc": "2.0",
  "result": {
    "transaction_id": "in8447D7EC98",
    "status": 409,
    "message": "A similar transaction was logged within the last hour. Please verify your transaction details before retrying."
  },
  "id": "1"
}

Example Response — Validation Error

json
{
  "jsonrpc": "2.0",
  "error": {
    "code": 400,
    "message": "{\"sender_phone\":[\"The sender phone field is required.\"]}"
  },
  "id": "1"
}

The bearer token is missing, invalid or expired. The response is plain JSON with HTTP 401, not a JSON-RPC envelope. Log in again and retry once.

Response Fields

FieldTypeDescription
statusstringAlways 401.
messagestringError message

Example Response

json
{
  "status": 401,
  "message": "Failed, Not authorized"
}

Log a Cash Pickup Transfer

Log a cash pickup transfer.

!

Warning: Check result.status before you commit. 409 returns the existing transaction_id (see Idempotency).

POST/transactionstransactions@logCashTranscation

Request Body

FieldTypeRequiredDescription
request_idstringYesYour unique reference. Must never be reused.
callback_urlstringYesHTTPS URL that receives the commit result
currency_codestringYesPayout currency. KES or USD. One of: KES, USD.
send_amountnumberYesAmount to pay out, max 2 decimal places
sender_first_namestringYesSender's first name
sender_last_namestringYesSender's last name
sender_date_of_birthstringYesyyyymmdd
sender_nationalitystringYesISO country code
sender_id_numberstringYesSender's ID document number
sender_id_typestringNoType of the sender's ID document
sender_addressstringNoSender's address
recipient_first_namestringYesRecipient's first name
recipient_last_namestringYesRecipient's last name
recipient_msisdnstringYesRecipient phone, e.g. 254712345678
recipient_addressstringYesRecipient's address
recipient_date_of_birthstringNoyyyymmdd
recipient_nationalitystringNoISO country code
recipient_id_numberstringNoRecipient's ID document number
recipient_id_typestringNoType of the recipient's ID document
recipient_occupationstringNoRecipient's occupation
recipient_emailstringNoMust be a valid email if sent
purposestringNoPurpose of the remittance
source_of_fundsstringNoSource of the funds being sent
sender_msisdnstringYesSender phone number
descriptionstringNoDescription of the transfer

Request Body Example

json
{
  "jsonrpc": "2.0",
  "method": "transactions@logCashTranscation",
  "params": {
    "request_id": "TXN-20261012-000186",
    "callback_url": "https://partner.example.com/afrisend/payments",
    "currency_code": "KES",
    "send_amount": 20000,
    "sender_first_name": "Peter",
    "sender_last_name": "Kiprono",
    "sender_msisdn": "12025550147",
    "sender_date_of_birth": "19780921",
    "sender_nationality": "KE",
    "sender_id_number": "29384756",
    "recipient_first_name": "Mercy",
    "recipient_last_name": "Wambui",
    "recipient_msisdn": "254733445566",
    "recipient_address": "Nakuru"
  },
  "id": "1"
}

Check result.status before committing.

Response Fields

FieldTypeDescription
resultobjectOperation result
result.transaction_idstringAfrisend transaction ID. Use it to commit, cancel and check status.
result.statusinteger200 accepted, 409 duplicate, 422 outside limits, 400 or 404 commit refused
result.messagestringOutcome description

Example Response — Logged

json
{
  "jsonrpc": "2.0",
  "result": {
    "transaction_id": "in8447D7EC98",
    "status": 200,
    "message": "transaction logged successfully"
  },
  "id": "1"
}

Example Response — Duplicate request_id

json
{
  "jsonrpc": "2.0",
  "result": {
    "transaction_id": "in8447D7EC98",
    "status": 409,
    "message": "A transaction with a similar request_id has already been recorded."
  },
  "id": "1"
}

Example Response — Similar Transaction Within the Last Hour

json
{
  "jsonrpc": "2.0",
  "result": {
    "transaction_id": "in8447D7EC98",
    "status": 409,
    "message": "A similar transaction was logged within the last hour. Please verify your transaction details before retrying."
  },
  "id": "1"
}

Example Response — Validation Error

json
{
  "jsonrpc": "2.0",
  "error": {
    "code": 400,
    "message": "{\"sender_phone\":[\"The sender phone field is required.\"]}"
  },
  "id": "1"
}

The bearer token is missing, invalid or expired. The response is plain JSON with HTTP 401, not a JSON-RPC envelope. Log in again and retry once.

Response Fields

FieldTypeDescription
statusstringAlways 401.
messagestringError message

Example Response

json
{
  "status": 401,
  "message": "Failed, Not authorized"
}

Commit Transaction

Confirm a LOGGED transaction and start the payout. Afrisend checks your balance at this point. The final result arrives at the callback_url you gave when you logged the transaction.

statusmessageWhat to do
400Partner balance and overdraw limit surpassedTop up, then commit again
400Top up partner balanceTop up, then commit again
400Partner should request account creationContact Afrisend: no account exists in this currency
404Partner not found / Partner balance not foundContact Afrisend
POST/transactionstransactions@commitTransactionasync

Request Body

FieldTypeRequiredDescription
paramsobjectYesParameters for the operation. Send {} if there are none.
transaction_idstringYesAfrisend transaction ID, from the log request

Request Body Example

json
{
  "jsonrpc": "2.0",
  "method": "transactions@commitTransaction",
  "params": {
    "transaction_id": "in8447D7EC98"
  },
  "id": "1"
}
Error codeMessage
404transaction not found
409Transaction already committed (the transaction is not LOGGED)

Response Fields

FieldTypeDescription
resultobjectOperation result
result.transaction_idstringAfrisend transaction ID. Use it to commit, cancel and check status.
result.statusinteger200 accepted, 409 duplicate, 422 outside limits, 400 or 404 commit refused
result.messagestringOutcome description

Example Response — Commit Accepted

json
{
  "jsonrpc": "2.0",
  "result": {
    "transaction_id": "in8447D7EC98",
    "status": 200,
    "message": "Service request has been received"
  },
  "id": "1"
}

Example Response — Insufficient Balance

json
{
  "jsonrpc": "2.0",
  "result": {
    "transaction_id": "in8447D7EC98",
    "status": 400,
    "message": "Top up partner balance"
  },
  "id": "1"
}

Example Response — Already Committed

json
{
  "jsonrpc": "2.0",
  "error": {
    "code": 409,
    "message": "Transaction already committed"
  },
  "id": "1"
}

The bearer token is missing, invalid or expired. The response is plain JSON with HTTP 401, not a JSON-RPC envelope. Log in again and retry once.

Response Fields

FieldTypeDescription
statusstringAlways 401.
messagestringError message

Example Response

json
{
  "status": 401,
  "message": "Failed, Not authorized"
}

Callback — Final Transaction Status

Sent as POST to your callback_url.

Callback Fields

FieldTypeDescription
transaction_idstringAfrisend transaction ID
tracking_idstringAfrisend tracking reference
statusstringOutcome of the commit
status_messagestringDetails of the outcome

Callback Example

json
{
  "transaction_id": "in8447D7EC98",
  "tracking_id": "AG_20261012_20106e210e4e0c5f1202",
  "status": "success",
  "status_message": "The service request is processed successfully."
}

Check Transaction Status

Get the current status of a transaction. Use it when a callback is late or missing.

POST/transactionstransactions@checkTransactionStatus

Request Body

FieldTypeRequiredDescription
paramsobjectYesParameters for the operation. Send {} if there are none.
transaction_idstringYesAfrisend transaction ID, from the log request

Request Body Example

json
{
  "jsonrpc": "2.0",
  "method": "transactions@checkTransactionStatus",
  "params": {
    "transaction_id": "in8447D7EC98"
  },
  "id": "1"
}
Error codeMessage
400transaction not found

Response Fields

FieldTypeDescription
resultobjectOperation result
result.transaction_idstringAfrisend transaction ID
result.statusstringSee Transaction statuses One of: LOGGED, COMMITTED, INPROGRESS, PENDING, COLLECTED, FAILED, REVERSED, CANCELLED.
result.remarkstringExplanation of the status

Example Response

json
{
  "jsonrpc": "2.0",
  "result": {
    "transaction_id": "in8447D7EC98",
    "status": "COLLECTED",
    "remark": "Transaction successfully processed"
  },
  "id": "1"
}

The bearer token is missing, invalid or expired. The response is plain JSON with HTTP 401, not a JSON-RPC envelope. Log in again and retry once.

Response Fields

FieldTypeDescription
statusstringAlways 401.
messagestringError message

Example Response

json
{
  "status": 401,
  "message": "Failed, Not authorized"
}

Get Transaction by Request ID

Find a transaction by your request_id. Use it to recover the transaction_id after a log request times out.

POST/transactionstransactions@getTransactionByRequestId

Request Body

FieldTypeRequiredDescription
paramsobjectYesParameters for the operation. Send {} if there are none.
request_idstringYesThe request_id you sent when logging

Request Body Example

json
{
  "jsonrpc": "2.0",
  "method": "transactions@getTransactionByRequestId",
  "params": {
    "request_id": "TXN-20261012-000184"
  },
  "id": "1"
}
Error codeMessage
404transaction not found (safe to log the transaction again with the same request_id)

Response Fields

FieldTypeDescription
result.transaction_idstringAfrisend transaction ID
result.statusstringSee Transaction statuses One of: LOGGED, COMMITTED, INPROGRESS, PENDING, COLLECTED, FAILED, REVERSED, CANCELLED.
result.remarkstringExplanation of the status
result.tracking_idstringAfrisend tracking reference

Example Response

json
{
  "jsonrpc": "2.0",
  "result": {
    "transaction_id": "in8447D7EC98",
    "status": "LOGGED",
    "tracking_id": "in8447D7EC98",
    "remark": "Transaction logged"
  },
  "id": "1"
}

The bearer token is missing, invalid or expired. The response is plain JSON with HTTP 401, not a JSON-RPC envelope. Log in again and retry once.

Response Fields

FieldTypeDescription
statusstringAlways 401.
messagestringError message

Example Response

json
{
  "status": 401,
  "message": "Failed, Not authorized"
}

Cancel Transaction

Cancel a transaction that is logged but not committed. Only LOGGED transactions can be cancelled. Otherwise the response returns the current status with the remark cannot cancel transaction.

POST/transactionstransactions@cancelTransaction

Request Body

FieldTypeRequiredDescription
paramsobjectYesParameters for the operation. Send {} if there are none.
transaction_idstringYesAfrisend transaction ID, from the log request

Request Body Example

json
{
  "jsonrpc": "2.0",
  "method": "transactions@cancelTransaction",
  "params": {
    "transaction_id": "in8447D7EC98"
  },
  "id": "1"
}
Error codeMessage
404transaction not found

Response Fields

FieldTypeDescription
resultobjectOperation result
result.transaction_idstringAfrisend transaction ID
result.statusstringSee Transaction statuses One of: LOGGED, COMMITTED, INPROGRESS, PENDING, COLLECTED, FAILED, REVERSED, CANCELLED.
result.remarkstringExplanation of the status

Example Response — Cancelled

json
{
  "jsonrpc": "2.0",
  "result": {
    "transaction_id": "in8447D7EC98",
    "status": "CANCELLED",
    "remark": "cancelled by partner"
  },
  "id": "1"
}

Example Response — Not Cancellable (Already Committed)

json
{
  "jsonrpc": "2.0",
  "result": {
    "transaction_id": "in8447D7EC98",
    "status": "COMMITTED",
    "remark": "cannot cancel transaction"
  },
  "id": "1"
}

The bearer token is missing, invalid or expired. The response is plain JSON with HTTP 401, not a JSON-RPC envelope. Log in again and retry once.

Response Fields

FieldTypeDescription
statusstringAlways 401.
messagestringError message

Example Response

json
{
  "status": 401,
  "message": "Failed, Not authorized"
}
Previous← Subscriber LookupNextAccount →
© 2026 Afrisend