createBindingAgreementPay

Note

Please contact Zalopay Team to be granted permission to use this functionality. Currently, only support on sandbox environment

Description

The createBindingAgreementPay API is a method provided by our JS-SDK that enables merchant mini-apps to initiate a payment binding process within the Zalopay.

Create Binding Agreement Pay Sequence Diagram

Explanation of the Diagram

Actors and Participants:

• User: Initiates the Binding Agreement Pay process.
• Merchant App: The mini-app used by the merchant.
• JS-SDK: The JavaScript SDK provided by Zalopay.
• Binding Agreement Pay feature: Handles the payment binding UI and logic.
• Merchant Server: The backend server of the merchant.
• Zalopay Server: Processes payment bindings.

Sequence Steps:

1. User Interaction: The user starts the binding payment process in the merchant app.
2. Request to Merchant Server: The merchant app sends a request to the merchant server with necessary parameters.
3. Generate Transaction Details: The merchant server generates transaction details like app_trans_id, req_date, and mac.
4. Call Zalopay Server: The merchant server calls the Zalopay server's API to create a binding.
5. Process Binding Creation: The Zalopay server processes the binding creation request.
6. Receive Binding Info: The Zalopay server responds with binding information.
7. Respond to Merchant App: The merchant server sends the binding data back to the merchant app.
8. Invoke JS-SDK Method: The merchant app calls createBindingAgreementPay(bindingToken) on the JS-SDK.
9. Open Binding Agreement Pay feature: Open BottomSheetWebview with Binding Agreement Pay page
10. Communicate with Zalopay Server: The Binding Agreement Pay feature uses the bindingToken to communicate with the Zalopay server.
11. Receive Binding Status: The Zalopay server returns the binding status to the Binding Agreement Pay feature.
12. Return Status to JS-SDK: The Binding Agreement Pay feature returns the result to the JS-SDK.
13. Final Status to Merchant App: The JS-SDK provides the final status to the merchant app.

From step 1 to step 7. Please read more Create new binding for the agreement document

From step 8 to step 12, communicate between Merchant mini-app and JS-SDK via createBindingAgreementPay API

Parameters

Param	Data type	Required	Description
bindingToken	string	Yes	A unique token provided by the Merchant Server representing the payment binding session. This token is obtained after the Merchant Server successfully creates a binding request with the Payment Server. (Expire time about 15 minutes)

Return Value

Param	Data type	Description
status	string	response status success

Error Code

Error Code	Description
071001	User has canceled binding agreement pay
071002	User is not valid
071003	User has been already active
071004	Binding has expired. Please try again after 15 minutes

Sample Code and Sample Return Data

Sample Request:

window.zlpSdk.Payment.createBindingAgreementPay({
  bindingToken: "2410210YvdL6l7ENgeVUx8dO21gGRbXj",
})
  .then((response) => console.log(response))
  .catch((error) => console.error(error.errorCode));

Sample success response:

{
  "status": "success"
}

Sample error response:

{
  "status": "error",
  "errorCode": "071001",
  "errorMessage": "User has canceled binding agreement pay"
}