Hosted Agreements

🚧

Early Access

Please note that this endpoint is currently in early access, and it may undergo changes as we continue to improve and refine the functionality.

This section describes the BVNK Hosted Agreements redirect flow, enabling your customers (Embedded Partner Customers) to review and accept required agreements seamlessly.

Overall Flow

Create a Hosted Agreement Session
You call POST /customers/agreement/session to generate a unique signing session. BVNK responds with a hostedUrl where your customer can sign the agreements.

Open BVNK’s Agreement Page (1st redirect)

• Your front end redirects the user to the returned hostedUrlconcantenated with redirectUri parameter.
• The user sees a public page with all of the necessary agreements and buttons to Submit or Cancel.

Sign the Agreements

• When the user clicks Submit, status session will be changed to SIGNEDautomatically. This finalises the signature of the session.

Complete the Process (2nd redirect)

• The BVNK-hosted page then issues a 302 redirect back to your redirectUri. This ensures the user is returned to your application with the updated session and status set to eitherSIGNEDor DECLINED.

Create the Embedded Customer

• Finally, if the user status session is SIGNED you include the signedAgreementSessionReference from the SIGNED session in a POST /customers call to create a new Embedded Customer.

Create a Hosted Agreement Session

Request

Request Body

Example Request

{
  "countryCode": "US"
}

Response

Example Response

{
  "reference": "92c9ae05-5b58-4b16-990a-19adfb8101cf",
  "status": "PENDING",
  "expiresOn": "2025-05-06T07:32:29.829482151Z",
  "hostedUrl": "https://signup.sandbox.bvnk.com/agreements?session=92c9ae05-5b58-4b16-990a-19adfb8101cf"
}

Key Considerations

• Ensure your frontend handles session expirations appropriately based on the expiresOn field.
• Clearly inform users that agreements are legally binding upon acceptance.
• Store the session reference securely, as it is necessary for subsequent customer creation.