Signing 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 document outlines the core endpoints, request/response formats, and example usage.
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 Agreements flow, enabling your Embedded Partner Customers to review and accept required agreements seamlessly. There are two available methods:
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:
-
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. -
Construct the redirect link to BVNK’s Agreement Page by appending the
session={reference}
andredirectUri={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 -
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 providedredirectUri
, with the session status (SIGNED
orDECLINED
) 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.
Sign agreements via API
BVNK now supports a direct API approach for signing agreements, removing the need for a user redirect.
Create Agreement Session via API
Environment | Endpoint |
---|---|
Production | POST https://api.bvnk.com/platform/v1/customers/agreement/sessions |
Sandbox | POST https://api.sandbox.bvnk.com/platform/v1/customers/agreement/sessions |
Request Body
Parameter | Type | Description | Required |
---|---|---|---|
countryCode | string | ISO country code (e.g., "US" ). | Yes |
customerType | string | INDIVIDUAL or COMPANY . | Yes |
useCase | string | Transaction type (FIAT , CRYPTO , CRYPTO_AND_FIAT ). | Yes |
Example Request
{
"countryCode": "DE",
"customerType": "Individual",
"useCase": "FIAT"
}
Response Body
Parameter | Type | Description |
---|---|---|
reference | string | Unique session identifier. |
status | string | Status (PENDING , SIGNED , DECLINED ). |
customerType | string | Type (COMPANY , Individual ). |
useCase | string | Transaction type (FIAT , CRYPTO , CRYPTO_AND_FIAT ). |
countryCode | string | Customer’s ISO country code. |
expiresOn | string | Session expiration (ISO8601 timestamp). |
agreements | array | 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.
Example Response
{
"reference": "5f74fee5-3e8e-4dcc-85cd-24b9205bb44d",
"status": "PENDING",
"customerType": "Individual",
"useCase": "FIAT",
"countryCode": "DE",
"expiresOn": "2025-05-23T15:05:20.859141Z",
"agreements": [ ... ]
}
Update Agreement Session Status
- Send
PUT /customers/agreement/sessions/{reference}
request with the session reference obtained in the previous step. - In the request, include the following Payload:
- session status (
SIGNED
orDECLINED
) - IP address
- session status (
{
"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
).
Example Verified Response
{
"reference": "5f74fee5-3e8e-4dcc-85cd-24b9205bb44d",
"status": "SIGNED",
...
}
Create a Customer
Once you've verified that the session status is SIGNED
, proceed to create your customer (business or individual):
- Include the verified
reference
obtained from the signed agreement session as thesignedAgreementSessionReference
field in yourPOST /customers
request payload. - This ensures the agreements are properly linked and recognized in your new customer creation.
Example
{
"signedAgreementSessionReference": "5f74fee5-3e8e-4dcc-85cd-24b9205bb44d",
"type": "INDIVIDUAL",
...
}
Ensure this reference matches exactly the signed agreement session you've validated to successfully finalize the onboarding process.
Key Considerations
- Store session references securely.
- Inform users clearly about the legally binding nature of agreements.
- Monitor and manage session expirations carefully.
Updated about 4 hours ago