Chapa Developer Documentation

This document will go through the necessary actions taken to verify transfers after you initiated a transfer using Chapa's transfers API.

How to Verify Transfers

Verifying payment is dependent on the method used when first initializing a transfer. Using your payout reference, a GET request is needed to be made to the Verify Transfer endpoint server.

Endpoint: https://api.chapa.co/v1/transfers/verify/{tx_ref}
Method: GET
Authorization: Pass your secret key as a bearer token in the request header to authorize this call.

{tx_ref} is the reference ID for the specific transfer.

cURL

JavaScript

PHP

Python

Successful Response

The API returns detailed transfer information:

{
  "message": "Transfer details",
  "status": "success",
  "data": {
    "account_name": "Israel Goytom",
    "account_number": "21312331234123",
    "mobile": null,
    "currency": "ETB",
    "amount": 100,
    "charge": 0,
    "mode": "live",
    "transfer_method": "bank",
    "narration": null,
    "chapa_transfer_id": "4d6a7cb7-0d51-4c27-9a19-cc3f066c85a3",
    "bank_code": 128,
    "bank_name": "Bunna Bank",
    "cross_party_reference": null,
    "ip_address": "UNKNOWN",
    "status": "success",
    "tx_ref": "chewatatest-6669",
    "created_at": "2022-07-26T16:38:32.000000Z",
    "updated_at": "2023-01-10T07:09:08.000000Z"
  }
}

Response Parameters

Parameter	Type	Description
`message`	string	Response message
`status`	string	Status of the request (success/failed)
`data.account_name`	string	Recipient account name
`data.account_number`	string	Recipient account number
`data.mobile`	string\|null	Recipient mobile number (if available)
`data.currency`	string	Currency code (ETB, USD)
`data.amount`	number	Transfer amount
`data.charge`	number	Transfer fee
`data.mode`	string	Mode (live/test)
`data.transfer_method`	string	Transfer method (bank, etc.)
`data.narration`	string\|null	Transfer narration (if available)
`data.chapa_transfer_id`	string	Chapa's internal transfer ID
`data.bank_code`	number	Bank code
`data.bank_name`	string	Bank name
`data.cross_party_reference`	string\|null	Cross-party reference (if available)
`data.ip_address`	string	IP address from which transfer was initiated
`data.status`	string	Transfer status (success, pending, failed)
`data.tx_ref`	string	Your transaction reference
`data.created_at`	string	Timestamp when transfer was created
`data.updated_at`	string	Timestamp when transfer was last updated

Failed Response

{
  "message": "Invalid transfer reference or Transfer is not found",
  "status": "failed",
  "data": null
}

Refer to our Error Codes page for all responses for this request.

Best Practices

Always verify transfers on your server before updating your records
Use the status field to determine if the transfer was successful
Store the chapa_transfer_id for future reference
Check the amount and currency to ensure they match your expected values

Next Steps

Transfer - Initiate a new transfer
All Transfers - View all your transfers
Error Codes - Handle errors gracefully