Prepare customer agreements

• Embedded model

Customers API v2

The new customer onboarding flow is recommended for all new integrations.

If you already have an existing integration with Customers API v1, you can continue using it. BVNK will continue to support this API going forward.

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