Prepare customer agreements

• Embedded model

Before creating customer accounts via API, ensure your customers have accepted and signed BVNK's Terms and Conditions.

The agreements can be signed in the following ways:

• Via HostedURL
• Via API

Sign agreements via HostedURL

We recommend preparing the Agreement Page before you set up the signing procedure. The page's URL will later be used as {redirect URL}.

To sign an agreement using a HostedURL with a redirect:

1. Send a POST /customers/agreement/sessions request with the following JSON payload to create a unique Hosted Agreement signing session.

   {
       "customerType": "INDIVIDUAL",
       "countryCode": "US",
       "useCase": "STABLECOIN_PAYOUTS"
   }

   The response from BVNK includes the agreement details:

   {
    "reference": "79d697b7-489a-4a01-96a2-f7403e8c5735",
    "status": "PENDING",
    "expiresOn": "2025-12-12T14:15:10Z",
    "agreements": [...]"
   }

   The reference field is the unique customer agreement session identifier.

2. Construct the redirect link to BVNK's Agreement Page by adding session={reference} and redirectUri={redirect URL} as query parameters to the base URL.

   Environment	Example of the constructed redirect link
   Sandbox	https://signup.sandbox.bvnk.com/agreements?session={reference}&redirectUri=http://example.com/callback
   Production	https://signup.bvnk.com/agreements?session={reference}&redirectUri=http://example.com/callback

3. Redirect your customer to the constructed BVNK Agreement Page.

What happens next

• The user reviews the required agreements on the Agreement Page and can choose to Submit or Cancel.
• When the user clicks Submit, the session status updates to SIGNED, completing the signature process.
• The user is redirected via 302 to the provided redirectUri, with the session status (SIGNED or DECLINED) included as a query parameter.

Once the agreement status changes to SIGNED, send a POST /platform/v1/customers request with the included signedAgreementSessionReference from the previous step to create the Embedded customer. For the detailed instructions, see Create a customer via API.

Sign agreements via API

BVNK supports a direct API method for signing agreements, eliminating the need for user redirection.

To create an Agreement Session via API, send a POST /customers/agreement/sessions request with the following body parameters:

{
    "countryCode": "DE",
    "customerType": "INDIVIDUAL",
    "useCase": "STABLECOIN_PAYOUTS"
}

Parameter	Description	Required
countryCode	Country code of the customer's address in the ISO 3166-1 alpha-2 format, for example, "US".	✅
customerType	Type of customer. Available options: - INDIVIDUAL: A natural person. - COMPANY: A legal entity.	✅
useCase	Type of product to which the customer agreement applies. Available options: - STABLECOIN_PAYOUTS: Enables sending stablecoin payments to customers' crypto wallets from fiat or crypto balances. - EMBEDDED_STABLECOIN_WALLETS: Allows partners to create and manage stablecoin wallets for their customers to facilitate crypto transactions. - EMBEDDED_FIAT_ACCOUNTS: Enables creating virtual accounts with unique vIBANs for customers to send, hold, and receive fiat funds.	✅

The response includes the agreement session details.

{
  "reference": "5f74fee5-3e8e-4dcc-85cd-24b9205bb44d",
  "status": "PENDING",
  "customerType": "INDIVIDUAL",
  "useCase": "STABLECOIN_PAYOUTS",
  "countryCode": "DE",
  "expiresOn": "2025-05-23T15:05:20.859141Z",
  "agreements": [ ... ]
}

Parameter	Description
reference	Unique session identifier.
status	Session status. Available options: - PENDING: The session is pending and the agreements have not been signed yet. - SIGNED: The agreement has been signed by the customer. - DECLINED: The customer has declined the agreement.
customerType	Type of customer. Available options: - INDIVIDUAL: A natural person. - COMPANY: A legal entity.
useCase	Type of product to which the customer agreement applies. Available options: - STABLECOIN_PAYOUTS: Enables sending stablecoin payments to customers' crypto wallets from fiat or crypto balances. - EMBEDDED_STABLECOIN_WALLETS: Allows partners to create and manage stablecoin wallets for their customers to facilitate crypto transactions. - EMBEDDED_FIAT_ACCOUNTS: Enables creating virtual accounts with unique vIBANs for customers to send, hold, and receive fiat funds.
countryCode	Country code of the customer's address in the ISO 3166-1 alpha-2 format, for example, "US".
expiresOn	Session expiration (ISO8601 timestamp).
agreements	List of agreements for review and acceptance.

Each agreement includes:

• name: Agreement identifier.
• displayName: Public-facing title.
• description: Agreement details.
• url: URL for agreement document.
• status: Session status of the agreement signing.
• privacyPolicyName: Privacy policy title.
• privacyPolicyDescription: Privacy policy details.
• privacyPolicyUrl: URL to privacy policy.

Update agreement session status

To update the agreement session status, follow these steps:

1. Send PUT /customers/agreement/sessions/{reference} request with the session reference obtained in the previous step.
2. In the request, include the following payload:
   • session status (SIGNED or DECLINED)
   • IP address

{
    "status": "SIGNED",
    "ipAddress": "192.172.1.16"
}

The session status will update accordingly.

Verify session status

To retrieve the session status, send the GET /customers/agreement/sessions/{reference} request with the session reference.

The response confirms the current session status (SIGNED, PENDING, or DECLINED).

{
  "reference": "5f74fee5-3e8e-4dcc-85cd-24b9205bb44d",
  "status": "SIGNED",
  ...
}

Key considerations

• Store session references securely.
• Clearly inform your customers about the legally binding nature of agreements.
• Monitor and manage session expirations carefully.

important

The Customers section in Portal and API is not enabled by default when a sandbox account is created. Contact the Solutions team to configure this capability.

---

What's next?

• Create a customer