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. For more details about request signature generation, see the About the signature section.

Payment statuses

• PENDING — The payment is being processed. No final result is available yet.
• REDIRECT — The payment is being processed. No final result is available yet. Available for checkout transactions.
• SUCCESS — The payment was completed successfully.
• FAILED — The payment is declined.
• SPECIFICATION — Additional information or action is required to continue processing the payment.

---

Callbacks

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. For more details about request signature generation, see the About the signature section. 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.

note

For H2H integrations, Amanpay can also send callbacks containing additional information required to continue the payment process. For example, a callback may contain a QR code or payment data that should be presented to the customer to complete the payment.

For request and callback examples, including method-specific additional data, see the documentation page for the corresponding payment method.

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.00,
    "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.00,
    "currency": "BDT",
    "paymentType": "purchase"
}

---

Payment status

When a transaction is being performed, it changes its statuses depending on different events occurring during its processing.

You can learn the status of your transaction:

• by using the Amanpay Dashboard which is available at https://merchant.amanpay.io. Contact the Amanpay support team or your account manager to get access there
• by checking callback the payment platform sends to your system
• by sending Amanpay a request to retrieve the payout status.

Parameter	Value
URL	https://gateway.amanpay.io
API endpoint	/payments/purchases/status
	/payments/payouts/status
HTTP request method	POST
Request body format	JSON

Header	Value	Description
Content-Type	application/json	HTTP header indicating the media type of the resource sent in the request body.
Authorization	calculated	Signature string. For the information on how to generate the signature, see Signature generation and verification.

Parameters of the request to retrieve a status:

The following table contains the parameters that have to be used in requests to retrieve a payout status.

Parameter	Type	Required	Description
merchantId	integer	Required	Your unique merchant ID that you got from Amanpay when integrating.
paymentId	string	Required	Payment ID unique within your system.

Here is an example of a request to retrieve a payout status.

Request example

{
  "merchantId": 138,
  "paymentId": "ORDER_100001_185_329"
}

Successful retrieved response

{
  "transactionId": "1122257",
  "paymentID": "ORDER_100001_185_329",
  "status": "FAILED",
  "amount": 500,
  "currency": "PKR",
  "paymentType": "purchase",
  "errorCode": "GENERAL_ERROR",
  "errorMessage": "An unexpected error occurred while processing your request"
}

Error response

{
  "result_code": "INVALID_REQUEST_ID",
  "result_message": "The requested ID does not exist"
}

Parameters of responses and callbacks

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

Callback

Parameter	Type	Always used	Used in	Description
transactionId	string	Yes	Callback Check status Response	Payment ID within the Amanpay payment platform.
operationId	string	Yes	Callback Check status Response	Operation ID within the Amanpay payment platform.
paymentID	string	No	Callback Check status Response	Payment ID within your system.
status	string	Yes	Callback Check status Response	Current status of your payment.
errorCode	string	No	Callback Check status Response	Error code.
errorMessage	string	No	Callback Check status Response	Description of the error.
amount	integer	Yes	Callback Check status Response	Payment amount you passed in your request.
currency	string	Yes	Callback Check status Response	Payment currency you passed in your request.
paymentType	string	Yes	Callback Check status Response	Payment method's type.
customerName	string	No	Callback Check status Response	Customer's full name.
customerAccountNumber	string	No	Callback Check status Response	Customer's account number.
QrData	string	No	Callback Check status Response	Qr data
PaymentData	string	No	Callback Check status Response	Payment data

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
CUSTOMER_COUNTRY_RESTRICTED	Transfers to customers in this country and from this country are not supported
PAYMENT_CHANNEL_UNAVAILABLE	Payment channel is disabled or temporarily unavailable due to downtime
INSUFFICIENT_MERCHANT_BALANCE	Merchant has insufficient balance to complete the transaction
INVALID_API_CREDENTIALS	API key or signature is invalid