Create a payment order

This topic introduces how to create a payment request and get the payment result. The general procedure takes the following steps:

• Create a payment order with the createCashierPayment API.
• Make the payment. The Customer needs to complete the payment order on a Checkout page.
• After the payment, the Partner can:

• Inquire about the payment order with the inquirePayment API.
• Receive notifications about the result of the payment order with the notifyPayment API.

Step 1. Create a payment

Process:

1. A Customer initiates a payment order on the Partner's platform.
2. The Partner calls the createCashierPayment API and creates a payment order with WorldFirst. Every payment request is identified by a unique payToRequestId which is an idempotency field.
3. WorldFirst accepts the payment order and responds to the Partner, together with a payToId that is assigned by WorldFirst and associated with the payToRequestId. WorldFirst also returns the Partner with a redirection URL in the actionForm.redirectUrl field.
4. The Partner needs to redirect the Customer to the Checkout page.
5. The Customer binds his or her WorldFirst account to make a payment. For more details on this step, refer to the User Experience section in the Introduction chapter.
6. After the payment is completed, the Partner can check the payment result with the inquirePayment API. WorldFirst returns the Partner with information such as payment status, payment amount, payment method, and payment order ID.
7. Once WorldFirst finishes processing the payment, WorldFirst notifies the Partner with the notifyPayment API. The Partner can forward the result of the payment order to the Customer.

Step 2. Inquire about the payment result

To obtain the payment status, you can monitor the asynchronous notification or actively call the inquirePayment API to get the payment status. Although a retransmission mechanism exists for the asynchronous notification, the notification might not be received due to network issues when the user successfully completes the payment. Therefore, it is necessary to actively inquire about the payment status by using the inquirePayment API.

Usually, when you encounter one of the following cases, call the inquirePayment API:

• The Partner can inquire about the payment result 5 seconds after making a payment.
• No clear payment status can be obtained. For example, when the payment status notification is not received within 30 minutes after receiving the response to the payment request.

Step 3. Receive payment notification

WorldFirst sends the Partner the result of the payment order after processing. The payment notification is carried out with the notifyPayment API. After receiving the payment notification, you must take the corresponding action to process the payment notification.

After receiving the payment notification, you need to take the following actions:

1. Verify the signature: to check whether the payment notification is sent by WorldFirst.

The payment result notification from WorldFirst is signed by WorldFirst. It is recommended to verify the signature and check whether the notification is sent by WorldFirst. For more details, refer to the Sign a request and validate the signature chapter.

2. Return a receipt acknowledgment message: to let WorldFirst know that you have already received the notification.

After receiving the notification from WorldFirst(Alipay), the Partner needs to send WorldFirst(Alipay) a response message to acknowledge the receipt of the notification.

The Partner needs to properly sign the message before making the response. For details, refer to the Sign a request and validate the signature chapter.

The response header observes the following structure:

Sample response header:

{
"headers": {
  "Content-Type": "application/json",
  "client-id": "*****",
  "response-time": "2022-03-07T07:49:27Z",
  "signature": "algorithm=RSA256,keyVersion=1,signature=VelVji6jp8*****"
  }
}

For more details about the response message, refer to the API overview chapter.

The response body has the following fixed value:

{
  "result":{
     "resultStatus":"S",
     "resultCode":"SUCCESS",
     "resultMessage":"success"
  }
}

If the Partner does not respond to WorldFirst(Alipay) that the notification has been received successfully, WorldFirst(Alipay) will resend the result.

The following policy represents how WorldFirst(Alipay) makes retry attempts:

• WorldFirst(Alipay) retries notifications 7 times.
• Intervals between notifications: 2m, 10m, 10m, 1h, 2h, 6h, and 15h.