Prepare Customer Agreements

The BVNK Agreements API enables you to create and manage agreements between BVNK and your customers (referred to as Embedded Partner Customers). This section describes the BVNK Agreements flow, enabling your Embedded Partner Customers to review and accept required agreements seamlessly.

Before creating Embedded Partner Customers (EPC) accounts via API, ensure that your customers accept and sign the BVNK's Terms and Conditions

The agreements can be signed in the following ways:

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" : "FIAT"
    }

    In the response from BVNK, you receive the agreement details:

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

    Here, reference is the unique customer agreement session reference.

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

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

What happens next

  • The user views required agreements on the Agreement Page and can choose to Submit or Cancel.
  • After the user clicks Submit, the session status changes to SIGNED, completing the signature process.
  • The user is then 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 /customers request with the included signedAgreementSessionReference from the previous step to create the Embedded Customer. For the detailed instruction, see Create a Customer via API.

Sign agreements via API

BVNK now supports a direct API approach for signing agreements, removing the need for a user redirect.

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

{
    "countryCode": "DE",
    "customerType": "Individual",
    "useCase": "FIAT"
}
ParameterDescriptionRequired
countryCodeISO country code (e.g., "US").Yes
customerTypeINDIVIDUAL or COMPANY.Yes
useCaseTransaction type (FIAT, CRYPTO, CRYPTO_AND_FIAT).Yes

In the response, you receive the agreement session details.

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

ParameterDescription
referenceUnique session identifier.
statusStatus (PENDING, SIGNED, DECLINED).
customerTypeType (COMPANY, Individual).
useCaseTransaction type (FIAT, CRYPTO, CRYPTO_AND_FIAT).
countryCodeCustomer’s ISO country code.
expiresOnSession expiration (ISO8601 timestamp).
agreementsList 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:

  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 be updated accordingly.

Verify session status

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

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

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

Key considerations

  • Store session references securely.
  • Inform users clearly about the legally binding nature of agreements.
  • Monitor and manage session expirations carefully.

What’s Next

Once you've verified that the session status is SIGNED, proceed to create your business or individual customer.