Payment Integration Process

Payment integration refers to the process where merchants can use the sub-contract address repeatedly within different time periods to receive payment funds for orders without being associated with specific users. The sub-contract address for payment integration can be used multiple times to receive payment funds from different orders, providing merchants with a flexible payment solution.

1. Payment Process

The sequence diagram of the payment process is as follows:

The call process is as follows:

1. The merchant system calls /payment/createPaymentOrder (Create Payment Order Interface) to initiate a payment request to Pay Protocol. Pay Protocol validates the merchant's request parameters and then returns the request address for invoking the payment page. The merchant redirects to the payment page by concatenating the domain name and request address, and the user makes the payment.
2. After the user confirms the payment, they can click the button on the page to return to the redirectionUrl (entered by the merchant) after the payment is successful.
3. After the transaction is successful, Pay Protocol returns the callback notification parameters via a POST request to notifyUrl (entered by the merchant during payment).
4. If, due to network reasons, the merchant system does not receive the callback notification, the merchant can call /payment/detail (Query Payment Order Details Interface) to query the transaction and payment information (the merchant can also directly call this query interface, without relying on the callback notification), or call /payment/notify (Initiate Acquiring Callback Notification).

warning

• Due to the unreliability of synchronous returns, the acquiring result must be based on the return of the callback notification or query interface, and cannot rely on synchronous redirection.
• After the merchant system receives the callback notification, it must verify the X-PAY-SIGN parameter in the notification request header to ensure that the payment notification is sent by Pay Protocol. Detailed verification rules can be found at Callback Notification Verification.
• After receiving the callback notification and passing the verification, please make sure to check whether the parameter values in the notification are consistent with those in the request, and handle subsequent business according to the paymentStatus parameter.

2. Refund Process

Within a certain period of time after the transaction is completed, if there is a situation where the buyer or seller needs a refund, due to the limitations of Web3 technology, the funds cannot be returned directly along the original path. Therefore, the merchant needs to conduct a transfer transaction through the background operation to ensure that the funds can safely return to the original payment address. The network fee incurred in the refund transfer is negotiated by the merchant with the user.

The interface call timing diagram of the refund process is as follows:

The call process is as follows:

1. The merchant system calls /refund/createRefundOrder (Initiate Refund Application Interface) to initiate a refund request to Pay Protocol. Pay Protocol verifies the merchant's request parameters and the order, generating a corresponding refund order.
2. After the refund order is generated, the merchant needs to approve it in the management backend and refund the user via transfer.
3. After the refund transaction is completed, Pay Protocol sends a POST request to notifyUrl (passed in by the merchant during the refund), returning the callback notification parameters.
4. If the merchant system does not receive the callback notification due to network issues, the merchant can call /refund/detail (Query Refund Order Details Interface) to query the transaction and refund information, or call /refund/notify (Initiate Refund Callback Notification).

warning

• Due to the unreliability of synchronous returns, the refund result must be based on the callback notification or the return of the query interface.
• After the merchant system receives the callback notification, it must verify the signature (verify the X-PAY-SIGN parameter in the notification request header) to ensure that the refund notification is sent by Pay Protocol. Detailed signature verification rules can be found at Callback Notification Signature.
• After receiving the callback notification and passing the signature verification, please make sure to check whether the parameter values in the notification are consistent with those in the request, and handle subsequent business according to the refundStatus parameter.

Refund Explanation

Refund method: Due to the irreversible mechanism of Web3, the merchant returns the funds to the user via transfer.

Refund cost: Due to the refund method, the merchant needs to bear the network fee consumption of the transaction. The network fee consumption has no fixed standard, and the merchant can negotiate a handling fee with the user.