Responses Callbacks

Response

Upon receiving your request, Amanpay returns a synchronous response (within a single HTTP session) to your system.

The response contains details of the payment you initiated in the payment platform and the current status of this payment. Note that responses to purchase and payout requests don't contain the final status of the payment as the final status for these operations is submitted to you in a callback.

When receiving responses from Amanpay, you should verify the signature in the Authorization header of a response to ensure authenticity.

Parameters that Amanpay sends in responses to your requests are described in the Parameters of responses and callbacks section below.

Here is an example of the data from a response to a purchase request.

{
    "transactionId": "62861",
    "paymentID": "payment_812",
    "status": "REDIRECT",
    "amount": 250.51,
    "currency": "BDT",
    "redirectUrl": "https://page.amanpay.io/checkout/04c881d8-8744-11f0-85ec",
    "paymentType": "purchase"
}

Callback

A callback is an HTTP request that Amanpay sends to your system. Callbacks are sent to you using the POST method and are meant to notify you about the final status of purchases and payouts that you initiate in the payment platform.

Amanpay sends callbacks:

to the URL you provided the Amanpay support team with during integration
to the URL you submit in the notifyUrl parameter if you need to receive callbacks for a specific payment to an individual URL

When receiving callbacks from Amanpay, you should verify the signature in the Authorization header of a callback to ensure authenticity.

Parameters that Amanpay sends in callbacks to your system are described in the Parameters of responses and callbacks section below.

Here is an example of the data from a callback containing information about a successfully completed purchase.

{
    "transactionId": "62861",
    "paymentID": "payment_812",
    "status": "SUCCESS",
    "amount": 250.51,
    "currency": "BDT",
    "paymentType": "purchase",
    "customerName": "Mark Cooper",
    "customerAccountNumber": "185927571757184"
}

The following is an example of a callback sent if a payment has been declined.

{
    "transactionId": "62861",
    "paymentID": "payment_812",
    "status": "FAILED",
    "errorCode": "GENERAL_ERROR",
    "errorMessage": "An unexpected error occurred while processing your request",
    "amount": 250.51,
    "currency": "BDT",
    "paymentType": "purchase"
}

Parameters of responses and callbacks

The following table contains the parameters used in responses and callbacks from the Amanpay payment platform.

Parameter	Type	Always used	Description
`transactionId`	string	Yes	Payment ID within the Amanpay payment platform.
`operationId`	string	Yes	Operation ID within the Amanpay payment platform.
`paymentID`	string	No	Payment ID within your system.
`status`	string	Yes	Current status of your payment.
`errorCode`	string	No	Error code. For the error codes that can be passed in this parameter, see the table below.
`errorMessage`	string	No	Description of the error. For the error messages that can be passed in this parameter, see the table below.
`amount`	integer	Yes	Payment amount you passed in your request.
`currency`	string	Yes	Payment currency you passed in your request.
`paymentType`	string	Yes	Payment method's type.
`customerName`	string	No	Customer's full name.
`customerAccountNumber`	string	No	Customer's account number.
`redirectUrl`	string	No	URL you should redirect your customer to. The parameter is submitted only in responses to purchase requests.

Listed below are the values that can be passed in the errorCode and errorMessage parameters.

Error code	Error message
`INVALID_CUSTOMER_ACCOUNT`	`The customer's phone number, email, or wallet ID is invalid or not found`
`CUSTOMER_NOT_VERIFIED`	`The customer's account requires identity verification (KYC) to proceed`
`CUSTOMER_ACCOUNT_BLOCKED`	`The customer's account is suspended or blocked`
`INSUFFICIENT_WALLET_BALANCE`	`The customer's wallet has insufficient balance to complete the transfer`
`MIN_TRANSFER_AMOUNT_VIOLATION`	`Transfer amount is below the minimum allowed threshold`
`MAX_TRANSFER_AMOUNT_VIOLATION`	`Transfer amount exceeds the maximum allowed per transaction`
`BLACKLISTED_CUSTOMER`	`The customer is on the internal blacklist`
`SELF_TRANSFER_NOT_ALLOWED`	`Cannot transfer funds to the same wallet or linked account`
`CUSTOMER_COUNTRY_RESTRICTED`	`Transfers to customers in this country and from this country are not supported`
`TRANSACTION_NOT_FOUND`	`No transfer found with the provided ID`
`TRANSFER_ALREADY_COMPLETED`	`This transfer has already been successfully processed`
`TRANSFER_EXPIRED`	`The payment link or session has expired`
`INVALID_API_KEY`	`Authentication failed. API Key is invalid or expired`
`GENERAL_ERROR`	`An unexpected error occurred while processing your request`
`PAYMENT_CANCELLED_BY_CUSTOMER`	`The payment was cancelled by the customer before completion`
`PAYMENT_NOT_COMPLETED_BY_CUSTOMER`	`The payment was not completed by the customer`
`CUSTOMER_BANK_UNREACHABLE`	`Unable to connect to the customer's bank. Please try again later`

Response​

Callback​

Parameters of responses and callbacks​

Response

Callback

Parameters of responses and callbacks