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 customers (Embedded Partner Customers) to review and accept required agreements seamlessly. There are two available methods:
1. Signing via HostedURL (redirect)
Create a Hosted Agreement Session
- Call
POST /customers/agreement/sessions
to generate a unique signing session. - BVNK responds with a
hostedUrl
for agreement signing.
Redirect User to BVNK’s Agreement Page
- Redirect your customer to the provided
hostedUrl
, appending theredirectUri
parameter. - The user views all necessary agreements and can Submit or Cancel.
Sign Agreements
- Clicking Submit sets the session status to
SIGNED
, completing the signature process.
Completion and Return Redirect
- The user is redirected (302) back to your provided
redirectUri
. - The redirect includes the session status (
SIGNED
orDECLINED
).
Create Embedded Customer
- If the status is
SIGNED
, use thesignedAgreementSessionReference
in aPOST /customers
call to create the new Embedded Customer.
2. Signing via APIs (No Redirect)
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.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
- Call
PUT /customers/agreement/sessions/{reference}
with the session reference obtained in the previous step. - Payload to include session status (
SIGNED
orDECLINED
).
{
"status": "SIGNED"
}
- This updates the session status accordingly.
Verify Session Status
- Retrieve session status by calling
GET /customers/agreement/sessions/{reference}
with the session reference. - Response confirms current session status (
SIGNED
,PENDING
, orDECLINED
).
Example Verified Response
{
"reference": "5f74fee5-3e8e-4dcc-85cd-24b9205bb44d",
"status": "SIGNED",
...
}
Creating 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 30 days ago