Response Codes

Understanding responses returned by the EcobankPay API

Important

Below are the general responses received after a payment transaction is initiated or for payment status requests.

Initial Transaction Response

Upon successful payment process initiated, the response received contains a JSON payload with the following parameters:

Parameter	Values	Value Type	Description
success	True, False	Boolean	True: request on transaction for payment successfully initiated to gateway False: request on transaction to gateway NOT successful.
url	URL	String	The gateway checkout page URL specifically for the transaction in question. Load or pop-up this URL in a browser for customer to completed payment process
error	Object	Object	Error details if success is False

Example Success Response:

{
  "invoice_id": "invoice001",
  "tx_reference": "1",
  "url": "https://pgw.paywithonline.com/v1/7755055152595959",
  "success": true,
  "message": "Invoice created"
}

Example Error Response:

{
  "success": false,
  "error": {
    "code": "GW-001",
    "message": "merchant_key missing or empty"
  }
}

Payment Status Response

Below is the general response received for a payment status request.

Parameter	Values	Value Type	Description
status	new, paid, cancelled, awaiting_payment, failed	String	new: payment transaction is new, initiated to the respective payment network paid: payment made successfully by customer cancelled: payment cancelled by customer awaiting_payment: payment pending. Customer does not complete or cancel payment. failed: Transaction failed. Reason for failure is provided in status_reason parameter.
status_reason	Free text	String	This parameter holds detail description for a Failed Transaction status. For other status values, it is empty.
buyer_firstname	Free text	String	First name of customer. Usually empty /null since no value is passed
buyer_lastname	Free text	String	Last name of customer. Usually empty / null
buyer_email	Free text	String	Email address of customer. Usually empty / null
buyer_phone	Free text	String	Phone number of customer. Usually empty / null
invoice_id	Free text	String	Invoice Id of transaction
amount		Float	Payment amount made
as_at		Date	Transaction timestamp on gateway
narration	Free Text	String	Description of payment made

Sample Status Response

{
  "invoice_id": "invoice001",
  "tx_reference": "121a8wmy78TRANSACTION1234Q",
  "status": "paid",
  "status_reason": "",
  "amount": 25.00,
  "buyer_firstname": "John",
  "buyer_lastname": "Doe",
  "buyer_email": "john.doe@example.com",
  "buyer_phone": "233201234567",
  "narration": "Payment for order #invoice001",
  "as_at": "2023-08-15T14:22:45Z"
}