Checkout Purchases

---

Amanpay Checkout lets you accept payments without building your own payment interface. Create a purchase through the Amanpay API, redirect the customer to the returned Checkout URL, and let Amanpay handle the payment flow.

1

Create a purchase

Send a POST request to the Amanpay API with the payment details.

2

Get the Checkout URL

Amanpay returns a redirectUrl for the created payment.

3

Redirect the customer

Redirect the customer to the provided URL to choose a payment method and complete the purchase.

4

Track the payment

Check the payment status or receive a callback to determine the final result.

Checkout Purchase Flow

---

---

Request

Use the following endpoint to create a Checkout purchase:

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

Header	Value	Required	Description
Content-Type	application/json	Required	HTTP header indicating the media type of the resource sent in the request body.
Authorization	calculated	Required	For more information about request signature generation, see the Signature section.

The following parameters can be used in purchase requests sent to the Amanpay payment platform.

Parameter	Type	Required	Description
merchantId	integer	Required	Your unique merchant ID that you received from Amanpay during integration.
paymentId	string	Required	Payment ID unique within your system.
amount	number	Required	Purchase amount in major currency units, e.g. 10.52 for 10 dollars 52 cents or 11.00 for 11 dollars.
currency	string	Required	Code of the purchase currency in the ISO-4217 alpha-3 format.
customerId	string	Conditional	Customer's ID unique within your system. If not passed in the request, the value from the customerEmail parameter is used. Either customerEmail or customerId must be provided.
customerEmail	string	Conditional	Customer's email. Either customerEmail or customerId must be provided.
customerIp	string	Optional	Customer's IP address.
customerName	string	Optional	Customer's full name.
customerKYCLevel	string	Optional	Verification level of the customer within your system. Possible values: verified, basic.
paymentMethod	string	Optional	Payment method's code. Possible values: bkash, nagad, jazzcash, easypaisa, raastqr. If not passed, the customer will have to choose a payment method on the checkout page from the methods available for the selected currency.
easypaisaNumber	string	Optional	Customer's mobile phone number associated with their Easypaisa e-wallet. If not passed, the customer will have to enter their phone number on the checkout page. Pass this parameter together with paymentMethod.
jazzcashNumber	string	Optional	Customer's mobile phone number associated with their JazzCash e-wallet. If not passed, the customer will have to enter their phone number on the checkout page. Pass this parameter together with paymentMethod.
raastQRNumber	string	Optional	Customer's mobile phone number associated with their wallet. If not passed, the customer will have to enter their phone number on the checkout page. Pass this parameter together with paymentMethod.
bkashNumber	string	Optional	Customer's mobile phone number associated with their bKash e-wallet. If not passed, the customer will have to enter their phone number on the checkout page. Pass this parameter together with paymentMethod.
nagadNumber	string	Optional	Customer's mobile phone number associated with their Nagad e-wallet. If not passed, the customer will have to enter their phone number on the checkout page. Pass this parameter together with paymentMethod.
recipientType	string	Optional	Customer's account type. Possible values: bank_account, mobile_wallet.
notifyUrl	string	Optional	URL for receiving callbacks for a specific payment.
returnUrl	string	Optional	URL to redirect the customer to after the payment has been completed.

Request example

{
  "merchantId": 123,
  "paymentId": "payment_812",
  "amount": 250,
  "currency": "PKR",
  "customerId": "customer174",
  "customerEmail": "mark_cooper@example.com"
}

Upon receiving your request, Amanpay sends a response to your system. To learn more information about responses, see the Responses & Callbacks

Response

Header	Value	Required	Description
Content-Type	application/json	Required	HTTP header indicating the media type of the resource sent in the request body.
Authorization	calculated	Required	For more details about request signature generation, see the About the signature section.

The following parameters are returned in purchase responses from the AmanPay payment platform.

Field	Type	Required	Description
transactionId	string	Required	Unique transaction identifier assigned by Amanpay.
paymentID	string	Required	Unique payment identifier provided in the purchase request.
status	string	Required	Current status of the purchase. All possible statuses - Responses & Callbacks
amount	number	Required	Payment amount in major currency units.
currency	string	Required	ISO-4217 alpha-3 currency code.
redirectUrl	string	Required	URL where the customer must be redirected to complete the payment on the Amanpay Checkout page.
paymentType	string	Required	Type of payment operation. For purchases, the value is purchase.
result_code	string	Conditional	Error code identifying the reason for the failed request. Returned only in case of an error.
result_message	string	Conditional	Description of the error. Returned only in case of an error.

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

Response example

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

After receiving the response, redirect the customer to the redirectUrl to continue the payment on the Amanpay Checkout page.

Error response

{
  "result_code": "DUPLICATE_PAYMENT_ID",
  "result_message": "Payment ID already exists"
}

The final status of the purchase will be provided in the callback and in the payment status response Responses & Callbacks