Create a purchase request

To initiate a purchase in the Amanpay payment platform, send it a request as described in this section.

URL	https://gateway.amanpay.io
API endpoint	/payments/purchases/initiate
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 a purchase request:

The following table contains the parameters that can be used in purchase requests you send to the Amanpay payment platform.

The parameters are divided into the following types depending on whether they are required in requests:

• Required—the parameter is always required in purchase requests
• Optional—the parameter is optional
• Conditionally required—the parameter may be required in purchase requests under certain conditions. The conditions are given in the parameter description

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.
amount	number	Required	Purchase amount in major currency units, e.g., pass 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	Optional	Customer's ID unique within your system. If not passed in the request, the value from the customerEmail parameter is used.
customerEmail	string	Required	Customer's email.
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. If not passed in the request, the customer will have to choose a payment method themselves on the checkout page.
easypaisaNumber	string	Optional	Customer's mobile phone number associated with their Easypaisa e-wallet. If not passed, the customer will have to enter their mobile phone number themselves on the checkout page. Pass this parameter in the request together with the paymentMethod parameter.
jazzcashNumber	string	Optional	Customer's mobile phone number associated with their JazzCash e-wallet. If not passed, the customer will have to enter their mobile phone number themselves on the checkout page. Pass this parameter in the request together with the paymentMethod parameter.
bkashNumber	string	Optional	Customer's mobile phone number associated with their bKash e-wallet. If not passed, the customer will have to enter their mobile phone number themselves on the checkout page. Pass this parameter in the request together with the paymentMethod parameter.
nagadNumber	string	Optional	Customer's mobile phone number associated with their Nagad e-wallet. If not passed, the customer will have to enter their mobile phone number themselves on the checkout page. Pass this parameter in the request together with the paymentMethod parameter.
recipientType	string	Optional	Customer's account type. Possible values: bank_account, mobile_wallet.
notifyUrl	string	Optional	URL for receiving callbacks for a specific payment. By adding this parameter to your request, you'll receive a callback for the payment to the URL you specify in this parameter.
returnUrl	string	Optional	URL to redirect the customer to after they've completed a payment.

Here is an example of a purchase request to the Amanpay payment platform. The example contains only basic set of parameters. The parameters that have to be used in purchase requests for a specific payment method are described in the corresponding payment method's section (for the payment methods supported in Amanpay, see Payment methods).

curl -X POST "https://gateway.amanpay.io/payments/purchases/initiate" \
  -H "Content-Type: application/json" \
  -H "Authorization: b78d07bc3e51899182339bfb39c85ab8629085c80f9b2312444669a3bdd78cc0522a1bcca50ede6be3a90fcf489100304cde09e14fa51a175a5fed0e36f6c26b" \
  -d '{
    "merchantId": 1758378,
    "paymentId": "payment_812",
    "amount": 250.51,
    "currency": "BDT",
    "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 Response section.

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"
}

The final status of the purchase is sent to your system in a separate callback. For the information about callbacks, see the Callback section.