Create a purchase request

To initiate a Host-to-Host 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	Required	Payment method's code. Possible values: bkash, nagad, jazzcash, easypaisa, raastqr.
easypaisaNumber	string	Conditionally required	Customer's mobile phone number associated with their Easypaisa e-wallet. Conditional — Required when paymentMethod is Easypaisa
jazzcashNumber	string	Conditionally required	Customer's mobile phone number associated with their JazzCash e-wallet. Conditional — Required when paymentMethod is JazzCash
raastQRNumber	string	Conditionally required	Customer's mobile phone number associated with their e-wallet. Conditional — Required when paymentMethod is RaastQR
bkashNumber	string	Conditionally required	Customer's mobile phone number associated with their bKash e-wallet.heckout page. Conditional — Required when paymentMethod is bKash
nagadNumber	string	Conditionally required	Customer's mobile phone number associated with their Nagad e-wallet. Conditional — Required when paymentMethod is Nagad
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",
    "paymentMethod": "raastqr", 
    "raastQRNumber": "03123456789"
}'

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": "PENDING",
    "amount": 250.51,
    "currency": "BDT",
    "paymentType": "purchase"
}

Depending on your integration configuration, a Host-to-Host payment flow may require additional data during payment processing, such as a one-time password (OTP), transaction ID (trxId), or other parameters.

Please contact your account manager to confirm whether these fields are required for your integration. For more information, see the Handling additional purchase data for Host-2-Host integration.

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