{ "openapi": "3.0.3", "info": { "title": "BVNK API Endpoints", "description": "The BVNK API is designed to facilitate seamless and secure transactions including payments, channels, and digital wallet transactions.", "version": "1.0.1" }, "servers": [ { "url": "https://api.sandbox.bvnk.com", "description": "Sandbox" }, { "url": "https://api.bvnk.com", "description": "Production" } ], "paths": { "/api/currency/crypto": { "get": { "tags": [ "Currencies" ], "summary": "List crypto currencies", "description": "Retrieves a list of all cryptocurrencies available on the BVNK platform. This list represents cryptocurrencies that end users can select whilst making a payment.\n\nAlso, see [Currencies](https://docs.bvnk.com/bvnk/references/currencies/) for the comprehensive list of available currencies.", "operationId": "listCurrenciesCrypto", "parameters": [ { "$ref": "#/components/parameters/OffsetNumber" }, { "$ref": "#/components/parameters/MaxNumber" }, { "in": "query", "name": "allowDeposits", "description": "Only list currencies that allow deposits.", "schema": { "default": false, "type": "boolean" } } ], "responses": { "200": { "$ref": "#/components/responses/OKCurrencies" }, "400": { "$ref": "#/components/responses/BadRequestNoMessage" } } } }, "/api/currency/fiat": { "get": { "tags": [ "Currencies" ], "summary": "List fiat currencies", "description": "Retrieves a list of all display fiat currencies available on BVNK's Crypto Payments API.\nThis list refers to currencies merchants can display on a payment page to an end user. It does not represent the list of currencies that can be held on the platform in wallets.", "operationId": "listCurrenciesFiat", "parameters": [ { "$ref": "#/components/parameters/OffsetNumber" }, { "$ref": "#/components/parameters/MaxNumber" } ], "responses": { "200": { "$ref": "#/components/responses/OKCurrenciesFiat" }, "400": { "$ref": "#/components/responses/BadRequestNoMessage" } } } }, "/api/currency/deposit": { "get": { "tags": [ "Currencies" ], "summary": "List wallet currencies", "description": "These are the currencies that can be used to create a new wallet.", "operationId": "listCurrenciesDeposit", "parameters": [ { "$ref": "#/components/parameters/OffsetNumber" }, { "$ref": "#/components/parameters/MaxNumber" } ], "responses": { "200": { "$ref": "#/components/responses/OKCurrencies" }, "400": { "$ref": "#/components/responses/BadRequestNoMessage" } } } }, "/api/currency/convert/{fromCode}/{toCode}": { "get": { "tags": [ "Currencies" ], "summary": "Get exchange rate", "description": "Provides a last traded price from connected liquidity providers between two assets.", "operationId": "readExchangeRate", "parameters": [ { "in": "path", "name": "fromCode", "required": true, "schema": { "type": "string", "example": "ETH" }, "description": "The currency to be converted from." }, { "in": "path", "name": "toCode", "required": true, "schema": { "type": "string", "example": "BTC" }, "description": "The currency to be converted to." }, { "in": "query", "name": "amount", "required": true, "schema": { "type": "number", "minimum": 0, "example": 1 }, "description": "The amount to be converted." } ], "responses": { "200": { "$ref": "#/components/responses/OKExchange" }, "400": { "$ref": "#/components/responses/BadRequestNoMessage" } } } }, "/api/currency/values/{baseCurrency}": { "get": { "tags": [ "Currencies" ], "summary": "List exchange rates", "description": "Lists available exchange rates for a given currency.", "operationId": "listExchangeRates", "parameters": [ { "in": "path", "name": "baseCurrency", "required": true, "schema": { "type": "string", "example": "ETH" }, "description": "The currency to get exchange rates for." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BulkExchangeDto" } } } } }, "400": { "$ref": "#/components/responses/BadRequestNoMessage" } } } }, "/api/v1/merchant": { "post": { "tags": [ "Merchant IDs" ], "summary": "Create merchant ID", "description": "Generate a Merchant ID for your account to process pay-ins and pay-outs through our API.\n\nA Merchant ID is essential as it designates the account wallet where incoming pay-ins will be settled. For instance, if a Merchant ID is associated with a EUR wallet ID, any incoming USDT payment will be automatically converted to EUR and deposited in the designated EUR wallet.\n\nVice versa, any outgoing USDT payment will be automatically converted and withdrawn from the designated EUR wallet.\n\nFor further information, please visit https://docs.bvnk.com/docs/creating-your-first-merchant to learn more about creating your first Merchant ID.", "operationId": "merchantIdCreate", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "displayName": { "description": "The name of the merchant that will be displayed on the payments page.", "type": "string", "example": "Test Merchant Name" }, "webhookUrl": { "description": "The URL that will recieve the webhooks.", "type": "string", "example": "https://www.URL.com/to/send/webhooks/to" }, "wallet": { "type": "object", "properties": { "id": { "description": "The ID of the wallet to link to the merchant ID.", "type": "string", "example": "501098" } } } }, "required": [ "displayName", "wallet" ] }, "examples": { "Create Merchant ID": { "summary": "Create a new Merchant ID linked to a EUR wallet", "value": { "displayName": "Acme Corp Payments", "webhookUrl": "https://acme-corp.com/webhooks/bvnk", "wallet": { "id": "501098" } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantDto" } } } }, "400": { "$ref": "#/components/responses/BadRequestMessage" } }, "security": [ { "ApiKeyAuth": [] } ] }, "get": { "tags": [ "Merchant IDs" ], "summary": "List merchant IDs", "description": "Retrieves merchant IDs setup on your account.", "operationId": "merchantIdList", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantDto" } } } } }, "400": { "$ref": "#/components/responses/BadRequestNoMessage" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/api/v1/pay/summary": { "post": { "summary": "Create payment", "description": "Creates an incoming (type IN) or outcoming (type OUT) crypto payment.\n\nAlternatively, it creates a crypto payment that is either sent via a Customer's wallet or deposited into it. For more information, see the [Make Crypto Payments](https://docs.bvnk.com/docs/create-a-crypto-payout#/) guide.\n\nThere are two flows depending on specifying `payOutDetails`: \n\n - If you add `PayOutDetails` with all its child parameters, the payment is successfully created and the funds are sent to the specified wallet, with no further actions needed.\n\n - If not included in the request, in the response you receive `redirectUrl`. This is a link to a page, where to you can redirect your Customer so they can finalize the payment.", "operationId": "paymentCreate", "tags": [ "Crypto Payments" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayRequestDto" }, "examples": { "Pay-in (type: IN) - ETH": { "summary": "Incoming crypto payment - Ethereum", "description": "Use case: Customer pays in ETH to receive EUR in their wallet. The payment is converted automatically.", "value": { "walletId": "a:24092328494070:G5i4XZ9:1", "amount": 223.05, "expiryMinutes": 20, "currency": "EUR", "returnUrl": "https://my-shop.com/payment-complete?ref=xyz", "reference": "myUniqueRef333", "customerId": "d063635e-0f83-4e47-a1f3-fc9484df1509", "type": "IN", "payInDetails": { "currency": "ETH", "network": "ETHEREUM" }, "complianceDetails": { "requesterIpAddress": "172.16.254.1", "partyDetails": [ { "type": "BENEFICIARY", "entityType": "COMPANY", "legalName": "BVNK LTD", "relationshipType": "SELF_OWNED", "countryCode": "DE", "registrationNumber": "5493001KJTIIGC8Y1R12" } ] } } }, "Pay-in (type: IN) - USDT": { "summary": "Incoming crypto payment - USDT (Tether)", "description": "Use case: Customer pays in USDT (ERC20) to receive USD. Stablecoin payment for e-commerce.", "value": { "walletId": "a:24092328494070:G5i4XZ9:1", "amount": 1000, "expiryMinutes": 30, "currency": "USD", "returnUrl": "https://my-shop.com/payment-complete?ref=usdt-payment", "reference": "USDT-PAYIN-001", "customerId": "d063635e-0f83-4e47-a1f3-fc9484df1509", "type": "IN", "currencyOptions": [ { "code": "USDT", "protocols": [ "ERC20", "TRC20" ] } ], "payInDetails": { "currency": "USDT", "network": "ETHEREUM" }, "complianceDetails": { "requesterIpAddress": "192.168.1.100", "partyDetails": [ { "type": "BENEFICIARY", "entityType": "INDIVIDUAL", "firstName": "John", "lastName": "Doe", "relationshipType": "THIRD_PARTY", "countryCode": "US" } ] } } }, "Pay-in (type: IN)": { "summary": "Incoming crypto payment", "value": { "walletId": "a:24092328494070:G5i4XZ9:1", "amount": 223.05, "expiryMinutes": 20, "currency": "EUR", "returnUrl": "https://my-shop.com/payment-complete?ref=xyz", "reference": "myUniqueRef333", "customerId": "d063635e-0f83-4e47-a1f3-fc9484df1509", "type": "IN", "payInDetails": { "currency": "ETH", "network": "ETHEREUM" }, "complianceDetails": { "requesterIpAddress": "172.16.254.1", "partyDetails": [ { "type": "BENEFICIARY", "entityType": "COMPANY", "legalName": "BVNK LTD", "relationshipType": "SELF_OWNED", "countryCode": "DE", "registrationNumber": "5493001KJTIIGC8Y1R12" } ] } } }, "Payout (type: OUT) - ETH": { "summary": "Outgoing crypto payment - Ethereum", "description": "Use case: Send ETH from EUR wallet to external Ethereum address. Two-step confirmation enabled for security.", "value": { "walletId": "a:24092328494070:G5i4XZ9:1", "amount": 223.05, "currency": "EUR", "returnUrl": "https://my-shop.com/payment-complete?ref=xyz", "reference": "myUniqueRef333", "customerId": "d063635e-0f83-4e47-a1f3-fc9484df1509", "type": "OUT", "twoStep": true, "payOutDetails": { "code": "crypto", "currency": "ETH", "address": "0xb794f5ea0ba39494ce839613fffba74279579268", "tag": "", "network": "ETHEREUM" }, "complianceDetails": { "requesterIpAddress": "172.16.254.1", "partyDetails": [ { "type": "BENEFICIARY", "entityType": "COMPANY", "legalName": "BVNK LTD", "relationshipType": "SELF_OWNED", "countryCode": "DE", "registrationNumber": "5493001KJTIIGC8Y1R12" } ] }, "embeddedCustomerDetails": { "reference": "07357926-aed0-44e1-a75b-7505557ee137" } } }, "Payout (type: OUT) - BTC": { "summary": "Outgoing crypto payment - Bitcoin", "description": "Use case: Send Bitcoin from USD wallet to external Bitcoin address. Direct payout without two-step.", "value": { "walletId": "a:24092328494070:G5i4XZ9:1", "amount": 500, "currency": "USD", "returnUrl": "https://my-shop.com/payout-complete?ref=btc-payout", "reference": "BTC-PAYOUT-001", "customerId": "d063635e-0f83-4e47-a1f3-fc9484df1509", "type": "OUT", "twoStep": false, "payOutDetails": { "code": "crypto", "currency": "BTC", "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa", "tag": "", "network": "BITCOIN" }, "complianceDetails": { "requesterIpAddress": "192.168.1.100", "partyDetails": [ { "type": "BENEFICIARY", "entityType": "INDIVIDUAL", "firstName": "Jane", "lastName": "Smith", "relationshipType": "THIRD_PARTY", "countryCode": "DE" } ] } } }, "Payout (type: OUT)": { "summary": "Outgoing crypto payment", "value": { "walletId": "a:24092328494070:G5i4XZ9:1", "amount": 223.05, "currency": "EUR", "returnUrl": "https://my-shop.com/payment-complete?ref=xyz", "reference": "myUniqueRef333", "customerId": "d063635e-0f83-4e47-a1f3-fc9484df1509", "type": "OUT", "twoStep": true, "payOutDetails": { "code": "crypto", "currency": "ETH", "address": "0xb794f5ea0ba39494ce839613fffba74279579268", "tag": "", "network": "ETHEREUM" }, "complianceDetails": { "requesterIpAddress": "172.16.254.1", "partyDetails": [ { "type": "BENEFICIARY", "entityType": "COMPANY", "legalName": "BVNK LTD", "relationshipType": "SELF_OWNED", "countryCode": "DE", "registrationNumber": "5493001KJTIIGC8Y1R12" } ] }, "embeddedCustomerDetails": { "reference": "07357926-aed0-44e1-a75b-7505557ee137" } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SummaryPaymentDto" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Insufficient funds": { "summary": "Insufficient funds error", "value": { "requestId": "fd3b64b97db85a7ebab39d5a1fb20867", "errorList": [ { "requestId": null, "code": "MER-PAY-2012", "parameter": "amount", "message": "insufficient funds" } ] } } } } } }, "500": { "$ref": "#/components/responses/UnexpectedErrorMessage" } }, "security": [ { "Hawk": [ "merchant" ] } ] }, "get": { "summary": "List payments", "description": "Retrieves a list of payments on a specific Wallet ID.", "tags": [ "Crypto Payments" ], "operationId": "paymentList", "parameters": [ { "in": "query", "name": "walletId", "required": false, "schema": { "type": "string" }, "description": "Unique identifier of the wallet associated with the payment.", "example": "acc:23040543559277:x8rvQ:0" }, { "in": "query", "name": "customerReference", "schema": { "type": "string" }, "description": "**DEPRECATED: will be removed soon**. The customer reference.", "example": "REF1234" }, { "in": "query", "name": "paymentExternalId", "schema": { "type": "string", "format": "uuid", "maxLength": 36 }, "description": "**DEPRECATED: will be removed soon**. The merchant payment uuid.", "example": "5C8D8D78-366A-4AFB-B658-A64CE543C5DB" }, { "in": "query", "name": "uuid", "schema": { "type": "string", "format": "uuid", "maxLength": 36 }, "description": "Unique identifier for the payment.", "example": "3A6FAFFA-F21D-416E-B17E-2529A9BC44A0" }, { "in": "query", "name": "reference", "schema": { "type": "string" }, "description": "Custom payment reference ID to link the payment to your customer.", "example": "REF767913" }, { "$ref": "#/components/parameters/FromDate" }, { "$ref": "#/components/parameters/ToDate" }, { "$ref": "#/components/parameters/OffsetNumber" }, { "$ref": "#/components/parameters/MaxNumber" }, { "in": "query", "name": "status", "schema": { "$ref": "#/components/schemas/PaymentStatusDto" } }, { "$ref": "#/components/parameters/Order" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SummaryPaymentDto" } } } } }, "400": { "$ref": "#/components/responses/BadRequestMessage" }, "500": { "$ref": "#/components/responses/UnexpectedErrorMessage" } }, "security": [ { "Hawk": [ "merchant" ] } ] } }, "/api/v1/pay/{uuid}/update/summary": { "put": { "summary": "Update payment", "description": "Updates a pending payment with currency or payout information.", "operationId": "paymentUpdate", "tags": [ "Crypto Payments" ], "parameters": [ { "in": "path", "required": true, "name": "uuid", "schema": { "type": "string", "example": "5C8D8D78-366A-4AFB-B658-A64CE543C5DB" }, "description": "The payment UUID." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "currency": { "type": "string", "example": "ETH" }, "payOutInstruction": { "$ref": "#/components/schemas/PayOutDetailDto" } } }, "examples": { "Update Payment": { "summary": "Update payment currency and payout address", "value": { "currency": "ETH", "payOutInstruction": { "code": "crypto", "currency": "ETH", "address": "0xb794f5ea0ba39494ce839613fffba74279579268", "network": "ETHEREUM" } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SummaryPaymentDto" } } } }, "400": { "$ref": "#/components/responses/BadRequestMessage" }, "500": { "$ref": "#/components/responses/UnexpectedErrorMessage" } }, "security": [ { "Hawk": [ "merchant" ] } ] } }, "/api/v1/pay/{uuid}/accept/summary": { "put": { "summary": "Accept payment", "description": "Accepts a pending payment with currency or payout information.", "operationId": "paymentAccept", "tags": [ "Crypto Payments" ], "parameters": [ { "in": "path", "required": true, "name": "uuid", "schema": { "type": "string", "example": "5C8D8D78-366A-4AFB-B658-A64CE543C5DB" }, "description": "The payment UUID." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SummaryPaymentDto" } } } }, "400": { "$ref": "#/components/responses/BadRequestMessage" }, "500": { "$ref": "#/components/responses/UnexpectedErrorMessage" } }, "security": [ { "Hawk": [ "merchant" ] } ] } }, "/api/v1/pay/{uuid}/confirm/summary": { "put": { "summary": "Confirm payment", "description": "Confirms a two-step payout.", "operationId": "paymentConfirm", "tags": [ "Crypto Payments" ], "parameters": [ { "in": "path", "required": true, "name": "uuid", "schema": { "type": "string", "example": "5C8D8D78-366A-4AFB-B658-A64CE543C5DB" }, "description": "The payment UUID received from [Accept an Estimate Payout](https://docs.bvnk.com/reference/payestimateaccept#/)." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConfirmPaymentRequestDto" }, "examples": { "Individual Beneficiary": { "summary": "Confirm payout with individual compliance details", "value": { "complianceDetails": { "requesterIpAddress": "172.16.254.1", "partyDetails": [ { "type": "BENEFICIARY", "entityType": "INDIVIDUAL", "firstName": "Jane", "lastName": "Smith", "dateOfBirth": "1990-03-15", "relationshipType": "THIRD_PARTY", "countryCode": "DE" } ] } } }, "Company Beneficiary": { "summary": "Confirm payout with company compliance details", "value": { "complianceDetails": { "requesterIpAddress": "172.16.254.1", "partyDetails": [ { "type": "BENEFICIARY", "entityType": "COMPANY", "legalName": "Globex Corporation", "relationshipType": "THIRD_PARTY", "registrationNumber": "12345678", "countryCode": "DE" } ] } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SummaryPaymentDto" } } } }, "400": { "$ref": "#/components/responses/BadRequestMessage" }, "500": { "$ref": "#/components/responses/UnexpectedErrorMessage" } }, "security": [ { "Hawk": [ "merchant" ] } ] } }, "/api/v1/pay/{uuid}/summary": { "get": { "summary": "Get payment", "description": "Retrieves details of a specific payment using the UUID of the payment.", "tags": [ "Crypto Payments" ], "operationId": "paymentRead", "parameters": [ { "in": "path", "required": true, "name": "uuid", "schema": { "type": "string", "example": "5C8D8D78-366A-4AFB-B658-A64CE543C5DB" }, "description": "The payment UUID." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SummaryPaymentDto" } } } }, "400": { "$ref": "#/components/responses/BadRequestMessage" }, "500": { "$ref": "#/components/responses/UnexpectedErrorMessage" } }, "security": [ { "Hawk": [ "merchant" ] } ] } }, "/api/v1/pay/validate": { "put": { "summary": "Validate address", "description": "Validates that a crypto address is correct.\n\nUse this endpoint to validate that an address exists, is correctly formatted, and includes all the required data. This endpoint can help prevent your end users losing funds when submitting a payout.", "tags": [ "Crypto Payments" ], "operationId": "paymentOutValidate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayOutDetailDto" }, "examples": { "Validate ETH Address": { "summary": "Validate an Ethereum wallet address", "value": { "code": "crypto", "currency": "ETH", "address": "0xb794f5ea0ba39494ce839613fffba74279579268", "network": "ETHEREUM" } } } } } }, "responses": { "200": { "description": "OK" }, "400": { "$ref": "#/components/responses/BadRequestMessage" }, "500": { "$ref": "#/components/responses/UnexpectedErrorMessage" } } } }, "/api/v1/pay/estimate": { "post": { "summary": "Create an estimate payout", "description": "Retrieves latest exchange rates, fees and network costs for a crypto payout without creating an actual payout. Provide either `walletRequiredAmount` (amount to send) or `paidRequiredAmount` (amount the recipient should receive). See the [Estimate Crypto Payouts](https://docs.bvnk.com/docs/estimate-crypto-payouts#/) guide for details.", "externalDocs": { "description": "Guide: Estimate Crypto Payouts", "url": "https://docs.bvnk.com/bvnk/use-cases/stablecoin-payments-for-platforms/pay-out-to-your-users#integrate-advanced-payout-capabilities" }, "tags": [ "Crypto Payments" ], "operationId": "payEstimate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEstimateRequestDto" }, "examples": { "Estimate": { "summary": "Sample estimate request", "value": { "walletId": "a:24072237783989:Unkx9kW:1", "walletCurrency": "USD", "paidRequiredAmount": 15, "paidCurrency": "USDT", "reference": "REF46730", "network": "ETHEREUM", "complianceDetails": { "requesterIpAddress": "172.16.254.1", "partyDetails": [] } } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EstimatePayoutResponseDto" }, "examples": { "success": { "summary": "Sample estimate response", "value": { "externalId": "4f7768e5-cd82-42c4-80d6-18d84a5b3832", "accountId": "4ea1277f-29d7-11ed-84d9-0a878439b77f", "walletId": "0da83d78-5c84-475f-a657-9b8b329e9491", "customerReference": "REF46730", "walletCurrency": "USD", "walletRequiredAmount": 15.79, "paidCurrency": "USDT", "paidRequiredAmount": 15, "feeCurrency": "USD", "feePredictedAmount": 0.16, "networkFeeCurrency": "USD", "networkFeePredictedAmount": 1.62, "totalWalletAmount": 15.95, "exchangeRate": 0.949715, "customerId": null, "paymentExternalId": null, "network": "ETHEREUM" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestMessage" }, "500": { "$ref": "#/components/responses/UnexpectedErrorMessage" } }, "security": [ { "Hawk": [ "merchant" ] } ] } }, "/api/v1/pay/estimate/{externalId}/update": { "put": { "summary": "Update an existing estimate payout", "description": "Refreshes the quote using the latest exchange rates and fees. Call periodically (e.g., every 30 seconds) with either `walletRequiredAmount` or `paidRequiredAmount` to recalculate the other.", "tags": [ "Crypto Payments" ], "operationId": "payEstimateUpdate", "parameters": [ { "in": "path", "name": "externalId", "required": true, "description": "The ID of the estimate payout.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEstimateRequestDto" }, "examples": { "updateByPaid": { "summary": "Refresh by desired paid amount", "value": { "paidRequiredAmount": 15, "reference": "REF46730-updated-1" } }, "updateByWallet": { "summary": "Refresh by wallet spend", "value": { "walletRequiredAmount": 15.79, "reference": "REF46730-updated-2" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EstimatePayoutResponseDto" } } } }, "400": { "$ref": "#/components/responses/BadRequestMessage" }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerErrorDto" } } } }, "500": { "$ref": "#/components/responses/UnexpectedErrorMessage" } }, "security": [ { "Hawk": [ "merchant" ] } ] } }, "/api/v1/pay/estimate/{externalId}/accept": { "post": { "summary": "Accept an estimated payout", "description": "Accepts the current estimate and converts it into a pending crypto payment.", "tags": [ "Crypto Payments" ], "operationId": "payEstimateAccept", "parameters": [ { "in": "path", "name": "externalId", "required": true, "description": "The ID of the estimate payout to accept.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptEstimateRequestDto" }, "examples": { "Individual Beneficiary": { "summary": "Accept estimate with individual compliance details", "value": { "customerId": "9e9bb7cb-f5d4-4f7b-bada-6ad156f3a8d8", "payOutDetails": { "currency": "ETH", "address": "0xb794f5ea0ba39494ce839613fffba74279579268", "network": "ETHEREUM" }, "complianceDetails": { "requesterIpAddress": "172.16.254.1", "partyDetails": [ { "type": "BENEFICIARY", "entityType": "INDIVIDUAL", "firstName": "Jane", "lastName": "Smith", "dateOfBirth": "1990-03-15", "relationshipType": "THIRD_PARTY", "countryCode": "DE" } ] } } }, "Company Beneficiary": { "summary": "Accept estimate with company compliance details", "value": { "customerId": "9e9bb7cb-f5d4-4f7b-bada-6ad156f3a8d8", "payOutDetails": { "currency": "ETH", "address": "0xb794f5ea0ba39494ce839613fffba74279579268", "network": "ETHEREUM" }, "complianceDetails": { "requesterIpAddress": "172.16.254.1", "partyDetails": [ { "type": "BENEFICIARY", "entityType": "COMPANY", "legalName": "Globex Corporation", "relationshipType": "THIRD_PARTY", "registrationNumber": "12345678", "countryCode": "DE" } ] } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SummaryPaymentDto" } } } }, "400": { "$ref": "#/components/responses/BadRequestMessage" }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerErrorDto" } } } }, "500": { "$ref": "#/components/responses/UnexpectedErrorMessage" } }, "security": [ { "Hawk": [ "merchant" ] } ] } }, "/compliance/v1/information-requests/{externalId}/actions": { "post": { "summary": "Submit originator data for Travel rule information request", "description": "Submits originator information for a crypto payment held under the Travel Rule, identified by the information request `externalId`. Use this endpoint to assign an originator (contact) to payments that appear in the **Missing Contacts** queue of the Portal.\n\nThe payment can be a direct crypto deposit, a channel transaction, or a crypto payment (MPS), as identified in the corresponding [`bvnk:compliance:v1:information-request` webhook](/bvnk/api-explorer/bvnk-webhooks/compliance-information-request).\n\n:::warning Entity-specific requirements\nThe contact service currently has different `externalId` requirements depending on the entity type:\n- `INDIVIDUAL`: `externalId` is **required**.\n- `COMPANY`: `externalId` is **optional**.\n:::", "tags": [ "Crypto Payments" ], "operationId": "complianceInformationRequestAction", "parameters": [ { "in": "path", "name": "externalId", "required": true, "description": "The ID of the information request to act on. Use the `data.id` value from the `bvnk:compliance:v1:information-request` webhook.", "schema": { "type": "string", "format": "uuid", "example": "bd51c10c-fff8-4d38-a6ef-411371238caa" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InformationRequestActionDto" }, "examples": { "Company Originator": { "summary": "Provide information - Company originator", "value": { "type": "PROVIDE_INFORMATION", "entity": { "contactId": null, "customerId": null, "relationshipType": "THIRD_PARTY", "type": "COMPANY", "legalName": "LuchinPaulTest", "registrationNumber": "123321" } } }, "Individual Originator": { "summary": "Provide information - Individual originator", "value": { "type": "PROVIDE_INFORMATION", "entity": { "contactId": null, "customerId": null, "type": "INDIVIDUAL", "externalId": "bd51c10c-fff8-4d38-a6ef-411371238caa", "firstName": "John", "lastName": "Doe", "dateOfBirth": "08-11-1998", "relationshipType": "THIRD_PARTY", "address": { "addressLine1": "10 Woodpecker", "addressLine2": "Turf", "city": "Cape Town", "region": "Western Cape", "postCode": "1234", "country": "ZA" } } } } } } } }, "responses": { "200": { "description": "Information accepted; the held payment will resume processing." }, "400": { "$ref": "#/components/responses/BadRequestMessage" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/UnexpectedErrorMessage" } }, "security": [ { "Hawk": [ "merchant" ] } ] } }, "/api/v2/channel": { "post": { "tags": [ "Crypto Channels" ], "summary": "Create channel", "description": "Creates a channel through which your customers can send crypto payments.", "operationId": "channelCreate", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantChannelRequestDto" }, "examples": { "Create Channel": { "summary": "Create an ETH payment channel", "value": { "walletId": "a:24092328494070:G5i4XZ9:1", "payCurrency": "ETH", "displayCurrency": "EUR", "reference": "c1b933d5-3354-4f83-a05f-0b53f1be85f2", "customerId": "d063635e-0f83-4e47-a1f3-fc9484df1509", "complianceDetails": { "requesterIpAddress": "172.16.254.1", "partyDetails": [ { "entityType": "INDIVIDUAL", "type": "BENEFICIARY", "firstName": "John", "lastName": "Doe", "dateOfBirth": "1984-06-30", "relationshipType": "THIRD_PARTY", "countryCode": "DE" } ] } } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantChannelDto" } } } }, "400": { "$ref": "#/components/responses/BadRequestMessage" }, "500": { "$ref": "#/components/responses/UnexpectedErrorMessage" } }, "security": [ { "Hawk": [ "merchant" ] } ] }, "get": { "tags": [ "Crypto Channels" ], "summary": "List channels", "description": "Retrieves all channels related to a Wallet ID.", "operationId": "channelList", "parameters": [ { "name": "walletId", "required": true, "in": "query", "schema": { "type": "string", "example": "a:24092328494070:G5i4XZ9:1" }, "description": "The merchant ID that the channels belong to" }, { "$ref": "#/components/parameters/OffsetString" }, { "$ref": "#/components/parameters/MaxString" }, { "name": "q", "in": "query", "description": "Use it to query channel based on the reference provided during creation. Can be UUID of the payment, reference, channel UUID, transaction hash, or wallet code.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantChannelDto" } } } } }, "400": { "$ref": "#/components/responses/BadRequestMessage" }, "500": { "$ref": "#/components/responses/UnexpectedErrorMessage" } }, "security": [ { "Hawk": [ "merchant" ] } ] } }, "/api/v2/channel/{uuid}": { "get": { "tags": [ "Crypto Channels" ], "summary": "Get channel", "description": "Retrieves a specific channel by its UUID.", "operationId": "channelRead", "parameters": [ { "name": "uuid", "in": "path", "description": "The UUID of the channel you are querying", "required": true, "schema": { "type": "string", "example": "9d1f67f2-a647-404b-9b02-247c77be81d0" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantChannelDto" } } } }, "404": { "description": "Not Found" } }, "security": [ { "Hawk": [ "merchant" ] } ] } }, "/api/v2/channel/{uuid}/spot": { "get": { "tags": [ "Crypto Channels" ], "summary": "Get channel spot rate", "description": "Poll the current spot rate for a channel. Use this endpoint if you are building your own UI and need to display the live conversion rate to customers.", "operationId": "channelSpotRate", "parameters": [ { "name": "uuid", "in": "path", "description": "The UUID of the channel you are querying", "required": true, "schema": { "type": "string", "example": "9d1f67f2-a647-404b-9b02-247c77be81d0" } } ], "responses": { "200": { "description": "OK" }, "404": { "description": "Not Found" } }, "security": [ { "Hawk": [ "merchant" ] } ] } }, "/api/v2/channel/payment/{uuid}": { "get": { "tags": [ "Crypto Channels" ], "summary": "Get channel payment", "description": "Retrieves a specific payment made into a channel.", "operationId": "channelPaymentRead", "parameters": [ { "name": "uuid", "in": "path", "description": "The UUID of the payment you are querying.", "required": true, "schema": { "type": "string", "example": "c0dc9c14-0312-4a6b-a1a3-a6dcebdcc8a4" } } ], "responses": { "200": { "description": "200", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantChannelPaymentDto" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientValidationErrorDto" } } } }, "404": { "description": "Not Found" } }, "security": [ { "Hawk": [ "merchant" ] } ] } }, "/api/v2/channel/payment": { "get": { "tags": [ "Crypto Channels" ], "summary": "List channel payments", "description": "Retrieves a list of payments to a channel on a specific Wallet ID.", "operationId": "channelPaymentList", "parameters": [ { "name": "walletId", "in": "query", "required": true, "description": "Unique identifier of the wallet associated with the transaction.", "schema": { "type": "string", "example": "a:24092328494070:G5i4XZ9:1" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "description": "The status of the channel payment.", "example": "COMPLETE", "enum": [ "DETECTED", "COMPLETE", "HELD", "CANCELLED" ] } }, { "$ref": "#/components/parameters/FromDate" }, { "$ref": "#/components/parameters/ToDate" }, { "$ref": "#/components/parameters/OffsetString" }, { "$ref": "#/components/parameters/MaxString" }, { "name": "q", "in": "query", "description": "Use it to query channel based on the reference provided during creation. Can be UUID of the payment, reference, channel UUID, transaction hash, or wallet code.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantChannelPaymentDto" } } } } } }, "security": [ { "Hawk": [ "merchant" ] } ] } }, "/payment/v1/rules": { "post": { "summary": "Create on-ramp payment rule", "description": "Creates a rule that links a crypto wallet to a fiat virtual account to automatically handle on-ramp (fiat → crypto) flow. The `trigger` field defines the flow to activate:\n\n - `payment:payin:fiat` — on-ramp\n\nFor more information, see the [Automate Fiat-to-Crypto Transfers](https://docs.bvnk.com/docs/automate-fiat-to-crypto-transfers#/) guide.", "tags": [ "Fiat Payments" ], "operationId": "paymentRuleCreate", "externalDocs": { "description": "Automate Fiat-to-Crypto Transfers", "url": "https://docs.bvnk.com/bvnk/use-cases/on-off-ramp/automate-fiat-to-crypto-transfers" }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Details required to link the crypto wallet and define the automated action.", "properties": { "reference": { "type": "string", "description": "Unique identifier of the transaction.", "example": "REF558628" }, "trigger": { "type": "string", "description": "Originating event that triggers the automated action. Use `payment:payin:fiat` for on-ramp fiat → crypto.", "example": "payment:payin:fiat" }, "walletId": { "type": "string", "description": "BVNK wallet ID for the wallet from/to which funds will be sent.", "example": "a:24122329329347:HsdJVhW:1" }, "fees": { "type": "object", "description": "Use to charge a fee from your end customer.", "properties": { "customerFee": { "$ref": "#/components/schemas/MoneyFeeV2" } } }, "beneficiary": { "type": "object", "description": "Details about the recipient of the crypto funds.", "properties": { "currency": { "type": "string", "description": "The cryptocurrency being sent (e.g., USDT, BTC, ETH).", "example": "USDT" }, "entity": { "oneOf": [ { "$ref": "#/components/schemas/PaymentRuleIndividual" }, { "$ref": "#/components/schemas/PaymentRuleCompany" } ], "discriminator": { "propertyName": "type", "mapping": { "INDIVIDUAL": "#/components/schemas/PaymentRuleIndividual", "COMPANY": "#/components/schemas/PaymentRuleCompany" } } }, "cryptoAddress": { "$ref": "#/components/schemas/PaymentRuleCryptoAddress" } } } }, "required": [ "reference", "trigger", "walletId", "beneficiary" ] }, "examples": { "Company beneficiary": { "summary": "Example POST request | Company beneficiary", "value": { "reference": "REF558628", "trigger": "event:payment:payin", "walletId": "a:24122329329347:HsdJVhW:1", "fees": { "customerFee": { "amount": 0.5, "currency": "USD" } }, "beneficiary": { "currency": "USDT", "entity": { "customerIdentifier": "9401203948572394595", "legalName": "3Com", "type": "COMPANY", "relationshipType": "SELF_OWNED", "registrationNumber": "ABC21D21FZC", "address": { "addressLine1": "123 Main St", "addressLine2": "Suite 200", "city": "New York", "stateCode": "NY", "postalCode": "10001", "countryCode": "US" } }, "cryptoAddress": { "network": "ETHEREUM", "address": "0x12323542636474747", "tag": "332455" } } } }, "Individual beneficiary": { "summary": "Example POST request | Individual beneficiary", "value": { "reference": "REF7558628", "walletId": "a:25031027518203:IUMTTAY:1", "trigger": "event:payment:fiat:payin", "fees": { "customerFee": { "amount": 1, "currency": "USD" } }, "beneficiary": { "entity": { "type": "INDIVIDUAL", "customerIdentifier": "9401203948572394595", "firstName": "John", "lastName": "Doe", "dateOfBirth": "1990-05-15", "relationshipType": "SELF_OWNED", "address": { "addressLine1": "Mainzer Landstraße 50", "addressLine2": "Level 5", "city": "Frankfurt am Main", "postalCode": "60325", "countryCode": "DE" } }, "cryptoAddress": { "network": "ETHEREUM", "address": "0xDDCD0Aa2C21d2d02ec0977565D037aBC67F7F151" } } } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the payment rule. You can use this value to update the rule via [`/payment/v1/rules/{id}](https://docs.bvnk.com/reference/paymentruleupdate#/).", "example": "98c0bb03-567f-11f0-b26e-6b1848874a27" }, "reference": { "type": "string", "example": "REF558628" }, "trigger": { "type": "string", "example": "event:payment:payin" }, "status": { "type": "string", "example": "ACTIVE" }, "fees": { "type": "object", "properties": { "customerFee": { "type": "object", "properties": { "amount": { "type": "number", "example": 0.5 }, "currency": { "type": "string", "example": "USD" } } } } }, "originator": { "type": "object", "properties": { "currency": { "type": "string", "example": "USD" }, "walletId": { "type": "string", "example": "acc:22041242429000:3MPpU:0" } } }, "beneficiary": { "type": "object", "properties": { "currency": { "type": "string", "example": "USDT" }, "entity": { "type": "object", "properties": { "legalName": { "type": "string", "example": "3Com" }, "type": { "type": "string", "example": "COMPANY" }, "relationshipType": { "type": "string", "example": "SELF_OWNED" }, "registrationNumber": { "type": "string", "example": "ABC21D21FZC" }, "address": { "type": "object", "properties": { "addressLine1": { "type": "string", "example": "123 Main St" }, "addressLine2": { "type": "string", "example": "Some address Line 2" }, "city": { "type": "string", "example": "New York" }, "region": { "type": "string", "example": "NY" }, "postCode": { "type": "string", "example": "10001" }, "country": { "type": "string", "example": "US" } } } } }, "cryptoAddresses": { "type": "object", "properties": { "network": { "type": "string", "example": "ETHEREUM" }, "addresses": { "type": "array", "items": { "type": "string" }, "example": [ "0x12323542636474747" ] }, "tag": { "type": "string", "example": "332455" } } } } }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2025-07-01T13:31:02.52Z" }, "createdAt": { "type": "string", "format": "date-time", "example": "2025-07-01T13:30:02.52Z" } } }, "examples": { "success": { "summary": "Example API Response (Success)", "value": { "id": "98c0bb03-567f-11f0-b26e-6b1848874a27", "reference": "REF558628", "trigger": "event:payment:payin", "status": "ACTIVE", "fees": { "customerFee": { "amount": 0.5, "currency": "USD" } }, "originator": { "currency": "USD", "walletId": "acc:22041242429000:3MPpU:0" }, "beneficiary": { "currency": "USDT", "entity": { "legalName": "3Com", "type": "COMPANY", "relationshipType": "SELF_OWNED", "registrationNumber": "ABC21D21FZC", "address": { "addressLine1": "Some address Line 1", "addressLine2": "Some address Line 2", "city": "Some city", "region": "Some region", "postCode": "ABCDEF", "country": "US" } }, "cryptoAddresses": { "network": "ETHEREUM", "addresses": [ "0x12323542636474747" ], "tag": "332455" } }, "metadata": {}, "updatedAt": "2025-07-01T13:31:02.52Z", "createdAt": "2025-07-01T13:30:02.52Z" } } } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "badRequest": { "summary": "See the BVNK Errors reference for details.", "value": { "code": "bvnk:ledger:4001", "status": "Bad Request", "traceId": "abc123-def456-ghi789", "message": "Received Bad Request", "details": { "documentLink": "https://docs.bvnk.com/reference/errors#/" } } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthorized": { "summary": "See the BVNK Errors reference for details.", "value": { "code": "BVNK-4003", "status": "401", "message": "Unauthorized.", "details": { "documentLink": "https://docs.bvnk.com/reference/errors#/" } } } } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "forbidden": { "summary": "See the BVNK Errors reference for details.", "value": { "code": "bvnk:ledger:4003", "status": "Forbidden", "traceId": "abc123-def456-ghi789", "message": "FORBIDDEN! You don't have the necessary permissions to access this resource.", "details": { "documentLink": "https://docs.bvnk.com/reference/errors#/" } } } } } } } }, "security": [ { "BearerAuth": [] } ] }, "get": { "summary": "List payment rules", "description": "Retrieves a list of all payment rules configured for your account.", "tags": [ "Fiat Payments" ], "operationId": "paymentRuleList", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentRuleResponse" } }, "examples": { "success": { "summary": "Example API Response (Success)", "value": [ { "id": "98c0bb03-567f-11f0-b26e-6b1848874a27", "reference": "REF558628", "trigger": "event:payment:payin", "status": "ACTIVE", "fees": { "customerFee": { "amount": 0.5, "currency": "USD" } }, "originator": { "currency": "USD", "walletId": "acc:22041242429000:3MPpU:0" }, "beneficiary": { "currency": "USDT", "entity": { "legalName": "3Com", "type": "COMPANY", "relationshipType": "SELF_OWNED", "registrationNumber": "ABC21D21FZC", "address": { "addressLine1": "123 Main St", "addressLine2": "Suite 200", "city": "New York", "region": "NY", "postCode": "10001", "country": "US" } }, "cryptoAddresses": { "network": "ETHEREUM", "addresses": [ "0x12323542636474747" ], "tag": "332455" } }, "metadata": {}, "updatedAt": "2025-07-01T13:31:02.52Z", "createdAt": "2025-07-01T13:30:02.52Z" }, { "id": "a1b2c3d4-5678-90ef-ghij-klmnopqrstuv", "reference": "REF7558628", "trigger": "payment:payin:fiat", "status": "ACTIVE", "fees": { "customerFee": { "amount": 1, "currency": "USD" } }, "originator": { "currency": "EUR", "walletId": "a:25031027518203:IUMTTAY:1" }, "beneficiary": { "currency": "USDT", "entity": { "type": "INDIVIDUAL", "customerIdentifier": "9401203948572394595", "firstName": "John", "lastName": "Doe", "dateOfBirth": "1990-05-15", "relationshipType": "SELF_OWNED", "address": { "addressLine1": "456 Business Park", "addressLine2": "Level 5", "city": "Dublin", "region": "Dublin", "postCode": "D02 XY45", "country": "IE" } }, "cryptoAddresses": { "network": "ETHEREUM", "addresses": [ "0xDDCD0Aa2C21d2d02ec0977565D037aBC67F7F151" ] } }, "metadata": {}, "updatedAt": "2025-07-15T10:20:30.45Z", "createdAt": "2025-07-15T10:15:20.30Z" } ] } } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "badRequest": { "summary": "See the BVNK Errors reference for details.", "value": { "code": "bvnk:ledger:4001", "status": "Bad Request", "traceId": "abc123-def456-ghi789", "message": "Received Bad Request", "details": { "documentLink": "https://docs.bvnk.com/reference/errors#/" } } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthorized": { "summary": "See the BVNK Errors reference for details.", "value": { "code": "BVNK-4003", "status": "401", "message": "Unauthorized.", "details": { "documentLink": "https://docs.bvnk.com/reference/errors#/" } } } } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "forbidden": { "summary": "See the BVNK Errors reference for details.", "value": { "code": "bvnk:ledger:4003", "status": "Forbidden", "traceId": "abc123-def456-ghi789", "message": "FORBIDDEN! You don't have the necessary permissions to access this resource.", "details": { "documentLink": "https://docs.bvnk.com/reference/errors#/" } } } } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/payment/v1/rules/{walletId}": { "get": { "summary": "List payment rules by wallet", "description": "Retrieves a list of payment rules applied to a specific wallet by its ID.", "tags": [ "Fiat Payments" ], "operationId": "paymentRuleListByWallet", "parameters": [ { "name": "walletId", "in": "path", "required": true, "description": "BVNK wallet ID to filter payment rules.", "schema": { "type": "string", "example": "acc:22041242429000:3MPpU:0" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentRuleResponse" } }, "examples": { "success": { "summary": "Example API Response (Success)", "value": [ { "id": "98c0bb03-567f-11f0-b26e-6b1848874a27", "reference": "REF558628", "trigger": "event:payment:payin", "status": "ACTIVE", "fees": { "customerFee": { "amount": 0.5, "currency": "USD" } }, "originator": { "currency": "USD", "walletId": "acc:22041242429000:3MPpU:0" }, "beneficiary": { "currency": "USDT", "entity": { "legalName": "3Com", "type": "COMPANY", "relationshipType": "SELF_OWNED", "registrationNumber": "ABC21D21FZC", "address": { "addressLine1": "123 Main St", "addressLine2": "Suite 200", "city": "New York", "region": "NY", "postCode": "10001", "country": "US" } }, "cryptoAddresses": { "network": "ETHEREUM", "addresses": [ "0x12323542636474747" ], "tag": "332455" } }, "metadata": {}, "updatedAt": "2025-07-01T13:31:02.52Z", "createdAt": "2025-07-01T13:30:02.52Z" } ] } } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "badRequest": { "summary": "See the BVNK Errors reference for details.", "value": { "code": "bvnk:ledger:4001", "status": "Bad Request", "traceId": "abc123-def456-ghi789", "message": "Received Bad Request", "details": { "documentLink": "https://docs.bvnk.com/reference/errors#/" } } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthorized": { "summary": "See the BVNK Errors reference for details.", "value": { "code": "BVNK-4003", "status": "401", "message": "Unauthorized.", "details": { "documentLink": "https://docs.bvnk.com/reference/errors#/" } } } } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "forbidden": { "summary": "See the BVNK Errors reference for details.", "value": { "code": "bvnk:ledger:4003", "status": "Forbidden", "traceId": "abc123-def456-ghi789", "message": "FORBIDDEN! You don't have the necessary permissions to access this resource.", "details": { "documentLink": "https://docs.bvnk.com/reference/errors#/" } } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/payment/v1/rules/{id}": { "patch": { "summary": "Update payment rule", "description": "Partially updates a previously created payment rule. Only properties included in the request are updated; omitted fields remain unchanged. Setting a nullable property to null clears it.", "tags": [ "Fiat Payments" ], "operationId": "paymentRuleUpdate", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID of the wallet configuration or rule to update. You can get this value from the `id` field of the [`/payment/v1/rules`](https://docs.bvnk.com/reference/paymentrulecreate#/) response.", "schema": { "type": "string", "format": "uuid", "example": "98c0bb03-567f-11f0-b26e-6b1848874a27" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Any subset of updatable fields may be provided.", "properties": { "fees": { "type": "object", "description": "Use to charge a fee from your end customer.", "properties": { "customerFee": { "$ref": "#/components/schemas/MoneyFeeV2" } } }, "beneficiary": { "type": "object", "description": "Details about the recipient of the crypto funds.", "properties": { "currency": { "type": "string", "description": "The cryptocurrency being sent.", "example": "USDT" }, "entity": { "anyOf": [ { "$ref": "#/components/schemas/PaymentRuleIndividualUpdate" }, { "$ref": "#/components/schemas/PaymentRuleCompanyUpdate" } ], "discriminator": { "propertyName": "type", "mapping": { "INDIVIDUAL": "#/components/schemas/PaymentRuleIndividualUpdate", "COMPANY": "#/components/schemas/PaymentRuleCompanyUpdate" } } }, "cryptoAddress": { "$ref": "#/components/schemas/PaymentRuleCryptoAddressUpdate" } } } } }, "examples": { "Update Fees": { "value": { "fees": { "customerFee": { "amount": 3.5, "currency": "USD" } } } }, "Change Company Name": { "value": { "beneficiary": { "entity": { "type": "COMPANY", "legalName": "Updated Test Company" } } } }, "Change Crypto Address": { "value": { "beneficiary": { "cryptoAddress": { "address": "0x742d35cc6634C0532925a3b844Bc9e7595f0bEA5", "network": "ETHEREUM", "tag": "ETTTT" } } } } } } } }, "responses": { "200": { "description": "Rule updated.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad request." }, "401": { "description": "Unauthorized." }, "403": { "description": "Forbidden." } }, "security": [ { "BearerAuth": [] } ] } }, "/payment/v1/rules/{id}/actions": { "post": { "summary": "Activate or deactivate payment rule", "description": "Activates or deactivates a payment rule. If you linked a rule to an incorrect wallet, you can deactivate it. Deactivated rules will not trigger automated actions but remain in your account for reference.", "tags": [ "Fiat Payments" ], "operationId": "paymentRuleAction", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "ID of the payment rule to activate or deactivate. You can get this value from the `id` field of the [`/payment/v1/rules`](https://docs.bvnk.com/reference/paymentrulecreate#/) response.", "schema": { "type": "string", "format": "uuid", "example": "98c0bb03-567f-11f0-b26e-6b1848874a27" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRuleActionRequest" }, "examples": { "Activate Rule": { "summary": "Activate a payment rule", "value": { "type": "ACTIVATE" } }, "Deactivate Rule": { "summary": "Deactivate a payment rule", "value": { "type": "DEACTIVATE" } } } } } }, "responses": { "204": { "description": "204 No Content" }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "badRequest": { "summary": "See the BVNK Errors reference for details.", "value": { "code": "bvnk:ledger:4001", "status": "Bad Request", "traceId": "abc123-def456-ghi789", "message": "Received Bad Request", "details": { "documentLink": "https://docs.bvnk.com/reference/errors#/" } } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthorized": { "summary": "See the BVNK Errors reference for details.", "value": { "code": "BVNK-4003", "status": "401", "message": "Unauthorized.", "details": { "documentLink": "https://docs.bvnk.com/reference/errors#/" } } } } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "forbidden": { "summary": "See the BVNK Errors reference for details.", "value": { "code": "bvnk:ledger:4003", "status": "Forbidden", "traceId": "abc123-def456-ghi789", "message": "FORBIDDEN! You don't have the necessary permissions to access this resource.", "details": { "documentLink": "https://docs.bvnk.com/reference/errors#/" } } } } } } }, "404": { "description": "Rule not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "BearerAuth": [] } ] } }, "/payment/v2/payouts": { "post": { "summary": "Initiate payout (v.2)", "description": "Creates a payout to business or individual customers.\n\nIn case of payment in Euro, the transaction is subject to **Verification of Payee** (VoP): if the beneficiary's name in the request doesn't match the name in the beneficiary's bank account, the status 202 Verification Failed is returned. To proceed with the payment, you must [Confirm Beneficiary's name](https://docs.bvnk.com/reference/payoutconfirmbeneficiaryv2#/). For the details, refer to the [Initiate Payouts (v.2)](https://docs.bvnk.com/docs/initiate-payment-2#/) guide.\n\nWe recommend sending as much beneficiary and bank information as you can. Complete details help correspondent banks and payment networks process the payout and reduce the risk of delays or rejections.", "tags": [ "Fiat Payments" ], "operationId": "payoutCreateV2", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyNew" }, { "name": "X-Verification-Id", "in": "header", "description": "Optional. Verification ID acquired from the beneficiary verification request via [`POST /platform/v1/beneficiaries/verification`](https://docs.bvnk.com/reference/verifybeneficiary). Include this header to use a previously verified beneficiary for the payout.\n\nWhen using this header, you can skip further confirmation of the beneficiary's name as BVNK already attempted to verify it.\n\nIf you don't add the header, you may need to [confirm the name](https://docs.bvnk.com/reference/payoutconfirmbeneficiaryv2#/).", "required": false, "schema": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutRequest" }, "examples": { "PayoutRequest - Individual Beneficiary": { "summary": "Individual beneficiary", "value": { "walletId": "a:25030543848767:1f8xnw3:1", "amount": 1000.5, "currency": "USD", "reference": "PAYOUT-2024-001", "method": "ACH", "beneficiary": { "remittanceInformation": "Payment for services", "entity": { "type": "INDIVIDUAL", "firstName": "John", "lastName": "Doe", "dateOfBirth": "15-01-1990", "relationshipType": "THIRD_PARTY", "address": { "addressLine1": "321 Side St", "city": "New York", "region": "NY", "postCode": "10001", "country": "US" } }, "bankAccount": { "accountNumber": "900012647634", "accountType": "CHECKING", "bank": { "identificationCode": "ATFEUS33", "nid": "021000021", "address": { "addressLine1": "123 Main St", "addressLine2": "Apt 4B", "city": "New York", "region": "NY", "postCode": "10001", "country": "US" } } } }, "metadata": { "source": "api", "memberId": "987654321" } } }, "PayoutRequest - Company Beneficiary": { "summary": "Company beneficiary", "value": { "walletId": "a:25030544959877:1f8xnw3:2", "amount": 5000, "currency": "EUR", "reference": "CORPORATE-PAYOUT-001", "method": "SEPA_CT", "beneficiary": { "remittanceInformation": "Invoice payment #INV-2024-001", "entity": { "type": "COMPANY", "legalName": "Acme Corporation Ltd", "relationshipType": "THIRD_PARTY", "address": { "addressLine1": "456 Business Park", "addressLine2": "Suite 100", "city": "Dublin", "region": "Leinster", "postCode": "D02 XY45", "country": "IE" } }, "bankAccount": { "accountNumber": "IE29 AIBK 9311 5212 3456 78", "accountType": "CHECKING", "bank": { "identificationCode": "AIBKIE2D", "address": { "addressLine1": "Connell Str. 15", "city": "Dublin", "country": "IE", "postCode": "D01 XK83" } } } }, "metadata": { "source": "api", "memberId": "987654321" } } } } } } }, "responses": { "201": { "description": "Payment accepted for processing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutResponse" }, "examples": { "PayoutResponse - Individual Beneficiary": { "summary": "Individual beneficiary", "value": { "id": "550e8400-e29b-41d4-a716-446655440000", "method": "BANK_TRANSFER", "reference": "PAYOUT-2024-001", "status": "PROCESSING", "type": "payment:payout:fiat", "direction": "OUT", "fees": { "customerFee": { "amount": 5, "currency": "USD" }, "processingFee": { "amount": 10, "currency": "USD" } }, "originator": { "amount": 1000.5, "currency": "USD", "walletId": "wallet-123", "customerId": "d063635e-0f83-4e47-a1f3-fc9484df1509", "entity": { "type": "COMPANY", "legalName": "3Com" } }, "beneficiary": { "remittanceInformation": "Payment for services", "amount": 995.5, "currency": "USD", "entity": { "type": "INDIVIDUAL", "firstName": "John", "lastName": "Doe", "relationshipType": "THIRD_PARTY" }, "bankAccount": { "accountNumber": "123456789", "bank": { "identificationCode": "ATFEUS33" } } }, "createdAt": "2024-01-15T10:30:00Z", "updatedAt": "2024-01-15T10:35:00Z", "metadata": { "source": "api", "merchantId": "merchant-123" }, "requestDetails": { "originator": { "ipAddress": "10.0.0.2" } } } }, "PayoutResponse - Company Beneficiary": { "summary": "Company beneficiary", "value": { "id": "660f9511-f30c-52e5-b827-557766551111", "method": "SEPA", "reference": "CORPORATE-PAYOUT-001", "status": "COMPLETED", "type": "payment:payout:fiat", "direction": "OUT", "fees": { "customerFee": { "amount": 15, "currency": "EUR" }, "processingFee": { "amount": 10, "currency": "EUR" } }, "originator": { "amount": 5000, "currency": "EUR", "walletId": "wallet-456", "customerId": "d063635e-0f83-4e47-a1f3-fc9484df1509", "entity": { "type": "COMPANY", "legalName": "3Com" } }, "beneficiary": { "remittanceInformation": "Invoice payment #INV-2024-001", "amount": 4985, "currency": "EUR", "entity": { "type": "COMPANY", "legalName": "Acme Corporation Ltd", "relationshipType": "THIRD_PARTY" }, "bankAccount": { "accountNumber": "IE29 AIBK 9311 5212 3456 78", "bank": { "identificationCode": "AIBKIE2D" } } }, "createdAt": "2024-01-15T09:00:00Z", "updatedAt": "2024-01-15T11:30:00Z", "metadata": { "source": "api" } } } } } } }, "202": { "description": "Confirmation required.", "content": { "application/json": { "schema": { "type": "object", "properties": { "Id": { "type": "string", "description": "Payout transaction identifier.", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "status": { "type": "string", "description": "Verification result status.", "enum": [ "PAYEE_VERIFICATION_REQUIRED" ] }, "requiredAction": { "type": "string", "description": "Action required to proceed with the payout.", "enum": [ "CONFIRM_BENEFICIARY" ] }, "verificationResult": { "type": "object", "properties": { "matchStatus": { "type": "string", "description": "Status of the name verification:\n\n- `PARTIAL_MATCH`: The name provided is similar but not exactly the same as the name of the beneficiary associated with the bank account.\n\n- `NO_MATCH`: The name provided does not match the name registered for this IBAN.\n\n- `NOT_POSSIBLE`: Payee verification is not available for this transfer, so we cannot confirm the recipient's details. Ensure all account information is correct before submitting the payment.\n\n- `TECHNICAL_ERROR`: The name verification is not possible due to technical reasons, such as temporary technical errors, or timeouts.", "enum": [ "PARTIAL_MATCH", "NO_MATCH", "NOT_POSSIBLE", "TECHNICAL_ERROR" ], "example": "MATCH" }, "actualName": { "type": "string", "description": " Name associated with the beneficiary's account.", "example": "George D. Collins" }, "providedName": { "type": "string", "description": "Name provided by the merchant. Only shown for `\"matchStatus\": \"PARTIAL_MATCH\"`.", "example": "George Colins" } } } }, "required": [ "Id", "status", "verificationResult", "requiredAction" ] }, "examples": { "PAYEE_VERIFICATION_REQUIRED": { "summary": "Verification failed. Partial match.", "value": { "Id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "requiredAction": "CONFIRM_BENEFICIARY", "status": "PAYEE_VERIFICATION_REQUIRED", "verificationResult": { "matchStatus": "PARTIAL_MATCH", "actualName": "George D. Collins", "providedName": "George Colins" } } }, "PAYEE_VERIFICATION_FAILED_TECHNICAL_ERROR": { "summary": "Verification failed. Technical error.", "value": { "Id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "requiredAction": "CONFIRM_BENEFICIARY", "status": "PAYEE_VERIFICATION_REQUIRED", "verificationResult": { "matchStatus": "TECHNICAL_ERROR", "providedName": "George Colins" } } }, "PAYEE_VERIFICATION_FAILED_NO_MATCH": { "summary": "Verification failed. No match.", "value": { "Id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "requiredAction": "CONFIRM_BENEFICIARY", "status": "PAYEE_VERIFICATION_REQUIRED", "verificationResult": { "matchStatus": "NO_MATCH", "providedName": "George Colins" } } }, "PAYEE_VERIFICATION_FAILED_NOT_POSSIBLE": { "summary": "Verification failed. Not possible.", "value": { "Id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "requiredAction": "CONFIRM_BENEFICIARY", "status": "PAYEE_VERIFICATION_REQUIRED", "verificationResult": { "matchStatus": "NOT_POSSIBLE", "providedName": "George Colins" } } } } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "BVNK error code." }, "traceId": { "type": "string", "description": "Unique identifier of the request for troubleshooting." }, "status": { "type": "string", "description": "Error status." }, "message": { "type": "string", "description": "Human-readable error message." }, "details": { "type": "object", "nullable": true, "description": "Additional error details.", "properties": { "documentLink": { "type": "string", "format": "uri", "description": "Link to error documentation." }, "errors": { "type": "object", "description": "Map of field names to lists of validation error messages.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } } }, "required": [ "code", "status", "message" ] }, "examples": { "walletNotFound": { "summary": "Wallet not found", "value": { "code": "bvnk:payment:0001", "traceId": "a57cfbc0399c5352debed39d67f9c3b5", "status": "Bad Request", "message": "Could not find wallet with id: a:26050638813890:hQzofm5:1", "details": null } }, "invalidCurrencyCode": { "summary": "Invalid currency code", "value": { "code": "bvnk:payment:0001", "traceId": "3ded33b6531c0a92dc1624d44c4c829c", "status": "Bad Request", "message": "Invalid currency code: EU.", "details": null } }, "beneficiaryValidationFailed": { "summary": "Beneficiary details validation failed", "value": { "code": "bvnk:payment:0005", "traceId": "98b3055e9287110c4cbb631eb60c946c", "status": "Bad Request", "message": "Beneficiary details validation failed", "details": { "documentLink": "https://docs.bvnk.com/reference/errors", "errors": { "requestBody": [ "Invalid transferDestination" ] } } } }, "currencyMismatch": { "summary": "Wallet, payout, and beneficiary currency mismatch", "value": { "code": "bvnk:payment:0001", "traceId": "cb69d1b95956ca95e72317c1db17de66", "status": "Bad Request", "message": "Wallet currency Euro, payout currency Pound Sterling and beneficiary currency Euro do not match", "details": null } }, "idempotencyConflict": { "summary": "Duplicate idempotency key", "value": { "code": "bvnk:payment:0006", "traceId": "ba50b81ac339a867966a8bc2707d91ae", "status": "Bad Request", "message": "Payout <1e30951c-3d90-449d-b783-a18b09c18ad7> with the idempotency key <24235a08-1628-4db0-afe3-c51849857bf6> already exists", "details": { "documentLink": "https://docs.bvnk.com/reference/errors", "errors": { "requestHeader": [ "24235a08-1628-4db0-afe3-c51849857bf6" ] } } } }, "capabilityNotEnabled": { "summary": "Capability not enabled for account", "value": { "code": "bvnk:payment:0009", "traceId": "d02dbd75ffcde80afea339def6c853aa", "status": "Bad Request", "message": "Customer fee is not enabled for this account.", "details": null } }, "disabledVirtualAccount": { "summary": "Virtual account disabled", "value": { "code": "bvnk:payment:0010", "traceId": "2fd62d450c6ca4dce48f6d568365af2f", "status": "Bad Request", "message": "Corresponding Virtual Account has been disabled for walletId: a:26050638813890:hQzofm5:1", "details": null } }, "invalidMoneyPrecision": { "summary": "Amount precision exceeds currency limit", "value": { "code": "bvnk:payment:0001", "traceId": "4cfb21b5753fc58a1f82a232d2089682", "status": "Bad Request", "message": "The currency GBP allows up to 2 decimal places, but 3 were provided.", "details": null } }, "validationFailed": { "summary": "Request validation failed", "value": { "code": "bvnk:payment:0001", "traceId": "3b98269ae2a84593be6f326744f03b87", "status": "Bad Request", "message": "Customer fee cannot be set for non-underlying customer payout requests.", "details": null } }, "dynamicValidationFailed": { "summary": "Dynamic request validation failed", "value": { "code": "bvnk:payment:0001", "traceId": "d401c901cfef7d526bb6ea80a3f070ee", "status": "Bad Request", "message": "Invalid request content", "details": { "documentLink": "https://docs.bvnk.com/reference/errors", "errors": { "field1": [ "error1", "error2" ], "field2": [ "error3" ] } } } } } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "BVNK error code." }, "traceId": { "type": "string", "description": "Unique identifier of the request for troubleshooting." }, "status": { "type": "string", "description": "Error status." }, "message": { "type": "string", "description": "Human-readable error message." }, "details": { "type": "object", "nullable": true, "description": "Additional error details." } }, "required": [ "code", "status", "message" ] }, "examples": { "merchantOwnershipMismatch": { "summary": "Merchant ID does not belong to the caller's account", "value": { "code": "bvnk:payment:0003", "traceId": "c2f9dda555a05198d741aac54b61d370", "status": "Forbidden", "message": "Provided merchantId does not belong to your account: 06338094-e387-4431-9cb5-55fd92bcab2f", "details": null } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "BVNK error code." }, "traceId": { "type": "string", "description": "Unique identifier of the request for troubleshooting." }, "status": { "type": "string", "description": "Error status." }, "message": { "type": "string", "description": "Human-readable error message." }, "details": { "type": "object", "nullable": true, "description": "Additional error details." } }, "required": [ "code", "status", "message" ] }, "examples": { "beneficiaryNotFound": { "summary": "Beneficiary not found", "value": { "code": "bvnk:payment:0004", "traceId": "4dea3a8aebf5fca5469dd6a4a2dd2bd8", "status": "Not Found", "message": "Beneficiary with reference 'some-reference' was not found", "details": null } } } } } }, "422": { "description": "Unprocessable entity.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "BVNK error code." }, "traceId": { "type": "string", "description": "Unique identifier of the request for troubleshooting." }, "status": { "type": "string", "description": "Error status." }, "message": { "type": "string", "description": "Human-readable error message." }, "details": { "type": "object", "nullable": true, "description": "Additional error details.", "properties": { "documentLink": { "type": "string", "format": "uri", "description": "Link to error documentation." }, "errors": { "type": "object", "description": "Map of field names to lists of validation error messages.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } } }, "required": [ "code", "status", "message" ] }, "examples": { "insufficientWalletBalance": { "summary": "Payout amount exceeds wallet balance", "value": { "code": "bvnk:payment:0007", "traceId": "b5fa1a218de63002f3e62920812b1305", "status": "Unprocessable Entity", "message": "Payout amount should be less than available wallet balance: 200", "details": { "documentLink": "https://docs.bvnk.com/reference/errors", "errors": {} } } }, "walletLimitExceeded": { "summary": "Wallet transaction limit exceeded", "value": { "code": "bvnk:payment:0063", "traceId": "eff5b4d970432d42f30c1e5299cca3da", "status": "Unprocessable Entity", "message": "Limit exceeded. We cannot satisfy this 200 EUR payment as transaction which you are trying to trigger is violating configured limits.", "details": { "documentLink": "https://docs.bvnk.com/reference/errors", "errors": { "totalAmount": [ "200" ] } } } }, "paymentMethodNotSupported": { "summary": "Payment method not supported for beneficiary", "value": { "code": "bvnk:payment:0008", "traceId": "d9a85dc2daa440c4ad04c03d82fb447f", "status": "Unprocessable Entity", "message": "Payment method CHAPS is not supported for a given beneficiary", "details": null } }, "currencyNotSupported": { "summary": "Currency not supported for payment", "value": { "code": "bvnk:payment:0013", "traceId": "2807fd4f9a3f9edb1c186c8b01d0ae73", "status": "Unprocessable Entity", "message": "Currency GBP is not supported for payment", "details": null } }, "processingProfileNotAssigned": { "summary": "Wallet has no processing profile assigned", "value": { "code": "bvnk:payment:0053", "traceId": "34d7955665f0a5e390eb75007c64edd3", "status": "Unprocessable Entity", "message": "Invalid wallet configuration. Please contact support for help", "details": null } }, "paymentMethodNotProvided": { "summary": "Payment method missing from request", "value": { "code": "bvnk:payment:0001", "traceId": "e825c1bcf2d5a6ea91036fae7f69cfcb", "status": "Unprocessable Entity", "message": "Payment method must be provided.", "details": null } } } } } } }, "security": [ { "Hawk": [ "withdrawal", "otc" ] } ] } }, "/payment/v2/payouts/{transactionId}": { "get": { "summary": "Retrieve payout (v.2)", "description": "Retrieves a specific payout. You can also use this endpoint to check the status of the crypto or fiat payout.", "tags": [ "Fiat Payments" ], "operationId": "payoutGetV2", "parameters": [ { "name": "transactionId", "in": "path", "required": true, "description": "The transaction ID of the payout that you want to retrieve.", "schema": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" } } ], "responses": { "200": { "description": "Payout retrieved successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutResponse" }, "examples": { "Fiat Payout - Individual Beneficiary": { "summary": "Fiat payout with individual beneficiary", "value": { "id": "550e8400-e29b-41d4-a716-446655440000", "method": "SEPA_CT", "reference": "PAYOUT-2024-001", "status": "PROCESSING", "type": "payment:payout:fiat", "direction": "OUT", "fees": { "customerFee": { "amount": 5, "currency": "EUR" }, "processingFee": { "amount": 10, "currency": "EUR" } }, "originator": { "amount": 1000.5, "currency": "EUR", "walletId": "wallet-123", "customerId": "d063635e-0f83-4e47-a1f3-fc9484df1509" }, "beneficiary": { "remittanceInformation": "Payment for services", "amount": 985.5, "currency": "EUR", "entity": { "type": "INDIVIDUAL", "firstName": "John", "lastName": "Doe", "relationshipType": "THIRD_PARTY" }, "bankAccount": { "accountNumber": "IE29 AIBK 9311 5212 3456 78", "accountType": "CHECKING", "bank": { "identificationCode": "AIBKIE2D", "country": "IE" } } }, "createdAt": "2024-01-15T10:30:00Z", "updatedAt": "2024-01-15T10:35:00Z", "metadata": { "source": "api", "merchantId": "merchant-123" } } }, "Crypto Payout": { "summary": "Crypto payout", "value": { "id": "660f9511-f30c-52e5-b827-557766551111", "method": "BOOK", "reference": "CRYPTO-PAYOUT-001", "status": "COMPLETED", "type": "payment:payout:fiat", "direction": "OUT", "fees": { "customerFee": { "amount": 0.001, "currency": "BTC" }, "processingFee": { "amount": 0.0005, "currency": "BTC" } }, "originator": { "amount": 0.1, "currency": "BTC", "walletId": "wallet-456", "customerId": "d063635e-0f83-4e47-a1f3-fc9484df1509" }, "beneficiary": { "remittanceInformation": "Crypto payment for services", "amount": 0.0985, "currency": "BTC", "entity": { "type": "INDIVIDUAL", "firstName": "Jane", "lastName": "Smith", "relationshipType": "SELF_OWNED" } }, "createdAt": "2024-01-15T09:00:00Z", "updatedAt": "2024-01-15T11:30:00Z", "metadata": { "source": "api", "merchantId": "merchant-123" } } } } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "security": [ { "Hawk": [ "withdrawal", "otc" ] } ] } }, "/payment/v2/payouts/{transactionId}/proof-of-payment": { "get": { "summary": "Get proof of payment in PDF", "description": "Retrieves a Proof of Payment PDF report for a fiat wallet payout. The proof of payment is available only for completed fiat payouts.", "tags": [ "Fiat Payments" ], "operationId": "payoutGetProofOfPaymentV2", "parameters": [ { "name": "transactionId", "in": "path", "required": true, "description": "The transaction ID of the payout for which to retrieve the proof of payment.", "schema": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000" } } ], "responses": { "200": { "description": "Proof of Payment PDF retrieved successfully.\n\n**Note**: The response returns a byte array. Ensure your client library supports handling binary/byte array responses.", "headers": { "Content-Type": { "description": "The media type of the response body.", "schema": { "type": "string", "example": "application/pdf" } }, "Content-Disposition": { "description": "Indicates that the response should be downloaded as an attachment with the specified filename.", "schema": { "type": "string", "example": "attachment; filename=\"019c70ce-71a3-75a4-950b-3c2d59ace333.pdf\"" } } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthorized": { "summary": "See the BVNK Errors reference for details.", "value": { "code": "BVNK-4001", "status": "401", "message": "Unauthorized.", "details": { "documentLink": "https://docs.bvnk.com/reference/errors#/" } } } } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "forbidden": { "summary": "See the BVNK Errors reference for details.", "value": { "code": "bvnk:ledger:4003", "status": "Forbidden", "traceId": "abc123-def456-ghi789", "message": "FORBIDDEN! You don't have the necessary permissions to access this resource.", "details": { "documentLink": "https://docs.bvnk.com/reference/errors#/" } } } } } } }, "404": { "description": "TransactionId not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "Hawk": [ "withdrawal", "otc" ] } ] } }, "/payment/v2/payouts/{Id}/actions": { "post": { "summary": "Confirm beneficiary's name", "description": "Confirms a payout when the beneficiary name check returns a mismatch warning. If not confirmed within five minutes, the action expires. In this case, make a new payout.", "tags": [ "Fiat Payments" ], "operationId": "payoutConfirmBeneficiaryV2", "parameters": [ { "name": "Id", "in": "path", "required": true, "description": "The payout transaction identifier returned by [`POST /payment/v2/payouts`](https://docs.bvnk.com/reference/payoutcreatev2).", "schema": { "type": "string", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutActionConfirmRequest" }, "examples": { "Confirm beneficiary": { "value": { "type": "CONFIRM_BENEFICIARY" } } } } } }, "responses": { "200": { "description": "Confirmation accepted; returns standard payout details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutResponse" } } } }, "400": { "description": "Bad request (e.g., expired confirmation window)." }, "404": { "description": "Transaction not found." } }, "security": [ { "Hawk": [ "withdrawal", "otc" ] } ] } }, "/platform/v1/beneficiaries/verification": { "post": { "summary": "Verify beneficiary's name", "description": "Verifies the beneficiary's name. You can call this endpoint before creating a payout via [`POST /payment/v2/payouts`](https://docs.bvnk.com/reference/payoutcreatev2#/) to verify the beneficiary's name and receive a verification ID that can be used in subsequent payout requests.\n\nWhen using this endpoint, make sure you specify the same beneficiary's names as you will use in the payload of the [Initiate Payout](https://docs.bvnk.com/reference/payoutcreatev2#/) request.", "operationId": "verifyBeneficiary", "tags": [ "Fiat Payments" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "title": "Individual Beneficiary", "required": [ "accountNumber", "bankCode", "firstName", "lastName", "currency" ], "properties": { "accountNumber": { "type": "string", "description": "Beneficiary's bank account number in the IBAN format.", "example": "GB29MDTR60000131926819" }, "bankCode": { "type": "string", "description": "Beneficiary's bank code (BIC/SWIFT code).", "example": "MDTRGB2L" }, "firstName": { "type": "string", "description": "Beneficiary's first name.", "example": "John" }, "lastName": { "type": "string", "description": "Beneficiary's last name.", "example": "Smith" }, "currency": { "type": "string", "description": "Currency of the beneficiary's bank account.", "enum": [ "USD", "EUR", "GBP" ], "example": "EUR" } } }, { "type": "object", "title": "Company Beneficiary", "required": [ "accountNumber", "bankCode", "businessName", "currency" ], "properties": { "accountNumber": { "type": "string", "description": "Beneficiary's bank account number (IBAN format).", "example": "GB29MDTR60000131926819" }, "bankCode": { "type": "string", "description": "Beneficiary's bank code (BIC/SWIFT code).", "example": "MDTRGB2L" }, "businessName": { "type": "string", "description": "Beneficiary's business name.", "example": "Acme Corporation Ltd" }, "currency": { "type": "string", "description": "The currency of the beneficiary's bank account.", "enum": [ "USD", "EUR", "GBP" ], "example": "EUR" } } } ] }, "examples": { "individual": { "summary": "Individual Beneficiary Verification", "value": { "accountNumber": "GB29MDTR60000131926819", "bankCode": "MDTRGB2L", "firstName": "John", "lastName": "Smith", "currency": "EUR" } }, "company": { "summary": "Company Beneficiary Verification", "value": { "accountNumber": "GB29MDTR60000131926819", "bankCode": "MDTRGB2L", "businessName": "Acme Corporation Ltd", "currency": "EUR" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "matchStatus", "providedName", "validUntil" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique verification ID that can be used in the `X-Verification-Id` header of subsequent [Initiate Payout](https://docs.bvnk.com/reference/payoutcreatev2#/) requests.", "example": "550e8400-e29b-41d4-a716-446655440000" }, "matchStatus": { "type": "string", "description": "Status of the name verification:\n\n- `MATCH`: The name provided matches the name of the beneficiary associated with the bank account.\n\n- `PARTIAL_MATCH`: The name provided is similar but not exactly the same as the name of the beneficiary associated with the bank account.\n\n- `NO_MATCH`: The name provided does not match the name registered for the bank account.\n\n- `NOT_REQUIRED`: The name verification is not required for the provided currency.\n\n- `NOT_POSSIBLE`: Payee verification is not available for this transfer, so we cannot confirm the recipient's details. Ensure all account information is correct before submitting the payment.\n\n- `TECHNICAL_ERROR`: The name verification is not possible due to technical reasons, such as temporary technical errors, or timeouts.", "enum": [ "MATCH", "PARTIAL_MATCH", "NO_MATCH", "NOT_REQUIRED", "NOT_POSSIBLE", "TECHNICAL_ERROR" ], "example": "MATCH" }, "providedName": { "type": "string", "description": "Name provided in the verification request.", "example": "John Smith" }, "actualName": { "type": "string", "description": "Actual name on the bank account. Only present for partial match status.", "example": "J. Smith" }, "validUntil": { "type": "string", "format": "date-time", "description": "Time when the verification request expires. By default, five minutes from creation.", "example": "2025-01-15T14:30:00Z" } } }, "examples": { "match": { "summary": "Name Match", "value": { "id": "550e8400-e29b-41d4-a716-446655440000", "matchStatus": "MATCH", "providedName": "John Smith", "validUntil": "2025-01-15T14:30:00Z" } }, "partial_match": { "summary": "Partial Name Match", "value": { "id": "550e8400-e29b-41d4-a716-446655440001", "matchStatus": "PARTIAL_MATCH", "providedName": "John Smith", "actualName": "J. Smith", "validUntil": "2025-01-15T14:30:00Z" } } } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Unauthorized - Invalid authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "Hawk": [ "merchant" ] } ] } }, "/payment/v1/payouts/{transactionReference}": { "get": { "tags": [ "Fiat Payments" ], "summary": "Get payout", "description": "Retrieves a specific payout.\n\nYou can also use this endpoint to check the status of the crypto or fiat payout.\n\n**Note**: The PENDING_APPROVAL status is only relevant for **fiat payouts**.", "deprecated": true, "x-deprecated-description": "This endpoint is deprecated. Please use the `GET /payment/v2/payouts/:transactionId` endpoint instead.", "operationId": "payoutRead", "parameters": [ { "name": "transactionReference", "in": "path", "description": "The transaction reference of the payout that you want to retrieve.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "5dc4e061-31c6-4b96-8c4d-0ea984aece0b" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnifiedPayoutResponse" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "example1": { "summary": "Payout Not Found", "value": { "code": "BVNK-5002", "status": "404", "message": "Could not find payout with transactionReference=5dc4e061-31c6-4b96-8c4d-0ea984aece0b" } } } } } } }, "security": [ { "Hawk": [ "merchant" ] } ] } }, "/payment/v1/payins/{transactionReference}/refund/estimate": { "post": { "tags": [ "Fiat Payments" ], "summary": "Estimate refund fee", "description": "Returns the estimated processing fee and the maximum remaining refundable balance for the pay-in. The fee will be deducted from your wallet when issuing a refund. The fee amount may vary depending on the merchant contract with BVNK.", "operationId": "estimateRefundFee", "externalDocs": { "description": "Guide: Estimate refund fee", "url": "https://docs.bvnk.com/bvnk/use-cases/virtual-accounts/refund-payments#estimate-refund" }, "security": [ { "Hawk": [ "merchant" ] } ], "parameters": [ { "name": "transactionReference", "in": "path", "required": true, "description": "Unique reference (UUID) of the pay-in you plan to refund.", "schema": { "type": "string", "format": "uuid", "example": "023e5e53-6f50-4af5-a7e4-c9f15d493f90" } } ], "requestBody": { "required": true, "description": "JSON payload describing the amount you wish to refund.", "content": { "application/json": { "schema": { "type": "object", "properties": { "value": { "description": "Amount in major currency units that will be refunded. Use dot as decimal separator.", "type": "number", "example": 150.5 }, "currency": { "description": "Three-letter ISO-4217 currency code.", "type": "string", "enum": [ "GBP", "USD", "EUR" ], "example": "EUR" } }, "required": [ "value", "currency" ] }, "examples": { "estimateRequest": { "summary": "Example estimate request", "value": { "value": 150.5, "currency": "EUR" } } } } } }, "responses": { "200": { "description": "Fee estimate returned successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "fee": { "type": "object", "description": "Projected fee for processing the refund", "properties": { "value": { "type": "number", "format": "decimal", "example": 1 }, "currency": { "type": "string", "example": "EUR" } }, "required": [ "value", "currency" ] }, "maxAvailableToRefund": { "type": "object", "description": "Remaining amount that can still be refunded for the pay-in. If no refund was performed, this parameter will be equal to the full amount", "properties": { "value": { "type": "number", "format": "decimal", "example": 150 }, "currency": { "type": "string", "example": "EUR" } }, "required": [ "value", "currency" ] } }, "required": [ "fee", "maxAvailableToRefund" ] }, "examples": { "estimateSuccess": { "summary": "Successful fee estimate", "value": { "fee": { "value": 1, "currency": "EUR" }, "maxAvailableToRefund": { "value": 150, "currency": "EUR" } } } } } } }, "400": { "description": "Estimate could not be produced because the pay-in is not refundable or the amount is invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "BVNK ERROR CODE" }, "status": { "type": "string", "description": "ERROR STATUS" }, "message": { "type": "string", "description": "ERROR MESSAGE" }, "details": { "type": "object", "properties": { "documentLink": { "type": "string", "format": "uri", "description": "Link to error documentation" }, "errors": { "type": "object", "properties": { "requestHeader": { "type": "array", "items": { "type": "string" } } } } } } }, "required": [ "code", "status", "message", "details" ] }, "examples": { "notRefundable": { "value": { "code": "bvnk:payment:0204", "status": "Bad Request", "message": "Pay-in 018e5e83-ac50-4df0-a7e4-c9f15d493f90 not refundable.", "details": { "documentLink": "https://docs.bvnk.com/reference/errors#/", "errors": { "requestHeader": [ "01967c8c-680b-7086-8718-b1b4f53231zz" ] } } } } } } } }, "500": { "$ref": "#/components/responses/UnexpectedErrorMessage" } } } }, "/payment/v1/payins/{transactionReference}/refund": { "post": { "summary": "Refund pay-in", "description": "Initiates seamless one-click refund processing for any previous pay-in. Once accepted, a refund transaction appears in your portal and can be acquired via API. \n\n Upon activation, the system automatically generates a new transaction according to our standard workflow. You can request multiple refunds for the same transaction, as long as the total refunded amount doesn't exceed what was originally paid in.", "tags": [ "Fiat Payments" ], "operationId": "refundPayin", "externalDocs": { "description": "Guide: Refund payments", "url": "https://docs.bvnk.com/bvnk/use-cases/virtual-accounts/refund-payments#refund-pay-in" }, "security": [ { "Hawk": [ "merchant" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "name": "transactionReference", "in": "path", "required": true, "description": "Unique reference (UUID) of the pay-in you want to refund.", "schema": { "type": "string", "format": "uuid", "example": "023e5e53-6f50-4af5-a7e4-c9f15d493f90" } } ], "requestBody": { "required": true, "description": "JSON payload describing the amount you wish to refund.", "content": { "application/json": { "schema": { "type": "object", "properties": { "paymentReference": { "description": "Merchant-side reference that ties the refund to your order, user, or invoice.", "type": "string", "example": "order123456" }, "amount": { "type": "object", "description": "The amount that will be refunded.\n\n**Note**: Only full refunds are supported for Automated Clearing House (ACH) transfers. The refund customer payment reference will not be propagated to the bank. The original pay-in customer payment reference is shown in the refund.", "properties": { "value": { "description": "Amount in major currency units (use dot as decimal separator).", "type": "number", "format": "double", "example": 150.5 }, "currency": { "description": "Three-letter ISO-4217 currency code.", "type": "string", "enum": [ "GBP", "USD", "EUR" ], "example": "EUR" } }, "required": [ "value", "currency" ] }, "metadata": { "$ref": "#/components/schemas/Metadata" } }, "required": [ "paymentReference", "amount" ] }, "examples": { "fullRefund": { "summary": "Full refund", "value": { "paymentReference": "order123456", "amount": { "value": 150, "currency": "EUR" }, "metadata": { "memberId": "987654321" } } }, "partialRefund": { "summary": "Partial refund", "value": { "paymentReference": "order123456", "amount": { "value": 50, "currency": "EUR" }, "metadata": { "memberId": "987654321" } } } } } } }, "responses": { "200": { "description": "Refund request accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "transactionReference": { "type": "string", "format": "uuid", "example": "018e5e83-ac50-4df0-a7e4-c9f15d493f90", "description": "Unique identifier for the refund transaction" }, "fee": { "type": "object", "description": "Projected fee for processing the refund", "properties": { "value": { "type": "number", "format": "decimal", "example": 1.5 }, "currency": { "type": "string", "example": "EUR" } }, "required": [ "value", "currency" ] } }, "required": [ "transactionReference", "fee" ] }, "examples": { "refundAccepted": { "summary": "Successful refund request", "value": { "transactionReference": "018e5e83-ac50-4df0-a7e4-c9f15d493f90", "fee": { "value": 1.5, "currency": "EUR" } } } } } } }, "400": { "description": "Estimate could not be produced because the pay-in is not refundable or the amount is invalid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "BVNK ERROR CODE" }, "status": { "type": "string", "description": "ERROR STATUS" }, "message": { "type": "string", "description": "ERROR MESSAGE" }, "details": { "type": "object", "properties": { "documentLink": { "type": "string", "format": "uri", "description": "Link to error documentation" }, "errors": { "type": "object", "properties": { "requestHeader": { "type": "array", "items": { "type": "string" } } } } } } }, "required": [ "code", "status", "message", "details" ] }, "examples": { "notRefundable": { "value": { "code": "bvnk:payment:0204", "status": "Bad Request", "message": "Pay-in 018e5e83-ac50-4df0-a7e4-c9f15d493f90 not refundable.", "details": { "documentLink": "https://docs.bvnk.com/reference/errors#/", "errors": { "requestHeader": [ "01967c8c-680b-7086-8718-b1b4f53231zz" ] } } } } } } } }, "500": { "$ref": "#/components/responses/UnexpectedErrorMessage" } } } }, "/payment/v1/payins/simulate": { "post": { "summary": "Simulate pay-in", "description": "Simulates pay-ins with different currencies and payment methods in the sandbox environment.\n\n**Important**: A `201` response indicates the pay-in was accepted for processing; it does not mean the funds have settled. The transaction may still be rejected asynchronously, for example, due to a blocked account, financial crime screening holds, or compliance checks. Monitor webhooks for the final transaction status.", "operationId": "simulatePayin", "deprecated": true, "tags": [ "Fiat Payments" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "walletId", "paymentReference", "amount", "originator" ], "properties": { "walletId": { "$ref": "#/components/schemas/UnifiedPayoutRequest/properties/walletId" }, "paymentReference": { "$ref": "#/components/schemas/UnifiedPayoutRequest/properties/paymentReference" }, "paymentMethod": { "type": "string", "description": "Payment method to be utilised for transactions. Optional. If not provided, the logic will be based on other dynamically determined attributes and routed for the specific wallet.\n\nUse the following methods for each currency:\n\n- GBP: `FASTER_PAYMENT` or `SWIFT`\n\n- EUR: `SEPA_CT`, `SEPA_INST`, or `SWIFT`\n\n- USD: `ACH`, `ACH_SAME_DAY`, `FEDWIRE`, `CUBIX`, or `SWIFT`", "enum": [ "FASTER_PAYMENT", "SWIFT", "SEPA_CT", "SEPA_INST", "ACH", "ACH_SAME_DAY", "FEDWIRE", "CUBIX" ], "example": "FASTER_PAYMENT" }, "amount": { "$ref": "#/components/schemas/UnifiedPayoutRequest/properties/amount" }, "originator": { "type": "object", "required": [ "name", "bankAccount" ], "properties": { "name": { "type": "string", "description": "Name of the sender of the pay-in.", "example": "Emily Kaldwin" }, "bankAccount": { "type": "object", "required": [ "accountNumber" ], "properties": { "accountNumber": { "type": "string", "description": "Account number of the sender of the pay-in.", "example": "GB87SYPE04082500000904" }, "accountNumberFormat": { "type": "string", "description": "Format type of the bank account number", "enum": [ "SCAN", "IBAN", "SWIFT", "ABA", "CUBIX" ], "example": "IBAN" } } } } } } }, "examples": { "GBP Faster Payment": { "summary": "Simulate a GBP pay-in via Faster Payment", "value": { "walletId": "a:24092328494070:G5i4XZ9:1", "paymentReference": "INV-2024-0042", "paymentMethod": "FASTER_PAYMENT", "amount": { "value": 500, "currency": "GBP" }, "originator": { "name": "Emily Kaldwin", "bankAccount": { "accountNumber": "GB87SYPE04082500000904", "accountNumberFormat": "IBAN" } } } } } } } }, "responses": { "201": { "description": "Accepted for processing. This does not indicate that the pay-in has settled. The transaction may still be rejected asynchronously due to account restrictions, financial crime screening holds, or compliance checks." }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "example1": { "summary": "Bad request.", "value": { "code": "BVNK-4001", "status": "400", "message": "Could not find wallet with id: a:24092328494070:G5i4XZ9:1" } } } } } } } } }, "/payment/v2/payins/simulation": { "post": { "summary": "Simulate pay-in (v.2)", "description": "Simulates pay-ins with different currencies and payment methods in the sandbox environment.\n\nThis version allows specifying originator entity details (individual or company) for more comprehensive testing scenarios.\n\n**Important**: A `201` response indicates the pay-in was accepted for processing. It does not mean the funds have settled. The transaction may still be rejected asynchronously, for example, due to a blocked account, financial crime screening holds, or compliance checks. Monitor webhooks for the final transaction status.", "operationId": "simulatePayinV2", "tags": [ "Fiat Payments" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "walletId", "remittanceInformation", "amount", "currency", "originator" ], "properties": { "walletId": { "$ref": "#/components/schemas/UnifiedPayoutRequest/properties/walletId" }, "method": { "type": "string", "description": "Payment method to be utilised for the pay-in. Optional. If not provided, the logic will be based on other dynamically determined attributes and routed for the specific wallet.\n\nUse the following methods for each currency:\n\n- GBP: `FASTER_PAYMENT` or `SWIFT`\n\n- EUR: `SEPA_CT`, `SEPA_INST`, or `SWIFT`\n\n- USD: `ACH`, `ACH_SAME_DAY`, `FEDWIRE`, `CUBIX`, or `SWIFT`", "enum": [ "FASTER_PAYMENT", "SWIFT", "SEPA_CT", "SEPA_INST", "ACH", "ACH_SAME_DAY", "FEDWIRE", "CUBIX" ], "example": "FASTER_PAYMENT" }, "remittanceInformation": { "$ref": "#/components/schemas/BeneficiaryRequest/properties/remittanceInformation" }, "amount": { "type": "number", "format": "decimal", "description": "The amount of the pay-in transaction.", "example": 1000.5 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Currency code (ISO-4217 format) for the pay-in transaction.", "example": "EUR" }, "originator": { "type": "object", "required": [ "name", "bankAccount" ], "properties": { "name": { "type": "string", "description": "Name of the sender of the pay-in.", "example": "Emily Kaldwin" }, "bankAccount": { "type": "object", "required": [ "accountNumber" ], "properties": { "accountNumber": { "type": "string", "description": "Account number of the sender of the pay-in.", "example": "GB87SYPE04082500000904" }, "accountNumberFormat": { "type": "string", "description": "Format type of the bank account number", "enum": [ "SCAN", "IBAN", "SWIFT", "ABA", "CUBIX" ], "example": "IBAN" }, "bankCode": { "type": "string", "description": "Originator's bank code (BIC/SWIFT code).", "example": "SAPYGB2L" } } } } } } }, "examples": { "Individual originator": { "summary": "Pay-in from an individual", "value": { "walletId": "a:24092328494070:G5i4XZ9:1", "method": "SEPA_CT", "remittanceInformation": "Invoice payment 12345", "amount": 1500, "currency": "EUR", "originator": { "name": "Emily Kaldwin", "bankAccount": { "accountNumber": "GB87SYPE04082500000904", "accountNumberFormat": "IBAN", "bankCode": "SRLGGB2L" } } } }, "Company originator": { "summary": "Pay-in from a company", "value": { "walletId": "a:24092328494070:G5i4XZ9:1", "method": "SWIFT", "remittanceInformation": "Corporate transfer REF001", "amount": 50000, "currency": "USD", "originator": { "name": "Acme Corporation Ltd", "bankAccount": { "accountNumber": "000123456789", "accountNumberFormat": "ABA", "bankCode": "ATFEUS33" } } } } } } } }, "responses": { "201": { "description": "Accepted for processing. This does not indicate that the pay-in has settled. The transaction may still be rejected asynchronously due to account restrictions, financial crime screening holds, or compliance checks." }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "example1": { "summary": "Invalid wallet ID", "value": { "code": "BVNK-4001", "status": "400", "message": "Could not find wallet with id: a:24092328494070:G5i4XZ9:1" } }, "example2": { "summary": "Invalid currency", "value": { "code": "BVNK-4002", "status": "400", "message": "Invalid currency code provided" } } } } } } } } }, "/payment/v1/transfers": { "post": { "summary": "Create internal transfer", "description": "Create an internal Fiat transfer to an existing beneficiary wallet.", "deprecated": true, "tags": [ "Fiat Payments" ], "operationId": "transferCreate", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTransferRequest" }, "examples": { "Internal Transfer": { "summary": "Transfer USD between wallets", "value": { "walletId": "a:24092328494070:G5i4XZ9:1", "amount": { "value": 700, "currency": "USD" }, "paymentReference": "Payment for invoice 12345", "instruction": { "type": "FIAT", "beneficiaryWalletId": "a:87333266494070:G5i9AT9:1" } } } } } } }, "responses": { "200": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTransferResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "example1": { "summary": "Bad request.", "value": { "code": "BVNK-3001", "status": "400", "message": "Idempotency key 16c5fd8f-cc38-4717-90b9-21288e19a3ac for account reference 5a9bf956-0410-43dc-b824-eb69048208cb already exists" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "example1": { "summary": "Forbidden.", "value": { "code": "BVNK-4003", "status": "403", "message": "Access Denied" } } } } } } }, "security": [ { "Hawk": [ "merchant" ] } ] } }, "/payment/v2/transfers": { "post": { "summary": "Create internal transfer (v.2)", "description": "Creates an internal stablecoin and fiat transfer between customer's and partner's wallets.\n\nPayment combinations:\n\n- Crypto to crypto\n\n- Fiat to fiat", "tags": [ "Fiat Payments", "Crypto Payments" ], "operationId": "transferCreateV2", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyNew" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferRequestV2" }, "examples": { "TransferRequest": { "summary": "Create internal transfer", "value": { "reference": "REF558628", "walletId": "a:24122329329347:HsdJVhW:2", "amount": 23, "currency": "USD", "beneficiary": { "walletId": "a:25021926815866:4jlPfFg:1" }, "metadata": { "memberId": "987654321" } } } } } } }, "responses": { "201": { "description": "Transfer created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferResponseV2" }, "examples": { "TransferResponse": { "summary": "Transfer response", "value": { "id": "ae29acc3-c54a-11f0-90b6-21c3f364ff25", "reference": "REF558628", "status": "COMPLETED", "type": "payment:transfer", "method": "BOOK", "fees": { "processingFee": { "amount": 0, "currency": "USD" } }, "originator": { "amount": 1.11, "currency": "USD", "entity": { "legalName": "3Com", "type": "COMPANY" }, "walletId": "a:25032550863140:zKwR3P9:1" }, "beneficiary": { "amount": 1.11, "currency": "USD", "entity": { "legalName": "4Com", "type": "COMPANY" }, "walletId": "a:25021926815866:4jlPfFg:1" }, "metadata": { "memberId": "987654321" }, "createdAt": "2025-11-19T13:21:38.870144Z", "updatedAt": "2025-11-19T13:21:38.870144Z" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "example1": { "summary": "Bad request.", "value": { "code": "BVNK-3001", "status": "400", "message": "Idempotency key 16c5fd8f-cc38-4717-90b9-21288e19a3ac for account reference 5a9bf956-0410-43dc-b824-eb69048208cb already exists" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "example1": { "summary": "Forbidden.", "value": { "code": "BVNK-4003", "status": "403", "message": "Access Denied" } } } } } } }, "security": [ { "Hawk": [ "merchant" ] } ] } }, "/payment/v2/transfers/{transferId}": { "get": { "summary": "Get transfer (v.2)", "description": "Retrieves a specific transfer details.", "operationId": "transferReadV2", "tags": [ "Fiat Payments", "Crypto Payments" ], "parameters": [ { "name": "transferId", "in": "path", "description": "The transfer ID that you want to retrieve.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "ae29acc3-c54a-11f0-90b6-21c3f364ff25" } } ], "responses": { "200": { "description": "Transfer retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferResponseV2" }, "examples": { "TransferResponse": { "summary": "Transfer response", "value": { "id": "ae29acc3-c54a-11f0-90b6-21c3f364ff25", "reference": "REF558628", "status": "COMPLETED", "method": "BOOK", "fees": { "processingFee": { "amount": 0, "currency": "USD" } }, "originator": { "amount": 1.11, "currency": "USD", "walletId": "a:25032550863140:zKwR3P9:1", "entity": { "type": "COMPANY", "legalName": "3Com" } }, "beneficiary": { "amount": 1.11, "currency": "USD", "walletId": "a:25021926815866:4jlPfFg:1", "entity": { "type": "COMPANY", "legalName": "3Com" } }, "metadata": { "memberId": "987654321" }, "createdAt": "2025-11-19T13:21:38.870144Z", "updatedAt": "2025-11-19T13:21:38.870144Z", "type": "payment:transfer" } } } } } }, "404": { "description": "Transfer not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "example1": { "summary": "Transfer Not Found", "value": { "code": "BVNK-3040", "status": "404", "message": "Transfer with ID ae29acc3-c54a-11f0-90b6-21c3f364ff25 not found" } } } } } } }, "security": [ { "Hawk": [ "merchant" ] } ] } }, "/payment/v1/transfers/{transactionReference}": { "get": { "tags": [ "Fiat Payments" ], "summary": "Get transfer", "description": "Retrieves a specific transfer details.", "deprecated": true, "operationId": "transferRead", "parameters": [ { "name": "transactionReference", "in": "path", "description": "The transactionReference of the transfer that you want to retrieve.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "5dc4e061-31c6-4b96-8c4d-0ea984aece0b" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferResponse" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "example1": { "summary": "Transfer Not Found", "value": { "code": "BVNK-3040", "status": "404", "message": "Transfer with reference 5a9bf956-0410-43dc-b824-eb69048208cb not found" } } } } } } }, "security": [ { "Hawk": [ "user", "account_read", "transaction_read" ] } ] } }, "/payment/v1/transfers/{walletId}/beneficiaries": { "get": { "tags": [ "Fiat Payments" ], "summary": "List transfer beneficiaries", "description": "Retrieves a list of beneficiaries eligible for transfers for a specified wallet.", "operationId": "transfersBeneficiaryRead", "parameters": [ { "name": "walletId", "in": "path", "description": "The wallet ID for which you are listing the eligible beneficiaries.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "a:24092328494070:G5i4XZ9:1" } }, { "name": "currencyCode", "in": "query", "description": "The currency code for the wallets.", "required": true, "schema": { "type": "string", "example": "GBP" } }, { "name": "walletType", "in": "query", "description": "The type of the wallets.", "required": false, "schema": { "type": "string", "example": "MAIN" } }, { "name": "customerReference", "in": "query", "description": "Customer reference for the wallets being requested.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "33e85982-e22b-4e8b-9057-445cf000bea9" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TransferBeneficiaryResponse" } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "example1": { "summary": "Forbidden.", "value": { "code": "BVNK-4003", "status": "403", "message": "Access Denied" } } } } } } }, "security": [ { "Hawk": [ "merchant" ] } ] } }, "/api/wallet": { "post": { "tags": [ "Wallets" ], "summary": "Create crypto wallet", "description": "Creates a crypto wallet on the BVNK platform.", "operationId": "walletCreate", "deprecated": true, "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletRequestDto" }, "examples": { "Create Wallet": { "summary": "Create an ETH wallet", "value": { "currency": "ETH", "description": "My 2nd ETH Wallet" } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletDto" } } } }, "400": { "$ref": "#/components/responses/BadRequestNoMessage" }, "500": { "description": "Unexpected Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerErrorDto" } } } } }, "security": [ { "Hawk": [ "user" ] } ] }, "get": { "tags": [ "Wallets" ], "summary": "List crypto wallets", "description": "Retrieves a list of wallets on your account. Displays the first 10 wallets without max set to higher.", "operationId": "walletList", "deprecated": true, "parameters": [ { "$ref": "#/components/parameters/OffsetInteger" }, { "$ref": "#/components/parameters/MaxInteger" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/WalletDto" } }, "examples": { "Common": { "summary": "List of Wallets", "value": [ { "id": 3796981, "description": "ETH wallet", "currency": { "id": 1969, "code": "ETH", "fiat": false, "icon": "https://media.dev.node.limited/61a40a06-1e8c-4968-a01a-539587debb3d.png", "name": "Ethereum", "withdrawalParameters": [], "options": { "confirmations": 12, "explorer": "https://etherscan.io/", "transaction": "https://etherscan.io/tx/{{hash}}", "address": "https://etherscan.io/address/{{address}}" }, "withdrawalFee": 0.001, "depositFee": 0, "supportsDeposits": true, "supportsWithdrawals": true, "quantityPrecision": 8, "pricePrecision": 8, "protocols": [ { "code": "ETH", "network": "Ethereum", "networkCode": "ETHEREUM" } ] }, "supportsWithdrawals": true, "supportsDeposits": true, "custodianWallet": null, "supportsThirdParty": false, "supportsInternalBvnkNetworkTransfers": false, "partner": null, "isEmoney": false, "supportedTransferDestinations": [ "LOCAL" ], "network": "ETHEREUM", "protocol": "ETH", "address": "0x15b3309d4a881f9d23c4fea9389b2c205606021f", "lookup": null, "balance": 0.00742096, "available": 0.00742096, "withdrawalFee": 0.001, "depositFee": 0, "convertedAvailable": 19.71, "alternatives": [], "approxAvailable": "0.00742096", "approxBalance": "0.00742096", "approxConvertedAvailable": "19.71", "lsid": "a:25061134333492:69iFbD6:1", "status": "ACTIVE" }, { "id": 3804725, "description": "40K", "currency": { "id": 1691, "code": "BTC", "fiat": false, "icon": "https://media.dev.node.limited/7b74200a-b16b-4548-b288-fb385a67d7ff.png", "name": "Bitcoin", "withdrawalParameters": [], "options": { "confirmations": 4, "address": "https://www.blockchain.com/btc/address/{{address}}", "explorer": "https://www.blockchain.com/explorer?view=btc", "transaction": "https://www.blockchain.com/btc/tx/{{hash}}" }, "withdrawalFee": 0.000005, "depositFee": 0, "supportsDeposits": true, "supportsWithdrawals": true, "quantityPrecision": 8, "pricePrecision": 8, "protocols": [ { "code": "BTC", "network": "Bitcoin", "networkCode": "BITCOIN" } ] }, "supportsWithdrawals": true, "supportsDeposits": true, "custodianWallet": null, "supportsThirdParty": false, "supportsInternalBvnkNetworkTransfers": false, "partner": null, "isEmoney": false, "supportedTransferDestinations": [], "network": "BITCOIN", "protocol": "BTC", "address": "tb1q0t74d4qwlyk8jf2upa7l0mjvyx5ftu78mkvse3", "lookup": null, "balance": 0, "available": 0, "withdrawalFee": 0.000005, "depositFee": 0, "convertedAvailable": 0, "alternatives": [], "approxAvailable": "0", "approxBalance": "0", "approxConvertedAvailable": "0", "lsid": "a:25061831425668:Ry7kRR6:1", "status": "ACTIVE" } ] } } } } } }, "security": [ { "Hawk": [ "user" ] } ] } }, "/api/wallet/{walletId}": { "get": { "tags": [ "Wallets" ], "summary": "Get crypto wallet", "description": "Retrieves detailed information about a specific wallet.", "operationId": "walletRead", "deprecated": true, "parameters": [ { "name": "walletId", "in": "path", "description": "Unique identifier of the wallet that you want to retrieve.", "required": true, "schema": { "type": "string", "example": "3858036" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletDto" } } } } }, "security": [ { "Hawk": [ "user" ] } ] } }, "/api/wallet/balances": { "get": { "tags": [ "Wallets" ], "summary": "List crypto wallet balances", "description": "Retrieves the balances of your wallets on platform.", "operationId": "walletBalanceList", "deprecated": true, "parameters": [ { "name": "date", "in": "query", "description": "Date at to retrieve balances.", "schema": { "type": "string", "example": "2020-03-17" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BalanceDto" } } } } } }, "security": [ { "Hawk": [ "user" ] } ] } }, "/api/transaction/v2/report": { "get": { "tags": [ "Wallets" ], "summary": "Transactions report (v.2)", "description": "Report all transactions from wallet in specified format. Report will be generated and sent to main account email in the specified format.", "operationId": "walletTransactionReportV2", "deprecated": true, "parameters": [ { "name": "walletId", "in": "query", "description": "Wallet id for which to retrieve transactions.", "schema": { "type": "string", "example": "a:24022356065814:B9JE7bQ:1" } }, { "$ref": "#/components/parameters/FromDate" }, { "$ref": "#/components/parameters/ToDate" }, { "name": "format", "in": "query", "description": "'json' - json format, 'csv' - csv format", "schema": { "type": "string", "example": "csv" } }, { "name": "transactionType", "in": "query", "description": "Transaction type code", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SimplifiedTransactionReportDto" } } } } } }, "security": [ { "Hawk": [ "user" ] } ] } }, "/ledger/v1/report-schedules": { "post": { "tags": [ "Wallets" ], "security": [ { "Hawk": [ "merchant" ] } ], "summary": "Create report schedule", "description": "Creates a new scheduled report that will be automatically generated and delivered according to the specified frequency and delivery preferences. Each user can create only one schedule per account.", "operationId": "createReportSchedule", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "time", "timezone", "frequencyType", "format", "channel", "reportParams" ], "properties": { "time": { "type": "string", "pattern": "^([01]?[0-9]|2[0-3]):[0-5][0-9]$", "description": "Time of day when the report should be generated and sent, in 24-hour format (HH:MM).", "example": "12:00" }, "timezone": { "type": "string", "description": "Timezone to use for scheduling the report generation. Must be a valid IANA timezone identifier. Use [Get Supported Timezones](https://docs.bvnk.com/reference/getsupportedtimezones#/) endpoint to get the list of timezones.", "example": "Europe/London" }, "frequencyType": { "type": "string", "enum": [ "DAILY", "WEEKLY", "MONTHLY" ], "description": "Frequency at which the report should be generated. The report is generated for the previous time period.\n\n For example, if the DAILY report is generated on 1st of January, it will contain the data for the previous day (31st of December). If the WEEKLY report is scheduled for Wednesday, it will contain the data for the previous Tuesday to this week's Wednesday.", "example": "DAILY" }, "frequencyDay": { "type": "integer", "minimum": 1, "maximum": 31, "description": "Specific day (1=Monday, 7=Sunday) for report generation. Only for `frequencyType` WEEKLY.\n\n To schedule a report for every day, set this value to `1`.", "example": 1 }, "format": { "type": "string", "enum": [ "CSV", "PDF", "JSON" ], "description": "File format for the generated report.", "example": "CSV" }, "channel": { "type": "string", "enum": [ "webhook", "email" ], "description": "Delivery method for the report: \n\n - `webhook` for API delivery\n\n - `email` for delivery via email.", "example": "webhook" }, "email": { "type": "string", "format": "email", "description": "Email address for report delivery. Required when channel is `email`, ignored for the `webhook` channel.", "example": "reports@company.com" }, "reportParams": { "type": "object", "required": [ "reportType" ], "properties": { "reportType": { "type": "string", "enum": [ "TRANSACTION", "TRADING_VOLUME", "PAYMENT_VOLUME", "DIGITAL_ASSETS_VOLUME", "PAYMENT", "WALLET_BALANCE" ], "description": "The type of report to be generated. Use 'TRANSACTION' to get the transactions report.\n\n**Currently, only 'TRANSACTION' is supported**. More report types will be available in the future.", "example": "TRANSACTION" }, "walletId": { "type": "string", "description": "The ID of the wallet to generate the report for.", "example": "a:02502251969431:yyDut96:1" } } } } }, "examples": { "daily_webhook": { "summary": "Daily report via webhook", "value": { "time": "12:00", "timezone": "Europe/London", "frequencyType": "DAILY", "frequencyDay": 1, "format": "CSV", "channel": "webhook", "reportParams": { "reportType": "TRANSACTION", "walletId": "a:02502251969431:yyDut96:1" } } }, "weekly_email": { "summary": "Weekly report via email", "value": { "time": "09:30", "timezone": "America/New_York", "frequencyType": "WEEKLY", "frequencyDay": 3, "format": "PDF", "channel": "email", "email": "finance@company.com", "reportParams": { "reportType": "TRANSACTION", "walletId": "a:02502251969431:yyDut96:1" } } }, "monthly_report": { "summary": "Monthly report on 15th day", "value": { "time": "08:00", "timezone": "UTC", "frequencyType": "MONTHLY", "frequencyDay": 15, "format": "JSON", "channel": "webhook", "reportParams": { "reportType": "TRANSACTION", "walletId": "a:02502251969431:yyDut96:1" } } } } } } }, "responses": { "201": { "description": "Report schedule created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the created report schedule", "example": "3afd38a6-fc31-4775-87e0-eaa556447825" }, "createdBy": { "type": "string", "description": "Base64 encoded identifier of the user who created the schedule", "example": "yOVN4ejn3xuZqGI5IW7Clwv9YO8MCboZWdXTxYuZR/4=" }, "name": { "type": "string", "nullable": true, "description": "Optional name for the report schedule", "example": null }, "accountReference": { "type": "string", "format": "uuid", "description": "Reference to the account this report schedule belongs to", "example": "4e9d4fa8-29d7-11ed-84d9-0a878439b77f" }, "time": { "type": "string", "description": "The scheduled time for report generation in 24-hour format", "example": "12:00" }, "timezone": { "type": "string", "description": "The timezone used for scheduling", "example": "Europe/London" }, "frequencyType": { "type": "string", "enum": [ "DAILY", "WEEKLY", "MONTHLY" ], "description": "The frequency of report generation", "example": "DAILY" }, "frequencyDay": { "type": "integer", "description": "The specific day for report generation based on frequency type", "example": 1 }, "format": { "type": "string", "enum": [ "CSV", "PDF", "JSON" ], "description": "The file format of the generated report (uppercase in response)", "example": "CSV" }, "channel": { "type": "string", "enum": [ "WEBHOOK", "EMAIL" ], "description": "The delivery method for the report (uppercase in response)", "example": "WEBHOOK" }, "email": { "type": "string", "format": "email", "nullable": true, "description": "Email address for delivery (`null` when channel is WEBHOOK)", "example": null }, "reportParams": { "type": "object", "description": "Parameters for the report configuration", "properties": { "reportType": { "type": "string", "enum": [ "TRANSACTION" ], "description": "The type of report to be generated", "example": "TRANSACTION" }, "walletId": { "type": "string", "description": "The ID of the wallet to generate the report for.", "example": "a:02502251969431:yyDut96:1" } } }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the report schedule was created", "example": "2026-01-12T16:02:46Z" } } }, "examples": { "daily_schedule_created": { "summary": "Daily report schedule created", "value": { "id": "3afd38a6-fc31-4775-87e0-eaa556447825", "createdBy": "SLXh6jH2Q1ZnmgRpKAgdfY2tanB/t/PNMILtfKvh2gc=", "accountReference": "4e9d4fa8-29d7-11ed-84d9-0a878439b77f", "time": "12:00", "timezone": "Europe/London", "frequencyType": "DAILY", "frequencyDay": 1, "format": "CSV", "channel": "WEBHOOK", "email": null, "reportParams": { "reportType": "TRANSACTION", "walletId": "a:25120857447503:4lMPgE6:1" }, "createdAt": "2026-01-12T16:02:46Z" } }, "email_schedule_created": { "summary": "Email report schedule created", "value": { "id": "7b2e9c4d-ae12-4567-bc89-def123456789", "createdBy": "XYZa1bC2d3E4f5G6h7I8j9K0l1M2n3O4p5Q6r7S8t9U=", "name": null, "accountReference": "8f1a2b3c-4d5e-6f70-8a9b-0c1d2e3f4a5b", "time": "09:30", "timezone": "America/New_York", "frequencyType": "WEEKLY", "frequencyDay": 1, "format": "PDF", "channel": "EMAIL", "email": "finance@company.com", "reportParams": { "reportType": "TRANSACTION", "walletId": "a:02502251969431:yyDut96:1" }, "createdAt": "2026-01-12T16:02:46Z" } } } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error code identifier", "example": "bvnk:layer1:2100" }, "status": { "type": "string", "description": "HTTP status description", "example": "Bad Request" }, "message": { "type": "string", "description": "General error message", "example": "Validation failed" }, "details": { "type": "object", "properties": { "documentLink": { "type": "string", "nullable": true, "description": "Link to relevant documentation", "example": null }, "errors": { "type": "object", "description": "Field-specific validation errors", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } } } }, "examples": { "invalid_time_format": { "summary": "Invalid time format", "value": { "code": "bvnk:layer1:2100", "status": "Bad Request", "message": "Validation failed", "details": { "documentLink": null, "errors": { "time": [ "Time is invalid." ] } } } } } } } }, "409": { "description": "Conflict - Report schedule already exists for this user", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error code identifier", "example": "bvnk:ledger:2201" }, "status": { "type": "string", "description": "HTTP status description", "example": "Conflict" }, "message": { "type": "string", "description": "Detailed error message explaining the conflict", "example": "The given user SLXh6jH2Q1ZnmgRpKAgdfY2tanB/t/PNMILtfKvh2gc=, has already setup report schedule" }, "details": { "type": "object", "nullable": true, "description": "Additional details about the error", "example": null } } }, "examples": { "user_already_has_schedule": { "summary": "User already has a report schedule", "value": { "code": "bvnk:ledger:2201", "status": "Conflict", "message": "The given user SLXh6jH2Q1ZnmgRpKAgdfY2tanB/t/PNMILtfKvh2gc=, has already setup report schedule", "details": null } } } } } } } }, "get": { "tags": [ "Wallets" ], "security": [ { "Hawk": [ "merchant" ] } ], "summary": "List report schedules", "description": "Retrieves a paginated list of report schedules for the authenticated user's account. Returns all schedules created by the user with their current configuration and delivery preferences.", "operationId": "listReportSchedules", "parameters": [ { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 }, "description": "Page number for pagination (0-based)", "example": 0 }, { "name": "size", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "description": "Number of items per page", "example": 20 } ], "responses": { "200": { "description": "Report schedules retrieved successfully", "content": { "application/json": { "schema": { "allOf": [ { "type": "object", "properties": { "content": { "type": "array", "description": "List of report schedules", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the report schedule", "example": "3afd38a6-fc31-4775-87e0-eaa556447825" }, "createdBy": { "type": "string", "description": "Base64 encoded identifier of the user who created the schedule", "example": "SLXh6jH2Q1ZnmgRpKAgdfY2tanB/t/PNMILtfKvh2gc=" }, "accountReference": { "type": "string", "format": "uuid", "description": "Reference to the account this report schedule belongs to", "example": "4e9d4fa8-29d7-11ed-84d9-0a878439b77f" }, "time": { "type": "string", "description": "The scheduled time for report generation in 24-hour format", "example": "14:00" }, "timezone": { "type": "string", "description": "The timezone used for scheduling", "example": "Europe/London" }, "frequencyType": { "type": "string", "enum": [ "DAILY", "WEEKLY", "MONTHLY" ], "description": "The frequency of report generation", "example": "WEEKLY" }, "frequencyDay": { "type": "integer", "description": "The specific day for report generation based on frequency type", "example": 3 }, "format": { "type": "string", "enum": [ "CSV", "PDF", "JSON" ], "description": "The file format of the generated report", "example": "JSON" }, "channel": { "type": "string", "enum": [ "WEBHOOK", "EMAIL" ], "description": "The delivery method for the report", "example": "WEBHOOK" }, "email": { "type": "string", "format": "email", "nullable": true, "description": "Email address for delivery (null when channel is WEBHOOK)", "example": null }, "reportType": { "type": "string", "enum": [ "TRANSACTION", "BALANCE", "SUMMARY" ], "description": "The type of report to be generated", "example": "TRANSACTION" } } } } } }, { "$ref": "#/components/schemas/PageMetadata" } ] }, "examples": { "single_schedule_response": { "summary": "Single report schedule in list", "value": { "content": [ { "id": "3afd38a6-fc31-4775-87e0-eaa556447825", "createdBy": "SLXh6jH2Q1ZnmgRpKAgdfY2tanB/t/PNMILtfKvh2gc=", "accountReference": "4e9d4fa8-29d7-11ed-84d9-0a878439b77f", "time": "14:00", "timezone": "Europe/London", "frequencyType": "WEEKLY", "frequencyDay": 3, "format": "JSON", "channel": "WEBHOOK", "email": null, "reportType": "TRANSACTION" } ], "pageable": { "pageNumber": 0, "pageSize": 20, "sort": [], "offset": 0, "paged": true, "unpaged": false }, "last": true, "totalPages": 1, "totalElements": 1, "first": true, "size": 20, "number": 0, "sort": [], "numberOfElements": 1, "empty": false } }, "empty_response": { "summary": "Empty list when no schedules exist", "value": { "content": [], "pageable": { "pageNumber": 0, "pageSize": 20, "sort": [], "offset": 0, "paged": true, "unpaged": false }, "last": true, "totalPages": 0, "totalElements": 0, "first": true, "size": 20, "number": 0, "sort": [], "numberOfElements": 0, "empty": true } } } } } }, "400": { "description": "Bad request - Invalid query parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error code identifier", "example": "bvnk:layer1:2100" }, "status": { "type": "string", "description": "HTTP status description", "example": "Bad Request" }, "message": { "type": "string", "description": "General error message", "example": "Validation failed" }, "details": { "type": "object", "properties": { "documentLink": { "type": "string", "nullable": true, "description": "Link to relevant documentation", "example": null }, "errors": { "type": "object", "description": "Field-specific validation errors", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } } } }, "examples": { "invalid_page_size": { "summary": "Invalid page size parameter", "value": { "code": "bvnk:layer1:2100", "status": "Bad Request", "message": "Validation failed", "details": { "documentLink": null, "errors": { "size": [ "Page size must be between 1 and 100." ] } } } } } } } } } } }, "/ledger/v1/report-schedules/{scheduleId}": { "put": { "tags": [ "Wallets" ], "security": [ { "Hawk": [ "merchant" ] } ], "summary": "Update existing report schedule", "description": "Updates an existing scheduled report with new frequency and delivery preferences. Only the user who created the schedule can update it.", "operationId": "updateReportSchedule", "parameters": [ { "name": "scheduleId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Unique identifier of the report schedule to update.", "example": "3afd38a6-fc31-4775-87e0-eaa556447825" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "time", "timezone", "frequencyType", "format", "channel" ], "properties": { "time": { "type": "string", "pattern": "^([01]?[0-9]|2[0-3]):[0-5][0-9]$", "description": "Time of day when the report should be generated and sent, in 24-hour format (HH:MM).", "example": "14:00" }, "timezone": { "type": "string", "description": "Timezone to use for scheduling the report generation. Must be a valid IANA timezone identifier. Use [Get Supported Timezones](https://docs.bvnk.com/reference/getsupportedtimezones#/) endpoint to get the list of timezones.", "example": "Europe/London" }, "frequencyType": { "type": "string", "enum": [ "DAILY", "WEEKLY", "MONTHLY" ], "description": "Frequency at which the report should be generated. The report is generated for the previous time period.\n\nFor example, if the DAILY report is generated on 1st of January, it will contain the data for the previous day (31st of December). If the WEEKLY report is scheduled for Wednesday, it will contain the data for the previous Tuesday to this week's Wednesday.", "example": "DAILY" }, "frequencyDay": { "type": "integer", "minimum": 1, "maximum": 31, "description": "Specific day (1=Monday, 7=Sunday) for report generation. Only for `frequencyType` WEEKLY.\n\nTo schedule a report for every day, set this value to `1`.", "example": 1 }, "format": { "type": "string", "enum": [ "CSV", "PDF", "JSON" ], "description": "File format for the generated report.", "example": "CSV" }, "channel": { "type": "string", "enum": [ "webhook", "email" ], "description": "Delivery method for the report:\n\n - `webhook` for API delivery\n\n - `email` for delivery via email", "example": "webhook" }, "email": { "type": "string", "format": "email", "description": "Email address for report delivery. Required when channel is `email`, ignored for the `webhook` channel.", "example": "reports@company.com" }, "reportParams": { "type": "object", "required": [ "reportType" ], "properties": { "reportType": { "type": "string", "enum": [ "TRANSACTION", "TRADING_VOLUME", "PAYMENT_VOLUME", "DIGITAL_ASSETS_VOLUME", "PAYMENT", "WALLET_BALANCE" ], "description": "The type of report to be generated. Use 'TRANSACTION' to get the transactions report.\n\n**Currently, only 'TRANSACTION' is supported**. More report types will be available in the future.", "example": "TRANSACTION" }, "walletId": { "type": "string", "description": "The ID of the wallet to generate the report for.", "example": "a:02502251969431:yyDut96:1" } } } } }, "examples": { "update_to_daily_webhook": { "summary": "Update to daily report via webhook", "value": { "time": "14:00", "timezone": "Europe/London", "frequencyType": "DAILY", "frequencyDay": 1, "format": "CSV", "channel": "webhook", "reportParams": { "reportType": "TRANSACTION", "walletId": "a:02502251969431:yyDut96:1" } } } } } } }, "responses": { "200": { "description": "Report schedule updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the updated report schedule.", "example": "3afd38a6-fc31-4775-87e0-eaa556447825" }, "createdBy": { "type": "string", "description": "Base64 encoded identifier of the user who created the schedule.", "example": "SLXh6jH2Q1ZnmgRpKAgdfY2tanB/t/PNMILtfKvh2gc=" }, "name": { "type": "string", "nullable": true, "description": "Optional name for the report schedule.", "example": null }, "accountReference": { "type": "string", "format": "uuid", "description": "Reference to the account this report schedule belongs to.", "example": "4e9d4fa8-29d7-11ed-84d9-0a878439b77f" }, "time": { "type": "string", "description": "Scheduled time for report generation in 24-hour format.", "example": "14:00" }, "timezone": { "type": "string", "description": "Timezone used for scheduling.", "example": "Europe/London" }, "frequencyType": { "type": "string", "enum": [ "DAILY", "WEEKLY", "MONTHLY" ], "description": "The frequency of report generation.", "example": "DAILY" }, "frequencyDay": { "type": "integer", "description": "Specific day for report generation based on frequency type.", "example": 1 }, "format": { "type": "string", "enum": [ "CSV", "PDF", "JSON" ], "description": "File format of the generated report (uppercase in response).", "example": "CSV" }, "channel": { "type": "string", "enum": [ "WEBHOOK", "EMAIL" ], "description": "Delivery method for the report (uppercase in response).", "example": "WEBHOOK" }, "email": { "type": "string", "format": "email", "nullable": true, "description": "Email address for delivery (`null` when channel is WEBHOOK).", "example": null }, "reportParams": { "type": "object", "description": "Parameters for the report configuration.", "properties": { "reportType": { "type": "string", "enum": [ "TRANSACTION" ], "description": "The type of report to be generated.", "example": "TRANSACTION" }, "walletId": { "type": "string", "description": "The ID of the wallet to generate the report for.", "example": "a:02502251969431:yyDut96:1" } } }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the report schedule was created.", "example": "2026-01-12T16:02:46Z" } } }, "examples": { "updated_daily_schedule": { "summary": "Updated weekly report schedule", "value": { "id": "3afd38a6-fc31-4775-87e0-eaa556447825", "createdBy": "SLXh6jH2Q1ZnmgRpKAgdfY2tanB/t/PNMILtfKvh2gc=", "name": null, "accountReference": "4e9d4fa8-29d7-11ed-84d9-0a878439b77f", "time": "14:00", "timezone": "Europe/London", "frequencyType": "WEEKLY", "frequencyDay": 3, "format": "JSON", "channel": "WEBHOOK", "email": null, "reportParams": { "reportType": "TRANSACTION", "walletId": "a:02502251969431:yyDut96:1" }, "createdAt": "2026-01-12T16:02:46Z" } } } } } }, "400": { "description": "Bad request - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "Error code identifier", "example": "bvnk:layer1:2100" }, "status": { "type": "string", "description": "HTTP status description", "example": "Bad Request" }, "message": { "type": "string", "description": "General error message", "example": "Validation failed" }, "details": { "type": "object", "properties": { "documentLink": { "type": "string", "nullable": true, "description": "Link to relevant documentation", "example": null }, "errors": { "type": "object", "description": "Field-specific validation errors", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } } } }, "examples": { "Invalid timezone": { "summary": "Invalid frequency day for monthly schedule", "value": { "code": "bvnk:layer1:2100", "status": "Bad Request", "message": "Validation failed", "details": { "documentLink": null, "errors": { "timezone": [ "Timezone is invalid." ], "createOrUpdateReportScheduleRequest": [ "Time and zone are invalid." ] } } } } } } } } } }, "delete": { "tags": [ "Wallets" ], "security": [ { "Hawk": [ "merchant" ] } ], "summary": "Delete report schedule", "description": "Deletes an existing report schedule. Only the user who created the schedule can delete it. Once deleted, no further reports will be generated according to this schedule.", "operationId": "deleteReportSchedule", "parameters": [ { "name": "scheduleId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Unique identifier of the report schedule to delete.", "example": "3afd38a6-fc31-4775-87e0-eaa556447825" } ], "responses": { "204": { "description": "Report schedule deleted successfully - No content returned" } } } }, "/ledger/v1/report-schedules/timezones": { "get": { "tags": [ "Wallets" ], "security": [ { "Hawk": [ "merchant" ] } ], "summary": "Get supported timezones", "description": "Retrieves a list of all supported timezones that can be used when creating or updating report schedules. Each timezone includes both the IANA timezone identifier and a human-readable label with UTC offset.", "operationId": "getSupportedTimezones", "responses": { "200": { "description": "Supported timezones retrieved successfully", "content": { "application/json": { "schema": { "type": "array", "description": "List of supported timezones", "items": { "type": "object", "properties": { "zoneId": { "type": "string", "description": "IANA timezone identifier that should be used in report schedule requests", "example": "Europe/London" }, "label": { "type": "string", "description": "Human-readable timezone label with UTC offset for display purposes", "example": "UTC+00:00 - Europe/London" } }, "required": [ "zoneId", "label" ] } }, "examples": { "timezone_list": { "summary": "List of supported timezones", "value": [ { "zoneId": "Pacific/Midway", "label": "UTC-11:00 - Pacific/Midway" }, { "zoneId": "Pacific/Honolulu", "label": "UTC-10:00 - Pacific/Honolulu" }, { "zoneId": "America/Anchorage", "label": "UTC-09:00 - America/Anchorage" }, { "zoneId": "America/Los_Angeles", "label": "UTC-08:00 - America/Los Angeles" }, { "zoneId": "America/Denver", "label": "UTC-07:00 - America/Denver" }, { "zoneId": "America/Chicago", "label": "UTC-06:00 - America/Chicago" }, { "zoneId": "America/New_York", "label": "UTC-05:00 - America/New York" }, { "zoneId": "America/Halifax", "label": "UTC-04:00 - America/Halifax" }, { "zoneId": "America/Argentina/Buenos_Aires", "label": "UTC-03:00 - America/Argentina/Buenos Aires" }, { "zoneId": "Atlantic/South_Georgia", "label": "UTC-02:00 - Atlantic/South Georgia" }, { "zoneId": "Atlantic/Azores", "label": "UTC-01:00 - Atlantic/Azores" }, { "zoneId": "Europe/London", "label": "UTC+00:00 - Europe/London" }, { "zoneId": "UTC", "label": "UTC+00:00 - UTC" }, { "zoneId": "Europe/Paris", "label": "UTC+01:00 - Europe/Paris" }, { "zoneId": "Europe/Athens", "label": "UTC+02:00 - Europe/Athens" }, { "zoneId": "Europe/Moscow", "label": "UTC+03:00 - Europe/Moscow" }, { "zoneId": "Asia/Dubai", "label": "UTC+04:00 - Asia/Dubai" }, { "zoneId": "Asia/Karachi", "label": "UTC+05:00 - Asia/Karachi" }, { "zoneId": "Asia/Dhaka", "label": "UTC+06:00 - Asia/Dhaka" }, { "zoneId": "Asia/Bangkok", "label": "UTC+07:00 - Asia/Bangkok" }, { "zoneId": "Asia/Singapore", "label": "UTC+08:00 - Asia/Singapore" }, { "zoneId": "Asia/Tokyo", "label": "UTC+09:00 - Asia/Tokyo" }, { "zoneId": "Australia/Sydney", "label": "UTC+10:00 - Australia/Sydney" }, { "zoneId": "Pacific/Guadalcanal", "label": "UTC+11:00 - Pacific/Guadalcanal" }, { "zoneId": "Pacific/Auckland", "label": "UTC+12:00 - Pacific/Auckland" } ] } } } } } } } }, "/api/v1/quote": { "post": { "tags": [ "Trading and Conversions" ], "summary": "Create quote", "description": "Creates a quote to convert currency between wallets.\n\nFor wallet-to-wallet payment quotes, the payment processing is synchronous. You can expect the following statuses in the response:\n\n| When | `quoteStatus` | `paymentStatus` |\n|------|-------------|---------------|\n| **Successful payment**|| |\n| Getting an estimate | `ESTIMATE` | `PENDING` |\n| Creating a quote | `PENDING` | `PENDING` |\n| Accepting the quote | `PAYMENT_OUT_PROCESSED` | `SUCCESS` |\n|**Failed payment**|| |\n| Pay-in fails | `PAYMENT_IN_FAILED` | `FAILED` |\n| Conversion fails | `CONVERSION_FAILED` | `FAILED` |\n| Pay-out fails | `PAYMENT_OUT_FAILED` | `FAILED` |\n\nIf you don't receive `\"paymentStatus\": \"SUCCESS\"` in the response, you can call `/api/v1/quote/{uuid}` to check the conversion progress.", "operationId": "quoteCreate", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteRequestDto" }, "examples": { "EUR to USDC": { "summary": "Convert EUR to USDC between wallets", "value": { "from": "EUR", "to": "USDC", "fromWalletLsid": "a:25052137356562:qjOSsJf:1", "toWalletLsid": "a:24092328494070:G5i4XZ9:2", "amountIn": 500, "useMinimum": false, "useMaximum": false, "payInMethod": "wallet", "payOutMethod": "wallet" } } } } } }, "parameters": [ { "name": "estimate", "in": "query", "description": "Create estimate quote", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteDto" } } } }, "400": { "$ref": "#/components/responses/BadRequestNoMessage" } }, "security": [ { "Hawk": [ "merchant" ] } ] } }, "/api/v1/quote/accept/{uuid}": { "put": { "tags": [ "Trading and Conversions" ], "summary": "Accept quote", "description": "Executes a quote.", "operationId": "quoteAccept", "parameters": [ { "name": "uuid", "in": "path", "description": "The quote UUID you are accepting.", "required": true, "schema": { "type": "string", "example": "5dc4e061-31c6-4b96-8c4d-0ea984aece0b" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "successUrl" ], "properties": { "successUrl": { "type": "string", "description": "The URL to redirect to after a successful conversion. Use `{{quote_id}}` as a placeholder for the quote UUID.", "example": "https://app.sandbox.bvnk.com/wallets/convert/complete/{{quote_id}}" } } }, "examples": { "Accept Quote": { "summary": "Accept the quote and execute conversion", "value": { "successUrl": "https://app.sandbox.bvnk.com/wallets/convert/complete/{{quote_id}}" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptedQuoteDto" } } } }, "400": { "$ref": "#/components/responses/BadRequestNoMessage" } }, "security": [ { "Hawk": [ "merchant" ] } ] } }, "/api/v1/quote/{uuid}": { "get": { "tags": [ "Trading and Conversions" ], "summary": "Get quote", "description": "Retrieves a specific quote.", "operationId": "quoteRead", "parameters": [ { "name": "uuid", "in": "path", "description": "UUID of the quote you are retrieving.", "required": true, "schema": { "type": "string", "example": "0a12a214-1619-43fa-9be1-0029f6a440a0" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteDto" } } } }, "400": { "$ref": "#/components/responses/BadRequestNoMessage" }, "404": { "description": "Not Found" } }, "security": [ { "Hawk": [ "merchant" ] } ] } }, "/api/v1/quote/{merchantId}": { "get": { "tags": [ "Trading and Conversions" ], "summary": "List quotes", "description": "Retrieves all quotes on a specific Merchant ID.", "operationId": "quoteList", "parameters": [ { "name": "merchantId", "in": "path", "description": "Merchant ID you are retrieving quotes from.", "required": true, "schema": { "type": "string", "example": "0a12a214-1619-43fa-9be1-0029f6a440a0" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/QuoteDto" } } } } }, "400": { "$ref": "#/components/responses/BadRequestNoMessage" }, "404": { "description": "Not Found" } }, "security": [ { "Hawk": [ "x-example" ] } ] } }, "/api/country": { "get": { "tags": [ "Onboarding" ], "summary": "Fetch country codes", "description": "Fetch list of all countries and associated ISO codes.", "operationId": "listCountries", "parameters": [ { "name": "max", "in": "query", "description": "Maximum number of items in response.", "required": false, "schema": { "type": "integer", "example": 135 } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CountryCodeDto" } } } } }, "400": { "$ref": "#/components/responses/BadRequestNoMessage" }, "404": { "description": "Not Found" } }, "security": [ { "Hawk": [ "x-example" ] } ] } }, "/api/v1/agreement": { "get": { "tags": [ "Onboarding" ], "summary": "Fetch agreements", "description": "Fetch all required agreement documents needed to onboard an Embedded Partner Merchant.", "operationId": "getAgreements", "parameters": [ { "name": "product", "in": "query", "description": "Type of product, currently only `embedded`.", "required": true, "schema": { "type": "string", "example": "embedded" } }, { "name": "country", "in": "query", "description": "ISO country code for the correct agreeements", "required": false, "schema": { "type": "string", "example": "DE" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgreementsDto" } } } }, "400": { "$ref": "#/components/responses/BadRequestNoMessage" }, "404": { "description": "Not Found" } }, "security": [ { "Hawk": [ "x-example" ] } ] } }, "/ledger/v2/wallets": { "post": { "tags": [ "Wallets" ], "summary": "Create wallet", "description": ":::info Beta\nThis endpoint is currently in beta. The API contract may change during this phase. We recommend testing thoroughly in sandbox before using it in production.\n:::\n\nCreates a crypto or fiat wallet associated with a wallet profile. You can create wallets for yourself or for your customers.", "operationId": "ledgerWalletCreateV2", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyNew" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerWalletV2CreateRequest" }, "example": { "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "currency": "USD", "name": "My Business Wallet", "profileId": "fiat:usd:ijkm9012" } } } }, "responses": { "201": { "description": "Wallet created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerWalletV2Response" }, "examples": { "Fiat wallet": { "summary": "Fiat wallet", "value": { "id": "a:25060945127830:rTgK3wN:1", "name": "USD SWIFT", "customer": { "id": "a1f84b6c-9e23-4d17-b590-7c4a83de2f10", "name": "Meridian Healthcare" }, "status": "ACTIVE", "balance": { "amount": 0.00, "currency": "USD" }, "paymentInstruments": [ { "type": "FIAT", "accountHolderName": "MERIDIAN HEALTHCARE SERVICES LTD", "accountHolderAddress": { "addressLine1": "78 Whitechapel High Street", "city": "London", "country": "GB", "postCode": "E1 7QX" }, "accountNumber": "GB82WEST12345698765432", "remittanceInformationPrefix": "REF NP7A421", "bankDetails": { "name": "Westminster Banking Group PLC", "address": { "addressLine1": "1 Poultry", "city": "London", "country": "GB", "postCode": "EC2R 8EJ" }, "bic": "SAPYGB2L", "nid": { "value": "200415", "type": "SORT_CODE" } } } ], "createdAt": "2025-06-09T14:05:12.830Z", "updatedAt": "2025-06-09T14:05:17.384Z" } }, "Crypto wallet": { "summary": "Crypto wallet", "value": { "id": "a:25060945183207:vLpR8mC:1", "name": "BTC Holdings", "customer": { "id": "c7a91d3e-48f2-4b76-a835-2e6d09f1c4b8", "name": "Greenfield Logistics" }, "status": "ACTIVE", "balance": { "amount": 0.00, "currency": "BTC" }, "paymentInstruments": [ { "type": "CRYPTO", "address": "bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4", "network": "BTC", "tag": "btc" } ], "createdAt": "2025-06-09T14:06:23.207Z", "updatedAt": "2025-06-09T14:06:45.129Z" } } } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "badRequest": { "summary": "See the BVNK Errors reference for details.", "value": { "code": "bvnk:ledger:4001", "status": "Bad Request", "traceId": "abc123-def456-ghi789", "message": "Received Bad Request", "details": { "documentLink": "https://docs.bvnk.com/reference/errors#/" } } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthorized": { "summary": "See the BVNK Errors reference for details.", "value": { "code": "bvnk:payment:0003", "status": "Unauthorized", "traceId": "abc123-def456-ghi789", "message": "Forbidden → received request with wrong authentication details", "details": { "documentLink": "https://docs.bvnk.com/reference/errors#/" } } } } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "forbidden": { "summary": "See the BVNK Errors reference for details.", "value": { "code": "bvnk:ledger:4003", "status": "Forbidden", "traceId": "abc123-def456-ghi789", "message": "FORBIDDEN! You don't have the necessary permissions to access this resource.", "details": { "documentLink": "https://docs.bvnk.com/reference/errors#/" } } } } } } }, "409": { "description": "Idempotency conflict — a request with this idempotency key is already in flight.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "conflict": { "summary": "Concurrent request with same idempotency key.", "value": { "code": "bvnk:ledger:4004", "status": "Conflict", "traceId": "abc123-def456-ghi789", "message": "Wallet creation request with the same idempotency key and account reference exists", "details": { "documentLink": "https://docs.bvnk.com/reference/errors#/" } } } } } } }, "422": { "description": "Idempotency key reuse — the same key was previously used with a different request payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unprocessableEntity": { "summary": "Idempotency key reused with different payload.", "value": { "code": "bvnk:ledger:4004", "status": "Unprocessable Entity", "traceId": "abc123-def456-ghi789", "message": "Wallet creation request with the same idempotency key and account reference exists", "details": { "documentLink": "https://docs.bvnk.com/reference/errors#/" } } } } } } }, "429": { "description": "Rate limited — too many requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "rateLimited": { "summary": "Rate limit exceeded.", "value": { "code": "bvnk:rate-limit:0001", "status": "Too Many Requests", "traceId": "abc123-def456-ghi789", "message": "Rate limit exceeded. Retry after the period indicated in the Retry-After header.", "details": { "documentLink": "https://docs.bvnk.com/reference/errors#/" } } } } } } } }, "security": [ { "Hawk": [ "merchant" ] } ] }, "get": { "tags": [ "Fiat Payments" ], "summary": "Get wallets", "description": ":::info Beta\nThis endpoint is currently in beta. The API contract may change during this phase. We recommend testing thoroughly in sandbox before using it in production.\n:::\n\nShows all *Direct* and *Customer* wallet types. Results are summaries only (**payment instruments are not included**); use `GET /ledger/v2/wallets/{id}` to retrieve a single wallet with full details including payment instruments.\n\nThe endpoint uses the [Lucene query syntax](https://lucene.apache.org/core/2_9_4/queryparsersyntax.html), for example, `GET https://api.bvnk.com/ledger/v2/wallets?q=customerId:550e8400-e29b-41d4-a716-446655440000 AND status:(ACTIVE OR INACTIVE)` returns all active and inactive wallets for that customer.\n\n**Note:** Field names in the `q` search expression are case-sensitive. If you use a field that is not recognised, it is ignored.\n\nOperator `OR` is only supported within the same field (group alternatives with parentheses), not across different fields.\n\n- Supported: `?q=currency:(USD OR EUR)`\n- Not supported: `?q=currency:USD OR customerId:550e8400-e29b-41d4-a716-446655440000`", "operationId": "ledgerWalletListV2", "parameters": [ { "name": "q", "in": "query", "description": "Search and filter expression in the Lucene syntax. Use `q` with `AND` / `OR` to combine filters. You can specify only one `currency` or `customerId` value, but several `status` and `currencyType` values.\n\n- `customerId`: Filter by customer ID. Values must be valid UUIDs.\n- `status`: Filter by the wallet status. Values must be `ACTIVE`, `INACTIVE`, or `TERMINATED`.\n- `currencyType`: Filter by the wallet's currency type. Values must be `FIAT` or `CRYPTO`.\n- **`currency`**: Filter by currency codes. Allowed values: `USD`, `EUR`, `GBP`, `USDT`, `POL`, `PYUSD`, `BTC`, `SOL`, `BNB`, `XRP`, `ETH`, `LTC`, `USDC`, `USDG`, `TRX`, `EURC`, `DOGE`.", "required": false, "schema": { "type": "string", "example": "customerId:550e8400-e29b-41d4-a716-446655440000 AND status:(ACTIVE OR INACTIVE)" } }, { "$ref": "#/components/parameters/PageNumber" }, { "$ref": "#/components/parameters/PageSize" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerWalletV2ListResponse" }, "example": { "content": [ { "id": "a:25031472839104:kR7mHxQ:1", "name": "EUR Operations", "status": "ACTIVE", "balance": { "amount": 48250.75, "currency": "EUR" }, "createdAt": "2025-03-14T09:12:33.104Z", "updatedAt": "2025-06-02T11:45:07.346Z" }, { "id": "a:25041855293741:pWnL4vB:1", "name": "USD Payroll", "customer": { "id": "c7a91d3e-48f2-4b76-a835-2e6d09f1c4b8", "name": "Greenfield Logistics" }, "status": "ACTIVE", "balance": { "amount": 125400.00, "currency": "USD" }, "createdAt": "2025-04-18T08:30:30.565Z", "updatedAt": "2025-06-10T14:22:19.873Z" }, { "id": "a:25041855367892:xNcD8kT:1", "name": "GBP Collections", "customer": { "id": "c7a91d3e-48f2-4b76-a835-2e6d09f1c4b8", "name": "Greenfield Logistics" }, "status": "ACTIVE", "balance": { "amount": 8730.50, "currency": "GBP" }, "createdAt": "2025-04-18T08:31:07.892Z", "updatedAt": "2025-06-08T16:05:43.291Z" }, { "id": "a:25052061784520:mVeJ2rA:1", "name": "USD Disbursements", "customer": { "id": "a1f84b6c-9e23-4d17-b590-7c4a83de2f10", "name": "Meridian Healthcare" }, "status": "ACTIVE", "balance": { "amount": 52080.00, "currency": "USD" }, "createdAt": "2025-05-20T12:16:24.520Z", "updatedAt": "2025-06-11T09:40:51.684Z" }, { "id": "a:25052061801337:hQwP5nF:1", "name": "EUR Supplier Payments", "customer": { "id": "a1f84b6c-9e23-4d17-b590-7c4a83de2f10", "name": "Meridian Healthcare" }, "status": "INACTIVE", "balance": { "amount": 0.00, "currency": "EUR" }, "createdAt": "2025-05-20T12:16:41.337Z", "updatedAt": "2025-05-28T10:02:15.904Z" } ], "pageable": { "pageNumber": 0, "pageSize": 50 }, "hasNext": true } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "badRequest": { "summary": "See the BVNK Errors reference for details.", "value": { "code": "bvnk:ledger:4001", "status": "Bad Request", "traceId": "abc123-def456-ghi789", "message": "Received Bad Request", "details": { "documentLink": "https://docs.bvnk.com/reference/errors#/" } } } } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "forbidden": { "summary": "See the BVNK Errors reference for details.", "value": { "code": "bvnk:ledger:4003", "status": "Forbidden", "traceId": "abc123-def456-ghi789", "message": "FORBIDDEN! You don't have the necessary permissions to access this resource.", "details": { "documentLink": "https://docs.bvnk.com/reference/errors#/" } } } } } } } }, "security": [ { "Hawk": [ "merchant" ] } ] } }, "/ledger/v2/wallets/profiles": { "get": { "summary": "Get wallet profiles", "description": ":::info Beta\nThis endpoint is currently in beta. The API contract may change during this phase. We recommend testing thoroughly in sandbox before using it in production.\n:::\n\nReturns available wallet profiles based on optional filters for currency codes and payment methods. For more information on how to apply it in the Embedded Wallets flow, refer to the [Retrieve wallet profiles](/bvnk/get-started/set-up-wallets/#retrieve-wallet-profiles) guide.\n\nThe endpoint uses the [Lucene query syntax](https://lucene.apache.org/core/2_9_4/queryparsersyntax.html), for example, `GET https://api.bvnk.com/ledger/v2/wallets/profiles?q=customerId:550e8400-e29b-41d4-a716-446655440000 AND currency:USD` returns USD wallet profiles for that customer.\n\n**Note:** Field names in the `q` search expression are case-sensitive. If you use a field that is not recognised, it is ignored.\n\nOperator `OR` is only supported within the same field (group alternatives with parentheses), not across different fields.\n\n- Supported: `?q=currency:(USD OR EUR)`\n- Not supported: `?q=currency:USD OR customerId:550e8400-e29b-41d4-a716-446655440000`", "operationId": "walletProfiles2", "tags": [ "Fiat Payments" ], "security": [ { "Hawk": [ "merchant" ] } ], "parameters": [ { "name": "q", "in": "query", "description": "Search and filter expression in the Lucene syntax. Use `q` with `AND` / `OR` to combine filters. You can specify only one `currency` or `customerId` value.\n\n- **`currency`**: Filter by currency codes. Allowed values: `USD`, `EUR`, `GBP`, `USDT`, `POL`, `PYUSD`, `BTC`, `SOL`, `BNB`, `XRP`, `ETH`, `LTC`, `USDC`, `USDG`, `TRX`, `EURC`, `DOGE`.\n- **`method`**: Filter by payment methods. Allowed values: `ACH`, `ACH_SAME_DAY`, `FEDWIRE`, `SWIFT`, `FASTER_PAYMENT`, `CHAPS`, `SEPA_CT`, `SEPA_INST`, `RTP`, `BOOK`, `FEDNOW`.\n- **`customerId`**: Filter by customer ID. Values must be valid UUIDs. If provided, only profiles that are available for the customer's account will be returned.", "required": false, "schema": { "type": "string", "example": "customerId:550e8400-e29b-41d4-a716-446655440000 AND currency:USD" } }, { "$ref": "#/components/parameters/PageNumber" }, { "$ref": "#/components/parameters/PageSize" } ], "responses": { "200": { "description": "List of wallet profiles matching the query", "content": { "application/json": { "examples": { "Common": { "summary": "Common", "value": { "totalElements": 9, "totalPages": 1, "content": [ { "id": "crypto:custodial:a0b8a34c", "currencies": [ "BTC", "SOL", "EURC", "BNB", "XRP", "ETH", "USDT", "DOGE", "USDC", "TRX", "POL" ], "methods": [] }, { "id": "fiat:usd:141d6bae", "currencies": [ "USD" ], "methods": [ "SWIFT" ] }, { "id": "fiat:gbp:16f367db", "currencies": [ "GBP" ], "methods": [ "FASTER_PAYMENT", "CHAPS" ] }, { "id": "fiat:usd:18f9a1bf", "currencies": [ "USD" ], "methods": [ "SWIFT" ] }, { "id": "fiat:usd:2a3fe604", "currencies": [ "USD" ], "methods": [] }, { "id": "fiat:usd:2d4901e0", "currencies": [ "USD" ], "methods": [ "BOOK" ] }, { "id": "fiat:eur:3392c62e", "currencies": [ "EUR" ], "methods": [ "SEPA_CT", "SEPA_INST" ] }, { "id": "fiat:usd:3a343359", "currencies": [ "USD" ], "methods": [ "SWIFT" ] }, { "id": "fiat:usd:520e259f", "currencies": [ "USD" ], "methods": [ "FEDWIRE", "ACH_SAME_DAY", "RTP", "BOOK", "ACH", "FEDNOW" ] } ], "pageable": { "pageNumber": 0, "pageSize": 50 }, "hasNext": false } } }, "schema": { "type": "object", "properties": { "totalElements": { "type": "integer", "description": "Total number of wallet profiles matching the query.", "example": 6 }, "totalPages": { "type": "integer", "description": "Total number of pages available.", "example": 1 }, "content": { "type": "array", "description": "List of wallet profiles.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Profile ID to be assigned to the Customer's wallet based on the currency and payment method.", "example": "fiat:gbp:abcd1234" }, "currencies": { "type": "array", "description": "Wallet's currency.", "items": { "type": "string", "enum": [ "USD", "EUR", "GBP", "USDT", "POL", "PYUSD", "BTC", "SOL", "BNB", "XRP", "ETH", "LTC", "USDC", "USDG", "TRX", "EURC", "DOGE" ] } }, "methods": { "type": "array", "description": "Payment methods available for the wallet.", "items": { "type": "string", "enum": [ "ACH", "ACH_SAME_DAY", "FEDWIRE", "SWIFT", "FASTER_PAYMENT", "CHAPS", "SEPA_CT", "SEPA_INST", "RTP", "BOOK", "FEDNOW" ] } } }, "required": [ "id", "currencies", "methods" ] } }, "pageable": { "type": "object", "description": "Pagination details for the current request.", "properties": { "pageNumber": { "type": "integer", "description": "Current page number (zero-based).", "example": 0 }, "pageSize": { "type": "integer", "description": "Number of items per page.", "example": 50 } }, "required": [ "pageNumber", "pageSize" ] }, "hasNext": { "type": "boolean", "description": "Whether there is a next page of results.", "example": false } }, "required": [ "totalElements", "totalPages", "content", "pageable", "hasNext" ] } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "badRequest": { "summary": "See the BVNK Errors reference for details.", "value": { "code": "bvnk:ledger:4001", "status": "Bad Request", "traceId": "abc123-def456-ghi789", "message": "Received Bad Request", "details": { "documentLink": "https://docs.bvnk.com/reference/errors#/" } } } } } } }, "401": { "description": "Authentication required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "unauthorized": { "summary": "See the BVNK Errors reference for details.", "value": { "code": "bvnk:payment:0003", "status": "Unauthorized", "traceId": "abc123-def456-ghi789", "message": "Forbidden → received request with wrong authentication details", "details": { "documentLink": "https://docs.bvnk.com/reference/errors#/" } } } } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "forbidden": { "summary": "See the BVNK Errors reference for details.", "value": { "code": "bvnk:ledger:4003", "status": "Forbidden", "traceId": "abc123-def456-ghi789", "message": "FORBIDDEN! You don't have the necessary permissions to access this resource.", "details": { "documentLink": "https://docs.bvnk.com/reference/errors#/" } } } } } } }, "429": { "description": "Rate limited — too many requests.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "rateLimited": { "summary": "Rate limit exceeded.", "value": { "code": "bvnk:rate-limit:0001", "status": "Too Many Requests", "traceId": "abc123-def456-ghi789", "message": "Rate limit exceeded. Retry after the period indicated in the Retry-After header.", "details": { "documentLink": "https://docs.bvnk.com/reference/errors#/" } } } } } } } } } }, "/ledger/v2/wallets/{id}": { "get": { "tags": [ "Fiat Payments" ], "summary": "Get wallet", "description": ":::info Beta\nThis endpoint is currently in beta. The API contract may change during this phase. We recommend testing thoroughly in sandbox before using it in production.\n:::\n\nRetrieves a single fiat or crypto wallet by its ID. You can retrieve your own or your customer's wallet.", "operationId": "ledgerWalletReadV2", "parameters": [ { "name": "id", "in": "path", "description": "The wallet identifier.", "required": true, "example": "a:25031472839104:kR7mHxQ:1", "schema": { "type": "string", "example": "a:25031472839104:kR7mHxQ:1" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerWalletV2Response" }, "examples": { "Fiat": { "summary": "Fiat wallet", "value": { "id": "a:25031472839104:kR7mHxQ:1", "name": "USD ACH", "status": "ACTIVE", "balance": { "amount": 48250.75, "currency": "USD" }, "paymentInstruments": [ { "type": "FIAT", "accountHolderName": "Greenfield Logistics Ltd", "accountNumber": "846203917458", "bankDetails": { "name": "Atlantic Federal Bank", "bic": "ATFEUS33", "nid": { "value": "621353", "type": "SORT_CODE" } } } ], "createdAt": "2025-03-14T09:12:33.104Z", "updatedAt": "2025-06-02T11:45:07.463Z" } }, "Crypto": { "summary": "Crypto wallet", "value": { "id": "a:25041867214503:bNx9TpL:1", "name": "USDC Treasury", "status": "ACTIVE", "balance": { "amount": 14727.556775, "currency": "USDC" }, "paymentInstruments": [ { "type": "CRYPTO", "address": "0x4a7b3c91d8e2f056a1b4c7d9e3f28a6b5c0d1e4f", "network": "Ethereum", "tag": "eth" } ], "createdAt": "2025-04-18T14:46:19.458Z", "updatedAt": "2025-06-10T08:33:52.463Z" } }, "Customer": { "summary": "Customer wallet", "value": { "id": "a:25052061784520:mVeJ2rA:1", "name": "USD SWIFT", "customer": { "id": "a1f84b6c-9e23-4d17-b590-7c4a83de2f10", "name": "Meridian Healthcare" }, "status": "ACTIVE", "balance": { "amount": 52080.00, "currency": "USD" }, "paymentInstruments": [ { "type": "FIAT", "accountHolderName": "MERIDIAN HEALTHCARE SERVICES LTD", "accountHolderAddress": { "addressLine1": "14 Canary Wharf", "addressLine2": "Floor 9", "city": "London", "country": "GB", "postCode": "E14 5AB" }, "accountNumber": "GB29MDTR60000131926819", "remittanceInformationPrefix": "REF HK4F291", "bankDetails": { "name": "Meridian Trust Bank PLC", "address": { "addressLine1": "250 Bishopsgate", "city": "London", "country": "GB", "postCode": "EC2M 4AA" }, "bic": "MDTRGB2LXXX", "nid": { "value": "600001", "type": "SORT_CODE" } } } ], "createdAt": "2025-05-20T12:16:24.520Z", "updatedAt": "2025-06-11T09:40:51.060Z" } } } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "badRequest": { "summary": "See the BVNK Errors reference for details.", "value": { "code": "bvnk:ledger:4001", "status": "Bad Request", "traceId": "abc123-def456-ghi789", "message": "Received Bad Request", "details": { "documentLink": "https://docs.bvnk.com/reference/errors#/" } } } } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "forbidden": { "summary": "See the BVNK Errors reference for details.", "value": { "code": "bvnk:ledger:4003", "status": "Forbidden", "traceId": "abc123-def456-ghi789", "message": "FORBIDDEN! You don't have the necessary permissions to access this resource.", "details": { "documentLink": "https://docs.bvnk.com/reference/errors#/" } } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "security": [ { "Hawk": [ "merchant" ] } ] } }, "/ledger/v1/wallets": { "post": { "tags": [ "Fiat Payments" ], "summary": "Create fiat wallet", "description": "Creates a fiat wallet for a specific Customer, generating a unique virtual account tied to the wallet.\n\n---\n\nFor more information, how to apply it in the Embedded Wallets flow, refer to the [Create a customer wallet](/bvnk/get-started/set-up-wallets/#create-a-wallet) guide.", "operationId": "createCustomerWallet", "deprecated": true, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWalletRequest" }, "examples": { "Fiat Wallet": { "summary": "Create a USD fiat wallet for a customer", "value": { "currencyCode": "USD", "name": "Customer USD Wallet", "customerReference": "b4e5c3d1-9a42-4e7b-8f34-7c6b2a89f3df", "instruction": { "walletProfile": "18f9a1bf-0d77-45f5-b5ff-1e90411d88ce", "type": "FIAT", "virtualAccountRequired": true } } }, "Crypto Wallet": { "summary": "Create a USDT crypto wallet for a customer", "value": { "currencyCode": "USDT", "name": "Customer USDT Wallet", "customerReference": "b4e5c3d1-9a42-4e7b-8f34-7c6b2a89f3df", "instruction": { "walletProfile": "f7fdb837-5053-45b0-86c8-96ece6fe02d0", "type": "CRYPTO", "virtualAccountRequired": true } } } } } } }, "responses": { "201": { "description": "Wallet created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletResponse" }, "examples": { "Fiat": { "summary": "Fiat Wallet Creation", "value": { "id": "a:25032877416178:1PL2yxP:1", "accountReference": "5bc49988-fe25-408f-bccc-3e0fe96cf322", "customerReference": "fb8c0b12-6552-429e-955e-70af0873331", "name": "USD ", "status": "ACTIVE", "balance": { "value": 0, "currencyCode": "USD" }, "ledgers": [ { "type": "FIAT", "accountHolderName": "Conrad Koch", "accountNumber": "900685240468", "code": "101019644", "accountNumberFormat": "ABA", "paymentReference": null, "bank": { "identificationCode": "101019644", "name": null, "address": null } } ], "capabilities": [ "SAFEGUARDED" ] } }, "Crypto": { "summary": "Crypto Wallet Creation", "value": { "id": "a:25065234155735:vE9Q6zE:1", "accountReference": "1274ab69-540c-4499-8b32-f51930c9bfed", "customerReference": "fb8c0b12-6552-429e-955e-70af08733310", "name": "USDT Test", "status": "ACTIVE", "balance": { "value": 0, "currencyCode": "USDT" }, "ledgers": [], "capabilities": [] } } } } } }, "400": { "description": "Bad request." }, "403": { "description": "Forbidden." } }, "security": [ { "Hawk": [ "merchant" ] } ] }, "get": { "tags": [ "Fiat Payments" ], "summary": "List customer's fiat wallets", "description": "Retrieves a list of wallets for your customers.\n\n• **Without parameters**: Returns all wallets associated with all your customers.\n\n• **With `customerReference` parameter**: Returns wallets for a specific customer only. Usage: `https://api.bvnk.com/ledger/v1/wallets?customerReference=550e8400-e29b-41d4-a716-446655440000\n`.\n\n**Deprecated:** use `GET /ledger/v2/wallets` instead.", "operationId": "ledgerWalletList", "deprecated": true, "parameters": [ { "name": "currencyCode", "in": "query", "description": "The currency code for the wallet.", "required": false, "schema": { "type": "string", "enum": [ "USD", "EUR", "GBP", "USDT", "POL", "PYUSD", "BTC", "SOL", "BNB", "XRP", "ETH", "LTC", "USDC", "USDG", "TRX" ], "example": "GBP" } }, { "name": "customerReference", "in": "query", "description": "Reference to the customer who owns the wallet.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "33e85982-e22b-4e8b-9057-445cf000bea9" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Size" }, { "name": "sort", "in": "query", "description": "Sorting criteria in the format `property,`. Default sort order is asc.", "required": false, "schema": { "type": "string", "example": "currencyCode,desc" } }, { "$ref": "#/components/parameters/OffsetInteger" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/WalletResponse" } }, "pageable": { "type": "object", "properties": { "pageNumber": { "type": "integer", "example": 0, "description": "The current page number." }, "pageSize": { "type": "integer", "example": 20, "description": "Number of items per page." }, "offset": { "type": "integer", "example": 0, "description": "Offset from the start, calculated as `pageNumber * pageSize`." } } }, "totalPages": { "type": "integer", "example": 3, "description": "The total number of available pages" }, "totalElements": { "type": "integer", "example": 57, "description": "The total number of elements across all pages" }, "numberOfElements": { "type": "integer", "example": 20, "description": "The number of elements in the current page" }, "last": { "type": "boolean", "example": false, "description": "Whether this is the last page" }, "first": { "type": "boolean", "example": true, "description": "Whether this is the first page" }, "empty": { "type": "boolean", "example": false, "description": "Whether the page contains no elements" } } }, "examples": { "Fiat wallet with SWIFT": { "summary": "Fiat wallet with SWIFT enabled", "value": { "content": [ { "id": "a:25031027518203:IUMTTAY:1", "accountReference": "3399c975-e1c1-4acf-9a90-6cfbdcdeaaea", "customerReference": "b94dcf2a-d377-469e-8846-e21f65b18a77", "name": "EUR SWIFT Wallet", "status": "ACTIVE", "balance": { "value": 1500.5, "currencyCode": "EUR" }, "ledgers": [ { "type": "FIAT", "accountHolderName": "System Pay Services (Malta) Limited", "accountNumber": "DE10601202004579784373", "code": "BEUCESMMXXX", "accountNumberFormat": "SWIFT", "paymentReference": "REF DZ0XJL4", "bank": { "identificationCode": "BEUCESMMXXX", "name": "Banco Europa Continental, S.A.", "address": { "addressLine1": "De San Nicolas 4", "city": "Bilbao", "postalCode": "48005", "countryCode": "ES" } } } ], "capabilities": "SAFEGUARDED" } ], "pageable": { "pageNumber": 0, "pageSize": 20, "offset": 0 }, "totalPages": 1, "totalElements": 1, "numberOfElements": 1, "last": true, "first": true, "empty": false } }, "Crypto wallet": { "summary": "Crypto wallet", "value": { "content": [ { "id": "a:24092328494070:G5i4XZ9:1", "accountReference": "4488d086-f2c2-5bdf-0b01-7dgcedfbfbb0", "customerReference": "c05edf3b-e488-580f-9958-f32g76c29b88", "name": "USDT Crypto Wallet", "status": "ACTIVE", "balance": { "value": 250, "currencyCode": "USDT" }, "ledgers": [ { "type": "CRYPTO", "address": "0x1234567890abcdef1234567890abcdef12345678", "network": "ETHEREUM", "tag": "eth" } ], "capabilities": "SAFEGUARDED" } ], "pageable": { "pageNumber": 0, "pageSize": 20, "offset": 0 }, "totalPages": 1, "totalElements": 1, "numberOfElements": 1, "last": true, "first": true, "empty": false } } } } } } }, "security": [ { "Hawk": [ "merchant" ] } ] } }, "/ledger/v1/wallets/profiles": { "get": { "summary": "Get wallet profiles", "description": "Returns available wallet profiles based on optional filters for currency codes and payment methods.\n\nFor more information, how to apply it in the Embedded Wallets flow, refer to the [Retrieve wallet profiles](/bvnk/get-started/set-up-wallets/#retrieve-wallet-profiles) guide.", "operationId": "walletProfiles", "deprecated": true, "tags": [ "Fiat Payments" ], "security": [ { "Hawk": [ "merchant" ] } ], "parameters": [ { "name": "currencyCodes", "in": "query", "description": "Filter by currency codes.\n\nNot all cryptocurrencies may be supported, as this depends on the specific jurisdiction. For example, for USA you can use only `BTC`, `SOL`, `ETH`, `USDT`, `USDC`, `TRX`.", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "USD", "EUR", "GBP", "USDT", "POL", "PYUSD", "BTC", "SOL", "BNB", "XRP", "ETH", "LTC", "USDC", "USDG", "TRX" ] }, "default": [ "USD" ], "example": [ "EUR", "GBP" ] }, "style": "form", "explode": true }, { "name": "paymentMethods", "in": "query", "description": "Filter by payment methods.\n\nIf you request an ACH Same Day payout outside its available window, it will be process as a next-day payout. However, the ACH Same Day fee may still be incurred.", "required": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "ACH", "ACH_SAME_DAY", "FEDWIRE", "SWIFT", "FASTER_PAYMENT", "SEPA_CT", "SEPA_INST" ] }, "default": [ "SWIFT" ], "example": [ "ACH", "FASTER_PAYMENT" ] }, "style": "form", "explode": true } ], "responses": { "200": { "description": "List of wallet profiles matching the query", "content": { "application/json": { "examples": { "Common": { "summary": "Common", "value": { "profiles": [ { "reference": "bd72bff2-6842-4212-9aa3-9298597d7d6e", "currencyCodes": [ "GBP" ], "paymentMethods": [ "FASTER_PAYMENT" ] }, { "reference": "c143fce7-a0e4-4475-86cd-ed37bc30efa5", "currencyCodes": [ "EUR" ], "paymentMethods": [ "SWIFT" ] }, { "reference": "18f9a1bf-0d77-45f5-b5ff-1e90411d88ce", "currencyCodes": [ "USD" ], "paymentMethods": [ "SWIFT" ] }, { "reference": "2a3fe604-2b14-4009-90b3-1e48f1a38b11", "currencyCodes": [ "USD" ], "paymentMethods": [ "ACH", "FEDWIRE" ] }, { "reference": "fe55d078-eaad-4c8b-a917-15170548df67", "currencyCodes": [ "EUR" ], "paymentMethods": [ "SEPA_CT", "SEPA_INST" ] } ] } }, "Spain": { "summary": "Spain", "value": { "profiles": [ { "reference": "f7fdb837-5053-45b0-86c8-96ece6fe02d0", "currencyCodes": [ "USDT", "PYUSD", "POL", "BTC", "SOL", "BNB", "XRP", "ETH", "USDC", "USDG", "LTC", "TRX" ], "paymentMethods": [] } ] } }, "USA": { "summary": "USA", "value": { "profiles": [ { "reference": "a0b8a34c-bfb9-43d8-9ee4-6eb076d107c0", "currencyCodes": [ "USDT", "BTC", "SOL", "ETH", "USDC", "USDG", "TRX" ], "paymentMethods": [] } ] } } }, "schema": { "type": "object", "properties": { "profiles": { "type": "array", "items": { "type": "object", "properties": { "reference": { "type": "string", "format": "uuid", "description": "Reference to be assigned to the Customer's wallet based on the currency and payment method.", "example": "bd72bff2-6842-4212-9aa3-9298597d7d6e" }, "currencyCodes": { "type": "array", "description": "Wallet's currency.", "items": { "type": "string", "enum": [ "USD", "EUR", "GBP", "USDT", "POL", "PYUSD", "BTC", "SOL", "BNB", "XRP", "ETH", "LTC", "USDC", "USDG", "TRX" ] } }, "paymentMethods": { "type": "array", "description": "Payment methods available for the wallet.", "items": { "type": "string", "enum": [ "ACH", "ACH_SAME_DAY", "FEDWIRE", "SWIFT", "FASTER_PAYMENT", "SEPA_CT", "SEPA_INST" ] } } }, "required": [ "reference", "currencyCodes", "paymentMethods" ] } } }, "required": [ "profiles" ] } } } } } } }, "/ledger/v1/wallets/{id}": { "get": { "tags": [ "Fiat Payments" ], "summary": "Get fiat wallet", "description": "Retrieves a specific wallet by its ID.\n\n**Deprecated:** use `GET /ledger/v2/wallets/{id}` instead.", "operationId": "ledgerWalletRead", "deprecated": true, "parameters": [ { "name": "id", "in": "path", "description": "The ID of the wallet that you want to retrieve", "required": true, "schema": { "type": "string", "example": "a:24092328494070:G5i4XZ9:1" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletResponse" }, "examples": { "Fiat wallet with SWIFT": { "summary": "Fiat wallet with SWIFT enabled", "value": { "id": "a:25031027518203:IUMTTAY:1", "accountReference": "3399c975-e1c1-4acf-9a90-6cfbdcdeaaea", "customerReference": "b94dcf2a-d377-469e-8846-e21f65b18a77", "name": "EUR SWIFT Wallet", "status": "ACTIVE", "balance": { "value": 1500.5, "currencyCode": "EUR" }, "ledgers": [ { "type": "FIAT", "accountHolderName": "System Pay Services (Malta) Limited", "accountNumber": "DE10601202004579784373", "code": "BEUCESMMXXX", "accountNumberFormat": "SWIFT", "paymentReference": "REF DZ0XJL4", "bank": { "identificationCode": "BEUCESMMXXX", "name": "Banco Europa Continental, S.A.", "address": { "addressLine1": "De San Nicolas 4", "city": "Bilbao", "postalCode": "48005", "countryCode": "ES" } } } ], "capabilities": "SAFEGUARDED" } }, "Crypto wallet": { "summary": "Crypto wallet", "value": { "id": "a:24092328494070:G5i4XZ9:1", "accountReference": "4488d086-f2c2-5bdf-0b01-7dgcedfbfbb0", "customerReference": "c05edf3b-e488-580f-9958-f32g76c29b88", "name": "USDT Crypto Wallet", "status": "ACTIVE", "balance": { "value": 250, "currencyCode": "USDT" }, "ledgers": [ { "type": "CRYPTO", "address": "0x1234567890abcdef1234567890abcdef12345678", "network": "ETHEREUM", "tag": "eth" } ], "capabilities": "SAFEGUARDED" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "example1": { "summary": "Resource Not Found", "value": { "code": "bvnk:ledger:5001", "status": "Not Found", "traceId": "abc123-def456-ghi789", "message": "Wallet not found" } } } } } } }, "security": [ { "Hawk": [ "merchant" ] } ] } }, "/ledger/v2/wallets/{id}/actions": { "post": { "tags": [ "Fiat Payments" ], "summary": "Execute wallet action", "description": ":::info Beta\nThis endpoint is currently in beta. The API contract may change during this phase. We recommend testing thoroughly in sandbox before using it in production.\n:::\n\nExecutes a lifecycle action on a wallet: TERMINATE, BLOCK, or UNBLOCK. A non-empty comment explaining the reason is required.", "operationId": "ledgerWalletExecuteAction", "parameters": [ { "in": "path", "name": "id", "required": true, "schema": { "type": "string", "example": "a:24092328494070:G5i4XZ9:1" }, "description": "The wallet identifier." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletActionRequest" }, "example": { "action": "TERMINATE", "comment": "CLIENT_REQUEST" } } } }, "responses": { "204": { "description": "No Content. The action was applied successfully." }, "422": { "description": "Bad request. For example, terminating a wallet while its balance is not zero.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "Terminate wallet with non-zero balance": { "summary": "Terminate wallet with non-zero balance", "description": "Returned when `action` is `TERMINATE` but the wallet balance must be zero before termination.", "value": { "code": "bvnk:ledger:4011", "details": null, "message": "Wallet a:26031146307962:a3MViub:1 balance must be zero before termination.", "status": "Unprocessable Entity", "traceId": "605925f3f20d9833cfe0ec7ffcfc3f48" } } } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "Forbidden": { "summary": "See the BVNK Errors reference for details.", "value": { "code": "bvnk:ledger:4003", "status": "Forbidden", "traceId": "abc123-def456-ghi789", "message": "FORBIDDEN! You don't have the necessary permissions to access this resource.", "details": { "documentLink": "https://docs.bvnk.com/reference/errors#/" } } } } } } }, "409": { "description": "Conflict. For example, blocking or unblocking a wallet that is already terminated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "Status update of the terminated wallet": { "summary": "Block or unblock a terminated wallet", "description": "Returned when `action` is `BLOCK` or `UNBLOCK` but the wallet is already `TERMINATED`.", "value": { "code": "bvnk:ledger:4009", "traceId": "522206a43b96c0ef98d39b466759fb10", "status": "Conflict", "message": "Wallet status update conflict for wallet ", "details": null } } } } } } }, "security": [ { "Hawk": [ "merchant" ] } ] } }, "/platform/v1/customers": { "get": { "tags": [ "Customers" ], "summary": "List customers", "description": ":::info Customers API v2\nThe [new customer onboarding flow](../../../get-started/create-embedded-partner-customer/create-customers-com) is recommended for all new integrations.\n\nIf you already have an existing integration with Customers API v1, you can continue using it. BVNK will continue to support this API going forward.\n:::\n\nRetrieves the full list of Customers.", "operationId": "listAccountCustomers", "parameters": [ { "name": "page", "in": "query", "description": "Page number (starts from `0`)", "example": 0, "schema": { "type": "number" } }, { "name": "size", "in": "query", "description": "Page size (max is `100`)", "example": 10, "schema": { "type": "number" } }, { "name": "name", "in": "query", "description": "Name of the customer to fetch", "example": "Customer-1", "schema": { "type": "string" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomersPage" } } } } } }, "post": { "tags": [ "Customers" ], "summary": "Create customer", "description": "\n\n:::warning\nBefore calling this endpoint, make sure you are not onboarding customers from restricted jurisdictions. For more information, see [BVNK Acceptable Use Policy](https://help.bvnk.com/hc/en-us/articles/11100445499666-BVNK-Acceptable-Use-Policy-Financial-Crime).\n:::\n\n:::info Customers API v2\nThe [new customer onboarding flow](../../../get-started/create-embedded-partner-customer/create-customers-com) is recommended for all new integrations.\n\nIf you already have an existing integration with Customers API v1, you can continue using it. BVNK will continue to support this API going forward.\n:::\n\nCreates an Embedded Partner Customer account. The customer can be 'Individual' or 'Company'.", "operationId": "createCustomer", "security": [ { "Hawk": [ "merchant" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "content": { "application/json": { "schema": { "discriminator": { "propertyName": "type", "mapping": { "company": "#/components/schemas/CreateCompanyCustomerRequest", "individual": "#/components/schemas/CreateIndividualCustomerRequest" } }, "anyOf": [ { "$ref": "#/components/schemas/CreateCompanyCustomerRequest" }, { "$ref": "#/components/schemas/CreateIndividualCustomerRequest" } ] }, "examples": { "Company - Limited Liability": { "summary": "Create a Limited Liability Company customer", "description": "Use case: Registering a UK-based LLC for business payments and crypto transactions.", "value": { "type": "company", "signedAgreementSessionReference": "78eedde1-2402-4a59-8bbd-ccecb6d612d1", "company": { "name": "UK Ltd Version 2.0", "description": "Number 1 customer, be super nice.", "entityType": "LIMITED_LIABILITY_COMPANY", "taxResidenceCountryCode": "DE", "taxNumber": "12-34567890", "registrationNumber": "1849203", "industryReference": "0a184641-30e2-4414-871f-3db1c683900e", "monthlyExpectedVolumesReference": "e1a6f510-1337-4000-a3c2-111111111111", "address": { "addressLine1": "Friedrichstraße 123", "city": "Berlin", "postalCode": "10117", "countryCode": "DE" }, "cdd": { "intendedUseOfAccount": "PAYROLL", "pepStatus": "NOT_PEP", "expectedMonthlyVolume": { "amount": "50000.00", "currency": "EUR" } }, "operationalAddress": { "addressLine1": "Unter den Linden 77", "city": "Berlin", "postalCode": "10117", "countryCode": "DE" }, "incorporationDate": "2001-12-31", "businessOperationsStartDate": "2020-12-31", "website": "https://www.health-music.com", "reliance": { "attestation": { "riskScore": "LOW", "eddCompleted": true } }, "isRegulated": true, "regulatorInformation": { "regulatorName": "Financial Conduct Authority", "regulatorJurisdiction": "DE" }, "isPubliclyListed": false, "associates": [ { "person": { "firstName": "J.", "lastName": "Health", "dateOfBirth": "1978-11-29", "nationality": "US", "birthCountryCode": "US", "address": { "addressLine1": "1313 Webfoot Street", "city": "Duckburg", "postalCode": "12345", "stateCode": "CA", "countryCode": "US" }, "reliance": { "identityDocumentMetadata": { "type": "PASSPORT", "number": "987654321", "expiryDate": "2031-01-01", "issueDate": "2021-01-01", "issuingCountryCode": "DE", "kycTimestamp": "2025-11-20T15:30:45.123Z" }, "biometricLiveness": { "livenessTimestamp": "2025-11-20T15:30:45.123Z" }, "addressVerification": { "type": "DOC" }, "attestation": { "riskScore": "LOW", "eddCompleted": true } }, "contactInfo": { "emailAddress": "johnny@heilung.de", "phoneNumber": "+1234567890" }, "taxIdentification": { "number": "345-56-357", "taxResidenceCountryCode": "DE" }, "estimatedYearlyIncome": "INCOME_0_TO_50K" }, "titles": [ "BUSINESS_OWNER", "ACCOUNT_REPRESENTATIVE", "DIRECTOR" ], "ownership": { "type": "DIRECT", "percentage": 100 } } ] } } }, "Company": { "summary": "Company payload", "value": { "type": "company", "signedAgreementSessionReference": "78eedde1-2402-4a59-8bbd-ccecb6d612d1", "company": { "name": "UK Ltd Version 2.0", "description": "Number 1 customer, be super nice.", "entityType": "LIMITED_LIABILITY_COMPANY", "taxResidenceCountryCode": "DE", "taxNumber": "12-34567890", "registrationNumber": "1849203", "industryReference": "0a184641-30e2-4414-871f-3db1c683900e", "monthlyExpectedVolumesReference": "e1a6f510-1337-4000-a3c2-111111111111", "address": { "addressLine1": "Friedrichstraße 123", "city": "Berlin", "postalCode": "10117", "countryCode": "DE" }, "cdd": { "intendedUseOfAccount": "PAYROLL", "pepStatus": "NOT_PEP", "expectedMonthlyVolume": { "amount": "50000.00", "currency": "EUR" } }, "operationalAddress": { "addressLine1": "Unter den Linden 77", "city": "Berlin", "postalCode": "10117", "countryCode": "DE" }, "incorporationDate": "2001-12-31", "businessOperationsStartDate": "2020-12-31", "website": "https://www.health-music.com", "reliance": { "attestation": { "riskScore": "LOW", "eddCompleted": true } }, "isRegulated": false, "isPubliclyListed": true, "publicInformation": { "listedExchange": "London Stock Exchange", "tickerSymbol": "BVNK" }, "associates": [ { "person": { "firstName": "J.", "lastName": "Health", "dateOfBirth": "1978-11-29", "nationality": "US", "birthCountryCode": "US", "address": { "addressLine1": "1313 Webfoot Street", "city": "Duckburg", "postalCode": "12345", "stateCode": "CA", "countryCode": "US" }, "reliance": { "identityDocumentMetadata": { "type": "PASSPORT", "number": "987654321", "expiryDate": "2031-01-01", "issueDate": "2021-01-01", "issuingCountryCode": "DE", "kycTimestamp": "2025-11-20T15:30:45.123Z" }, "biometricLiveness": { "livenessTimestamp": "2025-11-20T15:30:45.123Z" }, "addressVerification": { "type": "DOC" }, "attestation": { "riskScore": "LOW", "eddCompleted": true } }, "contactInfo": { "emailAddress": "johnny@heilung.de", "phoneNumber": "+1234567890" }, "taxIdentification": { "number": "345-56-357", "taxResidenceCountryCode": "DE" }, "estimatedYearlyIncome": "INCOME_0_TO_50K" }, "titles": [ "BUSINESS_OWNER", "ACCOUNT_REPRESENTATIVE", "DIRECTOR" ], "ownership": { "type": "DIRECT", "percentage": 100 } } ] } } }, "Individual - Partner-managed": { "summary": "Create an Individual customer (Partner-managed onboarding)", "description": "Use case: Registering an individual for personal crypto payments and wallet management.", "value": { "type": "individual", "individual": { "description": "Investments", "firstName": "Walton", "lastName": "Simmons", "dateOfBirth": "1985-08-15", "nationality": "AT", "birthCountryCode": "IT", "emailAddress": "wsimmons@example.com", "phoneNumber": "+1234567890", "address": { "addressLine1": "123 Main Street", "postalCode": "10001", "city": "New York", "countryCode": "US" }, "taxIdentification": { "number": "123-45-6789", "taxResidenceCountryCode": "US" }, "cdd": { "employmentStatus": "SALARIED", "sourceOfFunds": "SALARY", "pepStatus": "NOT_PEP", "intendedUseOfAccount": "GOODS_SERVICES", "expectedMonthlyVolume": { "amount": "10000.01", "currency": "USD" }, "estimatedYearlyIncome": "INCOME_0_TO_50K", "employmentIndustrySector": "AGRICULTURE_FORESTRY_FISHING_HUNTING" }, "reliance": { "identityDocumentMetadata": { "type": "PASSPORT", "number": "AB1234567", "issueDate": "2015-10-01", "expiryDate": "2030-12-31", "issuingCountryCode": "DE", "kycTimestamp": "2025-11-20T15:30:45.123Z" }, "biometricLiveness": { "livenessTimestamp": "2025-11-20T15:30:45.123Z" }, "addressVerification": { "type": "NON_DOC" }, "attestation": { "riskScore": "LOW", "eddCompleted": true } } }, "signedAgreementSessionReference": "78eedde1-2402-4a59-8bbd-ccecb6d612d1" } }, "Individual - BVNK-Managed": { "summary": "Create an Individual customer (BVNK-Managed onboarding)", "description": "Use case: Registering an individual where BVNK performs identity verification. Submit customer data here, then upload identity documents via the documents endpoint. No `reliance` block is included — BVNK handles verification.", "value": { "type": "individual", "individual": { "description": "Investments", "firstName": "Walton", "lastName": "Simmons", "dateOfBirth": "1985-08-15", "nationality": "AT", "birthCountryCode": "IT", "emailAddress": "wsimmons@example.com", "phoneNumber": "+1234567890", "address": { "addressLine1": "123 Main Street", "postalCode": "10001", "city": "New York", "countryCode": "US" }, "taxIdentification": { "number": "123-45-6789", "taxResidenceCountryCode": "US" }, "cdd": { "employmentStatus": "SALARIED", "sourceOfFunds": "SALARY", "pepStatus": "NOT_PEP", "intendedUseOfAccount": "GOODS_SERVICES", "expectedMonthlyVolume": { "amount": "10000.01", "currency": "USD" }, "estimatedYearlyIncome": "INCOME_0_TO_50K", "employmentIndustrySector": "AGRICULTURE_FORESTRY_FISHING_HUNTING" } }, "signedAgreementSessionReference": "78eedde1-2402-4a59-8bbd-ccecb6d612d1" } } } } } }, "responses": { "202": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerReferenceAndStatus" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "code", "status", "message" ], "properties": { "code": { "type": "string" }, "status": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "object", "properties": { "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } } } } }, "examples": { "industry-not-found": { "summary": "Industry reference does not exist", "value": [ { "code": "ACCOUNTS-2000", "status": "BAD_REQUEST", "message": "Invalid request", "details": { "errors": { "industryReference": [ "Industry with reference: 56e65ebc-06fa-11ef-bbf8-02d3d923cf2b does not exist" ] } } } ] } } } } } } } }, "/platform/v1/customers/{customerReference}/documents": { "post": { "summary": "Upload documents to customer", "description": ":::info Customers API v2\nThe [new customer onboarding flow](../../../get-started/create-embedded-partner-customer/create-customers-com) is recommended for all new integrations.\n\nIf you already have an existing integration with Customers API v1, you can continue using it. BVNK will continue to support this API going forward.\n:::\n\nAttach one or more documents to a customer's profile. This can be either a company customer (with optional linkage to a specific associate) or an individual customer. Files must be base64-encoded before submission.\n\n- For company-level documents, omit `customerPersonReference`.\n- For associate-level documents, provide the `customerPersonReference`.\n- The customer must be in `INFO_REQUIRED` status.", "operationId": "uploadCustomerDocuments", "tags": [ "Customers" ], "security": [ { "Hawk": [ "merchant" ] } ], "parameters": [ { "name": "customerReference", "in": "path", "required": true, "description": "The unique identifier of the customer to whom the documents will be attached. Must be in `INFO_REQUIRED` status.", "schema": { "type": "string", "example": "123e4567-e89b-12d3-a456-426614174000" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "items": { "anyOf": [ { "title": "Business Customer Document", "type": "object", "description": "Company-level document for a business customer.", "properties": { "customerPersonReference": { "type": "string", "format": "uuid", "description": "Unique identifier of associate (beneficial owner, director, etc.) the document belongs to. Omit to attach the document to the company itself.", "example": "9b2c3d4e-567f-48f0-abc1-03a4e3df12ab" }, "type": { "type": "string", "description": "Company-level document type:\n\n- `COMPANY_DOC`: Generic company document. Use `subType` to indicate the specific document (incorporation certificate, memorandum, articles of association, directors' registry, source of funds, regulatory licence, etc.).\n\n- `TRANSPARENCY_REGISTRY_EXTRACT`: Extract from the transparency / beneficial ownership registry.\n\n- `POWER_OF_ATTORNEY`: Power of attorney authorising a representative.", "enum": [ "COMPANY_DOC", "TRANSPARENCY_REGISTRY_EXTRACT", "POWER_OF_ATTORNEY" ], "example": "COMPANY_DOC" }, "subType": { "type": "string", "description": "Subtype of document. Required with `COMPANY_DOC` to indicate the specific company document.\n\n- `CAPITALISATION_OWNERSHIP_STRUCTURE`: Corporate/group structure or ownership documentation for complex structures\n\n- `DIRECTORS_REGISTRY`: Directors' registry or proof of directorship\n\n- `GOOD_STANDING_CERT`: Certificate of good standing\n\n- `INCORPORATION_ARTICLES`: Articles of Association\n\n- `INCORPORATION_CERT`: Certificate of incorporation or business formation\n\n- `INCUMBENCY_CERT`: Certificate of incumbency\n\n- `INFORMATION_STATEMENT`: Company information statement\n\n- `MEMORANDUM`: Memorandum of Association\n\n- `PARTNERSHIP_AGREEMENT`: Partnership agreement\n\n- `POWER_OF_ATTORNEY`: Power of attorney\n\n- `PROOF_OF_ADDRESS`: Utility bill, lease contract, or equivalent as proof of operational address\n\n- `PROOF_OF_NATURE_OF_BUSINESS`: Evidence describing the nature of the business\n\n- `REGULATORY_LICENSE`: Current regulatory licence\n\n- `SELF_DECLARATION_FORM`: Signed self-declaration form\n\n- `SHAREHOLDER_REGISTRY`: Shareholder registry\n\n- `SOURCE_OF_FUNDS`: Bank statements or equivalent SoF evidence\n\n- `STATE_REGISTRY`: Extract from the state business registry\n\n- `TRADE_LICENSE`: Trade licence\n\n- `TRUST_AGREEMENT`: Trust agreement\n\n- `OTHER`: Any other supporting company document", "enum": [ "CAPITALISATION_OWNERSHIP_STRUCTURE", "DIRECTORS_REGISTRY", "GOOD_STANDING_CERT", "INCORPORATION_ARTICLES", "INCORPORATION_CERT", "INCUMBENCY_CERT", "INFORMATION_STATEMENT", "MEMORANDUM", "PARTNERSHIP_AGREEMENT", "POWER_OF_ATTORNEY", "PROOF_OF_ADDRESS", "PROOF_OF_NATURE_OF_BUSINESS", "REGULATORY_LICENSE", "SELF_DECLARATION_FORM", "SHAREHOLDER_REGISTRY", "SOURCE_OF_FUNDS", "STATE_REGISTRY", "TRADE_LICENSE", "TRUST_AGREEMENT", "OTHER" ], "example": "INCORPORATION_CERT" }, "name": { "type": "string", "maxLength": 128, "description": "Filename of the document.", "example": "Company Structure.pdf" }, "description": { "type": "string", "maxLength": 255, "description": "Optional description.", "example": "Company incorporation certificate" }, "countryCode": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code.", "example": "DE" }, "externalReference": { "type": "string", "format": "uuid", "description": "External document tracking ID.", "example": "2b8d8bde-eef5-408a-9228-96bef24865ad" }, "content": { "type": "string", "description": "Base64-encoded file content.\n\nGenerate this by encoding the raw file bytes to base64 (PDF/JPG/PNG/etc.).\n- Node.js: fs.readFileSync('/path/to/file.pdf').toString('base64')\n- Browser: FileReader.readAsDataURL(file) and use only the part after the comma\n- Python: base64.b64encode(open('file.pdf','rb').read()).decode('ascii')\n\nSend the raw base64 string only (no `data:...;base64,` prefix) and without line breaks.", "example": "JVBERi0xLjUKJeLjz9MKMSAwIG9iago8PC9UeXBlIC9QYWdl..." } }, "required": [ "type", "name", "countryCode", "externalReference", "content" ] }, { "title": "Individual Customer Document", "type": "object", "description": "Document for individual customer", "properties": { "type": { "type": "string", "description": "Document type:\n\n- `AGREEMENT`: Signed agreement\n\n- `ARBITRARY_DOC`: Arbitrary supporting document not covered by the other types\n\n- `BANK_CARD`: Photo of a bank card\n\n- `BANK_STATEMENT`: Proof of address: bank document (bank statement, bank letter, mortgage payment document, or passbook)\n\n- `CONTRACT`: Signed contract\n\n- `COVID_VACCINATION_FORM`: COVID-19 vaccination form\n\n- `DRIVERS`: Driver's licence (two-sided: submit `FRONT_SIDE` then `BACK_SIDE`)\n\n- `DRIVERS_TRANSLATION`: Certified translation of a driver's licence\n\n- `FILE_ATTACHMENT`: Generic file attachment\n\n- `ID_CARD`: National ID card (two-sided: submit `FRONT_SIDE` then `BACK_SIDE`)\n\n- `ID_DOC_PHOTO`: Additional photo of an identity document\n\n- `INCOME_SOURCE`: Evidence of source of income (payslips, tax returns, or equivalent)\n\n- `INVESTOR_DOC`: Investor-related documentation\n\n- `OTHER`: Any other supporting document\n\n- `PASSPORT`: Passport (single-sided)\n\n- `PAYMENT_SOURCE`: Evidence of source of funds for a specific payment\n\n- `PROFILE_IMAGE`: Profile image of the individual\n\n- `RESIDENCE_PERMIT`: Residence permit (two-sided: submit `FRONT_SIDE` then `BACK_SIDE`)\n\n- `SELFIE`: Biometric selfie/liveness; must accompany every identity submission\n\n- `UTILITY_BILL`: Proof of address: utility provider document (electricity, water, gas, heating, sewerage, home phone, internet, or TV bill)\n\n- `UTILITY_BILL2`: Additional utility bill for proof of address\n\n- `VEHICLE_REGISTRATION_CERTIFICATE`: Vehicle registration certificate\n\n- `VIDEO_SELFIE`: Biometric video selfie/liveness recording", "enum": [ "AGREEMENT", "ARBITRARY_DOC", "BANK_CARD", "CONTRACT", "COVID_VACCINATION_FORM", "DRIVERS", "DRIVERS_TRANSLATION", "FILE_ATTACHMENT", "ID_CARD", "ID_DOC_PHOTO", "INCOME_SOURCE", "INVESTOR_DOC", "OTHER", "PASSPORT", "PAYMENT_SOURCE", "PROFILE_IMAGE", "RESIDENCE_PERMIT", "SELFIE", "UTILITY_BILL", "UTILITY_BILL2", "VEHICLE_REGISTRATION_CERTIFICATE", "VIDEO_SELFIE" ], "example": "PASSPORT" }, "subType": { "type": "string", "description": "Subtype of document. Required when uploading two-sided documents such as `ID_CARD`, `DRIVERS`, or `RESIDENCE_PERMIT`. Always upload `FRONT_SIDE` before `BACK_SIDE`. Not required for `PASSPORT` (single-sided).", "enum": [ "FRONT_SIDE", "BACK_SIDE" ], "example": "FRONT_SIDE" }, "name": { "type": "string", "maxLength": 128, "description": "Filename of the document.", "example": "Jane Smith Passport.pdf" }, "description": { "type": "string", "maxLength": 255, "description": "Optional description.", "example": "Passport single-sided" }, "countryCode": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code.", "example": "DE" }, "externalReference": { "type": "string", "format": "uuid", "description": "External document tracking ID.", "example": "4e1b3f32-ef2b-4413-8a3a-84df3cdd9211" }, "content": { "type": "string", "description": "Base64-encoded file content.\n\nGenerate this by encoding the raw file bytes to base64 (PDF/JPG/PNG/etc.).\n- Node.js: fs.readFileSync('/path/to/file.pdf').toString('base64')\n- Browser: FileReader.readAsDataURL(file) and use only the part after the comma\n- Python: base64.b64encode(open('file.pdf','rb').read()).decode('ascii')\n\nSend the raw base64 string only (no `data:...;base64,` prefix) and without line breaks.", "example": "JVBERi0xLjUKJeLjz9MKMSAwIG9iago8PC9UeXBlIC9QYWdl..." } }, "required": [ "type", "name", "countryCode", "externalReference", "content" ] } ] }, "example": [ { "type": "COMPANY_DOC", "subType": "INCORPORATION_CERT", "name": "Certificate of Incorporation.pdf", "description": "Certificate of incorporation", "countryCode": "DE", "externalReference": "2b8d8bde-eef5-408a-9228-96bef24865ad", "content": "JVBERi0xLjUKJeLjz9MKMSAwIG9iago8PC9UeXBlIC9QYWdl..." }, { "customerPersonReference": "9b2c3d4e-567f-48f0-abc1-03a4e3df12ab", "type": "PASSPORT", "name": "John Smith Passport.pdf", "description": "Passport single-sided", "countryCode": "DE", "externalReference": "8eabc8f2-7f76-4d2e-9fa6-0a11e94d3dcd", "content": "JVBERi0xLjUKJeLjz9MKMSAwIG9iago8PC9UeXBlIC9QYWdl..." } ] }, "examples": { "Business Document": { "summary": "Upload a company incorporation certificate", "value": [ { "type": "COMPANY_DOC", "subType": "INCORPORATION_CERT", "name": "Certificate of Incorporation.pdf", "description": "Certificate of incorporation", "countryCode": "DE", "externalReference": "2b8d8bde-eef5-408a-9228-96bef24865ad", "content": "JVBERi0xLjUKJeLjz9MKMSAwIG9iago8PC9UeXBlIC9QYWdl..." } ] }, "Individual Document": { "summary": "Upload a passport for an individual customer", "value": [ { "type": "PASSPORT", "name": "Jane Smith Passport.pdf", "description": "Passport single-sided", "countryCode": "DE", "externalReference": "4e1b3f32-ef2b-4413-8a3a-84df3cdd9211", "content": "JVBERi0xLjUKJeLjz9MKMSAwIG9iago8PC9UeXBlIC9QYWdl..." } ] } } } } }, "responses": { "202": { "description": "Documents accepted and queued for upload.", "content": { "application/json": { "schema": { "type": "object", "properties": { "reference": { "type": "string", "format": "uuid", "description": "Unique reference for the document upload request.", "example": "d42e1c62-27b8-4b3b-b51e-eb10edeb1731" }, "externalReference": { "type": "string", "format": "uuid", "description": "External reference sent in the request.", "example": "2b8d8bde-eef5-408a-9228-96bef24865ad" }, "status": { "type": "string", "enum": [ "INIT" ], "description": "Initial status of the document upload.", "example": "INIT" } } } } } }, "400": { "description": "Bad request — missing or invalid data.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "DOCUMENTS-4000" }, "status": { "type": "string", "enum": [ "BAD_REQUEST" ], "example": "BAD_REQUEST" }, "message": { "type": "string", "example": "Invalid document content" }, "details": { "type": "object", "properties": { "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "example": { "content": [ "Document file content is not valid base64" ] } } } } } } } } } } } }, "/platform/v1/customers/documents": { "get": { "tags": [ "Customers" ], "summary": "Get customer documents", "description": ":::info Customers API v2\nThe [new customer onboarding flow](../../../get-started/create-embedded-partner-customer/create-customers-com) is recommended for all new integrations.\n\nIf you already have an existing integration with Customers API v1, you can continue using it. BVNK will continue to support this API going forward.\n:::\n\nRetrieves the details of the specific document added for the Customer. If no parameters are specified, retrieves the array of available documents.", "operationId": "getCustomerDocuments", "security": [ { "Hawk": [ "merchant" ] } ], "parameters": [ { "name": "customerReference", "in": "query", "description": "Customer reference", "schema": { "type": "string", "format": "uuid", "example": "0a184641-30e2-4414-871f-3db1c683900e" } }, { "name": "externalReference", "in": "query", "description": "External document tracking ID", "schema": { "type": "string", "format": "uuid", "example": "501e87bb-24d7-4008-a249-f485512b8a14" } }, { "name": "name", "in": "query", "description": "Customer reference", "schema": { "type": "string", "maxLength": 128, "example": "J_Kaldwin_Passport.pdf" } }, { "name": "type", "in": "query", "description": "Document type", "schema": { "type": "string", "example": "PASSPORT" } }, { "name": "subtype", "in": "query", "description": "Subtype of document", "schema": { "type": "string", "example": "FRONT_SIDE" } }, { "name": "status", "in": "query", "description": "Initial status of the document upload", "schema": { "type": "string", "enum": [ "INIT", "PENDING", "APPROVED", "DECLINED" ], "example": "APPROVED" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "array", "items": { "type": "object", "properties": { "reference": { "type": "string", "format": "uuid", "description": "Internal document identifier" }, "externalReference": { "type": "string", "format": "uuid", "description": "External document tracking ID" }, "customerReference": { "type": "string", "format": "uuid", "description": "Customer identifier" }, "customerPersonReference": { "type": "string", "format": "uuid", "description": "Customer person identifier (for individuals)" }, "accountReference": { "type": "string", "format": "uuid", "description": "Associated account identifier" }, "type": { "type": "string", "description": "Document type" }, "subType": { "type": "string", "description": "Subtype of document" }, "name": { "type": "string", "description": "Filename of the document" }, "description": { "type": "string", "description": "Optional document description" }, "countryCode": { "type": "string", "description": "ISO 3166-1 alpha-2 country code" }, "country": { "type": "string", "description": "Full country name" }, "status": { "type": "string", "enum": [ "INIT", "PENDING", "APPROVED", "DECLINED" ], "description": "Current document status" } }, "required": [ "reference", "externalReference", "customerReference", "type", "name", "countryCode", "country", "status" ] } } }, "example": { "content": [ { "reference": "c1d7aa15-77f0-40b2-a990-ae0610422c73", "externalReference": "501e87bb-24d7-4008-a249-f485512b8a14", "customerReference": "d9f2ffc1-4d80-49ff-b44d-d3e43bd7b66a", "customerPersonReference": "b6179794-73a1-42d4-af56-bdb57313bc4b", "accountReference": "5bc49988-fe25-408f-bccc-3e0fe96cf322", "type": "PASSPORT", "name": "A_Sokolov_Residence_Permit.pdf", "description": "Document optional description", "countryCode": "DE", "country": "Germany", "status": "PENDING" }, { "reference": "34d5b0e3-8fb9-4f4e-86c5-3a438388c1c0", "externalReference": "09a92c28-6fbe-4ea8-bff3-88451078faa9", "customerReference": "d9f2ffc1-4d80-49ff-b44d-d3e43bd7b66a", "accountReference": "5bc49988-fe25-408f-bccc-3e0fe96cf322", "type": "CERTIFICATE_OF_INCORPORATION", "name": "Certificate of Incorporation.pdf", "description": "Document optional description", "countryCode": "FR", "country": "France", "status": "PENDING" } ] } } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/platform/v1/customers/documents/{documentReference}": { "delete": { "tags": [ "Customers" ], "summary": "Remove a document", "operationId": "deleteDocument", "description": ":::info Customers API v2\nThe [new customer onboarding flow](../../../get-started/create-embedded-partner-customer/create-customers-com) is recommended for all new integrations.\n\nIf you already have an existing integration with Customers API v1, you can continue using it. BVNK will continue to support this API going forward.\n:::\n\nDeletes a specified document from a Customer's profile.", "security": [ { "Hawk": [ "merchant" ] } ], "parameters": [ { "name": "documentReference", "in": "path", "description": "Internal document identifier", "required": true, "schema": { "type": "string", "format": "uuid", "example": "0a184641-30e2-4414-871f-3db1c683900e" } } ], "responses": { "204": { "description": "No Content", "content": {} }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/platform/v1/customers/documents/{documentReference}/url": { "get": { "tags": [ "Customers" ], "summary": "Get document download URL", "operationId": "getDocumentUrl", "description": ":::info Customers API v2\nThe [new customer onboarding flow](../../../get-started/create-embedded-partner-customer/create-customers-com) is recommended for all new integrations.\n\nIf you already have an existing integration with Customers API v1, you can continue using it. BVNK will continue to support this API going forward.\n:::\n\nRetrieves a temporary URL for document download.", "security": [ { "Hawk": [ "merchant" ] } ], "parameters": [ { "name": "documentReference", "in": "path", "description": "Internal document identifier", "required": true, "schema": { "type": "string", "format": "uuid", "example": "0a184641-30e2-4414-871f-3db1c683900e" } } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "type": "string", "format": "uri", "description": "Temporary link to the requested document", "example": "https://my-app-filestore.s3.eu-west-1.amazonaws.com/com.customer.document.model.CustomerDocumentValue/34d5b0e3-8fb9-4f4e-86c5-3a438388c1c0.pdf?X-Amz-Security-Token=AKIAIOSFODNN7EXAMPLE&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20250528T153951Z&X-Amz-SignedHeaders=host&X-Amz-Expires=60&X-Amz-Credential=AKIAIOSFODNN7EXAMPLE%2F20250528%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Signature=abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890" } } } }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/platform/v1/customers/{customerReference}": { "get": { "tags": [ "Customers" ], "summary": "Get customer", "description": ":::info Customers API v2\nThe [new customer onboarding flow](../../../get-started/create-embedded-partner-customer/create-customers-com) is recommended for all new integrations.\n\nIf you already have an existing integration with Customers API v1, you can continue using it. BVNK will continue to support this API going forward.\n:::", "operationId": "getCustomerWithExternalStatus", "security": [ { "Hawk": [ "merchant" ] } ], "parameters": [ { "name": "customerReference", "in": "path", "description": "Customer reference", "required": true, "schema": { "type": "string", "format": "uuid", "example": "0a184641-30e2-4414-871f-3db1c683900e" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCustomerResponse" }, "examples": { "Individual Customer": { "value": { "reference": "797a8908-72dd-44fb-95c5-ec6cb2152b7d", "status": "VERIFIED", "type": "INDIVIDUAL", "flowType": "API", "individual": { "description": "Top priority", "person": { "reference": "599802bd-485f-47fa-87ae-471968c6217f", "firstName": "Victor", "lastName": "Caneda", "dateOfBirth": "2004-02-17", "placeOfBirth": "US", "address": { "addressLine1": "001 Sharp Ports Apt. 858", "city": "New York", "postalCode": "10001", "stateCode": "NY", "state": "New York", "countryCode": "US", "country": "United States" } }, "details": { "nationality": "US", "birthCountryCode": "US", "contactInfo": { "emailAddress": "v.caneda@example.com", "phoneNumber": "+11953410688" }, "documentNumber": "4Q4FNK8JI4", "documentInfo": { "number": "4Q4FNK8JI4", "type": "ID_CARD", "issuingCountryCode": "US" }, "taxIdentification": { "number": "555-89-3168", "taxResidenceCountryCode": "US" } }, "cdd": { "intendedUseOfAccount": "TRANSFERS_OWN_WALLET", "pepStatus": "NOT_PEP", "expectedMonthlyVolume": { "amount": 500.01, "currency": "EUR" }, "employmentStatus": "SALARIED", "sourceOfFunds": "SALARY", "estimatedYearlyIncome": "INCOME_750K_TO_1M", "employmentIndustrySector": "ADMINISTRATIVE_SUPPORT_WASTE_MANAGEMENT_REMEDIATION_SERVICES" } }, "riskScore": "LOW", "verification": { "status": "completed" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequestMessage" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Customers" ], "summary": "Update customer", "description": "\n\n:::warning\nBefore calling this endpoint, make sure you are not onboarding customers from restricted jurisdictions. For more information, see [BVNK Acceptable Use Policy](https://help.bvnk.com/hc/en-us/articles/11100445499666-BVNK-Acceptable-Use-Policy-Financial-Crime).\n:::\n\n:::info Customers API v2\nThe [new customer onboarding flow](../../../get-started/create-embedded-partner-customer/create-customers-com) is recommended for all new integrations.\n\nIf you already have an existing integration with Customers API v1, you can continue using it. BVNK will continue to support this API going forward.\n:::\n\nUpdates customer information for individual customers. You can update contact information (email and phone), address details, and date of birth.\n\nOnly include the fields in your request that you want to update.", "operationId": "updateCustomer", "security": [ { "Hawk": [ "merchant" ] } ], "parameters": [ { "name": "customerReference", "in": "path", "description": "The unique identifier of the customer whose record will be updated. This must be a valid customer in the platform.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "0a184641-30e2-4414-871f-3db1c683900e" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Any subset of updatable fields may be provided.", "properties": { "externalReference": { "type": "string", "description": "External reference for the customer. You can use it to store your own reference identifier for the customer.", "example": "1234567890" }, "individual": { "type": "object", "description": "Individual customer information to update.", "properties": { "contactInfo": { "type": "object", "description": "Contact information for the customer.", "properties": { "emailAddress": { "type": "string", "format": "email", "description": "Email address.", "maxLength": 255, "example": "walton.simmons@company.com" }, "phoneNumber": { "type": "string", "description": "Phone number in the E.164 format.", "maxLength": 255, "example": "+14155552671" } } }, "address": { "allOf": [ { "$ref": "#/components/schemas/AddressV2" } ], "description": "Customer address. You can only update this field when the customer is in `INFO_REQUIRED` state.\n\nFor US addresses, both `stateCode` and `countryCode` should be provided." }, "dateOfBirth": { "type": "string", "format": "date", "description": "Date of birth in the YYYY-MM-DD format.\n\nYou can only update this field when the customer is in `INFO_REQUIRED` state.", "example": "1985-08-15" } } } } }, "examples": { "Update contact information": { "summary": "Update email and phone number", "value": { "individual": { "contactInfo": { "emailAddress": "walton.simmons@company.com", "phoneNumber": "+14155552671" } } } }, "Update address": { "summary": "Update customer address", "value": { "individual": { "address": { "addressLine1": "456 Park Avenue", "addressLine2": "Suite 1200", "city": "New York", "postalCode": "10022", "stateCode": "NY", "countryCode": "US", "country": "United States" } } } }, "Update date of birth": { "summary": "Correct date of birth", "value": { "individual": { "dateOfBirth": "1985-08-15" } } }, "Update multiple fields": { "summary": "Update contact info, address, and date of birth", "value": { "individual": { "contactInfo": { "emailAddress": "walton.simmons@company.com", "phoneNumber": "+14155552671" }, "address": { "addressLine1": "456 Park Avenue", "addressLine2": "Suite 1200", "city": "New York", "postalCode": "10022", "stateCode": "NY", "countryCode": "US", "country": "United States" }, "dateOfBirth": "1985-08-15" } } } } } } }, "responses": { "200": { "description": "Successfully updated customer details", "content": { "application/json": { "schema": { "type": "object", "required": [ "reference", "status" ], "properties": { "reference": { "type": "string", "format": "uuid", "description": "Customer reference identifier", "example": "0a184641-30e2-4414-871f-3db1c683900e" }, "status": { "type": "string", "description": "Customer status", "enum": [ "INIT", "PENDING", "APPROVED", "INFO_REQUIRED" ], "example": "APPROVED" } } }, "examples": { "Updated customer": { "summary": "Customer information updated successfully", "value": { "reference": "0a184641-30e2-4414-871f-3db1c683900e", "status": "APPROVED" } } } } } }, "400": { "description": "Bad request - validation failed or invalid data provided", "content": { "application/json": { "schema": { "$ref": "#/components/responses/BadRequestMessage" }, "examples": { "State restriction": { "summary": "State restriction error when updating address or date of birth", "value": { "code": "ACCOUNTS-2000", "status": "BAD_REQUEST", "message": "Invalid request", "details": { "errors": { "individual": [ "Customer with reference: 105b4406-7a2d-4967-8729-7b77edc6fc2d must have status INFO_REQUIRED to update address", "Customer with reference: 105b4406-7a2d-4967-8729-7b77edc6fc2d must have status INFO_REQUIRED to update date of birth" ] } } } } } } } }, "401": { "description": "Unauthorized - invalid or missing API credentials" }, "404": { "description": "Customer not found", "$ref": "#/components/responses/NotFound" } } } }, "/platform/v1/customers/{customerReference}/info-required": { "get": { "tags": [ "Customers" ], "summary": "List required information", "description": ":::info Customers API v2\nThe [new customer onboarding flow](../../../get-started/create-embedded-partner-customer/create-customers-com) is recommended for all new integrations.\n\nIf you already have an existing integration with Customers API v1, you can continue using it. BVNK will continue to support this API going forward.\n:::\n\nRetrieves detailed information about what documents and data are required for customer onboarding when their status is `INFO_REQUIRED`. This endpoint provides specific requirements for documents, questionnaires, and additional data needed to complete the onboarding process.", "operationId": "getCustomerInfoRequired", "security": [ { "Hawk": [ "merchant" ] } ], "parameters": [ { "name": "customerReference", "in": "path", "description": "Unique identifier of the customer in the UUID format.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "0a184641-30e2-4414-871f-3db1c683900e" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Current status of the customer. `INFO_REQUIRED` is related only to the Embedded model.", "enum": [ "INFO_REQUIRED", "PENDING", "VERIFIED", "REJECTED", "TERMINATED" ], "example": "INFO_REQUIRED" }, "infoRequired": { "type": "object", "description": "Details about what documents are required for onboarding. Only present when status is INFO_REQUIRED.", "properties": { "questionnaires": { "type": "array", "description": "List of questionnaires that need to be completed.", "items": { "type": "object" }, "example": "otherQuestionnaireFull" }, "documents": { "type": "array", "description": "List of document sets that need to be provided for compliance.", "items": { "type": "object", "properties": { "docSetType": { "type": "string", "description": "Type of document set", "enum": [ "IDENTITY", "SELFIE", "PROOF_OF_RESIDENCE" ], "example": "IDENTITY" }, "types": { "type": "array", "description": "Specific document types accepted for this document set.", "items": { "type": "string", "enum": [ "PASSPORT", "DRIVERS", "ID_CARD", "RESIDENCE_PERMIT", "SELFIE", "UTILITY_BILL" ] }, "example": [ "PASSPORT", "DRIVERS", "ID_CARD", "RESIDENCE_PERMIT" ] } } }, "example": [ { "docSetType": "IDENTITY", "types": [ "PASSPORT", "DRIVERS", "ID_CARD", "RESIDENCE_PERMIT" ] }, { "docSetType": "SELFIE", "types": [ "SELFIE" ] } ] }, "data": { "type": "array", "description": "Additional data requirements. Mirrors the response of the [`/platform/v1/customers/{customerReference}`](https://docs.bvnk.com/reference/getcustomerwithexternalstatus#/) endpoint.", "items": { "type": "object" }, "example": [] } } } } }, "examples": { "verified": { "summary": "Status VERIFIED", "value": { "status": "VERIFIED" } }, "rejected": { "summary": "Status REJECTED", "value": { "status": "REJECTED" } }, "info_required_minimal": { "summary": "Status INFO_REQUIRED", "value": { "status": "INFO_REQUIRED", "infoRequired": { "questionnaires": [], "documents": [ { "docSetType": "IDENTITY", "types": [ "PASSPORT", "DRIVERS", "ID_CARD", "RESIDENCE_PERMIT" ] }, { "docSetType": "SELFIE", "types": [ "SELFIE" ] }, { "docSetType": "PROOF_OF_RESIDENCE", "types": [ "UTILITY_BILL" ] } ], "data": [] } } }, "info_required_bad_documents": { "summary": "Status INFO_REQUIRED: wrong selfie and ID submitted", "value": { "status": "INFO_REQUIRED", "infoRequired": { "questionnaires": [], "documents": [ { "docSetType": "IDENTITY", "types": [ "PASSPORT", "DRIVERS", "ID_CARD", "RESIDENCE_PERMIT" ] }, { "docSetType": "SELFIE", "types": [ "SELFIE" ] } ], "data": [] } } }, "info_required_rejected_poa": { "summary": "Status INFO_REQUIRED: Proof of Address rejected", "value": { "status": "INFO_REQUIRED", "infoRequired": { "questionnaires": [], "documents": [ { "docSetType": "PROOF_OF_RESIDENCE", "types": [ "UTILITY_BILL" ] } ], "data": [] } } }, "info_required_missing_questionnaire_company": { "summary": "Status INFO_REQUIRED for Company: missing questionnaires", "value": { "status": "INFO_REQUIRED", "infoRequired": { "questionnaires": [ "otherQuestionnaireFull" ], "associates": [ { "roles": [ "BUSINESS_OWNER", "DIRECTOR", "ACCOUNT_REPRESENTATIVE" ] } ] } } }, "info_required_missing_company_data": { "summary": "Status INFO_REQUIRED for Company: missing data", "value": { "status": "INFO_REQUIRED", "infoRequired": { "questionnaires": [ "additionalCompanyDat" ], "data": [ "entityType", "address.addressLine1", "address.postalCode", "address.city" ], "associates": [ { "roles": [ "representative", "ubo", "director" ] } ] } } }, "info_required_requirements_satisfied": { "summary": "Status INFO_REQUIRED: requirements satisfied", "value": { "status": "INFO_REQUIRED", "infoRequired": {} } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/platform/v1/customers/agreement/sessions": { "post": { "tags": [ "Customers" ], "summary": "Create agreement signing session", "description": "Creates a session for customers to agree to the conditions and requirements.\n\n:::warning\nBefore calling this endpoint, make sure you are not onboarding customers from restricted jurisdictions. For more information, see [BVNK Acceptable Use Policy](https://help.bvnk.com/hc/en-us/articles/11100445499666-BVNK-Acceptable-Use-Policy-Financial-Crime).\n::: \n\n:::info Customers API v2\nThe [new customer onboarding flow](../../../get-started/create-embedded-partner-customer/create-customers-com) is recommended for all new integrations.\n\nIf you already have an existing integration with Customers API v1, you can continue using it. BVNK will continue to support this API going forward.\n:::", "operationId": "createAgreementSession", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "customerType", "countryCode", "useCase" ], "properties": { "customerType": { "$ref": "#/components/schemas/CustomerType" }, "countryCode": { "type": "string", "description": "Country code of the customer's address in the ISO 3166-1 alpha-2 format.", "example": "DE" }, "useCase": { "type": "string", "description": "Type of product to which the customer agreement applies.", "enum": [ "STABLECOIN_PAYOUTS", "EMBEDDED_STABLECOIN_WALLETS", "EMBEDDED_FIAT_ACCOUNTS" ], "example": "EMBEDDED_FIAT_ACCOUNTS" } } }, "examples": { "Company Agreement": { "summary": "Create agreement session for a company customer", "value": { "customerType": "COMPANY", "countryCode": "DE", "useCase": "EMBEDDED_FIAT_ACCOUNTS" } }, "Individual Agreement": { "summary": "Create agreement session for an individual customer", "value": { "customerType": "INDIVIDUAL", "countryCode": "DE", "useCase": "EMBEDDED_STABLECOIN_WALLETS" } } } } } }, "responses": { "200": { "description": "Agreement session created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "reference": { "type": "string", "description": "Unique session identifier" }, "status": { "type": "string", "description": "Agreement status", "enum": [ "PENDING", "SIGNED", "DECLINED" ] }, "customerType": { "type": "string", "description": "Type of customer" }, "useCase": { "type": "string", "description": "Type of product to which the customer agreement applies." }, "countryCode": { "type": "string", "description": "Customer's ISO country code" }, "expiresOn": { "type": "string", "format": "date-time", "description": "Session expiration (ISO8601 timestamp)" }, "agreements": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Agreement identifier" }, "displayName": { "type": "string", "description": "Public-facing title of the agreeement" }, "description": { "type": "string", "description": "Agreement details" }, "url": { "type": "string", "format": "uri", "description": "URL for agreement document" }, "status": { "type": "string", "description": "Session status of the agreement signing" }, "privacyPolicyName": { "type": "string", "description": "Privacy policy title" }, "privacyPolicyDescription": { "type": "string", "description": "Privacy policy details" }, "privacyPolicyUrl": { "type": "string", "format": "uri", "description": "URL to privacy policy" } } } } }, "example": { "reference": "5f74fee5-3e8e-4dcc-85cd-24b9205bb44d", "status": "PENDING", "customerType": "INDIVIDUAL", "useCase": "EMBEDDED_FIAT_ACCOUNTS", "countryCode": "DE", "expiresOn": "2025-05-23T15:05:20.859141Z", "agreements": [ { "name": "main_agreement", "displayName": "Main Agreement", "description": "Terms and conditions for using AKME LTD. services.", "url": "https://example.com/docs/agreement.pdf", "status": "PENDING", "privacyPolicyName": "Privacy Policy", "privacyPolicyDescription": "Details how your data is used.", "privacyPolicyUrl": "https://example.com/privacy" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/platform/v1/customers/agreement/sessions/{reference}": { "put": { "tags": [ "Customers" ], "summary": "Update agreement session status", "description": ":::info Customers API v2\nThe [new customer onboarding flow](../../../get-started/create-embedded-partner-customer/create-customers-com) is recommended for all new integrations.\n\nIf you already have an existing integration with Customers API v1, you can continue using it. BVNK will continue to support this API going forward.\n:::\n\nUpdates the signing status of an agreement session. Typically used after user submission to mark the session as SIGNED or DECLINED.", "operationId": "updateAgreementSession", "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the agreement session to update." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "ipAddress" ], "properties": { "status": { "type": "string", "enum": [ "SIGNED", "DECLINED" ], "description": "The new status of the session." }, "ipAddress": { "type": "string", "format": "ipv4", "description": "IP address of the user performing the action." } } }, "example": { "status": "SIGNED", "ipAddress": "192.172.1.16" } } } }, "responses": { "200": { "description": "Agreement session status was successfully updated." }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "get": { "tags": [ "Customers" ], "summary": "Retrieve agreement session status", "description": ":::info Customers API v2\nThe [new customer onboarding flow](../../../get-started/create-embedded-partner-customer/create-customers-com) is recommended for all new integrations.\n\nIf you already have an existing integration with Customers API v1, you can continue using it. BVNK will continue to support this API going forward.\n:::\n\nReturns the current status of an agreement session using its reference ID.", "operationId": "getAgreementSessionStatus", "parameters": [ { "name": "reference", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The unique identifier of the agreement session to retrieve." } ], "responses": { "200": { "description": "Agreement session data retrieved", "content": { "application/json": { "schema": { "type": "object", "properties": { "reference": { "type": "string" }, "status": { "type": "string", "enum": [ "PENDING", "SIGNED", "DECLINED" ] } } }, "example": { "reference": "5f74fee5-3e8e-4dcc-85cd-24b9205bb44d", "status": "SIGNED" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/platform/v1/wallet-sessions": { "post": { "tags": [ "Embedded Express" ], "summary": "Create express session", "description": "Creates a wallet session URL for Embedded Express customers, allowing them to access their branded stablecoin wallet. The URL is returned in `walletSessionUrl` and can be shared via web view, redirect, or other integration methods. Each session link is time-bound and user-specific for security. BVNK verifies the user's identity before granting access. For details on the customer experience, consult your Account Manager.\n\nTo maintain consistent branding, include the optional `theme` object with each session creation. This ensures your customer sees your colors and logo in their wallet interface.\n\nThe endpoint automatically manages onboarding based on the customer's status with BVNK:\n\n• New customers receive an onboarding link.\n\n• Existing BVNK customers who have not used Express receive an Express registration link.\n\n• Existing Express customers receive a login link.\n\n• Customers with an active session token can access the wallet interface directly.\n\nFor existing BVNK customers receiving an Express link for the first time, ensure the link is accessible only by the intended customer.\n\nUse this endpoint to enable Express features for your customers.", "operationId": "createExpressSession", "security": [ { "Hawk": [ "merchant" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CreateExpressSessionExistingCustomerRequest" }, { "$ref": "#/components/schemas/CreateExpressSessionNewCustomerRequest" } ] }, "examples": { "ExistingCustomer": { "summary": "Existing embedded customer", "description": "Request payload for an existing embedded customer who already exists in your system.", "value": { "customerReference": "22c8168d-f735-43f8-9a3b-a1578efeb86c", "theme": { "logo": "https://ok14static.oktacdn.com/fs/bco/1/fs0waisynotIeKa80697", "primary": "#121212", "secondary": "#382457", "accent": "#DEF832" } } }, "NewCustomer": { "summary": "New embedded customer", "description": "Request payload for a new customer who doesn't exist in your system yet.", "value": { "type": "INDIVIDUAL", "countryCode": "DE", "externalCustomerReference": "22c8168d-f735-43f8-9a3b-a1578efeb86n", "theme": { "logo": "https://ok14static.oktacdn.com/fs/bco/1/fs0waisynotIeKa80697", "primary": "#121212", "secondary": "#382457", "accent": "#DEF832" } } } } } } }, "responses": { "200": { "description": "Express session created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExpressSessionResponse" }, "examples": { "NewCustomer": { "summary": "Response for new customer", "description": "Response when creating a session for a new customer who doesn't exist in your system yet.", "value": { "externalCustomerReference": "22c8168d-f735-43f8-9a3b-a1578efeb86n", "customerType": "INDIVIDUAL", "useCase": "EMBEDDED_STABLECOIN_WALLETS", "countryCode": "DE", "theme": { "logo": "https://ok14static.oktacdn.com/fs/bco/1/fs0waisynotIeKa80697", "primary": "#121212", "accent": "#DEF832" }, "walletSessionUrl": "https://wallet.staging.bvnk.com/welcome?sessionId=019c768f-41ab-75ea-acb0-1aa5dc3b1e9b#token=jafR7d-LarxRQrlXQ5fWgg" } }, "ExistingCustomer": { "summary": "Response for existing customer", "description": "Response when creating a session for an existing customer who already exists in your system.", "value": { "customerReference": "22c8168d-f735-43f8-9a3b-a1578efeb86c", "customerType": "INDIVIDUAL", "useCase": "EMBEDDED_STABLECOIN_WALLETS", "theme": { "logo": "https://ok14static.oktacdn.com/fs/bco/1/fs0waisynotIeKa80697", "primary": "#121212", "accent": "#DEF832" }, "walletSessionUrl": "https://wallet.staging.bvnk.com/welcome?sessionId=019bfb29-21e8-7db0-84da-655db2886727#token=uScPjLZRSm8WRlGL006L2g" } } } } } }, "400": { "$ref": "#/components/responses/BadRequestNoMessage" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/platform/v1/customers/questionnaire/definitions": { "get": { "summary": "Get questionnaire definition", "description": ":::info Customers API v2\nThe [new customer onboarding flow](../../../get-started/create-embedded-partner-customer/create-customers-com) is recommended for all new integrations.\n\nIf you already have an existing integration with Customers API v1, you can continue using it. BVNK will continue to support this API going forward.\n:::\n\nFetches quiestionnaire schemas with questions, answer types, option lists. You can render the questionnaire in your UI. \n\n Questionnaires include the following sections: ", "tags": [ "Onboarding" ], "operationId": "getQuestionnaireDefinitions", "externalDocs": { "description": "Guide: Retrieve Questionnaires", "url": "https://docs.bvnk.com/bvnk/get-started/create-embedded-partner-customer/onboard-epc#retrieve-questionnaires" }, "security": [ { "Hawk": [ "merchant" ] } ], "parameters": [ { "name": "codes", "in": "query", "required": false, "description": "One or several questionnaire identifiers. Each code covers [Baseline](https://docs.bvnk.com/docs/embedded-compliance-requirements-businesses#/baseline-requirements) and [Industry-specific](https://docs.bvnk.com/docs/embedded-compliance-requirements-businesses#/vertical-specific-requirements) requirements.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "financialServicesQuestionnaireFull", "amlCryptoComplianceQuestionnaireFull", "gamblingQuestionnaireFull", "fintechsQuestionnaireFull", "otherQuestionnaireFull", "eddQuestionnaire" ] } }, "style": "form", "explode": true, "example": [ "amlCryptoComplianceQuestionnaireFull", "financialServicesQuestionnaireFull" ] } ], "responses": { "200": { "description": "Array of questionnaire schema objects.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "code", "title", "sections" ], "properties": { "code": { "type": "string", "description": "Questionnaire identifier", "enum": [ "financialServicesQuestionnaireFull", "amlCryptoComplianceQuestionnaireFull", "gamblingQuestionnaireFull", "fintechsQuestionnaireFull", "otherQuestionnaireFull", "eddQuestionnaire" ], "example": "amlCryptoComplianceQuestionnaireFull" }, "title": { "type": "string", "description": "Title of the questionnaire ", "example": "Digital Assets (Crypto) Questionnaire" }, "description": { "type": "string", "description": "What this questionnaire is about", "example": "This questionnaire assesses AML/CFT and crypto compliance practices." }, "sections": { "type": "array", "description": "Questionnaire section", "items": { "type": "object", "required": [ "code", "title", "items" ], "properties": { "code": { "type": "string", "description": "Section reference", "example": "nature_of_business_section" }, "title": { "type": "string", "description": "Section title", "example": "Nature of Business" }, "items": { "type": "array", "items": { "type": "object", "required": [ "code", "title", "type", "required" ], "properties": { "code": { "type": "string", "description": "Question reference code", "example": "products_services_offered" }, "title": { "type": "string", "description": "Title of the question", "example": "What products or services does your company offer?" }, "type": { "type": "string", "description": "Answer text, selected option", "enum": [ "textArea", "textInput", "selectDropdown", "fileAttachment" ], "example": "selectDropdown" }, "required": { "type": "boolean", "description": "Shows whether the question is mandatory or optional", "example": true }, "options": { "type": "array", "description": "Answer options", "items": { "type": "object", "required": [ "value", "title" ], "properties": { "value": { "type": "string", "example": "yes" }, "title": { "type": "string", "example": "Yes" }, "score": { "type": "number", "example": 10 } } } } } } } } } } } } } } } }, "400": { "description": "Invalid or missing `codes` parameter." } } } }, "/platform/v1/customers/{customerReference}/questionnaires": { "put": { "summary": "Submit questionnaire", "description": ":::info Customers API v2\nThe [new customer onboarding flow](../../../get-started/create-embedded-partner-customer/create-customers-com) is recommended for all new integrations.\n\nIf you already have an existing integration with Customers API v1, you can continue using it. BVNK will continue to support this API going forward.\n:::\n\nSubmit questionnaire answers provided by your customers. BVNK validates completeness asynchronously and transitions the customer to the next onboarding state when all required answers are present. In case some answers are missing, BVNK specifies them and waits for all the answers to be submitted", "tags": [ "Onboarding" ], "operationId": "submitQuestionnaireResponses", "externalDocs": { "description": "Guide: Submit Questionnaire Responses", "url": "https://docs.bvnk.com/bvnk/get-started/create-embedded-partner-customer/onboard-epc#submit-questionnaire-responses" }, "parameters": [ { "name": "customerReference", "in": "path", "required": true, "description": "Unique customer reference (UUID or other immutable identifier) returned when the customer was created.", "schema": { "type": "string", "format": "uuid", "example": "52ec68a9-1ff1-4b7c-a8b5-0630de484e42" } } ], "requestBody": { "required": true, "description": "Array of questionnaire answer sets.", "content": { "application/json": { "schema": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "code", "sections" ], "properties": { "code": { "type": "string", "description": "Questionnaire identifier", "enum": [ "financialServicesQuestionnaireFull", "amlCryptoComplianceQuestionnaireFull", "gamblingQuestionnaireFull", "fintechsQuestionnaireFull", "otherQuestionnaireFull", "eddQuestionnaire" ], "example": "amlCryptoComplianceQuestionnaireFull" }, "sections": { "type": "array", "items": { "type": "object", "description": "Questionnaire section", "required": [ "code", "items" ], "properties": { "code": { "type": "string", "description": "Section reference", "example": "nature_of_business_section" }, "items": { "type": "array", "description": "Questions", "items": { "type": "object", "required": [ "code", "value" ], "properties": { "code": { "type": "string", "description": "Question reference code", "example": "products_services_offered" }, "value": { "type": "string", "description": "Answer text, selected option `value`", "example": "embedded" } } } } } } } } } }, "examples": { "minimal": { "summary": "Minimal submission", "value": [ { "code": "amlCryptoComplianceQuestionnaireFull", "sections": [ { "code": "nature_of_business_section", "items": [ { "code": "products_services_offered", "value": "embedded" } ] } ] } ] } } } } }, "responses": { "200": { "description": "Submission accepted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "message" ], "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Questionnaire submitted successfully." } } } } } }, "400": { "description": "Validation error (e.g., unknown codes, missing required answers)." }, "404": { "description": "Customer reference not found." } } } }, "/platform/v1/customers/questionnaires": { "get": { "summary": "Search questionnaire submissions", "description": ":::info Customers API v1\nIf you already have an integration with Customers API v1, you can continue using it. BVNK will continue to support this API going forward.\n:::\n\nReturns previously submitted questionnaire answer sets matching the supplied filters", "tags": [ "Onboarding" ], "operationId": "getQuestionnaires", "externalDocs": { "description": "Guide: Search Questionnaire Submissions", "url": "https://docs.bvnk.com/bvnk/get-started/create-embedded-partner-customer/onboard-epc#search-questionnaire-submissions" }, "security": [ { "Hawk": [ "merchant" ] } ], "parameters": [ { "name": "customerReference", "in": "query", "required": true, "description": "Unique customer reference used when the questionnaire was submitted.", "schema": { "type": "string", "format": "uuid", "example": "52ec68a9-1ff1-4b7c-a8b5-0630de484e42" } }, { "name": "codes", "in": "query", "required": false, "description": "One or more questionnaire codes to include (comma-separated).", "schema": { "type": "array", "items": { "type": "string", "description": "Questionnaire identifier", "enum": [ "financialServicesQuestionnaireFull", "amlCryptoComplianceQuestionnaireFull", "gamblingQuestionnaireFull", "fintechsQuestionnaireFull", "otherQuestionnaireFull", "eddQuestionnaire" ] } }, "explode": true, "example": [ "amlCryptoComplianceQuestionnaireFull", "fintechsQuestionnaireFull" ] }, { "name": "statuses", "in": "query", "required": false, "description": "One or more validation states to filter by.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "INIT", "OK", "NOK" ] } }, "style": "form", "explode": true, "example": [ "OK" ] } ], "responses": { "200": { "description": "Array of questionnaire submissions that meet the criteria.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "customerReference", "questionnaireCode", "status", "submittedDate", "sections" ], "properties": { "customerReference": { "type": "string", "format": "uuid", "description": "Unique customer reference used when the questionnaire was submitted.", "example": "52ec68a9-1ff1-4b7c-a8b5-0630de484e42" }, "questionnaireCode": { "type": "string", "description": "Questionnaire code", "enum": [ "financialServicesQuestionnaireFull", "amlCryptoComplianceQuestionnaireFull", "gamblingQuestionnaireFull", "fintechsQuestionnaireFull", "otherQuestionnaireFull", "eddQuestionnaire" ], "example": "amlCryptoComplianceQuestionnaireFull" }, "status": { "type": "string", "description": "One or more validation states to filter by.", "enum": [ "INIT", "OK", "NOK" ], "example": "OK" }, "submittedDate": { "type": "string", "description": "Date and time of the submitted questionnaire", "format": "date-time", "example": "2025-05-14T14:45:00Z" }, "sections": { "type": "array", "description": "Questionnaire section", "items": { "type": "object", "required": [ "code", "items" ], "properties": { "code": { "type": "string", "description": "Section reference", "example": "nature_of_business_section" }, "items": { "type": "array", "description": "Questions", "items": { "type": "object", "required": [ "code", "value" ], "properties": { "code": { "type": "string", "description": "Question reference code", "example": "products_services_offered" }, "value": { "type": "string", "description": "Answer text, selected option `value`", "example": "embedded" } } } } } } } } } }, "example": [ { "customerReference": "52ec68a9-1ff1-4b7c-a8b5-0630de484e42", "questionnaireCode": "amlCryptoComplianceQuestionnaireFull", "status": "OK", "submittedDate": "2025-05-14T14:45:00Z", "sections": [ { "code": "nature_of_business_section", "items": [ { "code": "products_services_offered", "value": "embedded" } ] } ] } ] } } }, "400": { "description": "Missing `customerReference` parameter." } } } }, "/platform/v1/accounts/industries": { "get": { "tags": [ "Customers" ], "summary": "List industries", "operationId": "getIndustries", "description": "Retrieves a definitive list of industries and sub-industries, which can be included in the payload when creating a customer.", "externalDocs": { "description": "Guide: Retrieve Industry References", "url": "https://docs.bvnk.com/bvnk/references/industy-references#retrieve-industry-references" }, "security": [ { "Hawk": [ "merchant" ] } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Industry name", "example": "Finance" }, "children": { "type": "array", "description": "Sub-industries (if any)", "items": { "type": "object", "properties": { "reference": { "type": "string", "format": "uuid", "example": "c6a1d2e3-4f56-7890-abcd-ef1234567890" }, "name": { "type": "string", "example": "Banking" } } } } } } }, "example": [ { "name": "Finance", "children": [ { "reference": "c6a1d2e3-4f56-7890-abcd-ef1234567890", "name": "Banking" }, { "reference": "d7b2e3f4-5678-9012-cdef-ab3456789012", "name": "Insurance" } ] }, { "name": "Technology", "children": [ { "reference": "f9d4a5b6-7890-1234-ef01-de5678901234", "name": "Software" } ] } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/platform/v1/accounts/monthly-expected-volumes": { "get": { "tags": [ "Customers" ], "summary": "List monthly expected volumes", "operationId": "getMonthlyExpectedVolumes", "description": "Retrieves a definitive list of Expected Monthly Volume values, which can be included in the payload when creating a customer.", "externalDocs": { "description": "Guide: Retrieve Monthly Expected Volumes References", "url": "https://docs.bvnk.com/bvnk/references/monthly-expected-volumes#retrieve-monthly-expected-volumes" }, "security": [ { "Hawk": [ "merchant" ] } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MonthlyExpectedVolumes" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/platform/v1/fees/customer-fee-wallets": { "get": { "tags": [ "Wallets" ], "summary": "Get customer fee wallets", "operationId": "getCustomerFeeWallets", "description": "Retrieves the list of available wallets that can receive customer fees.\n\nFor more information, refer to [Customer fees](https://docs.bvnk.com/docs/charge-customer-fees#/).", "security": [ { "Hawk": [ "merchant" ] } ], "responses": { "200": { "description": "Successfully retrieved customer fee wallets", "content": { "application/json": { "schema": { "type": "object", "properties": { "customerFeeWallets": { "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string", "description": "The three-letter currency code of the wallet in the ISO 4217 format.", "example": "EUR" }, "destinationWalletId": { "type": "string", "description": "The `lsid` of the wallet where customer fees for the specified currency will be credited.", "example": "a:25022552887731:z261S0y:1" }, "pageable": { "type": "object", "properties": { "pageNumber": { "type": "integer" }, "pageSize": { "type": "integer" }, "offset": { "type": "integer" }, "paged": { "type": "boolean" }, "unpaged": { "type": "boolean" } } }, "last": { "type": "boolean" }, "totalElements": { "type": "integer" }, "totalPages": { "type": "integer" }, "first": { "type": "boolean" }, "size": { "type": "integer" }, "number": { "type": "integer" }, "sort": { "type": "array", "items": { "type": "string" } }, "numberOfElements": { "type": "integer" }, "empty": { "type": "boolean" } } } } } }, "example": { "content": [ { "destinationWalletId": "a:25041552279666:vpH2wtz:1", "currency": "EUR" } ], "pageable": { "pageNumber": 0, "pageSize": 20, "sort": [], "offset": 0, "paged": true, "unpaged": false }, "first": true, "last": true, "size": 20, "number": 0, "sort": [], "numberOfElements": 1, "empty": false } } } }, "403": { "description": "Forbidden - Authorization token not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "BVNK ERROR CODE" }, "status": { "type": "string", "description": "ERROR STATUS" }, "message": { "type": "string", "description": "ERROR MESSAGE" }, "details": { "type": "object", "nullable": true, "description": "ERROR DETAILS" } } }, "example": { "code": "bvnk:0000", "status": "Forbidden", "message": "Authorization token not found", "details": null } } } } } }, "put": { "tags": [ "Wallets" ], "summary": "Set wallet for customer fees", "operationId": "setCustomerFeeWallet", "description": "Sets up the customer fee wallet for a specific currency. The customer fee wallet is where the collected customer fees will be credited when processing transactions. For more information, refer to [Customer fees](https://docs.bvnk.com/docs/charge-customer-fees#/).", "security": [ { "Hawk": [ "merchant" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "currency", "destinationWalletId" ], "properties": { "currency": { "type": "string", "description": "The three-letter currency code of the wallet in the ISO 4217 format.", "example": "EUR" }, "destinationWalletId": { "type": "string", "description": "The `lsid` of the wallet where customer fees will be credited.", "example": "a:25022552887731:z261S0y:1" } } }, "examples": { "Set Fee Wallet": { "summary": "Set the EUR fee wallet for customer fees", "value": { "currency": "EUR", "destinationWalletId": "a:25022552887731:z261S0y:1" } } } } } }, "responses": { "200": { "description": "Successfully retrieved customer fee wallets", "content": { "application/json": { "schema": { "type": "object", "properties": { "customerFeeWallets": { "type": "array", "items": { "type": "object", "properties": { "currency": { "type": "string", "description": "The three-letter currency code of the wallet in the ISO 4217 format.", "example": "EUR" }, "destinationWalletId": { "type": "string", "description": "The ID of the wallet where customer fees for the specified currency will be credited.", "example": "a:25022552887731:z261S0y:1" } } } } } }, "example": { "content": [ { "destinationWalletId": "a:25041552279666:vpH2wtz:1", "currency": "EUR" } ] } } } }, "403": { "description": "Forbidden - Authorization token not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "BVNK ERROR CODE" }, "status": { "type": "string", "description": "ERROR STATUS" }, "message": { "type": "string", "description": "ERROR MESSAGE" }, "details": { "type": "object", "nullable": true, "description": "ERROR DETAILS" } } }, "example": { "code": "bvnk:0000", "status": "Forbidden", "message": "Authorization token not found", "details": null } } } }, "404": { "description": "Not Found - Wallet not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "bvnk:fees:0002" }, "status": { "type": "string", "example": "Not Found" }, "message": { "type": "string", "example": "Wallet with ID 'a:24022637884682:hxhalPr:1' not found." }, "details": { "type": "object", "nullable": true, "example": null } } } } } }, "422": { "description": "Unprocessable Entity - Invalid input parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "BVNK ERROR CODE" }, "status": { "type": "string", "description": "ERROR STATUS" }, "message": { "type": "string", "description": "ERROR MESSAGE" }, "details": { "type": "object", "nullable": true, "description": "ERROR DETAILS" } } }, "example": { "code": "bvnk:fees:0001", "status": "Unprocessable Entity", "message": "Wallet currency 'EUR' does not match fee currency 'USD'", "details": null } } } } } } }, "/onboarding/v1/applications": { "post": { "tags": [ "Onboarding" ], "summary": "Create business customer", "description": "Creates a business customer onboarding application in a single request. Submit company details, associates, and business profile together. BVNK enriches the submission and routes it to the onboarding orchestrator.\n\nJurisdiction guidance:\n- EU flows require associate nationality, birth country, and biometric/selfie evidence.\n- US flows require US tax identifiers where applicable and may require additional fields for control persons.\n- `stateCode` for US addresses is planned for a future release and is not yet enforced.\n\nOnboarding completes automatically once required company documents, associate identification documents, required questionnaires, and assigned agreements are all submitted and accepted for processing.", "operationId": "createBusinessCustomerOnboardingApplication", "security": [ { "Hawk": [ "merchant" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBusinessCustomerOnboardingRequest" }, "examples": { "BVNK-Managed EU example": { "summary": "Create a customer onboarding application for an EU company", "value": { "onboardingType": "EMBEDDED", "embeddedPartnerCustomer": { "partnerAccountReference": "partner-ref-001", "company": { "name": "Krause Fintech GmbH", "entityType": "CORPORATION", "taxNumber": "DE123456789", "registrationNumber": "HRB 123456", "incorporationDate": "2019-01-15", "businessOperationsStartDate": "2019-02-01", "address": { "addressLine1": "Heidestrasse 19", "city": "Koeln", "postalCode": "51247", "countryCode": "DE" }, "businessProfile": { "description": "German fintech company specializing in payment solutions and financial software", "naicsCode": "5239", "monthlyExpectedVolumes": "FROM_100K_TO_1M", "website": "https://www.krause-fintech.de", "customerTypes": "Both", "prohibitedJurisdictionsExposure": false, "annualIncomingTransactionValue": "500000", "annualOutgoingTransactionValue": "250000", "jurisdictionalPortfolioDistribution": [ { "country": "DE", "percentage": 45 }, { "country": "FR", "percentage": 35 }, { "country": "DE", "percentage": 25 } ], "isRegulated": true, "sourceOfFunds": "COMMERCIAL_ACTIVITIES", "intendedUseOfAccount": "SUPPLIER_VENDOR_PAYMENTS" }, "associates": [ { "person": { "firstName": "Freya", "lastName": "Krause", "dateOfBirth": "1982-03-24", "birthCountryCode": "DE", "nationality": "DE", "address": { "addressLine1": "Heidestrasse 19", "city": "Koeln", "postalCode": "51247", "countryCode": "DE" }, "contactInfo": { "emailAddress": "freya.krause@krause-fintech.de" }, "taxIdentification": { "number": "21/815/08150", "taxResidenceCountryCode": "DE" }, "position": "Geschaeftsfuehrer" }, "titles": [ "BUSINESS_OWNER", "DIRECTOR", "SIGNATORY", "ACCOUNT_REPRESENTATIVE" ], "ownership": { "percentage": 100, "type": "DIRECT" } } ] }, "useCase": "STABLECOIN_PAYOUTS", "externalReference": "ext-ref-001" } } } } } } }, "responses": { "200": { "description": "Onboarding application created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBusinessCustomerOnboardingResponse" }, "example": { "id": "810fd34b-54d3-4a95-9d87-28804c3353b9", "status": "NOT_STARTED" } } } }, "400": { "$ref": "#/components/responses/BadRequestMessage" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/onboarding/v1/applications/{onboardingId}/status": { "get": { "tags": [ "Onboarding" ], "summary": "Retrieve application status", "description": "Retrieves the current onboarding application state, including associates' validation status, outstanding required documents, questionnaire definitions, validation errors, and agreement statuses.\n\n- Associate `validationStatus=INVALID` means outstanding requirements still exist; inspect `requiredDocuments`, `questionnaireDefinitions`, and `validationErrors`.\n- On rejection, `rejectLabels` and `clientComment` describe why resubmission is required.", "operationId": "getOnboardingApplicationStatus", "security": [ { "Hawk": [ "merchant" ] } ], "parameters": [ { "name": "onboardingId", "in": "path", "required": true, "description": "Onboarding application ID returned by the create onboarding request.", "schema": { "type": "string", "format": "uuid", "example": "810fd34b-54d3-4a95-9d87-28804c3353b9" } } ], "responses": { "200": { "description": "Current onboarding status and requirements", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingStatusResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/onboarding/v1/applications/{onboardingId}/documents": { "post": { "tags": [ "Onboarding" ], "summary": "Upload company documents", "description": "Uploads company-level KYB documents for an onboarding application as `multipart/form-data`.\n\nThe `metadata` field is a JSON array and `files` contains one file per metadata entry in matching order.\n\nUse this endpoint for initial mandatory KYB files and for conditional/risk-triggered requests (for example Source of Wealth, AML policy, or regulatory licence). If a document is rejected later, re-upload the corrected file to this endpoint to replace the rejected submission.\n\nBest practice: upload documents sequentially and add a 1-second delay to reduce rate-limit pressure.", "operationId": "uploadOnboardingCompanyDocuments", "security": [ { "Hawk": [ "merchant" ] } ], "parameters": [ { "name": "onboardingId", "in": "path", "required": true, "description": "Onboarding application ID.", "schema": { "type": "string", "format": "uuid", "example": "810fd34b-54d3-4a95-9d87-28804c3353b9" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/OnboardingCompanyDocumentsUploadRequest" }, "examples": {} } } }, "responses": { "200": { "description": "Documents accepted for processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingCompanyDocumentsUploadResponse" }, "example": { "onboardingApplicationId": "810fd34b-54d3-4a95-9d87-28804c3353b9", "documentCount": 6, "message": "Documents accepted for processing" } } } }, "400": { "$ref": "#/components/responses/BadRequestMessage" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/onboarding/v1/associates/{associateId}/identification-documents": { "post": { "tags": [ "Onboarding" ], "summary": "Upload associate identity documents", "description": "Uploads identity and address verification documents for a specific associate as `multipart/form-data`.\n\nUse `associateId` from the onboarding status response (`GET /onboarding/v1/applications/{onboardingId}/status`).\n\nJurisdiction guidance:\n- EU: selfie/liveness and proof of address are generally mandatory.\n- US: selfie may be optional while tax and control-person requirements can apply.\n\nIf a submitted document is rejected, resubmit a corrected file through the same endpoint; the previous rejected document is replaced.", "operationId": "uploadOnboardingAssociateIdentificationDocuments", "security": [ { "Hawk": [ "merchant" ] } ], "parameters": [ { "name": "associateId", "in": "path", "required": true, "description": "Associate ID returned by onboarding status response.", "schema": { "type": "string", "format": "uuid", "example": "07b099fa-e1ee-4ad4-9cc4-6f2513a5a240" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/OnboardingAssociateIdentificationDocumentsUploadRequest" }, "examples": {} } } }, "responses": { "200": { "description": "Associate documents accepted for processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingAssociateIdentificationDocumentsUploadResponse" }, "example": { "associateId": "07b099fa-e1ee-4ad4-9cc4-6f2513a5a240", "acceptedDocumentCount": 3, "message": "Documents accepted for processing" } } } }, "400": { "$ref": "#/components/responses/BadRequestMessage" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/onboarding/v1/associates/{associateId}/questionnaires": { "put": { "tags": [ "Onboarding" ], "summary": "Submit associate questionnaires", "description": "Submits questionnaire responses for an associate. Always source questionnaire IDs, section IDs, item IDs, and accepted values from `questionnaireDefinitions` returned by onboarding status response (`GET /onboarding/v1/applications/{onboardingId}/status`), as structures vary by jurisdiction and risk profile.", "operationId": "submitOnboardingAssociateQuestionnaires", "security": [ { "Hawk": [ "merchant" ] } ], "parameters": [ { "name": "associateId", "in": "path", "required": true, "description": "Associate ID returned by onboarding status response.", "schema": { "type": "string", "format": "uuid", "example": "07b099fa-e1ee-4ad4-9cc4-6f2513a5a240" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingAssociateQuestionnairesSubmitRequest" }, "example": { "questionnaires": [ { "id": "estimatedYearlyIncome", "sections": { "estimatedYearlyIncome": { "items": { "estimatedYearlyIncome": { "value": "INCOME_100K_TO_250K" } } } } } ] } } } }, "responses": { "200": { "description": "Questionnaires submitted successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingAssociateQuestionnairesSubmitResponse" }, "example": { "success": true, "message": "Questionnaires submitted successfully", "submittedCount": 1 } } } }, "400": { "$ref": "#/components/responses/BadRequestMessage" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/onboarding/v1/assigned-agreements": { "get": { "tags": [ "Onboarding" ], "summary": "Retrieve assigned agreements", "description": "Returns agreements assigned to an onboarding application. All assigned agreements must reach `ACCEPTED` status for onboarding to proceed.\n\nUse this endpoint with the onboarding application ID: `GET /onboarding/v1/assigned-agreements?applicationId={onboardingId}`.\n\nAssigned agreements can be accepted at any point after customer creation (before or after document uploads); there is no ordering dependency.", "operationId": "getOnboardingAssignedAgreements", "security": [ { "Hawk": [ "merchant" ] } ], "parameters": [ { "name": "applicationId", "in": "query", "required": true, "description": "Onboarding application ID returned by `POST /onboarding/v1/applications`.", "schema": { "type": "string", "format": "uuid", "example": "810fd34b-54d3-4a95-9d87-28804c3353b9" } } ], "responses": { "200": { "description": "Assigned agreements for the onboarding application", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OnboardingAssignedAgreement" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/onboarding/v1/assigned-agreements/{assignedAgreementId}": { "patch": { "tags": [ "Onboarding" ], "summary": "Accept assigned agreement", "description": "Accepts an assigned agreement. Agreement status transitions from `PENDING` to `ACCEPTED`.\n\nUse the `assignedAgreementId` returned by `GET /onboarding/v1/assigned-agreements?applicationId={id}`. All assigned agreements must be accepted before onboarding can complete.", "operationId": "acceptOnboardingAssignedAgreement", "security": [ { "Hawk": [ "merchant" ] } ], "parameters": [ { "name": "assignedAgreementId", "in": "path", "required": true, "description": "Assigned agreement ID returned by the assigned agreements endpoint.", "schema": { "type": "string", "format": "uuid", "example": "06d119bc-64f6-46b2-aea2-3ff94c4c616f" } } ], "responses": { "200": { "description": "Agreement accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OnboardingAssignedAgreementAcceptResponse" }, "example": { "status": "ACCEPTED", "respondedAt": "2026-03-25T11:03:05.714549740Z", "respondedBy": { "type": "USER", "username": "partner@example.com" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/platform/v2/customers": { "post": { "tags": [ "Customers" ], "summary": "Create customer (v.2)", "description": "Starts a new customer onboarding application. Submit either a `company` or `individual` payload together with the `useCase`.\n\nJurisdiction guidance:\n- EU flows require associate nationality, birth country, and biometric/selfie evidence.\n- US flows require US tax identifiers where applicable and may require additional fields for control persons.\n- `stateCode` for US addresses is planned for a future release and is not yet enforced.\n\nOnboarding completes automatically once required company documents, associate identification documents, required questionnaires, and assigned agreements are all submitted and accepted for processing.\n\n:::warning\nBefore calling this endpoint, make sure you are not onboarding customers from restricted jurisdictions. For more information, see [BVNK Acceptable Use Policy](https://help.bvnk.com/hc/en-us/articles/11100445499666-BVNK-Acceptable-Use-Policy-Financial-Crime).\n:::", "operationId": "createCustomerV2", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Client-supplied idempotency key.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2CreateCustomerRequest" }, "examples": { "BVNK-Managed EU company": { "summary": "Create a company customer onboarding application for an EU company", "value": { "useCase": "STABLECOIN_PAYOUTS", "reference": "b3a4c1e2-9a1f-4c2b-8f11-7c2e5d4f9a01", "company": { "name": "Krause Fintech GmbH", "entityType": "CORPORATION", "taxIdentification": { "number": "DE123456789", "taxResidenceCountryCode": "DE" }, "registrationNumber": "HRB 123456", "incorporationDate": "2019-01-15", "businessOperationsStartDate": "2019-02-01", "address": { "addressLine1": "Heidestrasse 19", "city": "Koeln", "postalCode": "51247", "countryCode": "DE" }, "isOperationalAddressDifferent": false, "businessProfile": { "description": "German fintech company specializing in payment solutions and financial software", "naicsCode": "5239", "monthlyExpectedVolumes": "FROM_100K_TO_1M", "website": "https://www.krause-fintech.de", "customerTypes": "Both", "prohibitedJurisdictionsExposure": false, "annualIncomingTransactionValue": "500000", "annualOutgoingTransactionValue": "250000", "jurisdictionalPortfolioDistribution": [ { "country": "DE", "percentage": 45 }, { "country": "FR", "percentage": 35 }, { "country": "DE", "percentage": 25 } ], "isRegulated": true, "regulatorInformation": { "regulatorName": "BaFin", "regulatorJurisdiction": "DE" }, "isPubliclyListed": false, "sourceOfFunds": "COMMERCIAL_ACTIVITIES", "intendedUseOfAccount": "SUPPLIER_VENDOR_PAYMENTS" }, "associates": [ { "person": { "firstName": "Freya", "lastName": "Krause", "dateOfBirth": "1982-03-24", "nationality": "DE", "birthCountryCode": "DE", "address": { "addressLine1": "Heidestrasse 19", "city": "Koeln", "postalCode": "51247", "countryCode": "DE" }, "contactInfo": { "emailAddress": "freya.krause@krause-fintech.de" }, "taxIdentification": { "number": "21/815/08150", "taxResidenceCountryCode": "DE" }, "position": "Geschaeftsfuehrer" }, "titles": [ "UBO", "DIRECTOR", "SIGNATORY", "ACCOUNT_REPRESENTATIVE" ], "ownership": { "percentage": "100", "type": "DIRECT" } } ] } } }, "Individual": { "summary": "Create an individual customer", "value": { "useCase": "FIAT", "reference": "partner-ind-001", "individual": { "firstName": "Jane", "lastName": "Mueller", "emailAddress": "jane.mueller@example.com", "phoneNumber": "+49301234567", "dateOfBirth": "1990-06-15", "placeOfBirth": "Berlin", "nationality": "DE", "address": { "addressLine1": "Unter den Linden 77", "city": "Berlin", "postalCode": "10117", "countryCode": "DE" }, "taxIdentification": { "number": "21/815/09150", "taxResidenceCountryCode": "DE" }, "cdd": { "employmentStatus": "SALARIED", "sourceOfFunds": "SALARY", "pepStatus": "NOT_PEP", "intendedUseOfAccount": "TRANSFERS_OWN_WALLET", "expectedMonthlyVolume": "FROM_0_TO_10K" } } } } } } } }, "responses": { "201": { "description": "Customer onboarding application created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2CustomerResponse" }, "example": { "id": "0a184641-30e2-4414-871f-3db1c683900e", "reference": "b3a4c1e2-9a1f-4c2b-8f11-7c2e5d4f9a01", "status": "PENDING", "type": "COMPANY", "model": "EMBEDDED_BVNK_MANAGED", "useCase": "STABLECOIN_PAYOUTS", "name": "Krause Fintech GmbH", "createdAt": "2026-04-22T10:57:35.056865Z", "updatedAt": "2026-04-22T10:57:35.056865Z" } } } }, "400": { "$ref": "#/components/responses/BadRequestMessage" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "Idempotency key re-used with a different payload" }, "422": { "description": "The onboarding request was rejected" } } }, "get": { "tags": [ "Customers" ], "summary": "Search customers (v.2)", "description": "Searches customers associated with the caller's account, with optional filters and pagination.", "operationId": "searchCustomersV2", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "name", "in": "query", "required": false, "description": "Filter by customer display name (partial match).", "schema": { "type": "string", "example": "Krause" } }, { "name": "statuses", "in": "query", "required": false, "description": "Filter by lifecycle status. Repeat to pass multiple values.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "INFO_REQUIRED", "PENDING", "ACTIONS_REQUIRED", "VERIFIED", "REJECTED", "TERMINATED" ] } } }, { "name": "types", "in": "query", "required": false, "description": "Filter by customer type.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "COMPANY", "INDIVIDUAL" ] } } }, { "name": "models", "in": "query", "required": false, "description": "Filter by account-structure model.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "CUSTOMER_VIRTUAL_ACCOUNTS", "EMBEDDED_BVNK_MANAGED", "EMBEDDED_SELF_MANAGED", "DOUBLE_EMBEDDED" ] } } }, { "name": "reference", "in": "query", "required": false, "description": "Filter by partner-supplied reference (exact match).", "schema": { "type": "string" } }, { "name": "pageNumber", "in": "query", "required": false, "description": "Zero-based page number.", "schema": { "type": "integer", "minimum": 0, "example": 0 } }, { "name": "pageSize", "in": "query", "required": false, "description": "Number of items per page. Max 500.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "example": 20 } } ], "responses": { "200": { "description": "Paginated list of customers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2PaginatedCustomerSummaryResponse" }, "example": { "totalElements": 1, "totalPages": 1, "content": [ { "id": "0a184641-30e2-4414-871f-3db1c683900e", "reference": "b3a4c1e2-9a1f-4c2b-8f11-7c2e5d4f9a01", "status": "PENDING", "type": "COMPANY", "model": "EMBEDDED_BVNK_MANAGED", "name": "Krause Fintech GmbH", "createdAt": "2026-04-22T10:57:35.056865Z" } ], "pageable": { "pageNumber": 0, "pageSize": 20 }, "hasNext": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/platform/v2/customers/{id}": { "get": { "tags": [ "Customers" ], "summary": "Get customer (v.2)", "description": "Retrieves a customer by id, including the submitted onboarding body (`company` or `individual`). Person associates are inlined under `company.associates`; business-registration associates remain accessible via `GET /platform/v2/customers/{customerId}/associates/{associateId}`.", "operationId": "getCustomerV2", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Customer id.", "schema": { "type": "string", "format": "uuid", "example": "0a184641-30e2-4414-871f-3db1c683900e" } } ], "responses": { "200": { "description": "Customer details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2CustomerDetailResponse" }, "example": { "id": "0a184641-30e2-4414-871f-3db1c683900e", "reference": "b3a4c1e2-9a1f-4c2b-8f11-7c2e5d4f9a01", "status": "PENDING", "type": "COMPANY", "model": "EMBEDDED_BVNK_MANAGED", "useCase": "STABLECOIN_PAYOUTS", "name": "Krause Fintech GmbH", "createdAt": "2026-04-22T10:57:35.056865Z", "updatedAt": "2026-04-22T10:57:35.056865Z", "company": { "name": "Krause Fintech GmbH", "entityType": "CORPORATION", "taxIdentification": { "number": "DE123456789", "taxResidenceCountryCode": "DE" }, "registrationNumber": "HRB 123456", "incorporationDate": "2019-01-15", "businessOperationsStartDate": "2019-02-01", "address": { "addressLine1": "Heidestrasse 19", "city": "Koeln", "postalCode": "51247", "countryCode": "DE" }, "isOperationalAddressDifferent": false, "businessProfile": { "description": "German fintech company specializing in payment solutions and financial software", "naicsCode": "5239", "monthlyExpectedVolumes": "FROM_100K_TO_1M", "website": "https://www.krause-fintech.de", "customerTypes": "Both", "prohibitedJurisdictionsExposure": false, "annualIncomingTransactionValue": "500000", "annualOutgoingTransactionValue": "250000", "isRegulated": true, "regulatorInformation": { "regulatorName": "BaFin", "regulatorJurisdiction": "DE" }, "isPubliclyListed": false, "sourceOfFunds": "COMMERCIAL_ACTIVITIES", "intendedUseOfAccount": "SUPPLIER_VENDOR_PAYMENTS" }, "associates": [ { "person": { "firstName": "Freya", "lastName": "Krause", "dateOfBirth": "1982-03-24", "nationality": "DE", "birthCountryCode": "DE", "address": { "addressLine1": "Heidestrasse 19", "city": "Koeln", "postalCode": "51247", "countryCode": "DE" }, "contactInfo": { "emailAddress": "freya.krause@krause-fintech.de" }, "taxIdentification": { "number": "21/815/08150", "taxResidenceCountryCode": "DE" }, "position": "Geschaeftsfuehrer" }, "titles": [ "UBO", "DIRECTOR", "SIGNATORY", "ACCOUNT_REPRESENTATIVE" ], "ownership": { "percentage": "100", "type": "DIRECT" } } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/platform/v2/customers/{customerId}/documents": { "post": { "tags": [ "Manage Documents" ], "summary": "Upload company documents (v.2)", "description": "Uploads 1-3 company-level KYB documents for a customer as `multipart/form-data`.\n\nThe `metadata` field is a JSON array and `files` contains one file per metadata entry in matching order.\n\nUse this endpoint for initial mandatory KYB files and for conditional/risk-triggered requests (for example Source of Wealth, AML policy, or regulatory licence). If a document is rejected later, re-upload the corrected file to this endpoint to replace the rejected submission.\n\nBest practice: upload documents sequentially and add a 1-second delay to reduce rate-limit pressure.", "operationId": "uploadCustomerCompanyDocumentsV2", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "description": "Customer id.", "schema": { "type": "string", "format": "uuid", "example": "0a184641-30e2-4414-871f-3db1c683900e" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/V2CustomerDocumentsUploadRequest" } } } }, "responses": { "202": { "description": "Documents accepted for processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2UploadCustomerDocumentsResponse" }, "example": { "id": "9b0c4f1d-7aa2-4c7e-8d55-f8b4a1d6c210", "customerId": "0a184641-30e2-4414-871f-3db1c683900e", "totalDocuments": 3, "successCount": 3, "failureCount": 0, "documents": [ { "documentId": "b8f8a6b5-8f44-4b7c-8d1e-4a6a5a9b4a21", "type": "CERTIFICATE_OF_INCORPORATION", "filename": "certificate.pdf", "description": "Certificate of Incorporation", "status": "STORED", "uploadedAt": "2026-04-22T10:58:35.056865Z" } ], "createdAt": "2026-04-22T10:58:35.056865Z" } } } }, "400": { "$ref": "#/components/responses/BadRequestMessage" }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "get": { "tags": [ "Manage Documents" ], "summary": "List customer documents (v.2)", "description": "Returns a paginated list of documents associated with a customer.", "operationId": "listCustomerDocumentsV2", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "description": "Customer id.", "schema": { "type": "string", "format": "uuid", "example": "0a184641-30e2-4414-871f-3db1c683900e" } }, { "name": "pageNumber", "in": "query", "required": false, "description": "Zero-based page number.", "schema": { "type": "integer", "minimum": 0, "example": 0 } }, { "name": "pageSize", "in": "query", "required": false, "description": "Number of items per page. Max 500.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "example": 20 } } ], "responses": { "200": { "description": "Paginated list of documents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2PaginatedCustomerDocumentSummaryResponse" }, "example": { "totalElements": 1, "totalPages": 1, "content": [ { "id": "b8f8a6b5-8f44-4b7c-8d1e-4a6a5a9b4a21", "filename": "certificate.pdf", "type": "CERTIFICATE_OF_INCORPORATION", "status": "COMPLETE", "createdAt": "2026-04-22T10:58:35.056865Z" } ], "pageable": { "pageNumber": 0, "pageSize": 20 }, "hasNext": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/platform/v2/customers/{customerId}/documents/{documentId}": { "get": { "tags": [ "Manage Documents" ], "summary": "Get customer document (v.2)", "description": "Returns a single customer document by their `id`'s.", "operationId": "getCustomerDocumentV2", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "description": "Customer id.", "schema": { "type": "string", "format": "uuid", "example": "0a184641-30e2-4414-871f-3db1c683900e" } }, { "name": "documentId", "in": "path", "required": true, "description": "Document id.", "schema": { "type": "string", "format": "uuid", "example": "b8f8a6b5-8f44-4b7c-8d1e-4a6a5a9b4a21" } } ], "responses": { "200": { "description": "Customer document details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2CustomerDocumentResponse" }, "example": { "id": "b8f8a6b5-8f44-4b7c-8d1e-4a6a5a9b4a21", "filename": "certificate.pdf", "type": "CERTIFICATE_OF_INCORPORATION", "checksum": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "status": "COMPLETE", "createdAt": "2026-04-22T10:58:35.056865Z", "updatedAt": "2026-04-22T10:58:35.056865Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/platform/v2/customers/{customerId}/documents/{documentId}/content": { "get": { "tags": [ "Manage Documents" ], "summary": "Download customer document (v.2)", "description": "Downloads a customer document as a binary file attachment.", "operationId": "downloadCustomerDocumentV2", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "description": "Customer id.", "schema": { "type": "string", "format": "uuid", "example": "0a184641-30e2-4414-871f-3db1c683900e" } }, { "name": "documentId", "in": "path", "required": true, "description": "Document id.", "schema": { "type": "string", "format": "uuid", "example": "b8f8a6b5-8f44-4b7c-8d1e-4a6a5a9b4a21" } } ], "responses": { "200": { "description": "Binary file attachment", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/platform/v2/customers/{customerId}/associates": { "post": { "tags": [ "Customers" ], "summary": "Create customer associate (v.2)", "description": "Creates an associate under a customer onboarding application. The `entity` payload is discriminated by `type`: use `PERSON` for a natural person (UBO, director, signatory, account representative) or `BUSINESS_REGISTRATION` for a registered-business owner.", "operationId": "createCustomerAssociateV2", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "description": "Customer id.", "schema": { "type": "string", "format": "uuid", "example": "0a184641-30e2-4414-871f-3db1c683900e" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Client-supplied idempotency key.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2CreateAssociateRequest" }, "examples": { "Person associate": { "summary": "Create a natural-person associate", "value": { "types": [ "UBO", "DIRECTOR" ], "entity": { "type": "PERSON", "firstName": "Freya", "lastName": "Krause", "email": "freya.krause@krause-fintech.de", "phoneNumber": "+4915112345678", "dateOfBirth": "1982-03-24", "nationality": "DE", "birthCountryCode": "DE", "taxIdentificationNumber": "21/815/08150", "taxResidence": "DE", "position": "Geschaeftsfuehrer", "isPoliticallyExposedPerson": false, "percentageOfOwnership": "100", "ownershipType": "DIRECT", "controlOptions": { "canAppointDirectors": true, "hasSignificantControl": true, "controlsManagement": true, "controlsCorporateBody": true }, "address": { "addressLine1": "Heidestrasse 19", "city": "Koeln", "postalCode": "51247", "countryCode": "DE" } } } }, "Business registration associate": { "summary": "Create a registered-business associate", "value": { "types": [ "UBO" ], "entity": { "type": "BUSINESS_REGISTRATION", "entityName": "Krause Holdings Ltd", "registrationCountry": "DE", "registrationNumber": "12345678", "percentageOfOwnership": "75", "typeOfOwnership": "INDIRECT" } } } } } } }, "responses": { "200": { "description": "Associate created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Associate id." } } }, "example": { "id": "07b099fa-e1ee-4ad4-9cc4-6f2513a5a240" } } } }, "400": { "$ref": "#/components/responses/BadRequestMessage" }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "get": { "tags": [ "Customers" ], "summary": "List customer associates (v.2)", "description": "Returns a paginated list of associates for a customer.", "operationId": "listCustomerAssociatesV2", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "description": "Customer id.", "schema": { "type": "string", "format": "uuid", "example": "0a184641-30e2-4414-871f-3db1c683900e" } }, { "name": "pageNumber", "in": "query", "required": false, "description": "Zero-based page number.", "schema": { "type": "integer", "minimum": 0, "example": 0 } }, { "name": "pageSize", "in": "query", "required": false, "description": "Number of items per page. Max 500.", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "example": 20 } } ], "responses": { "200": { "description": "Paginated list of associates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2PaginatedAssociateSummaryResponse" }, "example": { "totalElements": 1, "totalPages": 1, "content": [ { "id": "07b099fa-e1ee-4ad4-9cc4-6f2513a5a240", "types": [ "UBO", "DIRECTOR" ], "displayName": "Freya Krause", "validation": { "status": "INCOMPLETE", "issues": [] }, "createdAt": "2026-04-22T10:57:35.056865Z", "updatedAt": "2026-04-22T10:57:35.056865Z" } ], "pageable": { "pageNumber": 0, "pageSize": 20 }, "hasNext": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/platform/v2/customers/{customerId}/associates/{associateId}": { "get": { "tags": [ "Customers" ], "summary": "Get customer associate (v.2)", "description": "Returns a single associate by id.", "operationId": "getCustomerAssociateV2", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "description": "Customer id.", "schema": { "type": "string", "format": "uuid", "example": "0a184641-30e2-4414-871f-3db1c683900e" } }, { "name": "associateId", "in": "path", "required": true, "description": "Associate id.", "schema": { "type": "string", "format": "uuid", "example": "07b099fa-e1ee-4ad4-9cc4-6f2513a5a240" } } ], "responses": { "200": { "description": "Associate details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2AssociateResponse" }, "example": { "id": "07b099fa-e1ee-4ad4-9cc4-6f2513a5a240", "types": [ "UBO", "DIRECTOR" ], "entity": { "type": "PERSON", "firstName": "Freya", "lastName": "Krause", "email": "freya.krause@krause-fintech.de", "phoneNumber": "+4915112345678", "dateOfBirth": "1982-03-24", "nationality": "DE", "birthCountryCode": "DE", "taxIdentificationNumber": "21/815/08150", "taxResidence": "DE", "position": "Geschaeftsfuehrer", "isPoliticallyExposedPerson": false, "percentageOfOwnership": "100", "ownershipType": "DIRECT", "controlOptions": { "canAppointDirectors": true, "hasSignificantControl": true, "controlsManagement": true, "controlsCorporateBody": true }, "address": { "addressLine1": "Heidestrasse 19", "city": "Koeln", "postalCode": "51247", "countryCode": "DE" } }, "validation": { "status": "INCOMPLETE", "issues": [] }, "createdAt": "2026-04-22T10:57:35.056865Z", "updatedAt": "2026-04-22T10:57:35.056865Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Customers" ], "summary": "Delete customer associate (v.2)", "description": "Deletes an associate from a customer onboarding application. Safe to call before the application transitions to a terminal state.", "operationId": "deleteCustomerAssociateV2", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "description": "Customer id.", "schema": { "type": "string", "format": "uuid", "example": "0a184641-30e2-4414-871f-3db1c683900e" } }, { "name": "associateId", "in": "path", "required": true, "description": "Associate id.", "schema": { "type": "string", "format": "uuid", "example": "07b099fa-e1ee-4ad4-9cc4-6f2513a5a240" } } ], "responses": { "204": { "description": "Associate deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/platform/v2/customers/{customerId}/associates/{associateId}/identification-documents": { "post": { "tags": [ "Manage Documents" ], "summary": "Upload associate identification documents (v.2)", "description": "Uploads 1-3 identification and address verification documents for a specific associate as `multipart/form-data`.\n\nUse `associateId` returned by the create-associate or list-associates endpoint.\n\nJurisdiction guidance:\n- EU: selfie/liveness and proof of address are generally mandatory.\n- US: selfie may be optional while tax and control-person requirements can apply.\n\nIf a submitted document is rejected, resubmit a corrected file through the same endpoint; the previous rejected document is replaced.", "operationId": "uploadAssociateIdentificationDocumentsV2", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "description": "Customer id.", "schema": { "type": "string", "format": "uuid", "example": "0a184641-30e2-4414-871f-3db1c683900e" } }, { "name": "associateId", "in": "path", "required": true, "description": "Associate id.", "schema": { "type": "string", "format": "uuid", "example": "07b099fa-e1ee-4ad4-9cc4-6f2513a5a240" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/V2IdentificationDocumentsUploadRequest" } } } }, "responses": { "202": { "description": "Documents accepted for processing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2UploadIdentificationDocumentsResponse" }, "example": { "id": "4b0b8e2e-2f4e-4bfa-86d2-95aed0512c5f", "associateId": "07b099fa-e1ee-4ad4-9cc4-6f2513a5a240", "acceptedDocumentCount": 3, "createdAt": "2026-04-22T11:00:35.056865Z" } } } }, "400": { "$ref": "#/components/responses/BadRequestMessage" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/platform/v2/customers/{customerId}/agreements": { "get": { "tags": [ "Agreements" ], "summary": "Get assigned agreements", "description": "Returns the set of agreements assigned to an existing customer. Each item carries its current `status` (PENDING / ACCEPTED / REJECTED) and, once responded to, the `respondedAt` timestamp. All assigned agreements must reach `ACCEPTED` for onboarding to proceed.", "operationId": "listCustomerAssignedAgreementsV2", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "customerId", "in": "path", "required": true, "description": "Unique identifier of the customer whose assigned agreements are being retrieved.", "schema": { "type": "string", "format": "uuid", "example": "0a184641-30e2-4414-871f-3db1c683900e" } } ], "responses": { "200": { "description": "List of assigned agreements", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2PaginatedAssignedAgreementResponse" }, "example": { "totalElements": 1, "totalPages": 1, "content": [ { "id": "b9fd5289-cae1-45f1-ae19-40ec4b06a452", "agreement": { "version": null, "title": "Partner Platform Agreement (Non-US)", "locale": null }, "status": "ACCEPTED", "respondedAt": "2026-05-11T07:33:56.058034Z", "respondedToDocumentChecksum": null, "createdAt": "2026-05-11T07:33:56.060999Z", "updatedAt": "2026-05-11T07:33:56.066011Z" } ], "pageable": { "pageNumber": 0, "pageSize": 64 }, "hasNext": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/platform/v2/agreements": { "post": { "tags": [ "Agreements" ], "summary": "Create pre-customer agreements", "description": "Create an agreement working set for a prospective customer (before a customer record exists). Identified by a partner-supplied `reference` that must be unique within the caller's account.\n\n:::warning\nBefore calling this endpoint, make sure you are not onboarding customers from restricted jurisdictions. For more information, see [BVNK Acceptable Use Policy](https://help.bvnk.com/hc/en-us/articles/11100445499666-BVNK-Acceptable-Use-Policy-Financial-Crime).\n:::", "operationId": "createPreCustomerAgreementsV2", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyNew" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reference", "useCase", "customerType", "countryCode" ], "properties": { "reference": { "type": "string", "description": "Partner-supplied identifier for the agreement working set. Must be unique within the caller's account and will later be used to retrieve, bulk-respond to, or bind the working set to a customer." }, "useCase": { "type": "string", "description": "Type of product to which the customer agreement applies.", "enum": [ "STABLECOIN_PAYOUTS", "EMBEDDED_STABLECOIN_WALLETS", "EMBEDDED_FIAT_ACCOUNTS" ] }, "customerType": { "type": "string", "description": "Type of customer the working set is being prepared for.", "enum": [ "COMPANY", "INDIVIDUAL" ] }, "countryCode": { "type": "string", "description": "Country code of the customer's address in the ISO 3166-1 alpha-2 format." } } }, "example": { "reference": "29be736f-92fc-4966-8ccc-94a9b6323770", "useCase": "STABLECOIN_PAYOUTS", "customerType": "COMPANY", "countryCode": "DE" } } } }, "responses": { "200": { "description": "Agreement working set created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2PreCustomerAgreementsResponse" }, "example": { "reference": "29be736f-92fc-4966-8ccc-94a9b6323770", "agreements": [ { "id": "c2cbc333-8c4c-4bd7-a3d3-92a377772cbb", "name": "Partner Platform Agreement (Non-US)", "description": "Terms and conditions for Partner Platform customers outside the US", "declinable": false, "status": "PENDING", "expiresAt": "2026-08-09T06:10:34.134943209Z" } ] } } } }, "400": { "$ref": "#/components/responses/BadRequestMessage" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "Idempotency-Key reused with a different payload, or `reference` is already bound to an existing customer." }, "502": { "description": "The agreements upstream is temporarily unavailable." } } }, "get": { "tags": [ "Agreements" ], "summary": "List pre-customer agreements by reference", "description": "List the agreement working set previously created for the given partner-supplied `reference`.", "operationId": "listPreCustomerAgreementsV2", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "reference", "in": "query", "required": true, "description": "Partner-supplied reference that identifies the working set. Must match the value used when the working set was created.", "schema": { "type": "string" }, "example": "29be736f-92fc-4966-8ccc-94a9b6323770" } ], "responses": { "200": { "description": "Agreement working set for the supplied reference", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2PreCustomerAgreementsResponse" }, "example": { "reference": "29be736f-92fc-4966-8ccc-94a9b6323770", "agreements": [ { "id": "c2cbc333-8c4c-4bd7-a3d3-92a377772cbb", "name": "Partner Platform Agreement (Non-US)", "description": "Terms and conditions for Partner Platform customers outside the US", "declinable": false, "status": "PENDING", "expiresAt": "2026-08-09T06:10:34.134943209Z" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/platform/v2/agreements/{id}": { "get": { "tags": [ "Agreements" ], "summary": "Get pre-customer agreement", "description": "Fetch a single pre-customer agreement entry by its UUID. The response includes the agreement's current `status` (PENDING / ACCEPTED / REJECTED) and the expiration date (`expiresAt`).", "operationId": "getPreCustomerAgreementV2", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Unique identifier of the pre-customer agreement entry.", "schema": { "type": "string", "format": "uuid" }, "example": "c2cbc333-8c4c-4bd7-a3d3-92a377772cbb" } ], "responses": { "200": { "description": "Pre-customer agreement details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2PreCustomerAgreement" }, "example": { "id": "c2cbc333-8c4c-4bd7-a3d3-92a377772cbb", "name": "Partner Platform Agreement (Non-US)", "description": "Terms and conditions for the Partner Platform customers outside the US", "declinable": false, "status": "PENDING", "expiresAt": "2026-08-09T06:10:34.134943209Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/platform/v2/agreements/{id}/content": { "get": { "tags": [ "Agreements" ], "summary": "Get pre-customer agreement content URL", "description": "Get a presigned URL for downloading the agreement document. Use this when you need a fresh URL outside of the list/get responses.", "operationId": "getPreCustomerAgreementContentV2", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Unique identifier of the pre-customer agreement entry whose document URL is being requested.", "schema": { "type": "string", "format": "uuid" }, "example": "c2cbc333-8c4c-4bd7-a3d3-92a377772cbb" } ], "responses": { "200": { "description": "Presigned download URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2PreCustomerAgreementContentResponse" }, "example": { "downloadUrl": "https://files.bvnk.com/agreements/c2cbc333-8c4c-4bd7-a3d3-92a377772cbb.pdf?token=AKIAIOSFODNN7EXAMPLE", "filename": "epc-partner-platform-agreement-non-us.pdf" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/platform/v2/agreements/actions": { "post": { "tags": [ "Agreements" ], "summary": "Bulk respond to pre-customer agreements", "description": "Accept or reject up to 50 agreements within a single working set in one call. The request is scoped by the partner-supplied `reference`; each `actions[]` item carries an `agreementId` (UUID) and a `type` (`ACCEPT` or `REJECT`). Per-item outcomes are returned as a paginated list of `AgreementActionResult`: successful items have a `status`; failed items have an `error`.", "operationId": "bulkRespondPreCustomerAgreementsV2", "security": [ { "BearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKeyNew" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reference", "actions" ], "properties": { "reference": { "type": "string", "description": "Partner-supplied reference that identifies the working set. Must match the value used when the working set was created." }, "actions": { "type": "array", "description": "Up to 50 per-agreement actions to apply within the working set. Each item is processed independently; per-item outcomes are returned in the response.", "maxItems": 50, "items": { "type": "object", "required": [ "agreementId", "type" ], "properties": { "agreementId": { "type": "string", "format": "uuid", "description": "Unique identifier of the pre-customer agreement entry to which this action applies." }, "type": { "type": "string", "description": "Action to apply to the agreement entry.", "enum": [ "ACCEPT", "REJECT" ] } } } } } }, "example": { "reference": "29be736f-92fc-4966-8ccc-94a9b6323770", "actions": [ { "agreementId": "c2cbc333-8c4c-4bd7-a3d3-92a377772cbb", "type": "ACCEPT" } ] } } } }, "responses": { "200": { "description": "Per-item action results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V2PaginatedAgreementActionResultResponse" }, "example": { "content": [ { "agreementId": "c2cbc333-8c4c-4bd7-a3d3-92a377772cbb", "status": "ACCEPTED" } ], "totalElements": 1, "totalPages": 1, "hasNext": false } } } }, "400": { "$ref": "#/components/responses/BadRequestMessage" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "description": "Idempotency-Key reused with a different payload." }, "502": { "description": "The agreements upstream is temporarily unavailable." } } } }, "/ledger/v1/transactions": { "get": { "tags": [ "Wallets" ], "summary": "Get transactions", "description": "Retrieves a paginated list of transactions for a specific wallet. Supports filtering by `walletId` and optional date range.\n\nThe date range can be applied to the `createdAt` or `updatedAt` timestamp, determined by the `filterMode`. If omitted, the `filterMode` defaults to `CREATED_AT`.\n\nRefer to the [Fiat payments guide](https://docs.bvnk.com/docs/listing-transactions).", "operationId": "walletListTransactions", "security": [ { "Hawk": [ "merchant" ] } ], "parameters": [ { "name": "walletId", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Unique identifier for the wallet to filter related transactions.", "example": "a:24022637884682:hxhalPr:1" }, { "name": "statuses", "in": "query", "required": false, "description": "Comma-separated list of statuses to filter by (`statuses=COMPLETED,CANCELLED`).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "DETECTED", "PROCESSING", "PENDING_APPROVAL", "COMPLETED", "ON_HOLD", "RETURNED", "EXPIRED", "CANCELLED", "FAILED" ] } }, "example": "COMPLETED,CANCELLED" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/Size" }, { "name": "filterMode", "in": "query", "required": false, "schema": { "type": "string", "description": "Specifies whether the date range should be applied to the `createdAt` or `updatedAt` timestamp.", "enum": [ "CREATED_AT", "UPDATED_AT" ], "example": "CREATED_AT" } }, { "name": "start", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Start date-time filter (inclusive). Format: ISO8601.", "example": "2025-04-30T12:27:40Z" }, { "name": "end", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "End date-time filter (inclusive). Format: ISO8601.", "example": "2025-05-30T12:27:40Z" } ], "responses": { "200": { "description": "Paginated list of transactions", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "array", "items": { "type": "object", "properties": { "transactionId": { "type": "string", "description": "Unique reference for the transaction." }, "paymentId": { "type": "string", "description": "Unique reference for the payment." }, "paymentReference": { "type": "string", "description": "Reference label to identify or describe the payment." }, "type": { "type": "string", "description": "Type of transaction which is being listed.\n\n - Fiat only: `PAYOUT`, `PAYIN`, `FEE`.\n\n - Crypto only: `paymentOut`, `channelDeposit`, `reversal`.\n\n- Both crypto and fiat: `internalTransfer`.", "enum": [ "PAYOUT", "PAYIN", "FEE", "internalTransfer", "paymentOut", "channelDeposit", "reversal" ] }, "status": { "type": "string", "description": "Current processing state of the transaction.", "enum": [ "DETECTED", "PROCESSING", "COMPLETED", "PENDING_APPROVAL", "ON_HOLD", "RETURNED", "EXPIRED", "CANCELLED", "FAILED" ] }, "walletId": { "type": "string", "description": "Unique identifier of the wallet for this transaction." }, "amount": { "type": "object", "description": "Total amount and currency of the transaction.", "properties": { "value": { "type": "number", "description": "Numeric value of the transaction." }, "currencyCode": { "type": "string", "description": "Currency in ISO 4217 format.", "enum": [ "USD", "EUR", "GBP" ] } } }, "runningBalance": { "type": "object", "description": "Real-time balance of the wallet immediately after this transaction.", "properties": { "value": { "type": "number", "description": "Updated balance amount." }, "currencyCode": { "type": "string", "description": "Currency code of the updated balance.", "enum": [ "USD", "EUR", "GBP" ] } } }, "originator": { "type": "object", "description": "Entity that initiated the transaction and sent the funds.", "properties": { "entity": { "type": "object", "description": "Sender (originator) identity information.", "properties": { "type": { "type": "string", "description": "Type of sender entity.", "enum": [ "COMPANY", "INDIVIDUAL" ] }, "name": { "type": "string", "description": "Name of the sender for companies." }, "firstName": { "type": "string", "description": "First name of the sender for individuals." }, "lastName": { "type": "string", "description": "Last name of the sender for individuals." } } }, "bankAccount": { "type": "object", "nullable": true, "description": "Bank account, from which the payment was initiated.", "properties": { "accountNumber": { "type": "string", "description": "Account number of the sender." }, "bankCode": { "type": "string", "description": "Bank code of the sender." } } }, "walletId": { "type": "string", "description": "Unique identifier of the originator's wallet." }, "amount": { "type": "object", "description": "Amount sent by the originator. For crypto payments.", "properties": { "value": { "type": "number", "description": "Numeric value of the amount." }, "currencyCode": { "type": "string", "description": "Currency in ISO 4217 or crypto ticker (e.g., USD, USDT)." } } } } }, "beneficiary": { "type": "object", "description": "Recipient of the transaction.", "properties": { "entity": { "type": "object", "description": "Entity information about the recipient.", "properties": { "type": { "type": "string", "description": "Type of recipient entity.", "enum": [ "COMPANY", "INDIVIDUAL" ] }, "name": { "type": "string", "description": "Name of the recipient for companies." }, "firstName": { "type": "string", "description": "First name of the recipient for individuals." }, "lastName": { "type": "string", "description": "Last name of the recipient for individuals." } } }, "bankAccount": { "type": "object", "nullable": true, "description": "Bank account that received the payment.", "properties": { "accountNumber": { "type": "string", "description": "Account number of the recipient." }, "bankCode": { "type": "string", "description": "Bank code of the recipient." } } }, "walletId": { "type": "string", "description": "Unique identifier of the beneficiary's wallet." }, "cryptoAddresses": { "type": "object", "description": "Crypto destination addresses. For crypto payments.", "properties": { "addresses": { "type": "array", "items": { "type": "string" }, "description": "List of blockchain addresses." }, "protocol": { "type": "string", "deprecated": true, "description": "Protocol or token standard (e.g., TRC20, ERC20)." }, "network": { "type": "string", "description": "Blockchain network (e.g., TRON, ETHEREUM)." } } }, "amount": { "type": "object", "description": "Amount received by the beneficiary. For crypto payments.", "properties": { "value": { "type": "number", "description": "Numeric value of the amount." }, "currencyCode": { "type": "string", "description": "Currency in ISO 4217 or crypto ticker (e.g., USD, USDT)." } } } } }, "details": { "type": "object", "description": "Additional transaction information.", "properties": { "paymentMethod": { "type": "string", "description": "Payment channel used for the transaction.", "enum": [ "SEPA_CT", "SEPA_INST", "FASTER_PAYMENT", "ACH", "ACH_SAME_DAY", "FEDWIRE", "BOOK", "SWIFT", "UNKNOWN" ] }, "fxRate": { "type": "object", "description": "Foreign exchange details applied when a transaction involves currency conversion (including crypto to fiat or crypto to crypto). Only for crypto transactions.", "properties": { "baseCurrency": { "type": "string", "description": "Base currency code for the conversion. Uses ISO 4217 for fiat or common crypto tickers (e.g., BTC, USDT) for digital assets." }, "counterCurrency": { "type": "string", "description": "Counter currency code for the conversion. Uses ISO 4217 for fiat or common crypto tickers (e.g., BTC, USDT) for digital assets." }, "merchantFxRate": { "type": "number", "description": "Effective rate applied to the merchant to convert baseCurrency to counterCurrency." }, "baseFxRate": { "type": "number", "description": "Underlying market reference rate for the currency pair at the time of conversion." }, "merchantSpread": { "type": "number", "description": "The spread applied by BVNK (merchantFxRate - baseFxRate), expressed as a fraction (e.g., 0.002 = 0.2%)." } } }, "complianceDetail": { "type": "object", "description": "Compliance context/details captured for a crypto transaction. Only for crypto transactions.", "additionalProperties": true }, "hash": { "type": "string", "description": "Blockchain transaction hash. Only for crypto transactions." }, "exchangeRate": { "type": "number", "description": "Exchange rate applied for the transaction. For crypto payments." } } }, "createdAt": { "type": "string", "format": "date-time", "description": "The timestamp when the transaction was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "The timestamp of the transaction's most recent update." } } } }, "pageable": { "type": "object", "properties": { "pageNumber": { "type": "integer" }, "pageSize": { "type": "integer" }, "offset": { "type": "integer" }, "paged": { "type": "boolean" }, "unpaged": { "type": "boolean" } } }, "last": { "type": "boolean" }, "totalElements": { "type": "integer" }, "totalPages": { "type": "integer" }, "first": { "type": "boolean" }, "size": { "type": "integer" }, "number": { "type": "integer" }, "sort": { "type": "array", "items": { "type": "string" } }, "numberOfElements": { "type": "integer" }, "empty": { "type": "boolean" } } }, "examples": { "Fiat Transactions": { "summary": "Fiat Transactions", "value": { "content": [ { "transactionId": "8ad5fb14-2597-11f0-b697-03aa6c4dada9", "paymentId": "019685ab-3510-7d75-8801-be1476233a18", "paymentReference": "IncomingEUR", "type": "PAYIN", "status": "COMPLETED", "amount": { "value": 1, "currencyCode": "EUR" }, "runningBalance": { "value": 61.37, "currencyCode": "EUR" }, "originator": { "entity": { "type": "INDIVIDUAL", "firstName": "J.", "lastName": "Brown" }, "bankAccount": { "accountNumber": "BE68905090998434", "bankCode": "TRWIBEB1XXX" }, "walletId": "a:24022637884682:hxhalPr:1" }, "beneficiary": { "entity": { "type": "COMPANY", "name": "SPS X" }, "bankAccount": { "accountNumber": "ES8668490001550006761991", "bankCode": "EAPFESM2" }, "walletId": "a:82030333833383:ZKH9YrP:1" }, "details": { "paymentMethod": "SEPA_CT" }, "createdAt": "2025-04-30T07:48:45.457148Z", "updatedAt": "2025-04-30T07:48:46.457148Z" }, { "transactionId": "8ad5fb15-2597-11f0-b697-03aa6c4dada9", "paymentId": "019685ab-3510-7d75-8801-be1476233a18", "paymentReference": "Charged payment", "type": "FEE", "status": "COMPLETED", "amount": { "value": -0.1, "currencyCode": "EUR" }, "runningBalance": { "value": 61.27, "currencyCode": "EUR" }, "originator": { "entity": { "type": "INDIVIDUAL", "firstName": "Gabriel", "lastName": "Syme" }, "bankAccount": { "accountNumber": "BE68905090998434", "bankCode": "TRWIBEB1XXX" }, "walletId": "a:24022637884682:hxhalPr:1" }, "beneficiary": { "entity": { "type": "COMPANY", "name": "SPS X" }, "bankAccount": { "accountNumber": "ES8668490001550006761991", "bankCode": "EAPFESM2" }, "walletId": "a:82030333833383:ZKH9YrP:1" }, "details": { "paymentMethod": "SEPA_CT" }, "createdAt": "2025-04-30T07:48:45.457308Z" } ], "pageable": { "pageNumber": 0, "pageSize": 20, "sort": [], "offset": 0, "paged": true, "unpaged": false }, "last": true, "totalElements": 2, "totalPages": 1, "first": true, "size": 20, "number": 0, "sort": [], "numberOfElements": 2, "empty": false } }, "Crypto Transaction": { "summary": "Crypto Payment (outbound with crypto address)", "value": { "content": [ { "transactionId": "30963771-1e1b-11f1-8765-41f1432b63b0", "paymentId": "019ce255-168a-796a-b06c-d458a7f99270", "paymentReference": "REF684770", "type": "paymentOut", "status": "COMPLETED", "walletId": "a:25091934461715:IMBnBn1:1", "amount": { "value": -10.02, "currencyCode": "USD" }, "runningBalance": { "value": 226.04, "currencyCode": "USD" }, "originator": { "entity": { "type": "COMPANY", "name": "BVNK Embedded ltd" }, "amount": { "value": 10.02, "currencyCode": "USD" } }, "beneficiary": { "entity": { "type": "INDIVIDUAL", "name": "BVNK MAIN" }, "cryptoAddresses": { "addresses": [ "TL95NEq6hAhjdo6EqyXvQCWxFrVrn3FN9L" ], "protocol": "TRC20", "network": "TRON" }, "amount": { "value": 10, "currencyCode": "USDT" } }, "details": { "exchangeRate": 1, "hash": "06e6c4e39fb8e04653ba786daf83bdfd51d1f75ef31c019dbb1744bd5e187836" }, "createdAt": "2026-03-12T13:55:55.376686Z", "updatedAt": "2026-03-12T13:56:12.180Z" } ], "pageable": { "pageNumber": 0, "pageSize": 20, "sort": [], "offset": 0, "paged": true, "unpaged": false }, "last": true, "totalElements": 1, "totalPages": 1, "first": true, "size": 20, "number": 0, "sort": [], "numberOfElements": 1, "empty": false } }, "Channel Transactions": { "summary": "Channel Transactions", "value": { "content": [ { "transactionId": "807842a0-7ce7-11f0-a489-656a45c25154", "paymentId": "0198c1df-8106-7ffa-aa8e-25152398e50b", "paymentReference": "HeldPaymentChannel", "type": "channelDeposit", "status": "COMPLETED", "amount": { "value": 9, "currencyCode": "USD" }, "runningBalance": { "value": 490.75, "currencyCode": "USD" }, "originator": { "entity": { "type": "INDIVIDUAL", "name": "Vlad ALEXEYEV" }, "bankAccount": null, "walletId": "a:24072237783989:Unkx9kW:1" }, "beneficiary": { "entity": { "type": "COMPANY", "name": "Payment Account" }, "bankAccount": null, "walletId": "a:67667667667667:ZKH9YrP:1" }, "details": { "fxRate": { "baseCurrency": "USDT", "counterCurrency": "USD", "merchantFxRate": 0.9996101520407041, "baseFxRate": 0.9996101520407041, "merchantSpread": 0 }, "complianceDetail": {}, "hash": "0x1c36aea6292ae2a1eaaa1ab631cfe0454d60b3e3c84d787df0543b943a5c48c2" }, "createdAt": "2025-08-19T10:30:18.344806Z" } ], "pageable": { "pageNumber": 0, "pageSize": 20, "sort": [], "offset": 0, "paged": true, "unpaged": false }, "last": true, "totalElements": 2, "totalPages": 1, "first": true, "size": 20, "number": 0, "sort": [], "numberOfElements": 2, "empty": false } } } } } } } } }, "/ledger/v1/reports": { "post": { "tags": [ "Wallets" ], "summary": "Generate report", "description": "Creates a report from a wallet in the specified format and sends it via the preferred delivery method: WEBHOOK or EMAIL.\n\nThe report type is determined by the `type` field in the request body:\n- `TRANSACTION` returns all transactions within a date range (`from` / `to`).\n- `BALANCE` returns the wallet balance at a specific point in time (`at`).\n\n:::note\n\nReports are delivered instantly but the data has a one-hour lag for the production environment and eight-hour delay in sandbox. For example, a report requested at 9:00 AM will include transactions only up to 8:00 AM.\n\n:::\n\nSee the [Receive Transactions Report via Webhook](https://docs.bvnk.com/docs/receive-transaction-history-report-via-webhook) guide for more information.", "operationId": "walletTransactionReport", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "walletId": { "type": "string", "description": "Wallet Id for which to retrieve transactions. If left blank, all transactions will be included in the report.", "example": "a:24092328494070:G5i4XZ9:1" }, "from": { "type": "string", "format": "date-time", "description": "Initial date of the period being reported on in the ISO format. Required for `TRANSACTION` reports.", "example": "2023-01-15T10:30:00Z" }, "to": { "type": "string", "format": "date-time", "description": "Final date of the period in the ISO format. Required for `TRANSACTION` reports.", "example": "2025-12-15T10:30:00Z" }, "at": { "type": "string", "format": "date-time", "description": "Point-in-time date for the report in the ISO format. Required for `BALANCE` reports.", "example": "2026-05-10T23:59:59" }, "format": { "type": "string", "description": "Format of the report file.", "enum": [ "JSON", "CSV", "PDF" ], "example": "JSON" }, "deliveryChannel": { "type": "string", "description": "Method of delivery for the report.", "enum": [ "EMAIL", "WEBHOOK" ], "example": "EMAIL" }, "type": { "type": "string", "description": "Report type. Use `TRANSACTION` for a transactions report over a date range, or `BALANCE` for a point-in-time balance snapshot.", "enum": [ "TRANSACTION", "BALANCE" ], "example": "TRANSACTION" } } }, "examples": { "Email Report": { "summary": "Request a JSON transaction report delivered via email", "value": { "walletId": "a:24092328494070:G5i4XZ9:1", "from": "2024-01-15T00:00:00Z", "to": "2024-12-31T23:59:59Z", "format": "JSON", "deliveryChannel": "EMAIL", "type": "TRANSACTION" } }, "Webhook Report": { "summary": "Request a CSV transaction report delivered via webhook", "value": { "walletId": "a:24092328494070:G5i4XZ9:1", "from": "2024-06-01T00:00:00Z", "to": "2024-12-31T23:59:59Z", "format": "CSV", "deliveryChannel": "WEBHOOK", "type": "TRANSACTION" } }, "Balance Report": { "summary": "Request a CSV balance report at a specific date delivered via email", "value": { "at": "2026-05-10T23:59:59", "format": "CSV", "deliveryChannel": "EMAIL", "type": "BALANCE", "walletId": "a:24112552810137:8GH0CoG:1" } } } } } }, "responses": { "201": { "description": "PROCESSING", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionReportDto" } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "BVNK error code." }, "status": { "type": "string", "description": "Error status." }, "message": { "type": "string", "description": "Error message." }, "details": { "type": "string", "nullable": true, "description": "Additional details about the error." } }, "required": [ "code", "status", "message" ] }, "examples": { "validation_error": { "summary": "Validation error example", "value": { "code": "bvnk:ledger:2105", "status": "Bad Request", "message": "to: must not be null", "details": null } } } } } } }, "security": [ { "Hawk": [ "user" ] } ] } } }, "components": { "schemas": { "GetCustomerResponse": { "oneOf": [ { "$ref": "#/components/schemas/GetCustomerResponseCompany" }, { "$ref": "#/components/schemas/GetCustomerResponseIndividual" } ], "discriminator": { "propertyName": "type", "mapping": { "COMPANY": "#/components/schemas/GetCustomerResponseCompany", "INDIVIDUAL": "#/components/schemas/GetCustomerResponseIndividual" } } }, "GetCustomerResponseCompany": { "type": "object", "required": [ "reference", "status", "type", "company" ], "properties": { "reference": { "type": "string", "format": "uuid", "description": "Unique customer identifier", "example": "0a184641-30e2-4414-871f-3db1c683900e" }, "status": { "type": "string", "description": "Customer external status", "enum": [ "PENDING", "VERIFIED", "REJECTED" ], "example": "VERIFIED" }, "type": { "type": "string", "description": "Type of customer", "enum": [ "COMPANY" ], "example": "COMPANY" }, "company": { "type": "object", "description": "Company details", "properties": { "name": { "type": "string", "description": "Customer name", "example": "UK Ltd Version 2.0" }, "description": { "type": "string", "description": "Customer description", "example": "Number 1 customer, be super nice." }, "taxResidenceCountryCode": { "type": "string", "description": "Tax residency of legal person (ISO 3166-1 alpha-2)", "example": "DE" }, "registrationNumber": { "type": "string", "description": "Registration number of legal person", "example": "1849203" }, "industry": { "type": "object", "description": "Industry information", "properties": { "reference": { "type": "string", "format": "uuid", "example": "b59c2055-7655-43bb-923d-0005928301d7" }, "name": { "type": "string", "example": "Finance" }, "children": { "type": "array", "description": "Sub-industries (if any)", "items": { "type": "object" } } } }, "monthlyExpectedVolumes": { "type": "object", "description": "Expected monthly volume range", "properties": { "reference": { "type": "string", "format": "uuid", "example": "b59c2055-7655-43bb-923d-0005928301d7" }, "name": { "type": "string", "example": "0 - 500 000.00 EUR" }, "min": { "type": "number", "example": 0 }, "max": { "type": "number", "example": 500000 } } }, "address": { "type": "object", "description": "Company address", "properties": { "addressLine1": { "type": "string", "example": "123 Main Street" }, "addressLine2": { "type": "string", "example": "Apartment 456" }, "postalCode": { "type": "string", "example": "NW1 4NP" }, "city": { "type": "string", "example": "London" }, "countryCode": { "type": "string", "example": "DE" }, "country": { "type": "string", "example": "Great Britain" }, "stateCode": { "type": "string", "example": "AL" } } }, "representative": { "type": "object", "description": "Company representative details", "properties": { "firstName": { "type": "string", "example": "John" }, "lastName": { "type": "string", "example": "Mirra" }, "dateOfBirth": { "type": "string", "format": "date", "example": "2001-12-31" }, "birthCountryCode": { "type": "string", "example": "HK" }, "nationality": { "type": "string", "example": "US" }, "address": { "type": "object", "description": "Representative address", "properties": { "addressLine1": { "type": "string", "example": "123 Main Street" }, "addressLine2": { "type": "string", "example": "Apartment 456" }, "postalCode": { "type": "string", "example": "NW1 4NP" }, "city": { "type": "string", "example": "London" }, "countryCode": { "type": "string", "example": "DE" }, "country": { "type": "string", "example": "Great Britain" }, "stateCode": { "type": "string", "example": "AL" } } } } } } } } }, "GetCustomerResponseIndividual": { "type": "object", "required": [ "reference", "status", "type", "individual" ], "properties": { "reference": { "type": "string", "format": "uuid", "description": "Unique customer identifier", "example": "797a8908-72dd-44fb-95c5-ec6cb2152b7d" }, "status": { "type": "string", "description": "Customer internal status", "enum": [ "PENDING", "VERIFIED", "REJECTED" ], "example": "VERIFIED" }, "type": { "type": "string", "description": "Type of customer", "enum": [ "INDIVIDUAL" ], "example": "INDIVIDUAL" }, "individual": { "type": "object", "description": "Individual details", "properties": { "description": { "type": "string", "description": "Customer description", "example": "Top priority" }, "person": { "type": "object", "description": "Personal identification details of the individual", "properties": { "reference": { "type": "string", "format": "uuid", "description": "Unique identifier for the individual", "example": "599802bd-485f-47fa-87ae-471968c6217f" }, "firstName": { "type": "string", "description": "First name of the individual", "example": "Victor" }, "lastName": { "type": "string", "description": "Last name of the individual", "example": "Caneda" }, "dateOfBirth": { "type": "string", "format": "date", "description": "Date of birth in the format YYYY-MM-DD", "example": "2004-02-17" }, "placeOfBirth": { "type": "string", "description": "ISO 3166-1 alpha-2 country code of birth", "example": "US" }, "address": { "$ref": "#/components/schemas/AddressV2", "description": "Individual's residential address" } } }, "details": { "type": "object", "description": "Additional identification and contact details for the individual", "properties": { "nationality": { "type": "string", "description": "ISO 3166-1 alpha-2 country code of nationality", "example": "US" }, "birthCountryCode": { "type": "string", "description": "ISO 3166-1 alpha-2 code of birth country", "example": "US" }, "contactInfo": { "type": "object", "description": "Contact details for the individual", "properties": { "emailAddress": { "type": "string", "description": "Primary email address", "example": "v.caneda@example.com" }, "phoneNumber": { "type": "string", "description": "Phone number in international format", "example": "+11953410688" } } }, "documentNumber": { "type": "string", "description": "Primary identification document number", "example": "4Q4FNK8JI4" }, "documentInfo": { "type": "object", "description": "Information about identification document", "properties": { "number": { "type": "string", "description": "Identification document number", "example": "4Q4FNK8JI4" }, "type": { "type": "string", "description": "Identity document type:\n\n- `PASSPORT`: Passport\n\n- `ID_CARD`: National ID card\n\n- `DRIVERS`: Driver's licence\n\n- `RESIDENCE_PERMIT`: Residence permit\n\n- `OTHER`: Other government-issued ID", "enum": [ "PASSPORT", "ID_CARD", "DRIVERS", "RESIDENCE_PERMIT", "OTHER" ], "example": "ID_CARD" }, "issuingCountryCode": { "type": "string", "description": "Country code of the issuing authority (ISO 3166-1 alpha-2)", "example": "US" } } }, "taxIdentification": { "type": "object", "description": "Tax identification information", "properties": { "number": { "type": "string", "description": "Tax identification number", "example": "555-89-3168" }, "taxResidenceCountryCode": { "type": "string", "description": "Country of tax residency (ISO 3166-1 alpha-2)", "example": "US" } } } } }, "cdd": { "type": "object", "description": "Customer due diligence details", "properties": { "intendedUseOfAccount": { "type": "string", "description": "Purpose of the account:\n\n- `TRANSFERS_OWN_WALLET`: Transfers to or from own wallet including bank accounts\n\n- `TRANSFERS_FAMILY_FRIENDS`: Transfers to or from family and friends\n\n- `INVESTMENTS`: Investments\n\n- `GOODS_SERVICES`: Purchases of goods and services\n\n- `DONATIONS`: Donations", "enum": [ "TRANSFERS_OWN_WALLET", "TRANSFERS_FAMILY_FRIENDS", "INVESTMENTS", "GOODS_SERVICES", "DONATIONS" ], "example": "TRANSFERS_OWN_WALLET" }, "pepStatus": { "type": "string", "description": "Politically Exposed Person status:\n\n- `NOT_PEP`: Not a PEP\n\n- `FORMER_PEP_2_YEARS`: Former or inactive PEP (within 2 years)\n\n- `FORMER_PEP_OLDER`: Former or inactive PEP (older than 2 years)\n\n- `DOMESTIC_PEP`: Domestic PEP\n\n- `FOREIGN_PEP`: Foreign PEP\n\n- `CLOSE_ASSOCIATES`: Close associates\n\n- `FAMILY_MEMBERS`: Family members", "enum": [ "NOT_PEP", "FORMER_PEP_2_YEARS", "FORMER_PEP_OLDER", "DOMESTIC_PEP", "FOREIGN_PEP", "CLOSE_ASSOCIATES", "FAMILY_MEMBERS" ], "example": "NOT_PEP" }, "expectedMonthlyVolume": { "type": "object", "description": "Expected monthly transaction volume", "properties": { "amount": { "type": "number", "description": "Monthly transaction volume amount", "example": 500.01 }, "currency": { "type": "string", "description": "Currency of the transaction volume (ISO 4217 code)", "example": "EUR" } } }, "employmentStatus": { "type": "string", "description": "Employment status:\n\n- `SELF_EMPLOYED`: Self employed and freelancer\n\n- `SALARIED`: Salaried\n\n- `UNEMPLOYED`: Unemployed\n\n- `RETIRED`: Retired\n\n- `NOT_PROVIDED`: Not provided", "enum": [ "SELF_EMPLOYED", "SALARIED", "UNEMPLOYED", "RETIRED", "NOT_PROVIDED" ], "example": "SALARIED" }, "sourceOfFunds": { "type": "string", "description": "Source of funds:\n\n- `SALARY`: Salary and employment income\n\n- `PENSION`: Pension and retirement income\n\n- `SAVINGS`: Savings and investments\n\n- `SELF_EMPLOYMENT`: Self employment and business income\n\n- `CRYPTO_TRADING`: Crypto trading\n\n- `GAMBLING`: Gambling and lottery winnings\n\n- `REAL_ESTATE`: Real estate sales", "enum": [ "SALARY", "PENSION", "SAVINGS", "SELF_EMPLOYMENT", "CRYPTO_TRADING", "GAMBLING", "REAL_ESTATE" ], "example": "SALARY" }, "estimatedYearlyIncome": { "type": "string", "description": "Estimated yearly income range. **Mandatory for US residents under the Partner-managed model**.\n\n- `INCOME_0_TO_50K`: 0 to 50,000 USD\n\n- `INCOME_50K_TO_100K`: 50,000 to 100,000 USD\n\n- `INCOME_100K_TO_250K`: 100,000 to 250,000 USD\n\n- `INCOME_250K_TO_500K`: 250,000 to 500,000 USD\n\n- `INCOME_500K_TO_750K`: 500,000 to 750,000 USD\n\n- `INCOME_750K_TO_1M`: 750,000 to 1,000,000 USD\n\n- `INCOME_ABOVE_1M`: Above 1,000,000 USD", "enum": [ "INCOME_0_TO_50K", "INCOME_50K_TO_100K", "INCOME_100K_TO_250K", "INCOME_250K_TO_500K", "INCOME_500K_TO_750K", "INCOME_750K_TO_1M", "INCOME_ABOVE_1M" ], "example": "INCOME_750K_TO_1M" }, "employmentIndustrySector": { "type": "string", "description": "Employment industry sector. **Required if your customers are individuals domiciled in a US state**.", "enum": [ "INVESTMENT", "HEDGE_FUND", "MONEY_SERVICE_BUSINESS", "STO_ISSUER", "PRECIOUS_METALS", "NON_PROFIT", "REGISTERED_INVESTMENT_ADVISOR", "AGRICULTURE_FORESTRY_FISHING_HUNTING", "MINING", "UTILITIES", "CONSTRUCTION", "MANUFACTURING", "WHOLESALE_TRADE", "RETAIL_TRADE", "TRANSPORTATION_WAREHOUSING", "INFORMATION", "FINANCE_INSURANCE", "REAL_ESTATE_RENTAL_LEASING", "PROFESSIONAL_SCIENTIFIC_TECHNICAL_SERVICES", "MANAGEMENT_OF_COMPANIES_ENTERPRISES", "ADMINISTRATIVE_SUPPORT_WASTE_MANAGEMENT_REMEDIATION_SERVICES", "EDUCATIONAL_SERVICES", "HEALTH_CARE_SOCIAL_ASSISTANCE", "ARTS_ENTERTAINMENT_RECREATION", "ACCOMMODATION_FOOD_SERVICES", "OTHER_SERVICES", "PUBLIC_ADMINISTRATION", "NOT_CLASSIFIED", "ADULT_ENTERTAINMENT", "AUCTIONS", "AUTOMOBILES", "BLOCKCHAIN", "CRYPTO", "DRUGS", "EXPORT_IMPORT", "E_COMMERCE", "FINANCIAL_INSTITUTION", "GAMBLING", "INSURANCE", "MARKET_MAKER", "SHELL_BANK", "TRAVEL_TRANSPORT", "WEAPONS" ], "example": "ADMINISTRATIVE_SUPPORT_WASTE_MANAGEMENT_REMEDIATION_SERVICES" } } } } }, "flowType": { "type": "string", "description": "Flow type used for customer creation", "example": "API" }, "riskScore": { "type": "string", "description": "Risk score of the customer", "enum": [ "LOW", "MEDIUM", "HIGH" ], "example": "LOW" }, "verification": { "type": "object", "description": "Verification status", "properties": { "status": { "type": "string", "example": "completed" } } } } }, "PaymentRuleIndividual": { "type": "object", "required": [ "type", "firstName", "lastName", "relationshipType" ], "properties": { "type": { "type": "string", "enum": [ "INDIVIDUAL" ], "description": "Entity type" }, "customerIdentifier": { "type": "string", "description": "Unique customer reference.", "example": "HJHJ4668KB" }, "firstName": { "type": "string", "description": "First name", "example": "John" }, "lastName": { "type": "string", "description": "Last name", "example": "Doe" }, "dateOfBirth": { "type": "string", "format": "date", "description": "Date of birth in YYYY-MM-DD format", "example": "1990-05-15" }, "address": { "$ref": "#/components/schemas/AddressV2" }, "relationshipType": { "type": "string", "enum": [ "SELF_OWNED", "THIRD_PARTY" ], "description": "Relationship type", "example": "SELF_OWNED" } } }, "PaymentRuleCompany": { "type": "object", "required": [ "type", "legalName", "relationshipType" ], "properties": { "type": { "type": "string", "enum": [ "COMPANY" ], "description": "Entity type" }, "customerIdentifier": { "type": "string", "description": "Unique customer reference.", "example": "HJHJ4668KB" }, "legalName": { "type": "string", "description": "Legal company name", "example": "TFV LTD" }, "registrationNumber": { "type": "string", "description": "Company registration number.", "example": "ABC21D21FZC" }, "address": { "$ref": "#/components/schemas/AddressV2" }, "relationshipType": { "type": "string", "enum": [ "SELF_OWNED", "THIRD_PARTY" ], "description": "Relationship type", "example": "SELF_OWNED" } } }, "PaymentRuleIndividualUpdate": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "INDIVIDUAL" ], "description": "Entity type" }, "customerIdentifier": { "type": "string", "nullable": true, "description": "Unique customer reference." }, "firstName": { "type": "string", "nullable": true, "description": "First name" }, "lastName": { "type": "string", "nullable": true, "description": "Last name" }, "dateOfBirth": { "type": "string", "format": "date", "nullable": true, "description": "Date of birth in YYYY-MM-DD format", "example": "1990-05-15" }, "address": { "$ref": "#/components/schemas/AddressV2" }, "relationshipType": { "type": "string", "enum": [ "SELF_OWNED", "THIRD_PARTY" ], "nullable": true, "description": "Relationship type" } } }, "PaymentRuleCompanyUpdate": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "COMPANY" ], "description": "Entity type" }, "customerIdentifier": { "type": "string", "nullable": true, "description": "Unique customer reference." }, "legalName": { "type": "string", "nullable": true, "description": "Legal company name" }, "registrationNumber": { "type": "string", "nullable": true, "description": "Company registration number." }, "address": { "$ref": "#/components/schemas/AddressV2" }, "relationshipType": { "type": "string", "enum": [ "SELF_OWNED", "THIRD_PARTY" ], "nullable": true, "description": "Relationship type" } } }, "PaymentRuleCryptoAddress": { "type": "object", "description": "Crypto destination details.", "properties": { "network": { "$ref": "#/components/schemas/BlockchainNetwork" }, "address": { "type": "string", "description": "Crypto wallet address.", "example": "0x12323542636474747" }, "tag": { "type": "string", "description": "Optional tag/memo for certain cryptocurrencies (e.g., XRP, XLM).", "example": "332455" } }, "required": [ "network", "address" ] }, "PaymentRuleCryptoAddressUpdate": { "type": "object", "description": "Crypto destination details.", "properties": { "network": { "$ref": "#/components/schemas/BlockchainNetwork" }, "address": { "type": "string", "nullable": true, "description": "Crypto wallet address." }, "tag": { "type": "string", "nullable": true, "description": "Optional tag for certain cryptocurrencies (e.g., XRP, XLM)." } } }, "PaymentRuleResponse": { "type": "object", "description": "Payment rule response object.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the payment rule. You can use this value to update the rule via [`/payment/v1/rules/{id}](https://docs.bvnk.com/reference/paymentruleupdate#/).", "example": "98c0bb03-567f-11f0-b26e-6b1848874a27" }, "reference": { "type": "string", "example": "REF558628" }, "trigger": { "type": "string", "example": "event:payment:payin" }, "status": { "type": "string", "example": "ACTIVE" }, "fees": { "type": "object", "properties": { "customerFee": { "type": "object", "properties": { "amount": { "type": "number", "example": 0.5 }, "currency": { "type": "string", "example": "USD" } } } } }, "originator": { "type": "object", "properties": { "currency": { "type": "string", "example": "USD" }, "walletId": { "type": "string", "example": "acc:22041242429000:3MPpU:0" } } }, "beneficiary": { "type": "object", "properties": { "currency": { "type": "string", "example": "USDT" }, "entity": { "type": "object", "properties": { "legalName": { "type": "string", "example": "3Com" }, "type": { "type": "string", "example": "COMPANY" }, "relationshipType": { "type": "string", "example": "SELF_OWNED" }, "registrationNumber": { "type": "string", "example": "ABC21D21FZC" }, "address": { "type": "object", "properties": { "addressLine1": { "type": "string", "example": "123 Main St" }, "addressLine2": { "type": "string", "example": "Some address Line 2" }, "city": { "type": "string", "example": "New York" }, "region": { "type": "string", "example": "NY" }, "postCode": { "type": "string", "example": "10001" }, "country": { "type": "string", "example": "US" } } } } }, "cryptoAddresses": { "type": "object", "properties": { "network": { "type": "string", "example": "ETHEREUM" }, "addresses": { "type": "array", "items": { "type": "string" }, "example": [ "0x12323542636474747" ] }, "tag": { "type": "string", "example": "332455" } } } } }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "updatedAt": { "type": "string", "format": "date-time", "example": "2025-07-01T13:31:02.52Z" }, "createdAt": { "type": "string", "format": "date-time", "example": "2025-07-01T13:30:02.52Z" } } }, "PaymentRuleActionRequest": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "ACTIVATE", "DEACTIVATE" ], "description": "Action to perform on the payment rule. Use `ACTIVATE` to enable the rule or `DEACTIVATE` to disable it. Deactivated rules will not trigger automated actions but remain in your account for reference." } } }, "AcceptEstimateRequestDto": { "type": "object", "properties": { "customerId": { "type": "string", "description": "Unique identifier for the customer", "example": "9e9bb7cb-f5d4-4f7b-bada-6ad156f3a8d8" }, "payOutDetails": { "$ref": "#/components/schemas/EstimatePayOutDetailDto" }, "complianceDetails": { "$ref": "#/components/schemas/ComplianceDetailDto" } }, "required": [ "customerId", "payOutDetails", "complianceDetails" ] }, "CreateEstimateRequestDto": { "type": "object", "required": [ "walletId", "walletCurrency", "paidCurrency", "network", "reference", "complianceDetails" ], "properties": { "walletId": { "type": "string", "description": "Unique identifier for the wallet.", "example": "acc:23040543559277:x8rvQ:0", "maxLength": 255 }, "merchantId": { "description": "**Deprecated. Don't use, if you specify `walletId`**.\n\n Your Merchant ID. You can find it on the Merchant Details page in your account.", "type": "string", "example": "5C8D8D78-366A-4AFB-B658-A64CE543C5DB", "minLength": 6, "maxLength": 50 }, "walletCurrency": { "type": "string", "description": "Currency code of the wallet.", "example": "ETH", "minLength": 2, "maxLength": 20, "pattern": "^[A-Za-z]+$", "x-setter-extra-annotation": "@ToUpperCase" }, "paidCurrency": { "type": "string", "description": "Currency in which the payout is made.", "example": "ETH", "minLength": 2, "maxLength": 20, "pattern": "^[A-Za-z]+$", "x-setter-extra-annotation": "@ToUpperCase" }, "reference": { "type": "string", "description": "Internal reference ID for the estimate request.", "example": "XRP commission", "minLength": 6, "maxLength": 255 }, "network": { "description": "Blockchain network to process the payment.", "$ref": "#/components/schemas/BlockchainNetwork" }, "complianceDetails": { "$ref": "#/components/schemas/ComplianceDetailDto" } }, "oneOf": [ { "title": "Specify walletRequiredAmount", "type": "object", "properties": { "walletRequiredAmount": { "type": "number", "format": "decimal", "description": "Amount in the funding wallet. Specify `walletRequiredAmount` to define how much you want to send. If provided, system calculates `paidRequiredAmount`.", "example": 2000 } }, "required": [ "walletRequiredAmount" ] }, { "title": "Specify paidRequiredAmount", "type": "object", "properties": { "paidRequiredAmount": { "type": "number", "format": "decimal", "description": "Amount to be paid from the wallet. Specify `paidRequiredAmount` to define how much the recipient should receive. If provided, system calculates `walletRequiredAmount`.", "example": 3823.23 } }, "required": [ "paidRequiredAmount" ] } ] }, "UpdateEstimateRequestDto": { "type": "object", "description": "Update payload to refresh the quote. Provide either `walletRequiredAmount` or `paidRequiredAmount`.", "required": [ "reference" ], "properties": { "walletRequiredAmount": { "type": "number", "format": "decimal", "description": "Amount in the funding wallet.", "example": 2000 }, "paidRequiredAmount": { "type": "number", "format": "decimal", "description": "Amount to be paid from the wallet.", "example": 3823.23 }, "reference": { "type": "string", "description": "Reference for the transaction. Use the same reference as in the initial [request](https://docs.bvnk.com/reference/payestimate#/).", "example": "XRP commission", "minLength": 6, "maxLength": 255 }, "complianceDetails": { "$ref": "#/components/schemas/ComplianceDetailDto" } }, "oneOf": [ { "title": "Specify walletRequiredAmount", "type": "object", "required": [ "walletRequiredAmount" ] }, { "title": "Specify paidRequiredAmount", "type": "object", "required": [ "paidRequiredAmount" ] } ] }, "InformationRequestActionDto": { "type": "object", "description": "Action to take on a held information request. Currently only `PROVIDE_INFORMATION` is supported, which assigns originator (contact) details to the related payment.", "required": [ "type", "entity" ], "properties": { "type": { "type": "string", "description": "Action type to apply to the information request.", "enum": [ "PROVIDE_INFORMATION" ], "example": "PROVIDE_INFORMATION" }, "entity": { "description": "Originator entity that is being assigned to the held payment. Use `INDIVIDUAL` for natural persons and `COMPANY` for legal entities.", "oneOf": [ { "$ref": "#/components/schemas/InformationRequestIndividualEntity" }, { "$ref": "#/components/schemas/InformationRequestCompanyEntity" } ], "discriminator": { "propertyName": "type", "mapping": { "INDIVIDUAL": "#/components/schemas/InformationRequestIndividualEntity", "COMPANY": "#/components/schemas/InformationRequestCompanyEntity" } } } } }, "InformationRequestIndividualEntity": { "type": "object", "description": "Individual originator details.\n\n:::warning `externalId` is required for `INDIVIDUAL` entities\nWhen `type` is `INDIVIDUAL`, `externalId` must be provided. This is a current contact-service requirement and is not enforced for `COMPANY` entities.\n:::", "required": [ "type", "externalId", "firstName", "lastName", "dateOfBirth", "relationshipType", "address" ], "properties": { "type": { "type": "string", "description": "Entity type.", "enum": [ "INDIVIDUAL" ], "example": "INDIVIDUAL" }, "contactId": { "type": "string", "nullable": true, "description": "Existing BVNK contact ID, if reusing a previously created contact. Use `null` to create a new contact from the supplied details.", "example": null }, "customerId": { "type": "string", "nullable": true, "description": "Customer ID associated with the contact, if applicable. Use `null` when not applicable.", "example": null }, "externalId": { "type": "string", "description": "**Required for `INDIVIDUAL` entities.** Your external identifier for this individual contact. Used to deduplicate contacts in your system.", "example": "bd51c10c-fff8-4d38-a6ef-411371238caa" }, "firstName": { "type": "string", "description": "First name of the individual.", "example": "John" }, "lastName": { "type": "string", "description": "Last name of the individual.", "example": "Doe" }, "dateOfBirth": { "type": "string", "description": "Date of birth of the individual in `dd-MM-yyyy` format.", "example": "08-11-1998" }, "relationshipType": { "type": "string", "description": "Relationship of the individual to the merchant.", "enum": [ "SELF_OWNED", "THIRD_PARTY" ], "example": "THIRD_PARTY" }, "address": { "$ref": "#/components/schemas/InformationRequestAddress" } } }, "InformationRequestCompanyEntity": { "type": "object", "description": "Company originator details.\n\n:::info `externalId` is optional for `COMPANY` entities\nUnlike `INDIVIDUAL` entities, `externalId` is not required when `type` is `COMPANY`.\n:::", "required": [ "type", "legalName", "relationshipType" ], "properties": { "type": { "type": "string", "description": "Entity type.", "enum": [ "COMPANY" ], "example": "COMPANY" }, "contactId": { "type": "string", "nullable": true, "description": "Existing BVNK contact ID, if reusing a previously created contact. Use `null` to create a new contact from the supplied details.", "example": null }, "customerId": { "type": "string", "nullable": true, "description": "Customer ID associated with the contact, if applicable. Use `null` when not applicable.", "example": null }, "externalId": { "type": "string", "description": "Optional. Your external identifier for this company contact. Not required for `COMPANY` entities.", "example": "ext-company-001" }, "legalName": { "type": "string", "description": "Legal name of the company.", "example": "LuchinPaulTest" }, "registrationNumber": { "type": "string", "description": "Company registration number.", "example": "123321" }, "relationshipType": { "type": "string", "description": "Relationship of the company to the merchant.", "enum": [ "SELF_OWNED", "THIRD_PARTY" ], "example": "THIRD_PARTY" } } }, "InformationRequestAddress": { "type": "object", "description": "Postal address of the individual originator.", "required": [ "addressLine1", "city", "postCode", "country" ], "properties": { "addressLine1": { "type": "string", "description": "First line of the address.", "example": "10 Woodpecker" }, "addressLine2": { "type": "string", "description": "Second line of the address. Optional.", "example": "Turf" }, "city": { "type": "string", "description": "City of the address.", "example": "Cape Town" }, "region": { "type": "string", "description": "Region or state of the address. Optional.", "example": "Western Cape" }, "postCode": { "type": "string", "description": "Postal code of the address.", "example": "1234" }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code.", "example": "ZA" } } }, "EstimatePayOutDetailDto": { "description": "Specify payment details", "type": "object", "properties": { "currency": { "description": "Currency code of the payout.", "type": "string", "example": "ETH", "minLength": 2, "maxLength": 20, "pattern": "^[A-Za-z]+$", "x-pattern-message": "Currency must only contain alphabetic characters.", "x-setter-extra-annotation": "@ToUpperCase" }, "address": { "description": "Address to withdrawal funds to.", "type": "string", "pattern": "^[A-Za-z0-9:]+(\\?dt=[A-Za-z0-9]+)?$", "x-pattern-message": "Address must consist of one or more alphanumeric characters (A-Z, a-z, 0-9) or colons (:). Optionally, it may be followed by a destination tag (?dt=) followed by one or more alphanumeric characters.", "example": "0xb794f5ea0ba39494ce839613fffba74279579268" }, "tag": { "description": "Payment destination tag. This fields isn't null when the `paidCurrency` currency value is XRP", "type": "string", "pattern": "^[A-Za-z0-9]*$", "x-pattern-message": "Tag must include only alphanumeric characters (A-Z, a-z, 0-9). It can also be an empty string.", "example": "", "maxLength": 255 }, "network": { "description": "Blockchain network to process the payment.", "$ref": "#/components/schemas/BlockchainNetwork" } }, "required": [ "currency", "address", "network" ] }, "EstimatePayoutResponseDto": { "$ref": "#/components/schemas/CryptoPayoutEstimateResponse" }, "CryptoPayoutEstimateRequest": { "type": "object", "required": [ "walletId", "walletCurrency", "paidCurrency", "reference", "network", "complianceDetails" ], "properties": { "walletId": { "type": "string", "format": "uuid", "description": "Unique identifier of the merchant requesting the estimate.", "example": "a:24072237783989:Unkx9kW:1" }, "walletRequiredAmount": { "type": "number", "format": "float", "description": "Amount in the funding wallet currency. Specify this to define how much you want to send. If provided, system calculates `paidRequiredAmount`.", "example": 15.79 }, "walletCurrency": { "type": "string", "description": "Currency code of the wallet from which the funds will be debited.", "example": "USD" }, "paidRequiredAmount": { "type": "number", "format": "float", "description": "Amount in the payout currency (buy currency). Specify this to define how much the recipient should receive. If provided, system calculates `walletRequiredAmount`.", "example": 15 }, "paidCurrency": { "type": "string", "description": "Currency code of the payout.", "example": "USDT" }, "reference": { "type": "string", "description": "Merchant's internal reference ID for the estimate request.", "example": "REF46730" }, "network": { "description": "Blockchain network to process the payout.", "$ref": "#/components/schemas/BlockchainNetwork" }, "complianceDetails": { "$ref": "#/components/schemas/ComplianceDetailDto" } }, "oneOf": [ { "required": [ "walletRequiredAmount" ] }, { "required": [ "paidRequiredAmount" ] } ] }, "CryptoPayoutEstimateUpdateRequest": { "type": "object", "description": "Update payload to refresh the quote. Provide either `walletRequiredAmount` or `paidRequiredAmount`.", "properties": { "walletRequiredAmount": { "type": "number", "format": "float", "description": "Amount in the wallet currency to spend.", "example": 15.79 }, "paidRequiredAmount": { "type": "number", "format": "float", "description": "Amount in the payout currency the recipient should receive.", "example": 15 }, "reference": { "type": "string", "description": "Reference for the transaction.", "example": "XRP commission" }, "complianceDetails": { "$ref": "#/components/schemas/ComplianceDetailDto" } }, "oneOf": [ { "required": [ "walletRequiredAmount" ] }, { "required": [ "paidRequiredAmount" ] } ] }, "CryptoPayoutEstimateResponse": { "type": "object", "properties": { "externalId": { "type": "string", "format": "uuid", "description": "Unique ID for the estimate request generated by the system.", "example": "4f7768e5-cd82-42c4-80d6-18d84a5b3832" }, "accountId": { "type": "string", "format": "uuid", "description": "Internal account ID associated with the estimate.", "example": "4ea1277f-29d7-11ed-84d9-0a878439b77f" }, "walletId": { "type": "string", "description": "Wallet identifier", "example": "acc:23040543559277:x8rvQ:0", "maxLength": 255 }, "customerReference": { "type": "string", "description": "The reference provided in the request.", "example": "REF46730" }, "walletCurrency": { "type": "string", "description": "The currency from which funds are debited.", "example": "USD" }, "walletRequiredAmount": { "type": "number", "format": "float", "description": "Calculated amount in the wallet currency required to fund the payout.", "example": 15.79 }, "paidCurrency": { "type": "string", "description": "The currency in which the payout is made.", "example": "USDT" }, "paidRequiredAmount": { "type": "number", "format": "float", "description": "The amount the recipient will receive.", "example": 15 }, "feeCurrency": { "type": "string", "description": "Currency in which the transaction fee is calculated.", "example": "USD" }, "feePredictedAmount": { "type": "number", "format": "float", "description": "Estimated transaction fee in the feeCurrency.", "example": 0.16 }, "networkFeeCurrency": { "type": "string", "description": "Currency for the blockchain network fee.", "example": "USD" }, "networkFeePredictedAmount": { "type": "number", "format": "float", "description": "Estimated blockchain network fee in networkFeeCurrency.", "example": 1.62 }, "totalWalletAmount": { "type": "number", "format": "float", "description": "Total amount debited from the wallet, including fees and network costs.", "example": 15.95 }, "exchangeRate": { "type": "number", "format": "float", "description": "Exchange rate applied between walletCurrency and paidCurrency.", "example": 0.949715 }, "customerId": { "type": "string", "nullable": true, "description": "Associated customer ID, if applicable.", "example": null }, "paymentExternalId": { "type": "string", "nullable": true, "description": "External payment ID, if linked to an actual transaction.", "example": null }, "network": { "type": "string", "description": "Blockchain network used for the estimate.", "example": "ETHEREUM" } } }, "PayoutActionConfirmRequest": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "CONFIRM_BENEFICIARY" ], "description": "Action to confirm proceeding with the payout despite beneficiary name mismatch." } } }, "PayoutRequest": { "type": "object", "required": [ "walletId", "amount", "currency", "beneficiary" ], "properties": { "walletId": { "type": "string", "description": "Identifier for your debit wallet associated with the transaction" }, "amount": { "type": "number", "format": "float", "minimum": 0, "description": "Payout amount in major currency units" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Three-letter ISO-4217 currency code. The following payment `method` is supported for each currency:\n\n- USD: `ACH`, `ACH_SAME_DAY`, `FEDWIRE`, `FEDNOW`, `SWIFT`, or `RTP`. Use `SWIFT` for international payouts and the other methods for domestic transactions.\n\n- EUR: `SEPA_CT`, `SEPA_INST`, or `SWIFT`\n\n- GBP: `FASTER_PAYMENT`, or `SWIFT`", "enum": [ "USD", "EUR", "GBP" ], "example": "USD" }, "reference": { "type": "string", "description": "Internal identifier that is shown in the CSV reports for custom use cases. Can be a UUID or any string to identify the payment.\n\nThe field is for information purposes only. It will be fully supported in future releases.", "maxLength": 250 }, "method": { "type": "string", "description": "Payment method when sending out of USA.\n\nThe field is mandatory for the `USD` payouts and optional for other currencies.\n\nIf not provided, the optimal payment method is selected automatically based on dynamically determined attributes.\n\nIf you request an ACH Same Day payout outside its available window, it will be process as a next-day payout. However, the ACH Same Day fee may still be incurred.\n\nWhen `EUR` is set in `currency`, you can select the following payment `method`:\n\n- `SEPA_CT`: Standard SEPA bank transfer. Payment processing time is 1-2 business days.\n\n- `SEPA_INST`: Instant bank transfer. Funds arrive in seconds, 24/7. May incur a small fee.", "enum": [ "ACH", "ACH_SAME_DAY", "SEPA_CT", "SEPA_INST", "FEDWIRE", "FASTER_PAYMENT", "BOOK", "SWIFT", "RTP", "FEDWIRE", "FEDNOW" ] }, "beneficiary": { "$ref": "#/components/schemas/BeneficiaryRequest" }, "fees": { "type": "object", "properties": { "customerFee": { "type": "object", "properties": { "amount": { "type": "number", "format": "float", "description": "Transfer amount in major currency units." }, "currency": { "type": "string", "description": "Three-letter ISO-4217 currency code.", "enum": [ "USD", "EUR", "GBP" ] } } } } }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "requestDetails": { "$ref": "#/components/schemas/RequestDetails" } } }, "TransferRequestV2": { "type": "object", "required": [ "walletId", "reference", "amount", "currency", "beneficiary" ], "properties": { "walletId": { "type": "string", "description": "Identifier for your debit wallet associated with the transaction." }, "amount": { "type": "number", "format": "float", "minimum": 0, "description": "Transfer amount in fiat and crypto currency units." }, "currency": { "type": "string", "description": "Currency code. Supports both fiat (ISO-4217) and crypto currencies." }, "reference": { "type": "string", "description": "Internal identifier that is shown in the CSV reports for custom use cases. Can be a UUID or any string to identify the payment.", "maxLength": 250 }, "beneficiary": { "type": "object", "required": [ "walletId" ], "description": "Beneficiary information for the transfer. For internal transfers, only the wallet ID is required.", "properties": { "walletId": { "type": "string", "description": "Identifier for the beneficiary wallet that will receive the transfer. The wallet to which funds will be credited.", "example": "a:24122329329347:HsdJVhW:1" } } }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "TransferResponseV2": { "type": "object", "required": [ "id", "reference", "type", "status", "method", "fees", "originator", "beneficiary", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique transfer identifier." }, "reference": { "type": "string", "description": "Transfer unique reference that you must provide." }, "type": { "type": "string", "enum": [ "payment:transfer" ], "description": "Payment type constant for transfers.", "example": "payment:transfer" }, "status": { "type": "string", "enum": [ "PROCESSING", "COMPLETED", "FAILED" ], "description": "Current transfer status. More statuses may be added in future releases." }, "method": { "type": "string", "enum": [ "BOOK" ], "description": "Transfer method.", "example": "BOOK" }, "fees": { "type": "object", "properties": { "processingFee": { "$ref": "#/components/schemas/MoneyFeeV2", "description": "Processing fee for the transfer applied by BVNK to a debiting wallet." } } }, "originator": { "type": "object", "required": [ "amount", "currency", "walletId", "entity" ], "description": "Originator information for the transfer.", "properties": { "amount": { "type": "number", "format": "float", "description": "Amount of the transfer." }, "currency": { "type": "string", "description": "Currency code. Supports both fiat (ISO-4217) and crypto currencies." }, "walletId": { "type": "string", "description": "The ID of the originator's wallet associated with the transfer." }, "entity": { "oneOf": [ { "$ref": "#/components/schemas/TransferIndividual" }, { "$ref": "#/components/schemas/TransferCompany" } ], "discriminator": { "propertyName": "type", "mapping": { "INDIVIDUAL": "#/components/schemas/TransferIndividual", "COMPANY": "#/components/schemas/TransferCompany" } } } } }, "beneficiary": { "type": "object", "required": [ "amount", "currency", "walletId" ], "description": "Beneficiary information for the transfer.", "properties": { "amount": { "type": "number", "format": "float", "description": "Amount credited to the beneficiary wallet." }, "currency": { "type": "string", "description": "Currency code. Supports both fiat (ISO-4217) and crypto currencies." }, "walletId": { "type": "string", "description": "The ID of the beneficiary's wallet associated with the transfer." }, "entity": { "oneOf": [ { "$ref": "#/components/schemas/TransferIndividual" }, { "$ref": "#/components/schemas/TransferCompany" } ], "discriminator": { "propertyName": "type", "mapping": { "INDIVIDUAL": "#/components/schemas/TransferIndividual", "COMPANY": "#/components/schemas/TransferCompany" } } } } }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp." } } }, "PayoutActionRequest": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "CONFIRM_BENEFICIARY" ], "description": "Type of action to execute" } } }, "PayoutResponse": { "type": "object", "required": [ "id", "method", "status", "type", "fees", "originator", "beneficiary", "metadata", "createdAt", "updatedAt", "direction" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique payout identifier." }, "method": { "type": "string", "enum": [ "SEPA_CT", "SEPA_INST", "FASTER_PAYMENT", "BACS", "TARGET2", "TIPS", "SWIFT", "ACH", "ACH_SAME_DAY", "FEDWIRE", "FEDNOW", "RTP", "BOOK", "UNKNOWN", "BANK_TRANSFER", "WIRE", "SEPA" ], "description": "Payment method used in the transaction. Note: This list can be changed in the future." }, "reference": { "type": "string", "description": "Free text reference provided during payout creation (used mostly for reconciliation reasons)." }, "status": { "type": "string", "enum": [ "PENDING", "PROCESSING", "PENDING_APPROVAL", "ON_HOLD", "COMPLETED", "CANCELLED", "FAILED", "RETURNED" ], "description": "Current payout status." }, "fees": { "$ref": "#/components/schemas/FeesResponse" }, "originator": { "type": "object", "required": [ "amount", "currency", "walletId", "entity" ], "properties": { "amount": { "type": "number", "format": "float", "description": "Amount of the payout." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Currency of the payout." }, "walletId": { "type": "string", "description": "The ID of the originator's wallet associated with the payout." }, "customerId": { "type": "string", "description": "The ID of the originator's customer associated with the payout." }, "entity": { "oneOf": [ { "$ref": "#/components/schemas/Individual" }, { "$ref": "#/components/schemas/Company" } ], "discriminator": { "propertyName": "type", "mapping": { "INDIVIDUAL": "#/components/schemas/Individual", "COMPANY": "#/components/schemas/Company" } } } } }, "beneficiary": { "$ref": "#/components/schemas/BeneficiaryResponse" }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "createdAt": { "type": "string", "format": "date-time", "description": "Creation timestamp." }, "updatedAt": { "type": "string", "format": "date-time", "description": "Last update timestamp." }, "type": { "type": "string", "enum": [ "payment:payout:fiat" ], "description": "Payment type constant." }, "direction": { "type": "string", "enum": [ "OUT" ], "description": "Payment direction constant." }, "trackingDetails": { "type": "array", "description": "External identifiers for the payment transaction, including tracking references for different payment methods. These can be used to trace transactions across global payment networks such as Fedwire and ACH.", "items": { "type": "object", "properties": { "externalTransactionId": { "type": "string", "description": "External identifier for the payout.", "example": "123e4567-e89b-12d3-a456-426614174000" }, "imad": { "type": "string", "maxLength": 22, "description": "Input Message Accountability Data. Used as the originator's tracking reference for WIRE transfers. Generated by the sending bank when a wire transfer is initiated in the US banking system.", "example": "20260304ABCDXXXX012345" }, "omad": { "type": "string", "maxLength": 22, "description": "Output Message Accountability Data. Used as beneficiary's tracking reference for WIRE transfers. Generated by the receiving bank upon delivery of a wire transfer in the US banking system.", "example": "20260304QMQP021000080" }, "traceNumber": { "type": "string", "maxLength": 15, "description": "Payment reference used for ACH payments.", "example": "021000080123456" }, "uetr": { "type": "string", "description": "Unique End-to-End Transaction Reference. Used in SWIFT payments. Remains consistent throughout the entire international payment journey across all participating banks.", "example": "550e8400-e29b-41d4-a716-446655440000" } } } } } }, "BeneficiaryRequest": { "type": "object", "required": [ "remittanceInformation", "entity", "bankAccount" ], "properties": { "remittanceInformation": { "type": "string", "description": "Payment reference sent to the beneficiary.\n\nCan contain only alphanumeric characters (a-z, A-Z, 0-9), whitespaces, or the `.,-` symbols.\n\nOther allowed characters and number of symbols vary depending on the used payment method or currency.\n\nCannot be \"null\" or empty string.", "pattern": "^[a-zA-Z0-9\\s,.-]{5,34}$", "minLength": 5, "maxLength": 34 }, "entity": { "oneOf": [ { "$ref": "#/components/schemas/Individual" }, { "$ref": "#/components/schemas/Company" } ], "discriminator": { "propertyName": "type", "mapping": { "INDIVIDUAL": "#/components/schemas/Individual", "COMPANY": "#/components/schemas/Company" } } }, "bankAccount": { "$ref": "#/components/schemas/BankAccountV2" } } }, "BeneficiaryResponse": { "type": "object", "required": [ "remittanceInformation", "entity", "amount", "currency" ], "properties": { "remittanceInformation": { "type": "string", "description": "Payment reference information.\n\nCan contain only alphanumeric characters (a-z, A-Z, 0-9), whitespaces, or the `.,-` symbols.\n\nOther allowed characters vary depending on the used payment method or currency.\n\nAlways required for payouts." }, "amount": { "type": "number", "format": "float", "description": "Amount received by the beneficiary." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Currency of the transaction received by the beneficiary." }, "entity": { "oneOf": [ { "$ref": "#/components/schemas/Individual" }, { "$ref": "#/components/schemas/Company" } ], "discriminator": { "propertyName": "type" } }, "bankAccount": { "$ref": "#/components/schemas/BankAccountV2", "description": "Bank account details. Always returned for FIAT payouts, but not for crypto payouts." } } }, "Individual": { "type": "object", "required": [ "type", "firstName", "lastName", "relationshipType" ], "properties": { "type": { "type": "string", "enum": [ "INDIVIDUAL" ], "description": "Entity type. Always present." }, "firstName": { "type": "string", "minLength": 1, "description": "First name" }, "lastName": { "type": "string", "minLength": 1, "description": "Last name" }, "dateOfBirth": { "type": "string", "format": "date", "pattern": "^\\d{2}-\\d{2}-\\d{4}$", "description": "Date of birth in DD-MM-YYYY format", "example": "15-01-1990" }, "address": { "$ref": "#/components/schemas/BeneficiaryAddress" }, "relationshipType": { "type": "string", "enum": [ "SELF_OWNED", "THIRD_PARTY" ], "description": "Relationship type." } } }, "Company": { "type": "object", "required": [ "type", "legalName", "relationshipType" ], "properties": { "type": { "type": "string", "enum": [ "COMPANY" ], "description": "Entity type." }, "legalName": { "type": "string", "minLength": 1, "description": "Legal company name" }, "address": { "$ref": "#/components/schemas/BeneficiaryAddress" }, "relationshipType": { "type": "string", "enum": [ "SELF_OWNED", "THIRD_PARTY" ], "description": "Relationship type." } } }, "TransferIndividual": { "type": "object", "required": [ "type", "firstName", "lastName" ], "properties": { "type": { "type": "string", "enum": [ "INDIVIDUAL" ], "description": "Entity type" }, "firstName": { "type": "string", "minLength": 1, "description": "First name" }, "lastName": { "type": "string", "minLength": 1, "description": "Last name" } } }, "TransferCompany": { "type": "object", "required": [ "legalName" ], "properties": { "type": { "type": "string", "enum": [ "COMPANY" ], "description": "Entity type" }, "legalName": { "type": "string", "minLength": 1, "description": "Legal company name" } } }, "BankAccountV2": { "type": "object", "required": [ "accountNumber", "bank" ], "properties": { "accountNumber": { "type": "string", "minLength": 1, "description": "Bank account number." }, "accountType": { "type": "string", "enum": [ "CHEQUE", "CHECKING", "SAVINGS", "TRANSMISSION" ], "description": "Type of bank account.\n\nMandatory for the `USD` payouts." }, "bank": { "$ref": "#/components/schemas/BankV2" }, "intermediaryBanks": { "type": "array", "items": { "$ref": "#/components/schemas/BankV2" }, "description": "List of intermediary banks." } } }, "BankV2": { "type": "object", "properties": { "identificationCode": { "type": "string", "description": "Bank identification code (SWIFT/BIC). Mandatory for non-IBAN accounts, for example, use it as a routing number for local `USD` payments. Optional for local payments in EUR." }, "nid": { "type": "string", "description": "National bank identifier. For the SWIFT USD payments, this is the account routing number: a nine-digit code that identifies your specific financial institution for electronic transactions.\n\nMandatory for the Swift USD payments. We recommend providing `nid` at any time, as some banks may not process the payments without it." }, "country": { "type": "string", "description": "Bank country code." }, "address": { "type": "object", "description": "Bank branch address. For SWIFT payments, `addressLine1`, `city`, `postCode`, and `country` are required.", "required": [ "country" ], "properties": { "addressLine1": { "type": "string", "description": "Bank branch primary address line.", "maxLength": 35 }, "addressLine2": { "type": "string", "description": "Bank branch secondary address line.", "maxLength": 35 }, "region": { "type": "string", "description": "Bank branch state or region." }, "city": { "type": "string", "description": "Bank branch city." }, "country": { "type": "string", "description": "Bank branch country code." }, "postCode": { "type": "string", "description": "Postal or ZIP code of the bank branch." } }, "example": { "addressLine1": "123 Bank St", "addressLine2": "Suite 100", "region": "New York", "city": "New York", "country": "US", "postCode": "10001" } } } }, "BankAddress": { "type": "object", "description": "Physical address of the bank. May be required or optional depending on payment methods and currencies. For **SWIFT** payments, the following fields are mandatory: `addressLine1`, `city`, `postCode`, `country`.", "properties": { "addressLine1": { "type": "string", "description": "Bank's primary address line.", "maxLength": 35 }, "addressLine2": { "type": "string", "description": "Bank's secondary address line.", "maxLength": 35 }, "region": { "type": "string", "description": "Bank's state or region of the address." }, "city": { "type": "string", "description": "Bank's city of the address." }, "country": { "type": "string", "description": "Bank's country code." }, "postCode": { "type": "string", "description": "Postal or ZIP code of the bank's address." } }, "example": { "addressLine1": "123 Main St", "addressLine2": "Apt 4B", "region": "California", "city": "Los Angeles", "country": "US", "postCode": "90001" } }, "Fees": { "type": "object", "properties": { "customerFee": { "$ref": "#/components/schemas/Money" } } }, "FeesResponse": { "type": "object", "required": [ "processingFee" ], "properties": { "customerFee": { "$ref": "#/components/schemas/MoneyFeeV2" }, "processingFee": { "$ref": "#/components/schemas/MoneyFeeV2" } } }, "RequestDetails": { "type": "object", "required": [ "originator" ], "properties": { "originator": { "type": "object", "properties": { "ipAddress": { "type": "string", "description": "The IP address of the customer initiating the payout.\n\nOnly required when you make a payment from a customer's wallet.", "example": "172.16.0.1" } }, "description": "Originator details." } } }, "Pageable": { "type": "object", "description": "Pagination information for the request", "properties": { "pageNumber": { "type": "integer", "description": "Current page number (0-based)", "example": 0 }, "pageSize": { "type": "integer", "description": "Number of items per page", "example": 20 }, "sort": { "type": "array", "description": "Sort criteria applied", "items": { "type": "string" }, "example": [] }, "offset": { "type": "integer", "description": "Offset of the first item", "example": 0 }, "paged": { "type": "boolean", "description": "Whether the result is paged", "example": true }, "unpaged": { "type": "boolean", "description": "Whether the result is unpaged", "example": false } } }, "PageMetadata": { "type": "object", "description": "Complete pagination metadata for paginated responses", "properties": { "pageable": { "$ref": "#/components/schemas/Pageable" }, "last": { "type": "boolean", "description": "Whether this is the last page", "example": true }, "totalPages": { "type": "integer", "description": "Total number of pages", "example": 1 }, "totalElements": { "type": "integer", "description": "Total number of elements across all pages", "example": 1 }, "first": { "type": "boolean", "description": "Whether this is the first page", "example": true }, "size": { "type": "integer", "description": "Page size", "example": 20 }, "number": { "type": "integer", "description": "Current page number (0-based)", "example": 0 }, "sort": { "type": "array", "description": "Sort criteria for the page", "items": { "type": "string" }, "example": [] }, "numberOfElements": { "type": "integer", "description": "Number of elements in the current page", "example": 1 }, "empty": { "type": "boolean", "description": "Whether the page is empty", "example": false } } }, "CurrencyDto": { "type": "object", "properties": { "code": { "type": "string", "description": "The currency code.", "example": "ETH" }, "depositFee": { "type": "number", "description": "The % fee to deposit the currency.", "example": 0 }, "fiat": { "type": "boolean", "description": "Is a fiat currency.", "default": false }, "icon": { "type": "string", "description": "The icon of the currency.", "example": "https://cdn.com/eth-icon.png" }, "id": { "type": "integer", "description": "The ID of the currency.", "format": "int64", "example": 1432 }, "name": { "type": "string", "description": "The currency name.", "example": "Ethereum" }, "options": { "$ref": "#/components/schemas/currencyOptions" }, "pricePrecision": { "type": "integer", "description": "The precision of decimal points for the currency.", "format": "int32", "default": 5 }, "protocols": { "type": "array", "description": "The alternative protocols array.", "items": { "$ref": "#/components/schemas/CurrencyProtocol" } }, "quantityPrecision": { "type": "integer", "description": "The precision of decimal points for the currency displayed.", "format": "int32", "default": 5 }, "supportsDeposits": { "type": "boolean", "description": "Is deposits for this currency supported.", "default": false }, "supportsWithdrawals": { "type": "boolean", "description": "Is withdrawals for this currency supported", "default": false }, "withdrawalFee": { "type": "number", "description": "The % fee to withdraw this currency.", "example": 0.01 }, "withdrawalParameters": { "type": "array", "description": "The withdrawal parameter object.", "items": { "$ref": "#/components/schemas/ExternalCurrencyWithdrawalParameter" } } } }, "CurrencyFiatDto": { "type": "object", "properties": { "code": { "type": "string", "description": "The currency code.", "example": "EUR" }, "depositFee": { "type": "number", "description": "The % fee to deposit the currency.", "example": 0 }, "fiat": { "type": "boolean", "description": "Is a fiat currency.", "default": true }, "icon": { "type": "string", "description": "The icon of the currency.", "example": null }, "id": { "type": "integer", "description": "The ID of the currency.", "format": "int64", "example": 1773 }, "name": { "type": "string", "description": "The currency name.", "example": "Euro" }, "options": { "description": "The currency options.", "type": "object" }, "pricePrecision": { "type": "integer", "description": "The precision of decimal points for the currency.", "format": "int32", "default": 2 }, "protocols": { "type": "array", "description": "The alternative protocols array.", "items": {}, "example": [] }, "quantityPrecision": { "type": "integer", "description": "The precision of decimal points for the currency displayed.", "format": "int32", "default": 2 }, "supportsDeposits": { "type": "boolean", "description": "Is deposits for this currency supported.", "default": true }, "supportsWithdrawals": { "type": "boolean", "description": "Is withdrawals for this currency supported", "default": true }, "withdrawalFee": { "type": "number", "description": "The % fee to withdraw this currency.", "example": 0.4 }, "withdrawalParameters": { "type": "array", "description": "The withdrawal parameter object.", "items": {}, "example": [] } } }, "ExternalCurrencyWithdrawalParameter": { "type": "object", "properties": { "id": { "type": "integer", "description": "The ID of the external currency.", "format": "int64", "example": 1432 }, "code": { "type": "string", "description": "The code of the external currency.", "example": "BTC" }, "name": { "type": "string", "description": "The name of the external currency.", "example": "Bitcoin" } } }, "CurrencyProtocol": { "type": "object", "properties": { "code": { "type": "string", "description": "The code of the currency.", "example": "ERC20" }, "network": { "type": "string", "description": "The network of the currency.", "example": "Ethereum" } } }, "currencyOptions": { "type": "object", "description": "The currency options.", "properties": { "transaction": { "type": "string", "description": "View onchain transactions.", "example": "https://etherscan.io/tx/{{hash}}" }, "explorer": { "type": "string", "description": "The explorer to view crypto network", "example": "https://etherscan.io/" }, "address": { "type": "string", "description": "View wallet address", "example": "https://etherscan.io/address/{{address}}" }, "confirmations": { "type": "integer", "description": "Number of confirmations needed.", "example": 12 } } }, "MerchantDto": { "type": "object", "properties": { "id": { "type": "integer", "description": "The ID of the Merchant ID.", "format": "int64", "example": 1432 }, "merchantId": { "type": "string", "description": "The Merchant ID as a UUID.", "example": "b312436e-e477-49d4-be7f-9d027f9b9e34" }, "displayName": { "type": "string", "description": "The name of the merchant displayed on the payments page.", "example": "Test Merchant Name" }, "secret": { "type": "string", "description": "The secret key used to validate webhooks.", "example": "MzI5OGUyZGMtN2FkOC00NzVkLThjNzEtMWVjMzk2ZjQ5OGMwYTBlZTBlOGYtMjBhNi00NjMxLWI1MTctMTI5MjlmMjdhYmM" }, "webhookUrl": { "type": "string", "description": "The webhooks URL that webhoosk are sent to.", "example": "https://www.URL.com/to/send/webhooks/to" }, "autoConvertInvalidPayments": { "type": "boolean", "description": "Is set to auto convert invalid payments.", "default": true }, "defaultExpiryMinutes": { "type": "integer", "description": "The default number of minutes before a payment expires for this Merchant ID.", "format": "int32", "example": 1440 }, "webhookVersion": { "type": "integer", "description": "The version of webhooks sent.", "format": "int32", "example": 1 }, "wallet": { "$ref": "#/components/schemas/WalletDto" }, "emailRecipients": { "type": "string", "description": "The recipients of event emails.", "example": null } } }, "WalletDto": { "type": "object", "properties": { "address": { "type": "string", "description": "The crypto wallet address", "example": "0x7be879d34f3Db833f70d9fE4873Bdd0cBcaC6bf6" }, "alternatives": { "type": "array", "description": "The array of alternative protocol addresses.", "items": {}, "example": [] }, "approxAvailable": { "type": "string", "description": "The approximate amount availible in the wallet.", "example": "0.59573928" }, "approxBalance": { "type": "string", "description": "The balance amount availible of the wallet.", "example": "0.59573928" }, "available": { "type": "number", "format": "float", "example": 0.59573928 }, "balance": { "type": "number", "description": "The balance of the wallet.", "format": "float", "example": 0.59573928 }, "convertedAvailable": { "type": "number", "description": "The availible converted amount", "format": "float", "example": 20917.59 }, "currency": { "$ref": "#/components/schemas/CurrencyDto" }, "custodianWallet": { "type": "boolean", "nullable": true, "description": "Is a custodian wallet.", "default": null }, "depositFee": { "type": "number", "description": "The fee to deposit funds in wallet.", "format": "float", "example": 0 }, "description": { "type": "string", "description": "The description of the wallet.", "example": "ETH wallet" }, "id": { "type": "integer", "description": "The wallet ID.", "format": "int64", "example": 1432 }, "isEmoney": { "type": "boolean", "description": "Is E Money Wallet", "default": false }, "lookup": { "type": "string", "nullable": true, "description": "Is a lookup.", "example": null }, "network": { "type": "string", "description": "The network of the wallet.\n\nWe recommend using the `network` parameter instead of `protocol`.", "example": "ETHEREUM" }, "protocol": { "type": "string", "description": "The protocol of the wallet.", "example": "ETH" }, "supportsDeposits": { "type": "boolean", "description": "Is able to support deposits.", "default": true }, "supportsThirdParty": { "type": "boolean", "description": "Is a third party wallet.", "default": false }, "supportsWithdrawals": { "type": "boolean", "description": "Is able to support withdrawals.", "default": true }, "withdrawalFee": { "type": "number", "description": "The fee to withdraw funds from wallet.", "format": "float", "example": 0.001 }, "supportsInternalBvnkNetworkTransfers": { "type": "boolean", "description": "Supports internal BVNK network transfers.", "default": false }, "partner": { "type": "string", "description": "Partner information.", "nullable": true, "example": null }, "supportedTransferDestinations": { "type": "array", "description": "List of supported transfer destinations.", "items": { "type": "string" }, "example": [ "LOCAL" ] }, "approxConvertedAvailable": { "type": "string", "description": "The approximate converted available amount as a string.", "example": "19.71" }, "lsid": { "type": "string", "description": "The wallet LSID (Local Session ID).", "example": "a:25061134333492:69iFbD6:1" }, "status": { "type": "string", "description": "The status of the wallet.", "enum": [ "ACTIVE", "INACTIVE", "TERMINATED" ], "example": "ACTIVE" } } }, "CreateWalletRequest": { "type": "object", "required": [ "currencyCode", "name", "customerReference", "instruction" ], "properties": { "currencyCode": { "type": "string", "description": "Currency code for the wallet.", "enum": [ "USD", "EUR", "GBP", "USDT", "POL", "PYUSD", "BTC", "SOL", "BNB", "XRP", "ETH", "LTC", "USDC", "USDG", "TRX" ], "example": "USD" }, "name": { "type": "string", "description": "Name of the wallet.", "example": "My Customer Wallet" }, "customerReference": { "type": "string", "format": "uuid", "description": "Unique reference to the customer who owns the wallet.", "example": "b4e5c3d1-9a42-4e7b-8f34-7c6b2a89f3df" }, "instruction": { "$ref": "#/components/schemas/Instruction" } } }, "Instruction": { "type": "object", "required": [ "type", "virtualAccountRequired" ], "properties": { "walletProfile": { "type": "string", "description": "Profile to assign to the wallet. *Required for fiat wallets*.\n\n Retrieve available profiles from `GET /ledger/v1/wallets/profiles`.", "example": "2a3fe604-2b14-4009-90b3-1e48f1a38b11" }, "type": { "type": "string", "enum": [ "FIAT", "CRYPTO" ], "description": "Type of the wallet." }, "virtualAccountRequired": { "type": "boolean", "description": "Indication whether a virtual account is required. Currently, only `true` is supported.", "default": true } } }, "LedgerWalletV2CreateRequest": { "type": "object", "required": [ "currency", "name", "profileId" ], "properties": { "customerId": { "type": "string", "format": "uuid", "description": "Unique identifier for the customer. **Required if you create a wallet for your customer**." }, "currency": { "type": "string", "description": "Currency code for the wallet." }, "name": { "type": "string", "description": "Display name for the wallet.", "minLength": 2, "maxLength": 255 }, "profileId": { "type": "string", "description": "ID of the wallet profile to associate. To get the full list of available wallet profiles, see [Get Wallet Profiles](/bvnk/api-explorer/endpoints/wallet-profiles). Required for fiat wallets." } } }, "LedgerWalletV2Balance": { "type": "object", "description": "Information about the available balance of the wallet.", "required": [ "amount", "currency" ], "properties": { "amount": { "type": "number", "description": "Balance amount as a decimal string for fixed precision.", "example": 1000.00 }, "currency": { "type": "string", "example": "USD" } } }, "LedgerWalletV2Capabilities": { "type": "object", "properties": { "safeguarded": { "type": "boolean" }, "currencyType": { "type": "string", "description": "Type of currency for the wallet. Can be used to filter wallets by type when retrieving the list of them.", "enum": [ "FIAT", "CRYPTO" ] } } }, "LedgerWalletV2BankAddress": { "type": "object", "description": "Physical address of the bank.", "properties": { "addressLine1": { "type": "string", "description": "Primary street address line.", "example": "123 Main Street" }, "addressLine2": { "type": "string", "nullable": true, "description": "Secondary address line (suite, floor, building, etc.)." }, "city": { "type": "string", "description": "City of the bank address.", "example": "New York" }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code of the bank address.", "example": "GB" }, "stateCode": { "type": "string", "description": "ISO 3166-2 state or province code.", "example": "NY" }, "postCode": { "type": "string", "description": "Postal or ZIP code of the bank address.", "example": "EC2R 8EJ" }, "fullAddress": { "type": "string", "nullable": true, "description": "Full formatted address string." } } }, "LedgerWalletV2Bank": { "type": "object", "description": "Bank details associated with the fiat payment instrument.", "required": [ "name", "bic" ], "properties": { "name": { "type": "string", "description": "Name of the bank.", "example": "Banco Europa Continental, S.A." }, "address": { "$ref": "#/components/schemas/LedgerWalletV2BankAddress" }, "bic": { "type": "string", "description": "Bank Identifier Code (SWIFT/BIC).", "example": "SAPYGB2L" }, "nid": { "$ref": "#/components/schemas/LedgerWalletV2BankNid" } } }, "LedgerWalletV2BankNid": { "type": "object", "description": "National identifier for the bank. Present when a local clearing code applies.", "required": [ "value" ], "properties": { "value": { "type": "string", "description": "The national identifier value (e.g. routing number, sort code).", "example": "601613" }, "type": { "type": "string", "description": "Type of the national identifier.", "enum": [ "ROUTING_NUMBER", "SORT_CODE", "OTHER" ], "example": "SORT_CODE" } } }, "LedgerWalletV2FiatLedger": { "type": "object", "description": "Information about the fiat payment instruments.\n\nWhen a payment reference is required for inbound payments, `remittanceInformationPrefix` indicates the required prefix (e.g. for SWIFT).", "required": [ "type", "accountHolderName", "accountNumber" ], "properties": { "type": { "type": "string", "enum": [ "FIAT" ], "description": "Type of ledger, must be FIAT for this schema." }, "accountHolderName": { "type": "string", "description": "Name of the account holder.", "example": "System Pay Services (Malta) Limited" }, "accountHolderAddress": { "description": "Physical address of the account holder.", "allOf": [ { "$ref": "#/components/schemas/LedgerWalletV2BankAddress" } ] }, "accountNumber": { "type": "string", "description": "Account number. Must be provided only if `type` = `FIAT`.", "example": "DE10601202004579784373" }, "remittanceInformationPrefix": { "type": "string", "description": "Prefix that must appear within the payment reference when a `reference` is required for this rail, for example, SWIFT.", "example": "REF FKGA983" }, "bankDetails": { "$ref": "#/components/schemas/LedgerWalletV2Bank" } }, "title": "Fiat payment instruments" }, "LedgerWalletV2CryptoLedger": { "type": "object", "description": "Information about the crypto payment instruments.", "required": [ "type", "address", "network" ], "properties": { "type": { "type": "string", "enum": [ "CRYPTO" ], "description": "Type of a payment instrument, must be CRYPTO for this schema." }, "address": { "type": "string", "description": "Crypto wallet address.", "example": "1BoatSLRHtKNngkdXEeobR76b53LETtpyT" }, "network": { "type": "string", "description": "Crypto wallet network.", "example": "Ethereum" }, "tag": { "type": "string", "description": "Optional crypto tag or memo, if required by the network.", "example": "eth" } }, "title": "Crypto payment instruments" }, "LedgerWalletV2Customer": { "type": "object", "description": "Customer with which this wallet is associated. Shown only for customer wallets.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the customer." }, "name": { "type": "string", "description": "Display name for the customer." } } }, "LedgerWalletV2Response": { "type": "object", "required": [ "id", "name", "status" ], "properties": { "id": { "type": "string", "description": "The wallet identifier.", "example": "a:25031472839104:kR7mHxQ:1" }, "name": { "type": "string", "description": "Display name of the wallet.", "example": "USD Operations" }, "customer": { "$ref": "#/components/schemas/LedgerWalletV2Customer" }, "status": { "type": "string", "description": "Status of the wallet.", "enum": [ "ACTIVE", "INACTIVE", "TERMINATED" ], "example": "ACTIVE" }, "balance": { "type": "object", "description": "Available balance for the wallet.", "required": [ "amount", "currency" ], "properties": { "amount": { "description": "Balance amount as a decimal string for fixed precision.", "type": "number", "example": 0.00 }, "currency": { "type": "string", "description": "Wallet currency code.", "example": "USD" } } }, "paymentInstruments": { "type": "array", "description": "Payment instruments associated with the wallet. A wallet can have multiple payment instruments to support different payment methods.", "items": { "oneOf": [ { "$ref": "#/components/schemas/LedgerWalletV2FiatLedger" }, { "$ref": "#/components/schemas/LedgerWalletV2CryptoLedger" } ] } }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the wallet was created in ISO 8601 format.", "example": "2025-02-13T22:55:56.104Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp of the most recent update to the wallet in ISO 8601 format.", "example": "2026-05-08T14:40:07.463Z" } } }, "LedgerWalletV2ListItem": { "type": "object", "description": "Wallet summary for list views. Covers Direct and Underlying wallets.", "properties": { "id": { "type": "string", "description": "The wallet identifier.", "example": "a:25041855293741:pWnL4vB:1" }, "name": { "type": "string", "description": "Display name of the wallet.", "example": "USD Operations" }, "customer": { "$ref": "#/components/schemas/LedgerWalletV2Customer" }, "status": { "type": "string", "description": "Status of the wallet.", "enum": [ "ACTIVE", "INACTIVE", "TERMINATED" ], "example": "ACTIVE" }, "balance": { "$ref": "#/components/schemas/LedgerWalletV2Balance" }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the wallet was created in ISO 8601 format.", "example": "2025-02-13T22:55:56.104Z" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Timestamp of the most recent update to the wallet in ISO 8601 format.", "example": "2024-12-18T14:12:11.743Z" } } }, "LedgerWalletV2Pageable": { "type": "object", "properties": { "pageNumber": { "type": "integer", "description": "Current page index (0-based).", "example": 0 }, "pageSize": { "type": "integer", "description": "Page size.", "example": 10 } } }, "LedgerWalletV2ListResponse": { "type": "object", "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/LedgerWalletV2ListItem" } }, "pageable": { "$ref": "#/components/schemas/LedgerWalletV2Pageable" }, "hasNext": { "type": "boolean", "description": "Flag that shows whether another page of results exists." } } }, "WalletActionType": { "type": "string", "description": "Type of wallet action to execute:\n\n- `TERMINATE`: Permanently deletes the wallet. **This action cannot be reversed**. For **fiat** wallets, the linked virtual account is also closed (not applicable to the crypto wallets). The wallet balance must be zero before termination—transfer funds to another wallet first if needed.\n\n- `BLOCK`: Temporarily freezes the wallet. A blocked wallet cannot receive deposits or make payments and typically has the `INACTIVE` status.\n\n- `UNBLOCK`: Unfreezes the blocked wallet.", "enum": [ "TERMINATE", "BLOCK", "UNBLOCK" ] }, "WalletActionRequest": { "type": "object", "required": [ "action", "comment" ], "properties": { "action": { "$ref": "#/components/schemas/WalletActionType" }, "comment": { "type": "string", "description": "Reason the wallet action is being executed.", "enum": [ "COMPLIANCE", "OPERATION", "OFFBOARDING", "CLIENT_REQUEST", "OTHER" ] } } }, "WalletResponse": { "type": "object", "required": [ "id", "accountReference", "customerReference", "name", "status", "balance", "ledgers" ], "properties": { "id": { "type": "string", "description": "Unique wallet ID.", "example": "a:24092328494070:G5i4XZ9:1" }, "accountReference": { "type": "string", "format": "uuid", "description": "Account reference for this wallet.", "example": "3399c975-e1c1-4acf-9a90-6cfbdcdeaaea" }, "customerReference": { "type": "string", "description": "Customer reference for this wallet.", "format": "uuid", "example": "b94dcf2a-d377-469e-8846-e21f65b18a77" }, "name": { "type": "string", "description": "Name of the wallet.", "example": "Wallet XYZ987" }, "status": { "type": "string", "description": "Status of the wallet.", "enum": [ "ACTIVE", "INACTIVE", "TERMINATED" ], "example": "ACTIVE" }, "balance": { "$ref": "#/components/schemas/Balance" }, "ledgers": { "type": "array", "items": { "$ref": "#/components/schemas/Ledger" } }, "capabilities": { "type": "string", "description": "Flag that shows that funds or assets are protected and kept separate from a company's own money. They can't be used for business operations or debts and remain available to the rightful owners.", "enum": [ "SAFEGUARDED" ], "example": "SAFEGUARDED" } } }, "Balance": { "type": "object", "description": "Information about the available balance of the wallet.", "required": [ "value", "currencyCode" ], "properties": { "value": { "type": "number", "description": "Available amount of funds in the wallet.", "format": "float", "example": 10 }, "currencyCode": { "type": "string", "description": "Wallet currency.", "enum": [ "USD", "EUR", "GBP", "USDT", "POL", "PYUSD", "BTC", "SOL", "BNB", "XRP", "ETH", "LTC", "USDC", "USDG", "TRX" ], "example": "GBP" } } }, "Ledger": { "oneOf": [ { "$ref": "#/components/schemas/FiatLedger" }, { "$ref": "#/components/schemas/CryptoLedger" } ], "discriminator": { "propertyName": "type", "mapping": { "FIAT": "#/components/schemas/FiatLedger", "CRYPTO": "#/components/schemas/CryptoLedger" } } }, "FiatLedger": { "type": "object", "description": "Information about the fiat ledger.\n\nIf the wallet is enabled for SWIFT, the `paymentReference` is returned", "required": [ "type", "accountNumber", "code" ], "properties": { "type": { "type": "string", "enum": [ "FIAT" ], "description": "Type of ledger, must be FIAT for this schema." }, "accountHolderName": { "type": "string", "description": "Name of the account holder.", "example": "System Pay Services (Malta) Limited" }, "accountNumber": { "type": "string", "description": "Account number. Must be provided only if `type` = `FIAT`.", "example": "DE10601202004579784373" }, "code": { "type": "string", "description": "Bank identification code (BIC/SWIFT code).", "example": "BEUCESMMXXX" }, "accountNumberFormat": { "type": "string", "description": "Format of the account number.", "example": "SWIFT" }, "paymentReference": { "type": "string", "description": "Reference to include with the payment.", "example": "REF DZ0XJL4" }, "bank": { "type": "object", "description": "Bank details associated with the fiat ledger.", "properties": { "identificationCode": { "type": "string", "description": "Bank identification code (BIC/SWIFT code).", "example": "BEUCESMMXXX" }, "name": { "type": "string", "description": "Name of the bank.", "example": "Banco Europa Continental, S.A." }, "address": { "description": "Physical address of the bank.", "$ref": "#/components/schemas/Address" } } } } }, "CryptoLedger": { "type": "object", "required": [ "type", "address", "network" ], "properties": { "type": { "type": "string", "enum": [ "CRYPTO" ], "description": "Type of ledger, must be CRYPTO for this schema." }, "address": { "type": "string", "description": "Crypto wallet address. Must be provided only if `type` = `CRYPTO`.", "example": "1BoatSLRHtKNngkdXEeobR76b53LETtpyT" }, "network": { "type": "string", "description": "Crypto wallet network or protocol. Must be provided only if `type` = `CRYPTO`.", "example": "Ethereum" }, "tag": { "type": "string", "description": "Optional crypto tag or memo, if required by the network.", "example": "eth" } } }, "ApiError": { "type": "object", "required": [ "code", "status", "message", "traceId" ], "properties": { "code": { "type": "string", "format": "uri-reference", "description": "URI reference identifying the error type, resolvable to documentation.", "example": "bvnk:ledger:4001" }, "status": { "type": "string", "description": "The HTTP status code name.", "example": "Bad Request" }, "message": { "type": "string", "description": "A human-readable message providing more details about the error.", "example": "Validation error." }, "traceId": { "type": "string", "description": "Tracing ID useful for searching in logs when shared by a customer.", "example": "abc123-def456-ghi789" }, "details": { "$ref": "#/components/schemas/Detail" } } }, "Detail": { "type": "object", "properties": { "documentLink": { "type": "string", "description": "Link to a document that explains the error or related documentation.", "example": "https://docs.bvnk.com/reference/errors" }, "errors": { "type": "array", "description": "List of validation errors.", "items": { "type": "string" }, "example": [ "Address country required" ] } } }, "PayRequestDto": { "description": "The request data required to create a payment in or a payment out.", "oneOf": [ { "$ref": "#/components/schemas/PayRequestInDto" }, { "$ref": "#/components/schemas/PayRequestOutDto" } ], "discriminator": { "propertyName": "type", "mapping": { "IN": "#/components/schemas/PayRequestInDto", "OUT": "#/components/schemas/PayRequestOutDto" } } }, "PayRequestInDto": { "title": "Pay-in (type: IN)", "description": "Request data for an incoming crypto payment (`type: IN`).", "type": "object", "properties": { "walletId": { "type": "string", "description": "Identifier for the debit wallet associated with the transaction.", "example": "a:24092328494070:G5i4XZ9:1" }, "merchantId": { "description": "**Deprecated. Don't use, if you specify `walletId`**.\n\n Your Merchant ID. You can find it on the Merchant Details page in your account.", "type": "string", "deprecated": true, "example": "5C8D8D78-366A-4AFB-B658-A64CE543C5DB", "minLength": 6, "maxLength": 50 }, "amount": { "description": "Payment amount. The minimum cryptocurrency deposit amount to be processed is 5 EUR.", "type": "number", "example": 223.05, "minimum": 5 }, "expiryMinutes": { "description": "The time period after which payment expires. Overrides the default expiry limit.", "type": "integer", "example": 20 }, "currency": { "description": "The virtual currency to display to end users. Determines the amount due after conversion.", "type": "string", "example": "EUR", "minLength": 2, "maxLength": 20, "x-setter-extra-annotation": "@ToUpperCase" }, "returnUrl": { "description": "The URL that the customer will be redirected to if they click **Back to Merchant** button on the payment web page. Must start with `https://`.", "type": "string", "example": "https://my-shop.com/payment-complete?ref=xyz" }, "reference": { "description": "The custom payment ID to identify the payment within your platform.", "type": "string", "example": "myUniqueRef333", "minLength": 6, "maxLength": 255 }, "customerId": { "description": "The unique ID for the party requesting the payment. If multiple payments for same party are requested, the ID should remain consistent.", "type": "string", "example": "d063635e-0f83-4e47-a1f3-fc9484df1509" }, "type": { "type": "string", "description": "Defines the payment direction. Must be `IN` for incoming payments.", "enum": [ "IN" ], "example": "IN" }, "payInDetails": { "$ref": "#/components/schemas/PayInDetailDto" }, "currencyOptions": { "type": "array", "description": "Limits cryptocurrencies and network protocols that customers can use to complete the payment. If omitted, customers can pay with any supported deposit currency. For more information, see [Collect payments](https://docs.bvnk.com/bvnk/use-cases/stablecoin-payments-for-platforms/get-payment/#collect-payments). For supported currencies and protocols, see the [Supported Currencies API](https://api.bvnk.com/api/currency/crypto?max=100&sort=rank&order=asc&allowDeposits=true).", "items": { "$ref": "#/components/schemas/PayRequestCurrencyOptionDto" } }, "complianceDetails": { "$ref": "#/components/schemas/ComplianceDetailDto" }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "embeddedCustomerDetails": { "description": "Unique customer reference. Must be in the UUID format.", "type": "object", "properties": { "reference": { "type": "string", "format": "uuid", "example": "07357926-aed0-44e1-a75b-7505557ee137" } } } }, "required": [ "walletId", "amount", "currency", "type", "reference", "customerId", "complianceDetails", "payInDetails" ] }, "PayRequestOutDto": { "title": "Payout (type: OUT)", "description": "Request data for an outgoing crypto payment (`type: OUT`).", "type": "object", "properties": { "walletId": { "type": "string", "description": "Identifier for the debit wallet associated with the transaction.", "example": "a:24092328494070:G5i4XZ9:1" }, "merchantId": { "description": "**Deprecated. Don't use, if you specify `walletId`**.\n\n Your Merchant ID. You can find it on the Merchant Details page in your account.", "type": "string", "example": "5C8D8D78-366A-4AFB-B658-A64CE543C5DB", "minLength": 6, "maxLength": 50 }, "amount": { "description": "Payment amount. The minimum cryptocurrency deposit amount to be processed is 5 EUR.", "type": "number", "example": 223.05, "minimum": 5 }, "expiryMinutes": { "description": "The time period after which payment expires. Overrides the default expiry limit.", "type": "integer", "example": 20 }, "currency": { "description": "The virtual currency to display to end users. Determines the amount due after conversion.", "type": "string", "example": "EUR", "minLength": 2, "maxLength": 20, "x-setter-extra-annotation": "@ToUpperCase" }, "returnUrl": { "description": "The URL that the customer will be redirected to if they click **Back to Merchant** button on the payment web page. Must start with `https://`.", "type": "string", "example": "https://my-shop.com/payment-complete?ref=xyz" }, "reference": { "description": "The custom payment ID to identify the payment within your platform.", "type": "string", "example": "myUniqueRef333", "minLength": 6, "maxLength": 255 }, "customerId": { "description": "The unique ID for the party requesting the payment. If multiple payments for same party are requested, the ID should remain consistent.", "type": "string", "example": "d063635e-0f83-4e47-a1f3-fc9484df1509" }, "type": { "type": "string", "description": "Defines the payment direction. Must be `OUT` for outgoing payments.", "enum": [ "OUT" ], "example": "OUT" }, "twoStep": { "description": "Activates a payout that is accepted in two stages.\n\nWhen you create a payout, the funds are reserved, and the quote locks for one hour with the `ACCEPTED` status. Review the quote and approve the payout by calling `PUT /api/v1/pay/{uuid}/confirm/summary` without payload.", "type": "boolean", "example": true }, "fees": { "type": "object", "description": "Customer fee to be charged for the transaction.\n\nCustomer fees are optional charges that can be added only to outgoing payments for your customers. These fees are separate from the transaction amount and transaction fees, and are collected from the customer's wallet.\n\nFor more information, refer to [Customer fees](https://docs.bvnk.com/docs/charge-customer-fees#/).", "properties": { "customerFee": { "type": "object", "description": "Details of the customer fee to be applied to the transaction.", "properties": { "currency": { "type": "string", "description": "The three-letter ISO currency code of the customer fee. This should match the currency of the transaction and must have a corresponding [fee wallet configured](https://docs.bvnk.com/reference/setcustomerfeewallet#/).", "example": "EUR" }, "amount": { "type": "number", "description": "The amount of the customer fee to be charged. This is a fixed fee per transaction. Ensure the customer's wallet has sufficient funds to cover this fee in addition to the transaction amount.", "example": 1 } }, "required": [ "currency", "amount" ] } } }, "payOutDetails": { "$ref": "#/components/schemas/PayOutDetailDto" }, "complianceDetails": { "$ref": "#/components/schemas/ComplianceDetailDto" }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "embeddedCustomerDetails": { "description": "Unique customer reference. Must be in the UUID format.", "type": "object", "properties": { "reference": { "type": "string", "format": "uuid", "example": "07357926-aed0-44e1-a75b-7505557ee137" } } } }, "required": [ "walletId", "amount", "currency", "type", "reference", "customerId", "complianceDetails" ] }, "createEPMRequestDto": { "description": "The request data required to create an Embedded Partner Merchant", "type": "object", "properties": { "firstName": { "type": "string", "description": "First name of the individual.", "example": "Joe" }, "lastName": { "type": "string", "description": "Last name of the individual.", "example": "Strange" }, "emailAddress": { "type": "string", "format": "email", "description": "Email address of the individual.", "example": "joe@strange.com" }, "accountName": { "type": "string", "description": "Name of the account to be created.", "example": "The Muffin Company" }, "businessRegistrationNumber": { "type": "string", "description": "Registration number of the business.", "example": "12345678" }, "address1": { "type": "string", "description": "Primary address line.", "example": "123 Drury Lane" }, "address2": { "type": "string", "description": "Secondary address line.", "example": "Unit 1" }, "postalCode": { "type": "string", "description": "Postal code of the address.", "example": "GV7J+F3" }, "city": { "type": "string", "description": "City of the address.", "example": "London" }, "countryOfIncorporationCode": { "type": "string", "description": "Country code where the business is incorporated.", "example": "DE" }, "usageReason": { "type": "string", "description": "Reason for using an EPM account.", "example": "The usage reason" }, "externalId": { "type": "string", "format": "uuid", "description": "A unique external identifier for the entity.", "example": "4549a370-0e9f-450a-bafa-65ffbd5954f2" }, "acceptedAgreementReferences": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "List of agreement references that the entity has accepted.", "example": [ "9fc28f1a-f946-11ed-a643-027612b7f6b5" ] } }, "required": [ "firstName", "lastName", "emailAddress", "accountName", "businessRegistrationNumber", "address1", "city", "countryOfIncorporationCode", "usageReason", "externalId", "acceptedAgreementReferences" ] }, "DirectionDto": { "type": "string", "description": "Defines whether a payment in or payment out.", "example": "IN", "enum": [ "IN", "OUT" ] }, "PayInDetailDto": { "description": "The payment in details, only needed when \"type\" is IN.", "type": "object", "properties": { "currency": { "description": "Crypto currency that customer must pay in, will return that address in redirectURL. For the complete list of avaialbe currencies, see [Currencies](https://docs.bvnk.com/bvnk/references/currencies/).", "type": "string", "example": "ETH", "minLength": 2, "maxLength": 20, "x-setter-extra-annotation": "@ToUpperCase" }, "network": { "description": "Network of the cryptocurrency. We recommend using the `network` parameter instead of `protocol`.\n\nFor the complete list of available networks, see [Currencies](https://docs.bvnk.com/bvnk/references/currencies/).", "type": "string", "example": "ETHEREUM", "x-setter-extra-annotation": "@ToUpperCase" }, "protocol": { "description": "Only used for multiple protocol currencies, like USDT. Will only generate address matching the protocol and no alternatives. **Deprecated**. Use `network` instead.", "type": "string", "deprecated": true, "example": "ERC20", "minLength": 5, "maxLength": 6, "x-setter-extra-annotation": "@ToUpperCase" } }, "required": [ "currency" ] }, "PayRequestCurrencyOptionDto": { "description": "Restricts a cryptocurrency and optionally which network protocols customers may use when paying.", "type": "object", "properties": { "code": { "type": "string", "description": "Cryptocurrency code (for example, `USDT`, `ETH`).", "example": "USDT" }, "protocols": { "type": "array", "description": "When set, only these network protocols are offered for this currency (for example, `ERC20`, `TRC20`). Omit to allow any supported protocol for the currency.", "items": { "type": "string" }, "example": [ "ERC20", "TRC20" ] } }, "required": [ "code" ] }, "PayOutDetailDto": { "description": "Details of the outgoing payment, only needed when `type` is `OUT`.\n\nIf you add `PayOutDetails`, remember to specify all of its child parameters.\n\nIf not included in the request, in the response you receive `redirectUrl`: a link to a page, where to you can redirect your Customer so they can finalize the payment.", "type": "object", "properties": { "code": { "description": "Gateway to be used. Currently, only 'crypto' is supported.", "type": "string", "example": "crypto" }, "currency": { "description": "Currency code, in which the payout needs to be made.", "type": "string", "example": "ETH", "minLength": 2, "maxLength": 20, "x-setter-extra-annotation": "@ToUpperCase" }, "address": { "description": "Address to which funds will be withdrawn. If left blank, you will be redirected to the hosted page to collect the necessary details.\n\nBVNK strictly enforces the [EIP-55](https://www.binance.com/en/square/post/8436113423258) checksum standard for mixed-case Ethereum addresses in Ethereum Virtual Machine (EVM) networks. If the casing doesn't exactly match the checksum, the address is considered invalid.\n\nMake sure that the `0x` prefix is lowercase and use one of the following formats:\n\n - All uppercase: `0xCCC2D224ADDEC8AA7A54BB22C7D4AC2D8ACA91BE`\n\n- All lowercase: `0xccc2d224addec8aa7a54bb22c7d4ac2d8aca91be` ", "type": "string", "example": "0xb794f5ea0ba39494ce839613fffba74279579268" }, "tag": { "description": "Tag of the payment destination. This field must not be empty when the `paidCurrency` currency value is `XRP`.", "type": "string" }, "network": { "description": "Network of the cryptocurrency. We recommend using the `network` parameter instead of `protocol`.\n\nFor the complete list of available networks, see [Currencies](https://docs.bvnk.com/bvnk/references/currencies/).", "type": "string", "example": "ETHEREUM", "x-setter-extra-annotation": "@ToUpperCase" }, "protocol": { "description": "Only used for multiple protocol currencies, like USDT. Will only generate address matching the protocol and no alternatives. **Deprecated**. Use `network` instead.", "deprecated": true, "type": "string", "example": "ERC20", "minLength": 5, "maxLength": 6, "x-setter-extra-annotation": "@ToUpperCase" } }, "required": [ "code", "currency", "address", "network" ] }, "ComplianceDetailDto": { "description": "Specify compliance details about the payment", "type": "object", "properties": { "requesterIpAddress": { "type": "string", "example": "172.16.254.1", "description": "IPv4/IPv6 address of the requester. Required only if `countryCode` is not provided.", "maxLength": 61 }, "contactId": { "type": "string", "example": "1b083898-73ca-42ba-b433-7dc20ea67667", "description": "Identifier of the contact that takes part of the virtual asset transfer. Can be used instead of `partyDetails`.", "maxLength": 36 }, "partyDetails": { "description": "Array of compliance information of the entities that take part of the virtual asset transfer.", "type": "array", "items": { "$ref": "#/components/schemas/PartyDetailDto" } } }, "required": [ "partyDetails" ] }, "ConfirmPaymentRequestDto": { "description": "Specify confirm two-step payment details", "type": "object", "properties": { "complianceDetails": { "$ref": "#/components/schemas/ComplianceDetailDto" } } }, "PartyDetailDto": { "description": "Compliance information of the party related to the virtual asset transfer.", "oneOf": [ { "$ref": "#/components/schemas/IndividualPartyDetailDto" }, { "$ref": "#/components/schemas/CompanyPartyDetailDto" } ], "discriminator": { "propertyName": "entityType", "mapping": { "INDIVIDUAL": "#/components/schemas/IndividualPartyDetailDto", "COMPANY": "#/components/schemas/CompanyPartyDetailDto" } } }, "EntityTypeEnumDto": { "description": "Identifies whether the party detail information belongs to an INDIVIDUAL or a COMPANY", "type": "string", "enum": [ "INDIVIDUAL", "COMPANY" ] }, "IndividualPartyDetailDto": { "title": "Individual", "description": "Compliance information of the Individual related to the virtual asset transfer", "type": "object", "properties": { "type": { "description": "Identifies whether the party detail information belongs to a BENEFICIARY or an ORIGINATOR. Possible values - BENEFICIARY, ORIGINATOR", "type": "string", "example": "BENEFICIARY" }, "entityType": { "$ref": "#/components/schemas/EntityTypeEnumDto" }, "firstName": { "description": "First name of the individual (required for INDIVIDUAL entity type)", "type": "string", "example": "John" }, "lastName": { "description": "Last name of the individual (required for INDIVIDUAL entity type)", "type": "string", "example": "Doe" }, "dateOfBirth": { "description": "Date of birth of the individual", "type": "string", "example": "1984-06-30" }, "relationshipType": { "description": "Type of the relationship between the BENEFICIARY/ORIGINATOR and the creator of the payment. Possible values - SELF_OWNED, THIRD_PARTY", "type": "string", "example": "THIRD_PARTY" }, "countryCode": { "description": "The ISO 3166-1-alpha-2 code of the country that the party resides in. Required only if `requesterIpAddress` is not provided.", "type": "string", "example": "DE" }, "regionCode": { "description": "ISO 3166-2:UA code for Ukraine regions. Required only if `countryCode` is `UA`. In this case, submissions with missing or invalid `regionCode` are rejected. For all other countries, the region code is ignored.\n\nFor the complete list of codes, see [ISO_3166-2:UA](https://www.iso.org/obp/ui/#iso:code:3166:UA).", "type": "string", "format": "UA-XX", "example": "UA-46" } }, "required": [ "type", "entityType", "relationshipType", "firstName", "lastName", "dateOfBirth", "countryCode" ] }, "CompanyPartyDetailDto": { "title": "Company", "description": "Compliance information of the company related to the virtual asset transfer", "type": "object", "properties": { "type": { "description": "Identifies whether the party detail information belongs to a BENEFICIARY or an ORIGINATOR. Possible values - BENEFICIARY, ORIGINATOR", "type": "string", "example": "BENEFICIARY" }, "entityType": { "$ref": "#/components/schemas/EntityTypeEnumDto" }, "legalName": { "description": "Name of the company (required for COMPANY entity type)", "type": "string", "example": "BVNK LTD" }, "relationshipType": { "description": "Type of the relationship between the BENEFICIARY/ORIGINATOR and the creator of the payment. Possible values - SELF_OWNED, THIRD_PARTY", "type": "string", "example": "SELF_OWNED" }, "countryCode": { "description": "The ISO 3166-1-alpha-2 code of the country that the party resides in. Required only if requesterIpAddress is not provided.", "type": "string", "example": "DE" }, "regionCode": { "description": "ISO 3166-2:UA code for Ukraine regions. Required only if `countryCode` is `UA`. In this case, submissions with missing or invalid `regionCode` are rejected. For all other countries, the region code is ignored.\n\nFor the complete list of codes, see [ISO_3166-2:UA](https://www.iso.org/obp/ui/#iso:code:3166:UA).", "type": "string", "format": "UA-XX", "example": "UA-46" }, "registrationNumber": { "description": "Legal Entity identifier", "type": "string", "example": "5493001KJTIIGC8Y1R12" } }, "required": [ "type", "entityType", "relationshipType", "legalName", "registrationNumber", "countryCode" ], "example": { "type": "BENEFICIARY", "entityType": "COMPANY", "legalName": "BVNK LTD", "relationshipType": "SELF_OWNED", "countryCode": "DE", "registrationNumber": "5493001KJTIIGC8Y1R12" } }, "SummaryPaymentDto": { "description": "Contains all the information about a summary payment object returned.", "type": "object", "properties": { "uuid": { "description": "Unique identifier for the merchant payment.", "type": "string", "maxLength": 50, "example": "3A6FAFFA-F21D-416E-B17E-2529A9BC44A0" }, "merchantDisplayName": { "description": "The display name for the merchant payment.", "maxLength": 255, "type": "string", "example": "Test Merchant Name" }, "walletId": { "description": "Your wallet's ID.", "type": "string", "maxLength": 255, "example": "acc:23040543559277:x8rvQ:0" }, "dateCreated": { "description": "The date and time, encoded into UNIX epoch timestamps.", "type": "integer", "format": "int64", "example": 1566203005000 }, "expiryDate": { "description": "The date and time, encoded into UNIX epoch timestamps.", "type": "integer", "format": "int64", "example": 1566203005000 }, "quoteExpiryDate": { "description": "Expiration date and time, encoded into UNIX epoch timestamps.", "type": "integer", "format": "int64", "example": 1566203005000 }, "acceptanceExpiryDate": { "description": "Date and time, encoded into UNIX epoch timestamps.", "type": "integer", "format": "int64", "example": 1566203005000 }, "quoteStatus": { "type": "string", "maxLength": 50, "example": "ACCEPTED" }, "reference": { "description": "Custom payment reference ID to tie the payment to your customer.", "type": "string", "example": "CryptoP-333", "minLength": 6, "maxLength": 255 }, "type": { "$ref": "#/components/schemas/DirectionDto" }, "subType": { "type": "string", "description": "Payment sub type.", "example": "merchantPayIn", "maxLength": 50, "enum": [ "merchantPayIn", "merchantPayOut", "merchantRefund" ] }, "status": { "$ref": "#/components/schemas/PaymentStatusDto" }, "displayCurrency": { "$ref": "#/components/schemas/PayAmountsDto" }, "walletCurrency": { "$ref": "#/components/schemas/PayAmountsDto" }, "paidCurrency": { "$ref": "#/components/schemas/PayAmountsDto" }, "feeCurrency": { "$ref": "#/components/schemas/PayAmountsDto" }, "displayRate": { "$ref": "#/components/schemas/ExchangeRateDto" }, "exchangeRate": { "$ref": "#/components/schemas/ExchangeRateDto" }, "address": { "$ref": "#/components/schemas/CryptoAddressDto" }, "returnUrl": { "description": "The URL that the customer will be redirected to if they click 'Back to Merchant' button on the payment web page.", "type": "string", "example": "https://my-shop.com/payment-complete?ref=xyz" }, "redirectUrl": { "description": "The URL to the payment page that you redirect your customers to.", "type": "string", "example": "https://pay.bvnk.com/payin?uuid=3A6FAFFA-F21D-416E-B17E-2529A9BC44A0" }, "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/GatewayTransactionDto" } }, "refund": { "description": "The payment this object is a refund of. This should reference the pay in that this refund was created for.", "type": "object" }, "refunds": { "description": "Refunds that have been requested for this payment. This should reference the refund payout for this pay in.", "type": "array", "items": { "type": "object" } }, "currencyOptions": { "$ref": "#/components/schemas/currencyOptions" }, "networkFeeCurrency": { "type": "object", "description": "Details of the network fee currency.", "properties": { "currency": { "type": "string", "description": "The currency code for the network fee.", "example": "EUR" }, "amount": { "type": "number", "description": "The network fee amount.", "example": 1 }, "actual": { "type": "number", "description": "The actual network fee amount charged.", "example": 0 } } }, "flow": { "type": "string", "example": "DEFAULT" } } }, "PaymentStatusDto": { "type": "string", "description": "The payment status.", "example": "PENDING", "enum": [ "PENDING", "PROCESSING", "CANCELLED", "COMPLETE", "UNDERPAID", "OVERPAID", "EXPIRED" ] }, "PayAmountsDto": { "description": "Contains the type of currency, amount to be paid, and amount received.", "type": "object", "properties": { "currency": { "description": "The currency acronym.", "type": "string", "example": "ETH" }, "amount": { "description": "The amount to be paid.", "type": "number", "example": 0 }, "actual": { "description": "The actual amount received.", "type": "number", "example": 76.45 } } }, "ExchangeRateDto": { "description": "Contains exchange rate information to convert from base currency to counter currency.", "type": "object", "properties": { "base": { "description": "The base currency acronym.", "type": "string", "example": "ETH" }, "counter": { "description": "The counter currency acronym.", "type": "string", "example": "EUR" }, "rate": { "description": "The exchange rate", "type": "number", "example": 1680.1 } } }, "CryptoAddressDto": { "description": "Payment address details", "type": "object", "properties": { "address": { "description": "The crypto address to send funds to", "type": "string", "example": "0xb794f5ea0ba39494ce839613fffba74279579268" }, "tag": { "description": "This is a payment destination tag. This fields isn't null when the paidCurrency currency value is XRP.", "type": "string", "example": "" }, "network": { "description": "The network of the address.\n\nWe recommend using the `network` parameter instead of `protocol`.", "type": "string", "example": "ETHEREUM" }, "protocol": { "description": "The protocol behind a currency, 'ERC20' or 'TRC20'. **Deprecated**. Use `network` instead.", "type": "string", "example": "ERC20", "deprecated": true }, "uri": { "description": "The destination address URI for QR code", "type": "string", "example": "ethereum:0xABCDabcdABcDabcDaBCDAbcdABcdAbCdABcDABCd?value=1.1e18" }, "alternatives": { "description": "The list of non-default addresses for other tokens", "type": "array", "items": { "$ref": "#/components/schemas/AlternativeAddressDto" } } } }, "AlternativeAddressDto": { "type": "object", "description": "The list of non-default addresses for other tokens.", "properties": { "network": { "description": "The network of the alternative address.\n\nWe recommend using the `network` parameter instead of `protocol`.", "type": "string", "example": "POLYGON" }, "protocol": { "description": "The protocol behind a currency. Matches currency for native tokens. **Deprecated**. Use `network` instead.", "type": "string", "example": "POLYGON", "deprecated": true }, "address": { "description": "The crypto address to send funds to.", "type": "string", "example": "0x101bfbc5018b777cb531aa9d68511b96d800b9c6" }, "tag": { "description": "This is a payment destination tag. This fields isn't null when the paidCurrency currency value is XRP.", "type": "string", "example": "null" }, "uri": { "description": "The destination address URI for QR code", "type": "string", "example": "polygon:0xA512f02EEa71580CBB7B5C3017F1f80A365f8329" } } }, "GatewayTransactionDto": { "description": "The specific details about transactions, onchain or offchain, linked to the payment.", "type": "object", "properties": { "dateCreated": { "type": "integer", "description": "The date and time, encoded into UNIX epoch timestamps.", "format": "int64", "example": 1566203005000 }, "dateConfirmed": { "type": "integer", "description": "The date and time, encoded into UNIX epoch timestamps.", "format": "int64", "example": 1566203005000 }, "hash": { "description": "Transaction hash.", "type": "string" }, "amount": { "description": "Payment amount.", "type": "number", "example": 100 }, "risk": { "type": "object" }, "networkFeeCurrency": { "description": "The currency acronym.", "type": "string", "example": "BTC" }, "networkFeeAmount": { "description": "The network fee amount.", "type": "number", "example": 1.05 }, "sources": { "description": "The list of source addresses, only applicable if payment in.", "type": "array", "items": { "type": "string", "example": "0xb794f5ea0ba39494ce839613fffba74279579268" } }, "displayRate": { "$ref": "#/components/schemas/ExchangeRateDto" }, "exchangeRate": { "$ref": "#/components/schemas/ExchangeRateDto" } } }, "ClientValidationErrorDto": { "description": "List of validation errors", "properties": { "errorList": { "type": "array", "items": { "$ref": "#/components/schemas/ValidationErrorDto" } } } }, "ValidationErrorDto": { "description": "Error object shared when an exception or error is encountered", "properties": { "code": { "description": "this is used to get internationalisation translation", "type": "string" }, "parameter": { "description": "input that is causing the error", "type": "string" }, "message": { "description": "exception message", "type": "string" } }, "required": [ "parameter", "code", "message" ] }, "AccountsValidationErrorDto": { "description": "Error object shared when an exception or error is encountered", "properties": { "code": { "description": "this is used to get internationalisation translation", "type": "string" }, "status": { "description": "this is the error status", "type": "string" }, "message": { "description": "exception message", "type": "string" }, "details": { "description": "input that is causing the error", "type": "object", "properties": { "documentLink": { "description": "optional link to error document", "type": "string" }, "errors": { "description": "List of parameter errors that need to be corrected", "type": "object" } } } }, "required": [ "status", "code", "message", "details" ] }, "ServerErrorDto": { "description": "Error object shared when an exception or error is encountered", "type": "object", "properties": { "code": { "description": "this is used to get internationalisation translation", "type": "string" }, "status": { "description": "this is the error status or definition", "type": "string" }, "message": { "description": "exception message", "type": "string" }, "documentLink": { "description": "optional link to error document", "type": "string" } }, "required": [ "code", "message" ] }, "AccountsServerErrorDto": { "description": "Error object shared when an exception or error is encountered", "type": "object", "properties": { "code": { "description": "this is used to get internationalisation translation", "type": "string" }, "status": { "description": "this is the error status or definition", "type": "string" }, "message": { "description": "exception message", "type": "string" }, "details": { "description": "optional link to error document", "type": "object", "properties": { "documentLink": { "description": "optional link to error document", "type": "string" } } } }, "required": [ "code", "message" ] }, "MerchantChannelRequestDto": { "type": "object", "required": [ "walletId", "payCurrency", "displayCurrency", "reference", "customerId", "complianceDetails" ], "properties": { "walletId": { "type": "string", "description": "Merchant ID is deprecated. Use `walletId` instead.\n\nUnique identifier of the wallet used in the operation.", "example": "0a12a214-1619-43fa-9be1-0029f6a440a0" }, "payCurrency": { "type": "string", "description": "The cryptocurrency code that the channel will operate on.", "example": "ETH" }, "displayCurrency": { "type": "string", "description": "The currency which pricing will be displayed to the end user in, can be the same as payCurrency, or can be different.", "example": "EUR" }, "reference": { "type": "string", "description": "An external reference for the channel that your customer will see.", "example": "c1b933d5-3354-4f83-a05f-0b53f1be85f2" }, "customerId": { "description": "Uniquely identifying the party requesting the payment. If multiple payments for same party are requested, the ID should remain consistent.", "type": "string", "example": "d063635e-0f83-4e47-a1f3-fc9484df1509" }, "complianceDetails": { "$ref": "#/components/schemas/ComplianceDetailDto" } }, "example": { "walletId": "a:24092328494070:G5i4XZ9:1", "payCurrency": "ETH", "displayCurrency": "EUR", "reference": "c1b933d5-3354-4f83-a05f-0b53f1be85f2", "customerId": "d063635e-0f83-4e47-a1f3-fc9484df1509", "complianceDetails": { "requesterIpAddress": "172.16.254.1", "partyDetails": [ { "entityType": "INDIVIDUAL", "type": "BENEFICIARY", "firstName": "John", "lastName": "Doe", "dateOfBirth": "1984-06-30", "relationshipType": "THIRD_PARTY", "countryCode": "DE", "regionCode": "null" } ] } } }, "MerchantChannelDto": { "type": "object", "properties": { "id": { "type": "integer", "description": "The UUID of the channel.", "example": 59157 }, "dateCreated": { "type": "integer", "description": "The date and time, encoded into UNIX epoch timestamps.", "example": 1631619193321 }, "lastUpdated": { "type": "integer", "description": "The date and time, encoded into UNIX epoch timestamps.", "example": 1631619193321 }, "merchantId": { "type": "string", "description": "The merchant ID linked to the channel.", "example": "0a12a214-1619-43fa-9be1-0029f6a440a0" }, "walletCurrency": { "type": "string", "description": "The wallet currency of the channel.", "example": "EUR" }, "displayCurrency": { "type": "string", "description": "The display currency of the channel.", "example": "EUR" }, "payCurrency": { "type": "string", "description": "The payed currency of the channel.", "example": "USDC" }, "address": { "type": "string", "description": "The address of the channel", "example": "0x225c8e46493f603e4577ab059c9fb38bb70475ba" }, "tag": { "type": "string", "description": "The tag for payments", "example": null }, "network": { "type": "string", "description": "The network of the channel.\n\nWe recommend using the `network` parameter instead of `protocol`.", "example": "ETHEREUM" }, "protocol": { "type": "string", "description": "The protocol of the channel. **Deprecated**. Use `network` instead.", "deprecated": true, "example": "ERC20" }, "reference": { "type": "string", "description": "The custom reference for the channel payment.", "example": "c1b933d5-3354-4f83-a05f-0b53f1be85f2" }, "status": { "type": "string", "description": "The status of the channel.", "enum": [ "OPEN" ] }, "uuid": { "type": "string", "description": "The UUID of the channel.", "example": "9d1f67f2-a647-404b-9b02-247c77be81d0" }, "redirectUrl": { "type": "string", "description": "The redirect URL to the channel payment page.", "example": "https://pay.sandbox.bvnk.com/channel?uuid=9d1f67f2-a647-404b-9b02-247c77be81d0" }, "uri": { "type": "string", "description": "The URI of the address for QR code", "example": "ethereum:0xb4e8bb9918248007dc9d0dc12ae1142f0d62ef0e" }, "alternatives": { "type": "array", "items": { "$ref": "#/components/schemas/AlternativeAddressDto" }, "example": [ { "network": "SOLANA", "protocol": "SOL", "address": "Cg41CUBFVMGodMowefNQEmYLZyiJm5fh1QkGbV441c48", "tag": null, "uri": "solana:4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU/transfer?address=Cg41CUBFVMGodMowefNQEmYLZyiJm5fh1QkGbV441c48" }, { "network": "ARBITRUM", "protocol": "ARBITRUM", "address": "0xdaf97c16cfb25430638346adcaeb9385b86ef8a8", "tag": null, "uri": "arbitrum:0x548e21c12e84d43ce8aca9990597e6a3bf61e114/transfer?address=0xdaf97c16cfb25430638346adcaeb9385b86ef8a8" } ] }, "walletId": { "type": "string", "description": "Unique identifier of the wallet used in the operation.", "example": "a:25080425672469:LoaFAwD:1" }, "walletDescription": { "type": "string", "description": "Human-readable description of the wallet used for the channel.", "example": "USDC Omni Wallet" }, "pegged": { "type": "boolean", "description": "Indicates whether the pay currency is a pegged stablecoin (e.g., USDC, USDT) that maintains a fixed value relative to a fiat currency. Set to `true` for stablecoins, `false` for volatile cryptocurrencies like BTC or ETH.", "example": false }, "accountReference": { "type": "string", "description": "Unique identifier linking the channel to a specific account or entity within your system. Enables tracking and reconciliation of transactions across multiple channels belonging to the same account or customer relationship.", "example": "b0cb95a5-66a5-4d2d-9b12-f500daf1f1fd" }, "contact": { "type": "object", "description": "Contact information associated with the channel.", "properties": { "id": { "type": "string", "example": "9b9dab06-31ea-4acb-897c-e50c0e2d785f" }, "name": { "type": "string", "example": "John Doe" }, "description": { "type": "string", "nullable": true, "example": null }, "relationshipType": { "type": "string", "example": "THIRD_PARTY" }, "entity": { "type": "object", "properties": { "externalId": { "type": "string", "example": "4a06d2bb-c321-4ee3-a9e6-d3598c021db1" }, "firstName": { "type": "string", "example": "John" }, "middleName": { "type": "string", "nullable": true, "example": null }, "lastName": { "type": "string", "example": "Doe" }, "dateOfBirth": { "type": "string", "example": "30-06-1984" }, "address": { "type": "object", "properties": { "addressLine1": { "type": "string", "nullable": true, "example": null }, "addressLine2": { "type": "string", "nullable": true, "example": null }, "region": { "type": "string", "nullable": true, "example": null }, "city": { "type": "string", "nullable": true, "example": null }, "country": { "type": "string", "example": "DE" }, "postCode": { "type": "string", "nullable": true, "example": null } } }, "category": { "type": "string", "example": "INTERNAL" }, "type": { "type": "string", "example": "INDIVIDUAL" } } }, "updatedAt": { "type": "string", "format": "date-time", "example": "2026-02-23T10:26:34.979Z" }, "createdAt": { "type": "string", "format": "date-time", "example": "2026-02-23T10:26:34.979Z" } } } } }, "MerchantChannelPaymentDto": { "type": "object", "properties": { "channelId": { "type": "string", "description": "The ID of the channel.", "example": "9d1f67f2-a647-404b-9b02-247c77be81d0" }, "merchantId": { "type": "string", "description": "The merchant ID linked to channel.", "example": "0a12a214-1619-43fa-9be1-0029f6a440a0" }, "merchantDisplayName": { "type": "string", "description": "The display name fo the merchant.", "example": "Merchant A" }, "reference": { "type": "string", "description": "The unique reference of the channel.", "example": "c1b933d5-3354-4f83-a05f-0b53f1be85f2" }, "dateCreated": { "type": "integer", "format": "int64", "description": "The date and time, encoded into UNIX epoch timestamps.", "example": 1631619489000 }, "lastUpdated": { "type": "integer", "format": "int64", "description": "The date and time, encoded into UNIX epoch timestamps.", "example": 1631619562000 }, "status": { "type": "string", "description": "The status of the channel payment.", "example": "COMPLETE", "enum": [ "DETECTED", "COMPLETE", "HELD", "CANCELLED" ] }, "uuid": { "type": "string", "description": "The uuid fo the channel payment.", "example": "c0dc9c14-0312-4a6b-a1a3-a6dcebdcc8a4" }, "hash": { "type": "string", "description": "The transaction hash of the channel payment.", "example": "0x152f2b3a3650a3e2e132abca0f81421c552ae14bc8466fac16889e8d32b3fd6a" }, "address": { "type": "string", "description": "The address of the channel.", "example": "0xb4e8bb9918248007dc9d0dc12ae1142f0d62ef0e" }, "tag": { "type": "string", "description": "The tag of the channel.", "example": null }, "paidCurrency": { "type": "string", "description": "The currency of the payment.", "example": "ETH" }, "displayCurrency": { "type": "string", "description": "The display currency of the channel.", "example": "JPY" }, "walletCurrency": { "type": "string", "description": "The currency of the wallet linked to the channel.", "example": "EUR" }, "feeCurrency": { "type": "string", "description": "The currency of the fee taken.", "example": "EUR" }, "paidAmount": { "type": "number", "description": "The amount paid to the channel.", "example": 0.01 }, "displayAmount": { "type": "number", "description": "The amount displayed of the channel payment.", "example": 3592.27 }, "walletAmount": { "type": "number", "description": "The amount converted to the wallet linked to the channel.", "example": 27.62 }, "feeAmount": { "type": "number", "description": "The amount of the fee taken.", "example": 0.27 }, "exchangeRate": { "$ref": "#/components/schemas/ExchangeRateDto" }, "displayRate": { "$ref": "#/components/schemas/ExchangeRateDto" }, "risk": { "type": "object", "deprecated": true, "properties": { "level": { "type": "string", "example": "UNKNOWN" }, "resourceName": { "type": "string", "example": "UNKNOWN" }, "resourceCategory": { "type": "string", "example": "UNKNOWN" }, "alerts": { "type": "array", "items": {}, "example": [] } } }, "sources": { "type": "array", "description": "The address source of the payment.", "items": { "type": "string" } }, "networkFee": { "$ref": "#/components/schemas/NetworkFeeDto" } } }, "NetworkFeeDto": { "type": "object", "properties": { "paidCurrency": { "type": "string" }, "paidAmount": { "type": "number" }, "displayCurrency": { "type": "string" }, "displayAmount": { "type": "number" } } }, "UnifiedPayoutRequest": { "type": "object", "required": [ "walletId", "amount", "paymentReference", "instruction" ], "properties": { "walletId": { "type": "string", "description": "Your debit wallet ID associated with the transaction.", "example": "a:24092328494070:G5i4XZ9:1" }, "amount": { "$ref": "#/components/schemas/Money" }, "paymentReference": { "type": "string", "description": "Custom identifier supplied for a transaction. It is used to link a transaction to a specific customer or use case.\nNote that the value is visible to the beneficiary. \nOnly whitespaces, alphanumeric characters (a-z, A-Z, 0-9), commas (,) and periods (.).\n\nFor `ACH` and `ACH_SAME_DAY` payouts, the value must have a maximum length of 10 characters.", "minLength": 5, "maxLength": 34, "pattern": "^[A-Za-z0-9.,\\-\\s]{5,140}$" }, "instruction": { "type": "object", "required": [ "type", "beneficiary" ], "properties": { "type": { "type": "string", "enum": [ "FIAT" ], "description": "The type of the instruction. Currently only 'FIAT' is supported." }, "paymentMethod": { "type": "string", "description": "Payment method when sending out of USA.\n\nIf you request an ACH Same Day payout outside its available window, it will be process as a next-day payout. However, the ACH Same Day fee may still be incurred.\n\nWhen `EUR` is set in `amount.currency`, you can select the following `paymentMethod` in `instruction`:\n\n- `SEPA_CT`: Standard SEPA bank transfer. Payment processing time is 1-2 business days.\n\n- `SEPA_INST`: Instant bank transfer. Funds arrive in seconds, 24/7. May incur a small fee.", "enum": [ "ACH", "ACH_SAME_DAY", "SEPA_CT", "SEPA_INST", "FEDWIRE", "RTP", "FEDNOW" ] }, "beneficiary": { "type": "object", "properties": { "details": { "$ref": "#/components/schemas/PayoutBeneficiaryDetails" } } } } }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "requestDetails": { "$ref": "#/components/schemas/RequestDetails" } }, "example": { "walletId": "a:24092328494070:G5i4XZ9:1", "amount": { "value": 1000, "currency": "USD" }, "paymentReference": "Payment for invoice 12345", "instruction": { "type": "FIAT", "paymentMethod": "ACH", "beneficiary": { "details": { "beneficiaryType": "SELF_OWNED", "transferDestination": "LOCAL", "currency": "USD", "individualDetails": { "firstName": "John", "lastName": "Doe", "dateOfBirth": "01/01/1980" }, "address": { "addressLine1": "123 Main St", "addressLine2": "Apt 4B", "region": "California", "city": "Los Angeles", "country": "US", "postCode": "90001" }, "bankDetails": { "accountNumber": "1234567890", "code": "ABC123", "address": { "addressLine1": "123 Main St", "addressLine2": "Apt 4B", "region": "California", "city": "Los Angeles", "country": "US", "postCode": "90001" }, "accountType": "SAVINGS", "bankTypeIdentifier": "SWIFT", "intermediaryBanks": [ { "name": "Intermediary Bank 1", "accountNumber": "0987654321", "code": "XYZ987" } ] } } } }, "metadata": { "source": "api", "merchantId": "merchant-123" }, "requestDetails": { "originator": { "ipAddress": "192.168.1.1" } } } }, "UnifiedPayoutResponse": { "type": "object", "properties": { "transactionReference": { "type": "string", "format": "uuid", "description": "Unique identifier for the transaction.", "example": "123e4567-e89b-12d3-a456-426614174000" }, "paymentReference": { "type": "string", "description": "Unique payment reference used to link a transaction to a specific customer or use case.\n\nThe value is visible to the beneficiary." }, "amount": { "$ref": "#/components/schemas/Money" }, "fee": { "$ref": "#/components/schemas/Money" }, "walletId": { "type": "string", "description": "Identifier for your debit wallet associated with the transaction." }, "status": { "type": "string", "description": "The status of the transaction.\n\n The PENDING_APPROVAL status is only relevant for **fiat payouts**.", "enum": [ "PENDING_APPROVAL", "PROCESSING", "COMPLETED", "FAILED", "CANCELLED", "RETURNED", "ON_HOLD" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the transaction was created." }, "details": { "$ref": "#/components/schemas/UnifiedPayoutDetails" }, "metadata": { "$ref": "#/components/schemas/Metadata" } }, "example": { "transactionReference": "123e4567-e89b-12d3-a456-426614174000", "paymentReference": "Invoice #12345", "amount": { "value": 1000, "currency": "USD" }, "fee": { "value": 10, "currency": "USD" }, "walletId": "a:24092328494070:G5i4XZ9:1", "status": "PROCESSING", "createdAt": "2024-09-26T14:30:00Z", "details": { "type": "FIAT", "beneficiary": { "entityType": "COMPANY", "companyDetails": { "name": "Doe Corp" }, "address": { "addressLine1": "123 Bank St", "addressLine2": "Suite 500", "region": "New York", "city": "New York", "countryCode": "US", "postCode": "10001", "fullAddress": "123 Bank St Suite 500" }, "bankAccount": { "format": "IBAN", "bankName": "ABC Bank", "accountNumber": "GB29MDTR60000131926819", "bankCode": "MDTRGB2L", "bankAddress": { "addressLine1": "123 Bank St", "addressLine2": "Suite 500", "region": "New York", "city": "New York", "countryCode": "US", "postCode": "10001", "fullAddress": "123 Bank St Suite 500" } }, "correspondentBic": "ABCDEF12" } }, "metadata": { "source": "api", "merchantId": "merchant-123" } } }, "Money": { "type": "object", "required": [ "value", "currency" ], "properties": { "value": { "type": "number", "format": "float", "description": "Transfer amount in major currency units." }, "currency": { "$ref": "#/components/schemas/FiatCurrencyCode" } }, "example": { "value": 100.5, "currency": "USD" } }, "MoneyFeeV2": { "type": "object", "required": [ "amount", "currency" ], "properties": { "amount": { "type": "number", "description": "Fee amount in fiat or crypto currency units." }, "currency": { "type": "string", "description": "Currency code. Supports both fiat (ISO-4217) and cryptocurrencies." } }, "example": { "amount": 100.5, "currency": "USD" } }, "FiatCurrencyCode": { "type": "string", "description": "Three-letter ISO-4217 currency code.", "enum": [ "USD", "EUR", "GBP" ], "example": "EUR" }, "BlockchainNetwork": { "type": "string", "description": "Blockchain network.", "enum": [ "TRON", "ETHEREUM", "LITECOIN", "BITCOIN", "RIPPLE", "DOGECOIN", "SOLANA", "ALGORAND", "CARDANO", "BINANCE", "POLYGON", "BITCOIN_CASH" ] }, "SortOrder": { "type": "string", "description": "Ordering direction.", "enum": [ "asc", "desc" ] }, "UnifiedPayoutDetails": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "FIAT", "CRYPTO" ], "description": "Type of the payout." }, "beneficiary": { "properties": { "entityType": { "type": "string", "enum": [ "INDIVIDUAL", "COMPANY" ], "description": "The type of entity, either INDIVIDUAL or COMPANY." }, "companyDetails": { "$ref": "#/components/schemas/CompanyDetails" }, "individualDetails": { "$ref": "#/components/schemas/IndividualDetails" }, "address": { "type": "object", "properties": { "addressLine1": { "type": "string", "description": "Recipient's primary address line." }, "addressLine2": { "type": "string", "description": "Recipient's secondary address line." }, "region": { "type": "string", "description": "State or region of the address." }, "city": { "type": "string", "description": "City of the recipient's address." }, "countryCode": { "type": "string", "description": "Country code of the recipient's address." }, "postCode": { "type": "string", "description": "Postal or ZIP code of the recipient's address." }, "fullAddress": { "type": "string", "description": "Full address." } }, "description": "Address of the recipient." }, "bankAccount": { "$ref": "#/components/schemas/BankAccount" }, "correspondentBic": { "type": "string", "description": "Correspondent bank BIC code.", "example": "ABCDEF12" } } } }, "example": { "type": "FIAT", "beneficiary": { "entityType": "COMPANY", "companyDetails": { "name": "Doe Corp" }, "address": { "addressLine1": "123 Bank St", "addressLine2": "Suite 500", "region": "New York", "city": "New York", "countryCode": "US", "postCode": "10001", "fullAddress": "123 Bank St Suite 500" }, "bankAccount": { "format": "IBAN", "bankName": "ABC Bank", "accountNumber": "GB29MDTR60000131926819", "bankCode": "MDTRGB2L", "bankAddress": { "addressLine1": "123 Bank St", "addressLine2": "Suite 500", "region": "New York", "city": "New York", "countryCode": "US", "postCode": "10001", "fullAddress": "123 Bank St Suite 500" } }, "correspondentBic": "ABCDEF12" } } }, "CreateTransferRequest": { "type": "object", "required": [ "walletId", "amount", "paymentReference", "instruction" ], "properties": { "walletId": { "type": "string", "description": "Identifier for the debit wallet associated with the transaction.", "example": "a:24092328494070:G5i4XZ9:1" }, "amount": { "$ref": "#/components/schemas/Money" }, "paymentReference": { "type": "string", "description": "Custom identifier supplied for a transaction. It is used to link a transaction to a specific customer or use case.\nNote that the value is visible to the beneficiary. \nOnly whitespaces, alphanumeric characters (a-z, A-Z, 0-9), commas (,) and periods (.).", "minLength": 5, "maxLength": 140, "pattern": "^[A-Za-z0-9.,\\s]{5,140}$" }, "instruction": { "type": "object", "required": [ "type", "beneficiaryWalletId" ], "properties": { "type": { "type": "string", "enum": [ "FIAT" ], "description": "The type of the instruction. Currently only 'FIAT' is supported." }, "beneficiaryWalletId": { "type": "string", "description": "Identifier for the credit wallet associated with the transaction." } } }, "metadata": { "$ref": "#/components/schemas/Metadata" } }, "example": { "walletId": "a:24092328494070:G5i4XZ9:1", "amount": { "value": 700, "currency": "USD" }, "paymentReference": "Payment for invoice 12345", "instruction": { "type": "FIAT", "beneficiary": { "walletId": "a:87333266494070:G5i9AT9:1" } }, "metadata": { "source": "api", "merchantId": "merchant-123" } } }, "CreateTransferResponse": { "type": "object", "required": [ "transactionReference", "fee" ], "properties": { "transactionReference": { "type": "string", "format": "uuid", "description": "Unique identifier for the transaction." }, "fee": { "$ref": "#/components/schemas/Money" } }, "example": { "transactionReference": "123e4567-e89b-12d3-a456-426614174000", "fee": { "value": 10, "currency": "USD" } } }, "TransferResponse": { "type": "object", "properties": { "transactionReference": { "type": "string", "format": "uuid", "description": "Unique identifier for the transaction.", "example": "123e4567-e89b-12d3-a456-426614174000" }, "paymentReference": { "type": "string", "description": "Optional payment reference." }, "amount": { "$ref": "#/components/schemas/Money" }, "fee": { "$ref": "#/components/schemas/Money" }, "walletId": { "type": "string", "description": "Identifier for the debit wallet associated with the transaction." }, "status": { "type": "string", "description": "The status of the transaction.", "enum": [ "PENDING", "COMPLETED", "FAILED", "REJECTED" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "Timestamp when the transaction was created." }, "details": { "$ref": "#/components/schemas/TransferDetails" }, "metadata": { "$ref": "#/components/schemas/Metadata" } }, "example": { "transactionReference": "123e4567-e89b-12d3-a456-426614174000", "paymentReference": "Invoice #12345", "amount": { "value": 1000, "currency": "USD" }, "fee": { "value": 10, "currency": "USD" }, "walletId": "a:24092328494070:G5i4XZ9:1", "status": "PROCESSING", "createdAt": "2024-09-26T14:30:00Z", "details": { "type": "WALLET", "beneficiary": { "entityType": "COMPANY", "companyDetails": { "name": "Doe Corp" }, "address": { "addressLine1": "123 Bank St", "addressLine2": "Suite 500", "region": "New York", "city": "New York", "countryCode": "US", "postCode": "10001" }, "walletId": "a:24092328494070:G5i4XZ9:1" } }, "metadata": { "source": "api", "merchantId": "merchant-123" } } }, "TransferDetails": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "WALLET" ], "description": "The type of the transfer. Currently only 'FIAT' is supported." }, "beneficiary": { "properties": { "entityType": { "type": "string", "enum": [ "INDIVIDUAL", "COMPANY" ], "description": "The type of entity, either INDIVIDUAL or COMPANY." }, "companyDetails": { "$ref": "#/components/schemas/CompanyDetails" }, "individualDetails": { "$ref": "#/components/schemas/IndividualDetails" }, "address": { "type": "object", "properties": { "addressLine1": { "type": "string", "description": "Primary address line." }, "addressLine2": { "type": "string", "description": "Secondary address line." }, "region": { "type": "string", "description": "State or region of the address." }, "city": { "type": "string", "description": "City of the address." }, "countryCode": { "type": "string", "description": "Country code." }, "postCode": { "type": "string", "description": "Postal or ZIP code of the address." } }, "description": "Address of the bank." }, "walletId": { "type": "string", "description": "Beneficiary wallet ID.", "example": "a:24092328494070:G5i4XZ9:1" } }, "description": "Beneficiary details." } }, "example": { "type": "WALLET", "beneficiary": { "entityType": "COMPANY", "companyDetails": { "name": "Doe Corp" }, "address": { "addressLine1": "123 Bank St", "addressLine2": "Suite 500", "region": "New York", "city": "New York", "countryCode": "US", "postCode": "10001" }, "walletId": "a:24092328494070:G5i4XZ9:1" } } }, "TransferBeneficiaryResponse": { "type": "object", "properties": { "walletId": { "type": "string", "description": "The unique identifier of the wallet." }, "name": { "type": "string", "description": "Name of the wallet." }, "balance": { "$ref": "#/components/schemas/Money" }, "walletType": { "type": "string", "description": "The type of the wallet", "enum": [ "CUSTOMER", "MAIN" ] } }, "example": { "walletId": "a:24092328494070:G5i4XZ9:1", "name": "some description", "balance": { "value": 1000, "currency": "USD" }, "walletType": "MAIN" } }, "BankAccount": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "SCAN", "IBAN", "SWIFT", "ABA", "CUBIX" ], "description": "Format of the bank account number." }, "bankName": { "type": "string", "description": "Name of the bank associated with the account." }, "accountNumber": { "type": "string", "description": "Bank account number." }, "bankCode": { "type": "string", "description": "Bank or branch SWIFT/BIC code." }, "bankAddress": { "type": "object", "properties": { "addressLine1": { "type": "string", "description": "Primary address line." }, "addressLine2": { "type": "string", "description": "Secondary address line." }, "region": { "type": "string", "description": "State or region of the address." }, "city": { "type": "string", "description": "City of the address." }, "countryCode": { "type": "string", "description": "Country code." }, "postCode": { "type": "string", "description": "Postal or ZIP code of the address." }, "fullAddress": { "type": "string", "description": "Full address." } }, "description": "Address of the bank." } }, "example": { "format": "IBAN", "bankName": "ABC Bank", "accountNumber": "GB29MDTR60000131926819", "bankCode": "MDTRGB2L", "bankAddress": { "addressLine1": "123 Bank St", "addressLine2": "Suite 500", "region": "New York", "city": "New York", "countryCode": "US", "postCode": "10001", "fullAddress": "123 Bank St Suite 500" } } }, "PayoutBeneficiaryDetails": { "type": "object", "required": [ "beneficiaryType", "transferDestination", "currency", "address", "bankDetails" ], "properties": { "beneficiaryType": { "type": "string", "enum": [ "SELF_OWNED", "THIRD_PARTY" ], "description": "Type of the beneficiary." }, "transferDestination": { "type": "string", "enum": [ "INTERNATIONAL", "LOCAL" ], "description": "Transfer destination of the beneficiary.\n\n- `LOCAL` for GBP (FPS), EUR (SEPA/SEPA Instant), and USD (ACH, ACH_SAME_DAY, and Fedwire).\n\n- `INTERNATIONAL` for GBP, EUR, and USD via SWIFT.", "example": "INTERNATIONAL" }, "currency": { "type": "string", "description": "Currency code for the beneficiary.", "enum": [ "USD", "EUR", "GBP" ], "example": "USD" }, "individualDetails": { "$ref": "#/components/schemas/IndividualDetails" }, "businessDetails": { "type": "object", "required": [ "businessName" ], "properties": { "businessName": { "type": "string", "description": "Name of the recipient's business.", "example": "Corvo Container Corporation" }, "companyRegistrationNumber": { "type": "string", "description": "Registration number of the business." } } }, "address": { "$ref": "#/components/schemas/Address" }, "bankDetails": { "$ref": "#/components/schemas/BankDetails" } }, "example": { "beneficiaryType": "SELF_OWNED", "transferDestination": "LOCAL", "currency": "USD", "individualDetails": { "firstName": "John", "lastName": "Doe", "dateOfBirth": "01/01/1980" }, "address": { "addressLine1": "123 Main St", "addressLine2": "Apt 4B", "region": "California", "city": "Los Angeles", "country": "US", "postCode": "90001" }, "bankDetails": { "accountNumber": "1234567890", "code": "ABC123", "accountType": "SAVINGS", "bankTypeIdentifier": "SWIFT", "intermediaryBanks": [ { "name": "Intermediary Bank 1", "accountNumber": "0987654321", "code": "XYZ987" } ] } } }, "IndividualDetails": { "type": "object", "required": [ "firstName", "lastName", "dateOfBirth" ], "properties": { "firstName": { "type": "string", "description": "First name of the individual." }, "lastName": { "type": "string", "description": "Last name of the individual." }, "dateOfBirth": { "type": "string", "pattern": "^\\d{2}/\\d{2}/\\d{4}$", "description": "Date of birth in the 'dd/MM/yyyy' format." } }, "example": { "firstName": "John", "lastName": "Doe", "dateOfBirth": "01/01/1980" } }, "CompanyDetails": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Name of the company." } }, "description": "Details of the company", "example": { "name": "John" } }, "BeneficiaryAddress": { "type": "object", "description": "Address of the beneficiary. May be required or optional depending on payment methods and currencies, as banking partners have different requirements. For example, the following `address` fields are mandatory if you provide specific methods:\n\n - USD LOCAL: `addressLine1`, `city`, `postCode`, `region`\n\n - SWIFT: `addressLine1`, `city`, `postCode`, `country`\n\n - EUR EASY_EP: `address.country`\n\n- SEPA transfers outside EEA: `address.country`\n\nThe `address` is optional for the following cases:\n\n- SEPA transfer within EEA\n\n - GBP and EUR LOCAL", "required": [ "country" ], "properties": { "addressLine1": { "type": "string", "description": "Recipient's primary address line.", "maxLength": 35 }, "addressLine2": { "type": "string", "description": "Recipient's secondary address line.", "maxLength": 35 }, "region": { "type": "string", "description": "Recipient's state or region of the address." }, "city": { "type": "string", "description": "Recipient's city of the address." }, "country": { "type": "string", "description": "Recipient's two-letter country code in the ISO 3166-1 alpha-2 format." }, "postCode": { "type": "string", "description": "Postal or ZIP code of the recipient's address." } }, "example": { "addressLine1": "123 Main St", "addressLine2": "Apt 4B", "region": "California", "city": "Los Angeles", "country": "US", "postCode": "90001" } }, "Address": { "type": "object", "required": [ "country" ], "properties": { "addressLine1": { "type": "string", "description": "Recipient's primary address line.", "maxLength": 35 }, "addressLine2": { "type": "string", "description": "Recipient's secondary address line.", "maxLength": 35 }, "region": { "type": "string", "description": "Recipient's state or region of the address." }, "city": { "type": "string", "description": "Recipient's city of the address." }, "country": { "type": "string", "description": "Recipient's country code." }, "postCode": { "type": "string", "description": "Postal or ZIP code of the recipient's address." } }, "example": { "addressLine1": "123 Main St", "addressLine2": "Apt 4B", "region": "California", "city": "Los Angeles", "country": "US", "postCode": "90001" } }, "BankDetails": { "type": "object", "properties": { "accountNumber": { "type": "string", "description": "Recipient's bank account number." }, "code": { "type": "string", "description": "Recipient's bank or branch code." }, "address": { "$ref": "#/components/schemas/Address" }, "accountType": { "type": "string", "enum": [ "CHEQUE", "SAVINGS", "TRANSMISSION" ], "description": "Type of bank account." }, "bankTypeIdentifier": { "type": "string", "enum": [ "SCAN", "IBAN", "SWIFT", "ABA", "CUBIX", "UNKNOWN" ], "description": "Bank account type identifier." }, "intermediaryBanks": { "type": "array", "description": "List of intermediary banks.", "items": { "$ref": "#/components/schemas/IntermediaryBank" } } }, "example": { "accountNumber": "1234567890", "code": "ABC123", "address": { "addressLine1": "123 Main St", "addressLine2": "Apt 4B", "region": "California", "city": "Los Angeles", "country": "US", "postCode": "90001" }, "accountType": "SAVINGS", "bankTypeIdentifier": "SWIFT", "intermediaryBanks": [ { "name": "Intermediary Bank 1", "accountNumber": "0987654321", "code": "XYZ987" } ] } }, "IntermediaryBank": { "type": "object", "required": [ "code" ], "properties": { "bankName": { "type": "string", "description": "Name of the bank." }, "code": { "type": "string", "description": "Bank code or branch code." }, "address": { "$ref": "#/components/schemas/Address" } }, "example": { "bankName": "XYZ Intermediary Bank", "code": "BANK123", "address": { "addressLine1": "123 Bank St", "addressLine2": "Suite 500", "region": "New York", "city": "New York City", "country": "US", "postCode": "10001" } } }, "Metadata": { "type": "object", "description": "Custom metadata key-value pairs. Structure: key: value. Restrictions:\n\n- Maximum five keys.\n\n- Each key maximum length 50 characters.\n\n- Each value maximum length 100 characters.\n\n- Keys and values must be simple strings.", "additionalProperties": { "type": "string", "maxLength": 100, "description": "Metadata value (max 100 characters)" }, "maxProperties": 5, "example": { "source": "api", "merchantId": "merchant-123" } }, "WalletRequestDto": { "type": "object", "properties": { "currency": { "type": "string", "description": "Currency of the wallet.", "example": "ETH" }, "description": { "type": "string", "description": "Name of the wallet.", "minLength": 2, "maxLength": 50, "example": "My 2nd ETH Wallet" } }, "required": [ "currency", "description" ] }, "BalanceDto": { "type": "object", "properties": { "currency": { "$ref": "#/components/schemas/CurrencyDto" }, "walletId": { "type": "integer", "description": "The ID of the wallet.", "format": "int64", "example": "a:24092328494070:G5i4XZ9:1" }, "available": { "type": "number", "description": "The available balance on the wallet.", "example": 100.03 }, "reserved": { "type": "number", "description": "The reserved balance on the wallet.", "example": 1 }, "convertedAvailable": { "type": "number", "description": "The converted available balance on the wallet.", "example": 100 }, "convertedReserved": { "type": "number", "description": "The converted reserved balance on the wallet.", "example": 104 }, "total": { "type": "number", "description": "The total amount on the wallet.", "example": 101.03 } } }, "TransactionReportDto": { "type": "object", "properties": { "id": { "type": "integer", "description": "The ID of the transaction request.", "format": "int64", "example": 594 }, "uuid": { "type": "string", "description": "The UUID of the transaction report.", "example": "9d1f67f2-a647-404b-9b02-247c77be81d0" }, "dateCreated": { "type": "integer", "description": "The date and time, encoded into UNIX epoch timestamps.", "format": "int64", "example": 1631619489000 }, "lastUpdated": { "type": "integer", "description": "The date and time, encoded into UNIX epoch timestamps.", "format": "int64", "example": 1631619489000 }, "expiryDate": { "type": "integer", "description": "The date and time, encoded into UNIX epoch timestamps.", "format": "int64", "example": 1631619489000 }, "status": { "type": "string", "description": "The status of the transaction report.", "example": "PENDING" }, "type": { "type": "string", "description": "The type of the report.", "example": "transactions" }, "requestData": { "$ref": "#/components/schemas/TransactionReportRequestDataDto" } } }, "TransactionReportRequestDataDto": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of report.", "example": "transactions" }, "externalProcessing": { "type": "string", "example": "null" }, "walletId": { "type": "string", "description": "The wallet ID For the report.", "format": "int64", "example": "a:24092328494070:G5i4XZ9:1" }, "transactionType": { "type": "string", "description": "The transaction type.", "example": "null" }, "fromDate": { "type": "string", "description": "The from date of the report.", "example": "2023-03-01" }, "toDate": { "type": "string", "description": "The to date of the report.", "example": "2023-06-30" }, "format": { "type": "string", "description": "The format of the report.", "example": "CSV" }, "languageTag": { "type": "string", "description": "The language tag of the report.", "example": "en-US" }, "category": { "type": "integer", "description": "The category of the report.", "example": 0 }, "accountName": { "type": "string", "description": "The account name.", "example": "null" }, "include": { "type": "string", "example": null }, "exclude": { "type": "string", "example": null } } }, "SimplifiedTransactionReportDto": { "type": "object", "properties": { "id": { "type": "integer", "description": "The ID of the transaction request.", "format": "int64", "example": 594 }, "uuid": { "type": "string", "description": "The UUID of the transaction report.", "example": "9d1f67f2-a647-404b-9b02-247c77be81d0" }, "dateCreated": { "type": "integer", "description": "The date and time, encoded into UNIX epoch timestamps.", "format": "int64", "example": 1631619489000 }, "lastUpdated": { "type": "integer", "description": "The date and time, encoded into UNIX epoch timestamps.", "format": "int64", "example": 1631619489000 }, "expiryDate": { "type": "integer", "description": "The date and time, encoded into UNIX epoch timestamps.", "format": "int64", "example": 1631619489000 }, "status": { "type": "string", "description": "The status of the transaction report.", "example": "PENDING" }, "type": { "type": "string", "description": "The type of the report.", "example": "transactions" } } }, "QuoteRequestDto": { "type": "object", "properties": { "from": { "type": "string", "description": "The currency to convert from.", "example": "EUR" }, "to": { "type": "string", "description": "The currency to convert to.", "example": "USDC" }, "fromWalletLsid": { "type": "string", "description": "The ID of the wallet, from which the currency is converted. You can find the wallet ID in the wallet list response.", "example": "a:25052137356562:qjOSsJf:1" }, "useMinimum": { "type": "boolean", "description": "Is converting the minimum allowed amount.", "example": false }, "useMaximum": { "type": "boolean", "description": "Is converting the max amount of the wallet.", "example": false }, "toWalletLsid": { "type": "string", "description": "The ID of the wallet, to which the currency is converted.", "example": "a:24092328494070:G5i4XZ9:2" }, "amountIn": { "type": "number", "description": "The amount being converted.", "example": 10 }, "payInMethod": { "type": "string", "description": "The type of method in.", "example": "wallet" }, "payOutMethod": { "type": "string", "description": "The type of method out.", "example": "wallet" } }, "required": [ "from", "to", "fromWalletLsid", "useMinimum", "useMaximum", "toWalletLsid", "amountIn", "payInMethod", "payOutMethod" ] }, "ExchangeRequestDto": { "type": "object", "properties": { "from": { "type": "string", "description": "The currency to convert from.", "example": "EUR" }, "to": { "type": "string", "description": "The currency to convert to.", "example": "USDC" }, "payInMethod": { "type": "string", "description": "The type of method in.", "example": "wallet" }, "payOutMethod": { "type": "string", "description": "The type of method out.", "example": "wallet" } }, "required": [ "from", "to", "fromWallet", "useMinimum", "useMaximum", "toWalletLsid", "amountIn", "payInMethod", "payOutMethod" ] }, "QuoteDto": { "type": "object", "properties": { "id": { "type": "integer", "description": "The ID of the quote.", "format": "int64", "example": 1432 }, "from": { "type": "string", "description": "The currency to convert from.", "example": "EUR" }, "to": { "type": "string", "description": "The currency to convert to.", "example": "ETH" }, "amountIn": { "type": "number", "description": "The amount converted to.", "example": 500 }, "amountDue": { "type": "number", "description": "The amount due to be converted.", "example": 500 }, "amountOut": { "type": "number", "description": "The amount being converted out.", "example": 1.12 }, "price": { "type": "number", "description": "The price quoted.", "example": 446.43 }, "quoteStatus": { "type": "string", "description": "The status of the quote.\n\nYou can expect it to remain in the `PENDING` status until you call `/api/v1/quote/accept/{uuid}` and the quote is accepted.", "enum": [ "ESTIMATE", "PENDING", "ACCEPTED", "PAYMENT_IN_FAILED", "PAYMENT_OUT_PROCESSED", "CONVERSION_FAILED", "PAYMENT_OUT_FAILED", "REFUNDED" ] }, "paymentStatus": { "type": "string", "description": "The payment status that reflects the progress of the conversion.\n\nYou can expect it to remain in the `PENDING` status until you call `/api/v1/quote/accept/{uuid}` and the quote is accepted.", "enum": [ "PENDING", "SUCCESS", "CANCELLED", "FAILED", "REFUND_PENDING", "REFUNDED", "REFUND_FAILED" ] }, "acceptanceExpiryDate": { "type": "integer", "description": "The date and time, encoded into UNIX epoch timestamps.", "format": "int64", "example": 1566198657000 }, "acceptanceDate": { "type": "integer", "description": "The date and time, encoded into UNIX epoch timestamps.", "format": "int64", "example": 1566198657000 }, "paymentExpiryDate": { "type": "integer", "description": "The date and time, encoded into UNIX epoch timestamps.", "format": "int64", "example": 1566198657000 }, "paymentReceiptDate": { "type": "integer", "description": "The date and time, encoded into UNIX epoch timestamps.", "format": "int64", "example": 1566198657000 }, "payInLegs": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentLegDto" } }, "payInMethod": { "$ref": "#/components/schemas/PayInMethodDto" }, "payOutMethod": { "$ref": "#/components/schemas/PayOutMethodDto" }, "uuid": { "type": "string", "description": "The UUID of the quote.", "example": "B6670497-D139-47E8-9F4A-F97A5D977057" }, "payOutInstruction": { "$ref": "#/components/schemas/PayOutInstructionDto" }, "payInInstruction": { "$ref": "#/components/schemas/PayInInstructionDto" }, "usePayInMethod": { "$ref": "#/components/schemas/AccountMethodDto" }, "usePayOutMethod": { "$ref": "#/components/schemas/AccountMethodDto" }, "fee": { "type": "number", "description": "The fee for the quote.", "example": 1.02 }, "processingFee": { "type": "number", "description": "The processing fee.", "example": 1.02 }, "type": { "type": "string", "description": "The type of quote.", "enum": [ "FIXED", "MARKET" ] }, "netPrice": { "type": "number", "description": "The net price fo the quote.", "example": 1234.02 }, "grossPrice": { "type": "number", "description": "The gross price of the quote.", "example": 1134.02 }, "amountInGross": { "type": "number", "description": "The price of the quote in gross.", "example": 102 }, "amountInNet": { "type": "number", "description": "The price of the quote in net.", "example": 104 }, "fees": { "$ref": "#/components/schemas/FeesDto" }, "dateCreated": { "type": "integer", "description": "The date and time, encoded into UNIX epoch timestamps.", "format": "int64", "example": 1566198657000 }, "lastUpdated": { "type": "integer", "description": "The date and time, encoded into UNIX epoch timestamps.", "format": "int64", "example": 1566198657000 } } }, "FetchExchangeRateDto": { "type": "object", "properties": { "id": { "type": "integer", "description": "The ID of the quote. null for estimates.", "format": "int64", "example": null }, "from": { "type": "string", "description": "The currency to convert from.", "example": "EUR" }, "to": { "type": "string", "description": "The currency to convert to.", "example": "ETH" }, "amountIn": { "type": "number", "description": "The amount converted to.", "example": 1 }, "amountDue": { "type": "number", "description": "The amount due to be converted.", "example": 1 }, "amountOut": { "type": "number", "description": "The amount being converted out.", "example": 0.00423042 }, "price": { "type": "number", "description": "The current exchange rate.", "example": 2363.8314871809 }, "quoteStatus": { "type": "string", "description": "The status of the quote.", "example": "ESTIMATE" }, "paymentStatus": { "type": "string", "description": "The payment status.", "example": "PENDING" }, "acceptanceExpiryDate": { "type": "integer", "description": "The date and time, encoded into UNIX epoch timestamps.", "format": "int64", "example": 1566198657000 }, "acceptanceDate": { "type": "integer", "description": "The date and time, encoded into UNIX epoch timestamps.", "format": "int64", "example": null }, "paymentExpiryDate": { "type": "integer", "description": "The date and time, encoded into UNIX epoch timestamps.", "format": "int64", "example": 1566198657000 }, "paymentReceiptDate": { "type": "integer", "description": "The date and time, encoded into UNIX epoch timestamps.", "format": "int64", "example": null }, "payInLegs": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentLegDto" } }, "payInMethod": { "$ref": "#/components/schemas/PayInMethodDto" }, "payOutMethod": { "$ref": "#/components/schemas/PayOutMethodDto" }, "uuid": { "type": "string", "description": "The UUID of the quote.", "example": "B6670497-D139-47E8-9F4A-F97A5D977057" }, "payOutInstruction": { "type": "string", "description": "Pay out instructions, null for estimates", "example": null }, "payInInstruction": { "type": "string", "description": "Pay in instructions, null for estimates", "example": null }, "usePayInMethod": { "type": "string", "description": "pay in method, null for estimates", "example": null }, "usePayOutMethod": { "type": "string", "description": "Pay out method, null for estimates", "example": null }, "fee": { "type": "number", "description": "The fee for the quote.", "example": 1.02 }, "processingFee": { "type": "number", "description": "The processing fee.", "example": 1.02 }, "type": { "type": "string", "description": "The type of quote.", "enum": [ "FIXED", "MARKET" ] }, "netPrice": { "type": "number", "description": "The net price fo the quote.", "example": 1234.02 }, "grossPrice": { "type": "number", "description": "The gross price of the quote.", "example": 1134.02 }, "amountInGross": { "type": "number", "description": "The price of the quote in gross.", "example": 102 }, "amountInNet": { "type": "number", "description": "The price of the quote in net.", "example": 104 }, "fees": { "$ref": "#/components/schemas/FeesDto" }, "dateCreated": { "type": "integer", "description": "The date and time, encoded into UNIX epoch timestamps.", "format": "int64", "example": 1566198657000 }, "lastUpdated": { "type": "integer", "description": "The date and time, encoded into UNIX epoch timestamps.", "format": "int64", "example": 1566198657000 } } }, "PaymentLegDto": { "type": "object", "properties": { "id": { "type": "integer", "description": "The ID of the payment.", "format": "int64", "example": 1432 }, "amount": { "type": "number", "description": "The amount of the payment.", "example": 100.32 }, "dateCreated": { "type": "integer", "description": "The date and time, encoded into UNIX epoch timestamps.", "format": "int64", "example": 1566198657000 }, "reference": { "type": "string", "description": "The reference of the payment.", "example": "65b46950-d4b7-11ee-a174-39a638922745" }, "currency": { "type": "string", "description": "The currency of the payment.", "example": "EUR" } } }, "PayInMethodDto": { "type": "object", "properties": { "id": { "type": "integer", "description": "The ID fo the pay in method.", "format": "int64", "example": 5 }, "code": { "type": "string", "description": "The code of the payin.", "example": "wallet" }, "settlementCurrency": { "type": "string", "description": "The settlement currency of the pay in.", "example": "USD" }, "requestedCurrency": { "type": "string", "description": "The requested currency of the pay in.", "example": "EUR" }, "estimatedExchangeRate": { "type": "number", "description": "The estimated exchange rate of the pay in.", "example": 0.923 }, "accountMethods": { "type": "array", "items": { "type": "string" } } } }, "PayOutMethodDto": { "type": "object", "properties": { "id": { "type": "integer", "description": "The ID of the pay out.", "format": "int64", "example": 1432 }, "code": { "type": "string", "description": "The code of the pay out.", "example": "gateway" }, "currency": { "type": "string", "description": "The currency of the pay out.", "example": "EUR" }, "accountMethods": { "type": "array", "items": { "type": "string" } } } }, "AccountMethodDto": { "type": "object", "properties": { "id": { "type": "integer", "description": "The account method ID.", "format": "int64", "example": 1432 }, "display": { "type": "string", "description": "The display details of the account method.", "example": "null" } } }, "PayOutInstructionDto": { "type": "string", "example": null }, "PayInInstructionDto": { "type": "object", "properties": { "action": { "type": "string", "example": "NONE" }, "form": { "type": "string", "example": null }, "redirectUrl": { "type": "string", "example": null }, "displayParameters": { "type": "string", "example": null } } }, "AcceptedQuoteDto": { "type": "object", "properties": { "quote": { "$ref": "#/components/schemas/QuoteDto" }, "payInInstruction": { "$ref": "#/components/schemas/PayInInstructionDto" } } }, "FeesDto": { "type": "object", "properties": { "percentage": { "$ref": "#/components/schemas/FeeDto" }, "value": { "$ref": "#/components/schemas/FeeDto" } } }, "FeeDto": { "type": "object", "properties": { "service": { "type": "number", "example": "0.01" }, "processing": { "type": "number", "example": "0.02" } } }, "ExchangeDto": { "type": "object", "properties": { "value": { "type": "number", "description": "The last traded price exchange rate.", "example": "0.05649637" } } }, "BulkExchangeDto": { "type": "object", "properties": { "baseCode": { "type": "string", "description": "The chosen currency to exchange from.", "example": "ETH" }, "counterCode": { "type": "string", "description": "The currency to exchange base to.", "example": "BTC" }, "rate": { "type": "number", "description": "The exchange rate.", "example": "0.05649637" } } }, "CountryCodeDto": { "type": "object", "properties": { "allowRegistration": { "type": "boolean", "description": "Indicates if registration is allowed.", "example": true }, "code": { "type": "string", "description": "Country code.", "example": "DE" }, "defaultCurrency": { "type": "string", "description": "Default currency code.", "example": "GBP" }, "documents": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "Document code.", "example": "idPassport" }, "description": { "type": "string", "description": "Description of the document.", "example": "ID or Passport" }, "id": { "type": "integer", "description": "Document identifier.", "example": 372 }, "required": { "type": "boolean", "description": "Indicates if the document is required.", "example": true } }, "description": "List of required documents." } }, "id": { "type": "integer", "description": "Unique identifier.", "example": 79 }, "name": { "type": "string", "description": "Country name.", "example": "United Kingdom" }, "options": { "type": "object", "properties": { "minimumOrderValue": { "type": "integer", "description": "Minimum order value.", "example": 50 }, "limitValue": { "type": "integer", "description": "Limit value for transactions.", "example": 800 }, "minimumTransferValue": { "type": "integer", "description": "Minimum value for transfers.", "example": 20 }, "minimumPartnerValue": { "type": "integer", "description": "Minimum value for partner transactions.", "example": 0 }, "requireProofOfPayment": { "type": "string", "description": "Indicates if proof of payment is required.", "example": "TRUE" }, "supportInstantTransfer": { "type": "boolean", "nullable": true, "description": "Indicates if instant transfers are supported.", "example": null }, "unverifiedMaximum": { "type": "string", "description": "Maximum value for unverified accounts.", "example": "800" }, "orderMinimumValue": { "type": "string", "description": "Minimum value for orders.", "example": "50" }, "transferMinimumValue": { "type": "string", "description": "Minimum value for transfers.", "example": "20" }, "withdrawalMaximum": { "type": "string", "description": "Maximum withdrawal amount.", "example": "25000" }, "withdrawalThreshold": { "type": "string", "description": "Threshold for withdrawal transactions.", "example": "15000" } }, "description": "Options related to transactions." }, "region": { "type": "string", "nullable": true, "description": "Geographical region if applicable.", "example": null } } }, "AgreementsDto": { "type": "array", "items": { "type": "object", "properties": { "declinable": { "type": "boolean", "description": "Indicates whether the agreement can be declined.", "example": false }, "description": { "type": "string", "description": "Description of the agreement.", "example": "The BVNK Master Client Agreement governs the opening, use and closure of a BVNK account. Please review the information provided and click to accept." }, "id": { "type": "integer", "description": "Unique identifier for the agreement.", "example": 8 }, "name": { "type": "string", "description": "Name of the agreement.", "example": "MASTER_CLIENT_AGREEMENT" }, "privacyPolicyDescription": { "type": "string", "description": "Description of the privacy policy associated with the agreement.", "example": "Privacy Policy describes our data handling practices when you access content we own or operate on the website located at www.bvnk.com or any other associated websites we own or operate" }, "privacyPolicyName": { "type": "string", "description": "Name of the privacy policy.", "example": "BVNK Privacy Policy" }, "privacyPolicyUrl": { "type": "string", "format": "uri", "description": "URL to the privacy policy document.", "example": "https://help.bvnk.com/hc/en-us/articles/7662076884882-Privacy-Policy" }, "reference": { "type": "string", "description": "Reference identifier for the agreement.", "example": "9fc28f1a-f946-11ed-a643-027612b7f6b5" }, "url": { "type": "string", "format": "uri", "description": "URL to the agreement document.", "example": "https://agreements.bvnk.com/Client_Master_Agreement.pdf" } } } }, "EmbeddedPartnerWebhookDto": { "type": "object", "properties": { "account": { "type": "object", "properties": { "id": { "type": "integer", "description": "The account ID.", "example": 13456 }, "reference": { "type": "string", "description": "The account reference ID in UUID format.", "example": "7c6854d8-f07e-4165-bf52-7bc7a1007d57" }, "name": { "type": "string", "description": "The name of the account.", "example": "Embedded partner legal name" }, "enabled": { "type": "boolean", "description": "The enabled state of the account.", "example": true }, "parentReference": { "type": "string", "description": "The EP account reference for EPM accounts, null when actioned on EP account", "example": null }, "dateCreated": { "type": "string", "description": "The creation date of the account, in ISO format.", "example": "2023-07-24T09:34:27Z" }, "lastUpdated": { "type": "string", "description": "The updated date of the account, in ISO format.", "example": "2023-07-24T11:35:23Z" } } }, "secret": { "type": "string", "description": "The secret key used to validate webhooks. shown when creating", "example": "ZmI5YWM2YmMtNDBhYy00MjhiLTk1YzYtMjEzZGI1YjM3ZTE3MGViZjlmYzEtMTE3ZC00ODViLThmNDEtMzMwOTg1YWM2NG" }, "url": { "type": "string", "format": "uri", "description": "The URL webhooks will be sent to", "example": "https://webhook.site/8e231f77-f475-40b3-80a9-4dd8846c2830" }, "dateCreated": { "type": "string", "description": "The creation date of the webhook URL, in ISO format.", "example": "2024-01-30T00:00:00Z" }, "lastUpdated": { "type": "string", "description": "The updated date of the webhook URL, in ISO format.", "example": "2024-02-26T08:03:50Z" } } }, "CustomersPage": { "type": "object", "required": [ "content", "page" ], "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerOverviewDto" } }, "page": { "$ref": "#/components/schemas/Page" } } }, "CustomersPageInternal": { "type": "object", "required": [ "content", "page" ], "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerInternalDto" } }, "page": { "$ref": "#/components/schemas/Page" } } }, "CustomerOverviewDto": { "type": "object", "required": [ "reference", "status", "type", "name" ], "properties": { "reference": { "type": "string", "format": "uuid", "example": "0a184641-30e2-4414-871f-3db1c683900e" }, "status": { "$ref": "#/components/schemas/CustomerStatusExternal" }, "type": { "$ref": "#/components/schemas/CustomerType" }, "name": { "type": "string", "description": "Customer name", "example": "UK Ltd Version 2.0" }, "description": { "type": "string", "description": "Customer description", "example": "Number 1 customer, be super nice." } } }, "CustomerStatusExternal": { "type": "string", "description": "Customer external status", "enum": [ "PENDING", "VERIFIED", "REJECTED" ], "example": "VERIFIED" }, "CustomerType": { "type": "string", "description": "Type of customer", "enum": [ "COMPANY", "INDIVIDUAL" ], "example": "COMPANY" }, "Page": { "type": "object", "required": [ "size", "totalElements", "totalPages", "number" ], "properties": { "size": { "type": "integer", "description": "Page size", "example": 10 }, "totalElements": { "type": "integer", "description": "Total elements count", "example": 10 }, "totalPages": { "type": "integer", "description": "Pages count, equal to totalElements / size", "example": 10 }, "number": { "type": "integer", "description": "Current page number (starts from 0)", "example": 0 } } }, "CustomerInternalDto": { "type": "object", "required": [ "reference", "accountReference", "status", "statusInternal", "type" ], "properties": { "reference": { "type": "string", "format": "uuid", "example": "0a184641-30e2-4414-871f-3db1c683900e" }, "accountReference": { "type": "string", "format": "uuid", "example": "0a184641-30e2-4414-871f-3db1c683900e" }, "status": { "$ref": "#/components/schemas/CustomerStatusExternal" }, "statusInternal": { "$ref": "#/components/schemas/CustomerStatusInternal" }, "statusReason": { "type": "string", "description": "Screening result reason", "example": "Manually verified" }, "lastVerifiedOn": { "type": "string", "format": "datetime", "description": "Timestamp of the last screening with `VERIFIED` status in result" }, "type": { "$ref": "#/components/schemas/CustomerType" }, "company": { "$ref": "#/components/schemas/CorporateCustomer" } } }, "CustomerStatusInternal": { "type": "string", "description": "Customer external status", "enum": [ "PENDING", "VERIFIED", "REJECTED" ], "example": "REJECTED" }, "CorporateCustomer": { "type": "object", "required": [ "name", "taxResidenceCountryCode", "registrationNumber", "industry", "monthlyExpectedVolumes", "address", "representative" ], "properties": { "name": { "type": "string", "description": "Customer name", "example": "UK Ltd Version 2.0" }, "description": { "type": "string", "description": "Customer description", "example": "Number 1 customer, be super nice." }, "taxResidenceCountryCode": { "type": "string", "description": "Tax residency of legal person (ISO 3166-1 alpha-2)", "example": "DE" }, "registrationNumber": { "type": "string", "description": "Registration number of legal person", "example": "1849203" }, "industry": { "$ref": "#/components/schemas/Industry" }, "monthlyExpectedVolumes": { "$ref": "#/components/schemas/MonthlyExpectedVolumes" }, "address": { "$ref": "#/components/schemas/AddressV2" }, "representative": { "$ref": "#/components/schemas/CorporateCustomerRepresentative" } } }, "CorporateCustomerRepresentative": { "type": "object", "required": [ "firstName", "lastName", "dateOfBirth", "address" ], "properties": { "firstName": { "type": "string", "pattern": "[^0-9]*", "minLength": 2, "maxLength": 255, "description": "First name.", "example": "John" }, "lastName": { "type": "string", "pattern": "[^0-9]*", "minLength": 2, "maxLength": 255, "description": "Last name.", "example": "Mirra" }, "dateOfBirth": { "type": "string", "description": "Date of birth in the ISO-8601 format.", "format": "\\d{4}-\\d{2}-\\d{2}", "example": "2001-12-31" }, "birthCountryCode": { "type": "string", "description": "2-letter birth country code in the ISO 3166-1 alpha-2 format.", "example": "HK" }, "nationality": { "type": "string", "description": "2-letter nationality code in the ISO 3166-1 alpha-2 format.", "example": "US" }, "address": { "$ref": "#/components/schemas/AddressV2" } } }, "MonthlyExpectedVolumes": { "type": "object", "properties": { "reference": { "type": "string", "description": "Unique identifier for the volume range", "format": "uuid", "example": "b59c2055-7655-43bb-923d-0005928301d7" }, "name": { "type": "string", "description": "Name of the volume range", "example": "0 - 500 000.00 EUR" }, "min": { "type": "integer", "description": "Minimum expected volume within this range", "example": 0 }, "max": { "type": "integer", "description": "Maximum expected volume within this range", "example": 500000 } } }, "Industry": { "type": "object", "properties": { "reference": { "type": "string", "format": "uuid", "example": "b59c2055-7655-43bb-923d-0005928301d7" }, "name": { "type": "string", "example": "Finance" }, "children": { "type": "array", "description": "Present only if the industry has sub-industries", "items": { "$ref": "#/components/schemas/Industry" } } } }, "AddressV2": { "type": "object", "required": [ "addressLine1", "postalCode", "city", "countryCode" ], "properties": { "addressLine1": { "type": "string", "maxLength": 255, "description": "Main address", "example": "123 Main Street" }, "addressLine2": { "type": "string", "maxLength": 255, "description": "Apartment numbers or suite number", "example": "Apartment 456" }, "postalCode": { "type": "string", "maxLength": 255, "description": "Postal code", "example": "NW1 4NP" }, "city": { "type": "string", "maxLength": 255, "description": "City", "example": "London" }, "countryCode": { "$ref": "#/components/schemas/AddressCountryCode" }, "country": { "type": "string", "description": "Country of residence", "example": "Great Britain" }, "stateCode": { "type": "string", "maxLength": 2, "description": "2-letter state code. **Required for US customers**.", "example": "AL" } } }, "AddressCountryCode": { "type": "string", "description": "2-letter country code in the ISO 3166-1 alpha-2 format.", "example": "DE" }, "CreateCompanyCustomerRequest": { "type": "object", "additionalProperties": false, "required": [ "type", "company", "signedAgreementSessionReference" ], "properties": { "type": { "type": "string", "enum": [ "company" ], "example": "company" }, "company": { "$ref": "#/components/schemas/CreateCorporateCustomer" }, "signedAgreementSessionReference": { "type": "string", "description": "Agreement acceptance reference. See [Prepare Customer Agreements](https://docs.bvnk.com/docs/signing-customer-agreements#/)", "example": "78eedde1-2402-4a59-8bbd-ccecb6d612d1" } } }, "CreateIndividualCustomerRequest": { "type": "object", "additionalProperties": false, "required": [ "type", "individual", "signedAgreementSessionReference" ], "properties": { "type": { "type": "string", "enum": [ "individual" ], "example": "individual" }, "individual": { "$ref": "#/components/schemas/CreateIndividualCustomer" }, "signedAgreementSessionReference": { "type": "string", "description": "Agreement acceptance reference. See [Prepare Customer Agreements](https://docs.bvnk.com/docs/signing-customer-agreements#/)", "example": "78eedde1-2402-4a59-8bbd-ccecb6d612d1" } } }, "CreateExpressSessionExistingCustomerRequest": { "title": "Existing Embedded Customer", "type": "object", "additionalProperties": false, "required": [ "customerReference" ], "description": "Request payload for your existing embedded customer who is already registered on the BVNK platform.", "properties": { "customerReference": { "type": "string", "format": "uuid", "description": "Reference of the existing customer in BVNK.", "example": "22c8168d-f735-43f8-9a3b-a1578efeb86c" }, "theme": { "$ref": "#/components/schemas/ExpressTheme" } } }, "CreateExpressSessionNewCustomerRequest": { "title": "New Customer", "type": "object", "additionalProperties": false, "required": [ "type", "countryCode", "externalCustomerReference" ], "description": "Request payload for a new customer who doesn't exist on the BVNK platform yet.", "properties": { "type": { "type": "string", "enum": [ "INDIVIDUAL", "COMPANY" ], "description": "Type of customer to create.", "example": "INDIVIDUAL" }, "countryCode": { "type": "string", "maxLength": 2, "description": "Country code of the customer's address in the ISO 3166-1 alpha-2 format.", "example": "DE" }, "externalCustomerReference": { "type": "string", "format": "uuid", "description": "Your internal customer identifier. This should be a unique identifier for the customer in your platform.", "example": "22c8168d-f735-43f8-9a3b-a1578efeb86n" }, "theme": { "$ref": "#/components/schemas/ExpressTheme" } } }, "ExpressTheme": { "type": "object", "additionalProperties": false, "description": "Optional theme customization for the Express interface. Allows you to customize the Express interface to match your brand.", "properties": { "logo": { "type": "string", "format": "uri", "description": "URL to your company logo. The logo will be displayed throughout the Express interface.", "example": "https://ok14static.oktacdn.com/fs/bco/1/fs0waisynotIeKa80697" }, "primary": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "description": "Primary brand color as a hex code.", "example": "#121212" }, "secondary": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "description": "Secondary color as a hex code.", "example": "#382457" }, "accent": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "description": "Accent color as a hex code.", "example": "#DEF832" } } }, "ExpressSessionResponse": { "type": "object", "additionalProperties": false, "description": "Response containing the wallet session URL and customer information.", "required": [ "walletSessionUrl" ], "properties": { "externalCustomerReference": { "type": "string", "format": "uuid", "description": "Your internal customer identifier. Present in responses for new customers.", "example": "22c8168d-f735-43f8-9a3b-a1578efeb86n" }, "customerReference": { "type": "string", "format": "uuid", "description": "BVNK's internal customer identifier. Present in responses for existing customers.", "example": "22c8168d-f735-43f8-9a3b-a1578efeb86c" }, "customerType": { "type": "string", "enum": [ "INDIVIDUAL", "COMPANY" ], "description": "Type of customer.", "example": "INDIVIDUAL" }, "useCase": { "type": "string", "enum": [ "STABLECOIN_PAYOUTS", "EMBEDDED_STABLECOIN_WALLETS", "EMBEDDED_FIAT_ACCOUNTS" ], "description": "Type of product to which the customer agreement applies.", "example": "EMBEDDED_STABLECOIN_WALLETS" }, "countryCode": { "type": "string", "maxLength": 2, "description": "Country code of the customer's address in the ISO 3166-1 alpha-2 format. Present in responses for new customers.", "example": "DE" }, "theme": { "$ref": "#/components/schemas/ExpressTheme", "description": "Theme customization applied to the Express interface, matching the theme provided in the request." }, "walletSessionUrl": { "type": "string", "format": "uri", "description": "URL that redirects the customer to the wallet interface. The customer then either completes onboarding or logs in through this interface. Provide this URL to your customer via a web view, redirect, or another integration method.", "example": "https://wallet.staging.bvnk.com/welcome?sessionId=f5b2d8cd-887d-421c-ae00-9d3f82b5a45f#token=jafR7d-LarxRQrlXQ5fWgg" } } }, "CreateCorporateCustomer": { "type": "object", "required": [ "name", "entityType", "taxResidenceCountryCode", "registrationNumber", "industryReference", "monthlyExpectedVolumesReference", "address", "associates" ], "properties": { "name": { "type": "string", "description": "Legal name of the company.", "maxLength": 255, "example": "UK Ltd Version 2.0" }, "description": { "type": "string", "maxLength": 255, "description": "Optional description or short bio of the company.", "example": "Number 1 customer, be super nice." }, "entityType": { "type": "string", "description": "Business entity type.", "enum": [ "LIMITED_LIABILITY_COMPANY", "PUBLICLY_LISTED_COMPANY", "SOLE_PROPRIETOR", "PARTNERSHIP", "CORPORATION", "TRUST", "PRIVATE_FOUNDATION", "CHARITY", "NON_PROFIT_ORGANIZATION", "PUBLIC_AGENCIES_OR_AUTHORITIES" ] }, "taxResidenceCountryCode": { "type": "string", "maxLength": 2, "description": "The 2-character country code for the company's tax residence (ISO 3166-1 alpha-2).", "example": "DE" }, "taxNumber": { "type": "string", "description": "Tax number of the USA-based company. **Required for the USA customers**.", "maxLength": 255, "example": "12-34567890" }, "registrationNumber": { "type": "string", "minLength": 5, "maxLength": 20, "description": "Official company registration number.", "example": "1849203" }, "industryReference": { "type": "string", "format": "uuid", "description": "Industry reference in the UUID format. See the full list on the [Industry References](../../../references/industy-references/#industry-reference-table) page.\n\nIf you cannot find the industry you are looking for, specify `industryNaicsCode` or `industryNaceCode` instead.", "example": "0a184641-30e2-4414-871f-3db1c683900e" }, "industryNaceCode": { "type": "integer", "description": "Code from the Nomenclature of Economic Activities (NACE). Applicable to companies based in EU and EEA. See the full list on the [Industry References](../../../references/industy-references/#industry-reference-table) page.\n\n At least one of `industryReference`, `industryNaicsCode`, or `industryNaceCode` must be provided.", "example": "5223" }, "industryNaicsCode": { "type": "integer", "description": "Code from the North American Industry Classification System (NAICS). Applicable to companies based in the US and Mexico. See the full list on the [Industry References](../../../references/industy-references/#industry-reference-table) page.\n\nAt least one of `industryReference`, `industryNaicsCode`, or `industryNaceCode` must be provided.", "example": "6619" }, "monthlyExpectedVolumesReference": { "type": "string", "format": "uuid", "description": "Monthly expected volumes reference in the UUID format. See the full list [here](https://docs.bvnk.com/docs/retrieve-monthly-expected-volumes-references-1#/).", "example": "0a184641-30e2-4414-871f-3db1c683900e" }, "address": { "$ref": "#/components/schemas/AddressV2" }, "cdd": { "$ref": "#/components/schemas/CorporateCdd" }, "operationalAddress": { "$ref": "#/components/schemas/AddressV2", "description": "Operational address of the company. Optional. Specify if different from `company.address`." }, "incorporationDate": { "type": "string", "format": "date", "description": "Incorporation date of the company in the ISO-8601 format.", "example": "2001-12-31" }, "businessOperationsStartDate": { "type": "string", "format": "date", "description": "Actual date when the company began conducting its business activities or commercial operations. ISO-8601 format.", "example": "2011-12-03" }, "website": { "type": "string", "format": "url", "maxLength": 255, "description": "Website URL of the company.", "example": "https://www.example.com" }, "associates": { "$ref": "#/components/schemas/CreateCorporateCustomerAssociates" }, "reliance": { "$ref": "#/components/schemas/CorporateReliance" }, "isRegulated": { "type": "boolean", "description": "Whether the company is regulated by a financial authority. If `true`, `regulatorInformation` is required.\n\nMandatory for the onboarding of customers from the US states that do not require money transmitter license (MTL). The non-MTL states are **not** listed in [What licenses registrations does BVNK and BVNK's Partners have](https://help.bvnk.com/hc/en-us/articles/11094354781074-What-licenses-registrations-does-BVNK-and-BVNK-s-Partners-have).", "example": false }, "regulatorInformation": { "$ref": "#/components/schemas/RegulatorInformation" }, "isPubliclyListed": { "type": "boolean", "description": "Whether the company is publicly listed on a stock exchange. If `true`, `publicInformation` is required.\n\nMandatory for the onboarding of customers from the US states that do not require money transmitter license (MTL). The non-MTL states are **not** listed in [What licenses registrations does BVNK and BVNK's Partners have](https://help.bvnk.com/hc/en-us/articles/11094354781074-What-licenses-registrations-does-BVNK-and-BVNK-s-Partners-have).", "example": false }, "publicInformation": { "$ref": "#/components/schemas/PublicInformation" } } }, "RegulatorInformation": { "type": "object", "description": "Regulator details. Required when `isRegulated` is `true`.", "required": [ "regulatorName", "regulatorJurisdiction" ], "properties": { "regulatorName": { "type": "string", "description": "Name of the financial regulator overseeing the company.", "example": "Financial Conduct Authority" }, "regulatorJurisdiction": { "type": "string", "description": "Jurisdiction of the regulator.", "example": "DE" } } }, "PublicInformation": { "type": "object", "description": "Public listing details. Required when `isPubliclyListed` is `true`.", "required": [ "listedExchange", "tickerSymbol" ], "properties": { "listedExchange": { "type": "string", "description": "Name of the stock exchange where the company is listed.", "example": "London Stock Exchange" }, "tickerSymbol": { "type": "string", "description": "The company's ticker symbol on the exchange.", "example": "BVNK" } } }, "CreateIndividualCustomer": { "type": "object", "required": [ "description", "firstName", "lastName", "dateOfBirth", "nationality", "birthCountryCode", "emailAddress", "address", "taxIdentification", "cdd" ], "properties": { "description": { "type": "string", "description": "Enter additional notes or description of this individual customer. This field can include relevant background information, special requirements, customer preferences, account purpose, or any other details that may be helpful for future reference." }, "firstName": { "type": "string", "description": "First name.", "example": "Walton" }, "lastName": { "type": "string", "description": "Last name.", "example": "Simmons" }, "dateOfBirth": { "type": "string", "format": "date", "description": "Date of birth in YYYY-MM-DD format.", "example": "1985-08-15" }, "nationality": { "type": "string", "description": "Nationality (ISO 2-letter code). *Required for EU customers*.", "example": "AT" }, "birthCountryCode": { "type": "string", "description": "Birth country code (ISO 2-letter code). *Required for EU customers*.", "example": "IT" }, "emailAddress": { "type": "string", "format": "email", "description": "Email address.", "example": "wsimmons@example.com" }, "phoneNumber": { "type": "string", "description": "Phone number. Optional.", "example": "+1234567890" }, "address": { "allOf": [ { "$ref": "#/components/schemas/AddressV2" }, { "type": "object", "properties": { "stateCode": { "type": "string", "description": "State code. **Required for US customers**", "example": "NY" } } } ] }, "taxIdentification": { "type": "object", "required": [ "number", "taxResidenceCountryCode" ], "description": "Tax identification details. **Required for USA residents**.", "properties": { "number": { "type": "string", "description": "SSN/ITIN for US, tax number for rest of the world", "example": "123-45-6789" }, "taxResidenceCountryCode": { "type": "string", "description": "Tax residency country ISO 2-letter code", "example": "US" } } }, "cdd": { "type": "object", "description": "Customer Due Diligence details", "properties": { "employmentStatus": { "type": "string", "enum": [ "SELF_EMPLOYED", "SALARIED", "UNEMPLOYED", "RETIRED", "NOT_PROVIDED" ], "description": "Employment status: \n\n- `SELF_EMPLOYED`: Self employed and freelancer\n\n- `SALARIED`: Salaried\n\n- `UNEMPLOYED`: Unemployed\n\n- `RETIRED`: Retired\n\n- `NOT_PROVIDED`: Not provided", "example": "SALARIED" }, "sourceOfFunds": { "type": "string", "enum": [ "SALARY", "PENSION", "SAVINGS", "SELF_EMPLOYMENT", "CRYPTO_TRADING", "GAMBLING", "REAL_ESTATE" ], "description": "Source of funds:\n\n - `SALARY`: Salary and employment income\n\n - `PENSION`: Pension and retirement income\n\n - `SAVINGS`: Savings and investments\n\n - `SELF_EMPLOYMENT`: Self employment and business income\n\n - `CRYPTO_TRADING`: Crypto trading\n\n - `GAMBLING`: Gambling and lottery winnings\n\n - `REAL_ESTATE`: Real estate sales", "example": "SALARY" }, "pepStatus": { "type": "string", "enum": [ "NOT_PEP", "FORMER_PEP_2_YEARS", "FORMER_PEP_OLDER", "DOMESTIC_PEP", "FOREIGN_PEP", "CLOSE_ASSOCIATES", "FAMILY_MEMBERS" ], "description": "Politically Exposed Person status:\n\n - `NOT_PEP`: Not a PEP\n\n - `FORMER_PEP_2_YEARS`: Former or inactive PEP (within 2 years)\n\n - `FORMER_PEP_OLDER`: Former or inactive PEP (older than 2 years)\n\n - `DOMESTIC_PEP`: Domestic PEP\n\n - `FOREIGN_PEP`: Foreign PEP\n\n - `CLOSE_ASSOCIATES`: Close associates\n\n - `FAMILY_MEMBERS`: Family members", "example": "NOT_PEP" }, "intendedUseOfAccount": { "type": "string", "enum": [ "TRANSFERS_OWN_WALLET", "TRANSFERS_FAMILY_FRIENDS", "INVESTMENTS", "GOODS_SERVICES", "DONATIONS" ], "description": "Purpose of the account:\n\n- `TRANSFERS_OWN_WALLET`: Transfers to or from own wallet including bank accounts\n\n - `TRANSFERS_FAMILY_FRIENDS`: Transfers to or from family and friends\n\n - `INVESTMENTS`: Investments\n\n - `GOODS_SERVICES`: Purchases of goods and services\n\n - `DONATIONS`: Donations", "example": "INVESTMENTS" }, "expectedMonthlyVolume": { "type": "object", "description": "Expected monthly volume", "properties": { "amount": { "type": "string", "description": "Expected monthly volume amount", "example": "10000.01" }, "currency": { "type": "string", "description": "Currency (USD or EUR)", "example": "USD" } }, "required": [ "amount" ] }, "estimatedYearlyIncome": { "type": "string", "description": "Estimated yearly income range. **Mandatory for US residents under the Partner-managed model**.\n\n- `INCOME_0_TO_50K`: 0 to 50,000 USD\n\n- `INCOME_50K_TO_100K`: 50,000 to 100,000 USD\n\n- `INCOME_100K_TO_250K`: 100,000 to 250,000 USD\n\n- `INCOME_250K_TO_500K`: 250,000 to 500,000 USD\n\n- `INCOME_500K_TO_750K`: 500,000 to 750,000 USD\n\n- `INCOME_750K_TO_1M`: 750,000 to 1,000,000 USD\n\n- `INCOME_ABOVE_1M`: Above 1,000,000 USD", "enum": [ "INCOME_0_TO_50K", "INCOME_50K_TO_100K", "INCOME_100K_TO_250K", "INCOME_250K_TO_500K", "INCOME_500K_TO_750K", "INCOME_750K_TO_1M", "INCOME_ABOVE_1M" ], "example": "INCOME_0_TO_50K" }, "employmentIndustrySector": { "type": "string", "description": "Employment industry sector. **Required if your customers are individuals domiciled in a US state**.", "enum": [ "INVESTMENT", "HEDGE_FUND", "MONEY_SERVICE_BUSINESS", "STO_ISSUER", "PRECIOUS_METALS", "NON_PROFIT", "REGISTERED_INVESTMENT_ADVISOR", "AGRICULTURE_FORESTRY_FISHING_HUNTING", "MINING", "UTILITIES", "CONSTRUCTION", "MANUFACTURING", "WHOLESALE_TRADE", "RETAIL_TRADE", "TRANSPORTATION_WAREHOUSING", "INFORMATION", "FINANCE_INSURANCE", "REAL_ESTATE_RENTAL_LEASING", "PROFESSIONAL_SCIENTIFIC_TECHNICAL_SERVICES", "MANAGEMENT_OF_COMPANIES_ENTERPRISES", "ADMINISTRATIVE_SUPPORT_WASTE_MANAGEMENT_REMEDIATION_SERVICES", "EDUCATIONAL_SERVICES", "HEALTH_CARE_SOCIAL_ASSISTANCE", "ARTS_ENTERTAINMENT_RECREATION", "ACCOMMODATION_FOOD_SERVICES", "OTHER_SERVICES", "PUBLIC_ADMINISTRATION", "NOT_CLASSIFIED", "ADULT_ENTERTAINMENT", "AUCTIONS", "AUTOMOBILES", "BLOCKCHAIN", "CRYPTO", "DRUGS", "EXPORT_IMPORT", "E_COMMERCE", "FINANCIAL_INSTITUTION", "GAMBLING", "INSURANCE", "MARKET_MAKER", "SHELL_BANK", "TRAVEL_TRANSPORT", "WEAPONS" ], "example": "AGRICULTURE_FORESTRY_FISHING_HUNTING" } }, "required": [ "employmentStatus", "sourceOfFunds", "pepStatus", "intendedUseOfAccount", "expectedMonthlyVolume" ] }, "reliance": { "$ref": "#/components/schemas/Reliance" } } }, "Reliance": { "type": "object", "description": "Additional fields for the Partner-managed customer onboarding.", "properties": { "identityDocumentMetadata": { "type": "object", "description": "Details of the ID document that you have already verified. Used under the Partner-managed model. See [Individual Requirements](https://docs.bvnk.com/docs/compliance-requirements-for-individuals2#/) section for the supported documents.", "properties": { "type": { "type": "string", "description": "Type of the identity document. Used under the Partner-managed model.\n\n- `PASSPORT`: Passport\n\n- `ID_CARD`: National ID card\n\n- `DRIVERS`: Driver's licence\n\n- `RESIDENCE_PERMIT`: Residence permit\n\n- `OTHER`: Other government-issued ID", "enum": [ "PASSPORT", "ID_CARD", "DRIVERS", "RESIDENCE_PERMIT", "OTHER" ], "example": "PASSPORT" }, "number": { "type": "string", "description": "Identity document number.", "example": "AB1234567" }, "expiryDate": { "type": "string", "format": "date", "description": "Expiry date of the identity document. Required for all documents, except documents of the type `ID_CARD` and `OTHER`.", "example": "2030-12-31" }, "issueDate": { "type": "string", "format": "date", "description": "Issue date of the identity document.", "example": "2015-10-01" }, "issuingCountryCode": { "type": "string", "description": "ISO 3166-1 alpha-2 country code of the issuing country.", "minLength": 2, "maxLength": 2, "example": "DE" }, "kycTimestamp": { "type": "string", "format": "date-time", "description": "Timestamp of the KYC identity verification.", "example": "2025-11-20T15:30:45.123Z" } }, "required": [ "type", "number", "issuingCountryCode", "kycTimestamp" ] }, "biometricLiveness": { "type": "object", "description": "**EU Only**. Timestamps for liveness checks performed on your side.", "properties": { "livenessTimestamp": { "type": "string", "format": "date-time", "description": "Timestamp of the biometric liveness check.", "example": "2025-11-20T15:30:45.123Z" } }, "required": [ "livenessTimestamp" ] }, "addressVerification": { "type": "object", "description": "The method you used to verify the residential address of the Customer. Used under the Partner-managed model.", "properties": { "type": { "type": "string", "description": "Proof of Address type. Used under the Partner-managed model.\n\n- `DOC`: Verified by a document\n\n- `NON_DOC`: Verified via a database or registry", "enum": [ "DOC", "NON_DOC" ], "example": "NON_DOC" } }, "required": [ "type" ] } }, "required": [ "identityDocumentMetadata", "biometricLiveness", "addressVerification" ] }, "RelianceAttestation": { "type": "object", "description": "Additional fields for the Partner-managed customer onboarding for corporate customers. Risk score levels and EDD completion status for customer attestation.", "properties": { "riskScore": { "$ref": "#/components/schemas/CreateCorporateRiskScore", "description": "Your internal risk rating for this customer per Personally Identifiable Information (PII).", "example": "LOW" }, "eddCompleted": { "type": "boolean", "enum": [ true, false ], "description": "Indicates if you have already performed Enhanced Due Diligence (EDD).\n\n BVNK doesn't verify customer attestations within this flow, so make sure you have completed the EDD.", "example": true } }, "required": [ "riskScore", "eddCompleted" ] }, "CorporateReliance": { "type": "object", "description": "Additional fields for the Partner-managed customer onboarding for corporate customers. Incorporation, Address, and SoF are handled via /documents in Step 3.", "properties": { "attestation": { "$ref": "#/components/schemas/RelianceAttestation" } }, "required": [ "attestation" ] }, "CorporateCdd": { "type": "object", "description": "Customer Due Diligence details for corporate customers.", "properties": { "pepStatus": { "type": "string", "enum": [ "NOT_PEP", "FORMER_PEP_2_YEARS", "FORMER_PEP_OLDER", "DOMESTIC_PEP", "FOREIGN_PEP", "CLOSE_ASSOCIATES", "FAMILY_MEMBERS" ], "description": "Politically Exposed Person status:\n\n - `NOT_PEP`: Not a PEP\n\n - `FORMER_PEP_2_YEARS`: Former or inactive PEP (within 2 years)\n\n - `FORMER_PEP_OLDER`: Former or inactive PEP (older than 2 years)\n\n - `DOMESTIC_PEP`: Domestic PEP\n\n - `FOREIGN_PEP`: Foreign PEP\n\n - `CLOSE_ASSOCIATES`: Close associates\n\n - `FAMILY_MEMBERS`: Family members", "example": "NOT_PEP" }, "intendedUseOfAccount": { "type": "string", "enum": [ "SUPPLIER_VENDOR_PAYMENTS", "PAYROLL", "CUSTOMER_PAYMENTS_RECEIVED", "CUSTOMER_PAYOUTS_REFUNDS_SETTLEMENTS", "OPERATING_EXPENSES", "DIVIDEND_PROFIT_DISTRIBUTIONS", "LOAN_REPAYMENT_FINANCIAL_ACTIVITIES", "INTERCOMPANY_TRANSFER" ], "description": "Purpose of the account:\n\n- `SUPPLIER_VENDOR_PAYMENTS`: Supplier and vendor payments. For the Partner-managed customer onboarding only\n\n - `PAYROLL`: Payroll and salary payments\n\n - `CUSTOMER_PAYMENTS_RECEIVED`: Customer payments received. For the Partner-managed customer onboarding only\n\n - `CUSTOMER_PAYOUTS_REFUNDS_SETTLEMENTS`: Customer payouts, refunds, and settlements. For the Partner-managed customer onboarding only\n\n - `OPERATING_EXPENSES`: Operating expenses. For the Partner-managed customer onboarding only\n\n - `DIVIDEND_PROFIT_DISTRIBUTIONS`: Dividend and profit distributions. For the Partner-managed customer onboarding only\n\n - `LOAN_REPAYMENT_FINANCIAL_ACTIVITIES`: Loan repayment and financial activities. For the Partner-managed customer onboarding only\n\n - `INTERCOMPANY_TRANSFER`: Intercompany transfers. For the Partner-managed customer onboarding only", "example": "PAYROLL" }, "expectedMonthlyVolume": { "type": "object", "description": "Expected monthly volume", "properties": { "amount": { "type": "string", "description": "Expected monthly volume amount", "example": "50000.00" }, "currency": { "type": "string", "description": "Currency (USD or EUR)", "example": "EUR" } }, "required": [ "amount" ] } }, "required": [ "pepStatus", "intendedUseOfAccount", "expectedMonthlyVolume" ] }, "CreateCorporateRiskScore": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ], "description": "Risk score levels. Used under the Partner-managed model.\n\n- `LOW`: Low risk\n\n- `MEDIUM`: Medium risk\n\n- `HIGH`: High risk", "example": "LOW" }, "CreateCorporateCustomerAssociates": { "type": "array", "items": { "type": "object", "required": [ "person" ], "properties": { "person": { "type": "object", "required": [ "firstName", "lastName", "dateOfBirth", "address", "contactInfo" ], "properties": { "firstName": { "type": "string", "minLength": 2, "maxLength": 255, "pattern": "[^0-9]*", "description": "First name of the Associate person.", "example": "John" }, "lastName": { "type": "string", "minLength": 2, "maxLength": 255, "pattern": "[^0-9]*", "description": "Last name of the Associate person.", "example": "Hurt" }, "dateOfBirth": { "type": "string", "format": "date", "description": "Date of birth in the ISO-8601 format.", "example": "2001-12-31" }, "birthCountryCode": { "type": "string", "maxLength": 2, "description": "2-letter birth country code in the ISO 3166-1 alpha-2 format.", "example": "HK" }, "nationality": { "type": "string", "maxLength": 2, "description": "2-letter nationality code in the ISO 3166-1 alpha-2 format.", "example": "US" }, "address": { "$ref": "#/components/schemas/AddressV2" }, "contactInfo": { "properties": { "emailAddress": { "type": "string", "format": "email", "maxLength": 255, "description": "Email address.", "example": "wsimmons@example.com" }, "phoneNumber": { "type": "string", "maxLength": 255, "description": "Phone number.", "example": "+1234567890" } } }, "taxIdentification": { "type": "object", "description": "Tax identification details", "properties": { "number": { "type": "string", "maxLength": 255, "description": "SSN/ITIN for US, tax number for rest of the world", "example": "123-45-6789" }, "taxResidenceCountryCode": { "type": "string", "maxLength": 2, "description": "Tax residency country ISO 2-letter code", "example": "US" } }, "required": [ "number", "taxResidenceCountryCode" ] }, "estimatedYearlyIncome": { "type": "string", "description": "Estimated yearly income range of the associate. Mandatory for associates with the `BUSINESS_OWNER` title when onboarding customers from the US states that do not require money transmitter license (MTL). The non-MTL states are **not** listed in [What licenses registrations does BVNK and BVNK's Partners have](https://help.bvnk.com/hc/en-us/articles/11094354781074-What-licenses-registrations-does-BVNK-and-BVNK-s-Partners-have).\n\n- `INCOME_0_TO_50K`: 0 to 50,000 USD\n\n- `INCOME_50K_TO_100K`: 50,000 to 100,000 USD\n\n- `INCOME_100K_TO_250K`: 100,000 to 250,000 USD\n\n- `INCOME_250K_TO_500K`: 250,000 to 500,000 USD\n\n- `INCOME_500K_TO_750K`: 500,000 to 750,000 USD\n\n- `INCOME_750K_TO_1M`: 750,000 to 1,000,000 USD\n\n- `INCOME_ABOVE_1M`: Above 1,000,000 USD", "enum": [ "INCOME_0_TO_50K", "INCOME_50K_TO_100K", "INCOME_100K_TO_250K", "INCOME_250K_TO_500K", "INCOME_500K_TO_750K", "INCOME_750K_TO_1M", "INCOME_ABOVE_1M" ], "example": "INCOME_0_TO_50K" }, "reliance": { "$ref": "#/components/schemas/Reliance" } } }, "titles": { "type": "array", "description": "Job title or position", "items": { "type": "string", "enum": [ "BUSINESS_OWNER", "ACCOUNT_REPRESENTATIVE", "DIRECTOR" ] } }, "ownership": { "type": "object", "description": "Ownership details for the associate.", "properties": { "type": { "type": "string", "description": "Ownership type.\n\n- DIRECT: The associate has a direct, immediate ownership stake or relationship with the company.\n\n- INDIRECT: The associate's ownership or control flows through one or more intermediary entities.", "enum": [ "DIRECT", "INDIRECT" ] }, "percentage": { "type": "number", "description": "Ownership percentage.", "example": 100 } } } } } }, "CustomerReferenceAndStatus": { "type": "object", "required": [ "reference", "status" ], "properties": { "reference": { "type": "string", "format": "uuid", "example": "0a184641-30e2-4414-871f-3db1c683900e" }, "status": { "$ref": "#/components/schemas/CustomerStatusExternal" } } }, "CustomerDto": { "type": "object", "description": "Customer data transfer object", "required": [ "reference", "status", "type" ], "properties": { "reference": { "type": "string", "format": "uuid", "example": "0a184641-30e2-4414-871f-3db1c683900e" }, "status": { "$ref": "#/components/schemas/CustomerStatusExternal" }, "type": { "$ref": "#/components/schemas/CustomerType" }, "company": { "$ref": "#/components/schemas/CorporateCustomer" } } }, "CreateAddress": { "type": "object", "required": [ "addressLine1", "postalCode", "city", "countryCode" ], "properties": { "addressLine1": { "type": "string", "maxLength": 255, "description": "Main address", "example": "123 Main Street" }, "addressLine2": { "type": "string", "maxLength": 255, "description": "Apartment numbers or suite number", "example": "Apartment 456" }, "postalCode": { "type": "string", "maxLength": 255, "description": "Postal code", "example": "NW1 4NP" }, "city": { "type": "string", "maxLength": 255, "description": "City", "example": "London" }, "countryCode": { "$ref": "#/components/schemas/AddressCountryCode" } } }, "ErrorResponse": { "type": "array", "items": { "$ref": "#/components/schemas/Error" } }, "Error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "$ref": "#/components/schemas/ErrorCode" }, "message": { "type": "string", "minLength": 1, "example": "must not be null" }, "fieldName": { "type": "string", "example": "accountId" } } }, "ErrorCode": { "type": "string", "enum": [ "VALIDATION", "FORBIDDEN", "INTERNAL_ERROR" ], "example": "VALIDATION", "description": "Error code:\n * VALIDATION - The request is invalid.\n * FORBIDDEN - Expected error when requested resource does not exist\n * INTERNAL_ERROR - Something unexpected occurred." }, "CreateBusinessCustomerOnboardingRequest": { "type": "object", "description": "Create request for a business customer onboarding application.", "required": [ "onboardingType", "embeddedPartnerCustomer" ], "properties": { "onboardingType": { "type": "string", "description": "Onboarding mode. Must be `EMBEDDED` for the onboarding of your customers.", "enum": [ "EMBEDDED" ], "example": "EMBEDDED" }, "embeddedPartnerCustomer": { "$ref": "#/components/schemas/EmbeddedPartnerCustomerOnboardingPayload" } } }, "EmbeddedPartnerCustomerOnboardingPayload": { "type": "object", "description": "Customer payload containing company details, associates, and product use case.", "required": [ "partnerAccountReference", "company", "useCase", "externalReference" ], "properties": { "partnerAccountReference": { "type": "string", "description": "Unique reference for this customer in your platform.", "example": "partner-ref-001" }, "company": { "$ref": "#/components/schemas/CustomerOnboardingCompany" }, "useCase": { "type": "string", "description": "Product use case for this customer.", "enum": [ "STABLECOIN_PAYOUTS", "EMBEDDED_STABLECOIN_WALLETS", "EMBEDDED_FIAT_ACCOUNTS" ], "example": "STABLECOIN_PAYOUTS" }, "externalReference": { "type": "string", "description": "Your internal reference identifier for this customer.", "example": "ext-ref-001" }, "attestation": { "$ref": "#/components/schemas/RelianceAttestation", "description": "Partner-managed (Reliance) attestation fields. Required for Partner-managed onboarding." }, "reliance": { "$ref": "#/components/schemas/Reliance", "description": "Partner-managed (Reliance) identity and verification metadata. Required for Partner-managed onboarding and jurisdiction-dependent fields." } } }, "CustomerOnboardingCompany": { "type": "object", "description": "Business entity details for customer onboarding.", "required": [ "name", "entityType", "taxNumber", "registrationNumber", "incorporationDate", "businessOperationsStartDate", "address", "businessProfile", "associates" ], "properties": { "name": { "type": "string", "description": "Legal name of the business entity.", "example": "Krause Fintech GmbH" }, "entityType": { "type": "string", "description": "Legal entity type of the business.", "enum": [ "CORPORATION", "LIMITED_LIABILITY_COMPANY", "PUBLICLY_LISTED_COMPANY", "SOLE_PROPRIETOR", "PARTNERSHIP", "TRUST", "PRIVATE_FOUNDATION", "CHARITY", "NON_PROFIT_ORGANIZATION", "PUBLIC_AGENCIES_OR_AUTHORITIES", "OTHER" ], "example": "CORPORATION" }, "taxNumber": { "type": "string", "description": "Tax identification number (for example EIN in the US, VAT or national tax ID in the EU).", "example": "DE123456789" }, "registrationNumber": { "type": "string", "description": "Business registration number (for example HRB in Germany or Companies House number in the UK).", "example": "HRB 123456" }, "incorporationDate": { "type": "string", "format": "date", "description": "Date of incorporation in `YYYY-MM-DD` format.", "example": "2019-01-15" }, "businessOperationsStartDate": { "type": "string", "format": "date", "description": "Date the business began operations in `YYYY-MM-DD` format.", "example": "2019-02-01" }, "address": { "$ref": "#/components/schemas/CustomerOnboardingAddress" }, "businessProfile": { "$ref": "#/components/schemas/CustomerOnboardingBusinessProfile" }, "associates": { "type": "array", "description": "Associated natural persons connected to the business. At least one associate is required.", "minItems": 1, "items": { "$ref": "#/components/schemas/CustomerOnboardingAssociate" } } } }, "CustomerOnboardingAddress": { "type": "object", "description": "Address details. `stateCode` is planned for future mandatory use in US addresses.", "required": [ "addressLine1", "city", "postalCode", "countryCode" ], "properties": { "addressLine1": { "type": "string", "description": "Street address line 1.", "example": "Heidestrasse 19" }, "city": { "type": "string", "description": "City.", "example": "Koeln" }, "postalCode": { "type": "string", "description": "Postcode or ZIP code.", "example": "51247" }, "countryCode": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code.", "example": "DE" }, "stateCode": { "type": "string", "description": "US state code.", "example": "NY" } } }, "CustomerOnboardingBusinessProfile": { "type": "object", "description": "Business context, CDD data, and nature-of-business information.", "required": [ "description", "naicsCode", "monthlyExpectedVolumes", "website", "customerTypes", "prohibitedJurisdictionsExposure", "annualIncomingTransactionValue", "annualOutgoingTransactionValue", "jurisdictionalPortfolioDistribution", "isRegulated", "sourceOfFunds", "intendedUseOfAccount" ], "properties": { "description": { "type": "string", "description": "Brief description of the business and its activities." }, "naicsCode": { "type": "string", "description": "Code from the North American Industry Classification System (NAICS). Applicable to companies based in the US and Mexico. See the full list on the [Industry References](../../../references/industy-references/#industry-reference-table) page.", "example": "5239" }, "monthlyExpectedVolumes": { "type": "string", "description": "Expected monthly transaction volume range.", "enum": [ "UNDER_100K", "FROM_100K_TO_1M", "FROM_1M_TO_10M", "FROM_10M_TO_100M", "OVER_100M" ], "example": "FROM_100K_TO_1M" }, "website": { "type": "string", "format": "uri", "description": "Primary business website URL.", "example": "https://www.krause-fintech.de" }, "customerTypes": { "type": "string", "description": "Types of customers served.", "enum": [ "Both", "Individuals", "Businesses" ], "example": "Both" }, "prohibitedJurisdictionsExposure": { "type": "boolean", "description": "Flag showing whether the business has exposure to prohibited jurisdictions per BVNK risk appetite.", "example": false }, "annualIncomingTransactionValue": { "type": "string", "description": "Estimated annual incoming transaction value in USD equivalent, expressed as numeric string.", "example": "500000" }, "annualOutgoingTransactionValue": { "type": "string", "description": "Estimated annual outgoing transaction value in USD equivalent, expressed as numeric string.", "example": "250000" }, "jurisdictionalPortfolioDistribution": { "type": "array", "description": "Jurisdictions representing 25% or more of portfolio distribution.", "items": { "$ref": "#/components/schemas/CustomerOnboardingJurisdictionDistribution" } }, "isRegulated": { "type": "boolean", "description": "Indicates whether the business holds a regulatory licence.", "example": true }, "sourceOfFunds": { "type": "string", "description": "Primary source of funds. Documentary evidence may be requested during compliance review.", "enum": [ "COMMERCIAL_ACTIVITIES", "SHAREHOLDER_CAPITAL", "VENTURE_CAPITAL", "SALE_OF_ASSETS", "CRYPTO_FUNDRAISING", "CRYPTO_TRADING_REVENUE", "CORPORATE_LOANS", "OTHER" ], "example": "COMMERCIAL_ACTIVITIES" }, "intendedUseOfAccount": { "type": "string", "description": "Intended use of the BVNK account.", "enum": [ "SUPPLIER_VENDOR_PAYMENTS", "INTERCOMPANY_TRANSFER", "PAYROLL", "CUSTOMER_PAYMENTS_RECEIVED", "CUSTOMER_PAYOUTS_REFUNDS_SETTLEMENTS", "OPERATING_EXPENSES", "DIVIDEND_PROFIT_DISTRIBUTIONS", "LOAN_REPAYMENT_FINANCIAL_ACTIVITIES" ], "example": "SUPPLIER_VENDOR_PAYMENTS" } } }, "CustomerOnboardingJurisdictionDistribution": { "type": "object", "required": [ "country", "percentage" ], "properties": { "country": { "type": "string", "description": "ISO 3166-1 alpha-2 country code.", "example": "DE" }, "percentage": { "type": "number", "format": "double", "description": "Percentage allocation for the jurisdiction.", "example": 45 } } }, "CustomerOnboardingAssociate": { "type": "object", "description": "An associate connected to the business.", "required": [ "person", "titles" ], "properties": { "person": { "$ref": "#/components/schemas/CustomerOnboardingAssociatePerson" }, "titles": { "type": "array", "description": "Roles assigned to the associate. At least one title is required.\n\n- `BUSINESS_OWNER`: Ultimate Beneficial Owner\n\n- `SIGNATORY`: authorised signatories, individuals officially empowered by an organization", "minItems": 1, "items": { "type": "string", "enum": [ "BUSINESS_OWNER", "DIRECTOR", "SIGNATORY", "ACCOUNT_REPRESENTATIVE" ] } }, "ownership": { "$ref": "#/components/schemas/CustomerOnboardingOwnership", "description": "Ownership details. Required when `BUSINESS_OWNER` is included in `titles`." } } }, "CustomerOnboardingAssociatePerson": { "type": "object", "description": "Natural person details for an associate.", "required": [ "firstName", "lastName", "dateOfBirth", "address", "contactInfo", "position" ], "properties": { "firstName": { "type": "string", "description": "First name matching the government-issued ID." }, "lastName": { "type": "string", "description": "Last name matching the government-issued ID." }, "dateOfBirth": { "type": "string", "format": "date", "description": "Date of birth in the `YYYY-MM-DD` format." }, "nationality": { "type": "string", "description": "ISO 3166-1 alpha-2 nationality. Required in EU and conditional in US.", "example": "DE" }, "birthCountryCode": { "type": "string", "description": "ISO 3166-1 alpha-2 country of birth. Required in EU and conditional in US.", "example": "DE" }, "address": { "$ref": "#/components/schemas/CustomerOnboardingAddress" }, "contactInfo": { "type": "object", "required": [ "emailAddress" ], "properties": { "emailAddress": { "type": "string", "format": "email", "description": "Email used for verification flow invitations.", "example": "freya.krause@krause-fintech.de" } } }, "taxIdentification": { "$ref": "#/components/schemas/CustomerOnboardingTaxIdentification", "description": "Tax identification details. SSN/TIN is mandatory for US persons." }, "position": { "type": "string", "description": "Role or title at the company.", "example": "CEO" } } }, "CustomerOnboardingTaxIdentification": { "type": "object", "properties": { "number": { "type": "string", "description": "Tax identification number." }, "taxResidenceCountryCode": { "type": "string", "description": "ISO 3166-1 alpha-2 tax residence country code. Required when `taxIdentification.number` is provided.", "example": "DE" } } }, "CustomerOnboardingOwnership": { "type": "object", "properties": { "percentage": { "type": "number", "format": "double", "description": "Ownership percentage.", "example": 100 }, "type": { "type": "string", "description": "Ownership type. Required when `ownership.percentage` is provided.", "enum": [ "DIRECT", "INDIRECT" ], "example": "DIRECT" } } }, "CreateBusinessCustomerOnboardingResponse": { "type": "object", "required": [ "id", "status" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Onboarding application ID used in subsequent onboarding API calls. Save this value for further use." }, "status": { "type": "string", "description": "Initial onboarding status.", "enum": [ "NOT_STARTED", "IN_PROGRESS", "SUBMITTED", "REQUIRED_ACTIONS", "APPROVED", "REJECTED", "SUSPENDED" ], "example": "NOT_STARTED" } } }, "OnboardingStatusResponse": { "type": "object", "required": [ "onboardingId", "status", "createdAt", "updatedAt", "associates", "agreements" ], "properties": { "onboardingId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "description": "Application status.", "enum": [ "NOT_STARTED", "IN_PROGRESS", "SUBMITTED", "REQUIRED_ACTIONS", "APPROVED", "REJECTED", "SUSPENDED" ], "example": "SUBMITTED" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "associates": { "type": "array", "items": { "$ref": "#/components/schemas/OnboardingStatusAssociate" } }, "agreements": { "type": "array", "items": { "$ref": "#/components/schemas/OnboardingStatusAgreement" } } }, "example": { "onboardingId": "810fd34b-54d3-4a95-9d87-28804c3353b9", "status": "SUBMITTED", "createdAt": "2026-03-25T10:57:35.056865Z", "updatedAt": "2026-03-25T10:57:38.991647Z", "associates": [ { "id": "07b099fa-e1ee-4ad4-9cc4-6f2513a5a240", "roles": [ "ACCOUNT_REPRESENTATIVE", "DIRECTOR", "SIGNATORY", "UBO" ], "percentageOfOwnership": 100, "validationStatus": "INVALID", "requiredDocuments": [ { "docSetType": "SELFIE", "types": [ "SELFIE" ], "status": "REJECTED", "rejectLabels": [ "BAD_SELFIE" ], "clientComment": "A new liveness check has been requested." } ], "questionnaireDefinitions": [], "validationErrors": [ { "message": "identificationDocuments must not be empty" } ] } ], "agreements": [ { "id": "9adf3e01-8d13-4fc3-9fc4-8f3f6fd0af44", "name": "Partner Platform Agreement (Non-US)", "status": "PENDING", "declinable": false } ] } }, "OnboardingStatusAssociate": { "type": "object", "required": [ "id", "roles", "validationStatus", "requiredDocuments", "questionnaireDefinitions", "validationErrors" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Associate ID used for document upload and questionnaire submission." }, "roles": { "type": "array", "description": "Roles assigned to the associate. At least one title is required.\n\n- `BUSINESS_OWNER`: Ultimate Beneficial Owner\n\n- `SIGNATORY`: authorised signatories, individuals officially empowered by an organization", "items": { "type": "string", "enum": [ "ACCOUNT_REPRESENTATIVE", "DIRECTOR", "SIGNATORY", "UBO" ] } }, "percentageOfOwnership": { "type": "number", "format": "double", "example": 100 }, "validationStatus": { "type": "string", "enum": [ "VALID", "INVALID" ], "description": "Associate validation status. If the status is `INVALID`, check `requiredDocuments` and `validationErrors` for outstanding items." }, "requiredDocuments": { "type": "array", "description": "Array of the required document sets", "items": { "$ref": "#/components/schemas/OnboardingRequiredDocument" } }, "questionnaireDefinitions": { "type": "array", "description": "Questionnaires that must be completed for the associate. Includes field definitions, options, and validation rules.", "items": { "$ref": "#/components/schemas/OnboardingQuestionnaireDefinition" } }, "validationErrors": { "type": "array", "description": "Specific validation failures for the associate.", "items": { "type": "object", "additionalProperties": true } } } }, "OnboardingRequiredDocument": { "type": "object", "required": [ "docSetType", "types", "status" ], "properties": { "docSetType": { "type": "string", "description": "Document set category.", "example": "SELFIE" }, "types": { "type": "array", "description": "Accepted document types for this set.", "items": { "type": "string" } }, "status": { "type": "string", "description": "Document status.\n\n- `NOT_SUBMITTED`: Document not yet uploaded. Action required.\n- `PENDING`: Document uploaded and queued for verification.\n- `APPROVED`: Document verified and accepted.\n- `REJECTED`: Document failed verification. Check `rejectLabels` and `clientComment` for reason. Resubmission required.", "enum": [ "NOT_SUBMITTED", "PENDING", "APPROVED", "REJECTED" ] }, "rejectLabels": { "type": "array", "items": { "type": "string" } }, "clientComment": { "type": "string" } } }, "OnboardingQuestionnaireDefinition": { "type": "object", "description": "Questionnaire definition assigned to an associate.", "required": [ "id", "sections" ], "properties": { "id": { "type": "string", "description": "Questionnaire identifier used when submitting responses.", "example": "estimatedYearlyIncome" }, "title": { "type": "string", "description": "Human-readable questionnaire title." }, "sections": { "type": "object", "description": "Questionnaire sections keyed by section ID.", "additionalProperties": { "$ref": "#/components/schemas/OnboardingQuestionnaireSectionDefinition" } } } }, "OnboardingQuestionnaireSectionDefinition": { "type": "object", "description": "Questionnaire section definition.", "properties": { "label": { "type": "string", "description": "Section label." }, "items": { "type": "object", "description": "Questionnaire fields keyed by field ID.", "additionalProperties": { "$ref": "#/components/schemas/OnboardingQuestionnaireFieldDefinition" } } } }, "OnboardingQuestionnaireFieldDefinition": { "type": "object", "description": "Questionnaire field definition with accepted options and validation rules.", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "description": "Field identifier.", "example": "estimatedYearlyIncome" }, "type": { "type": "string", "description": "Field type.", "example": "SELECT" }, "label": { "type": "string", "description": "Field label presented to users." }, "required": { "type": "boolean", "description": "Whether the field is mandatory." }, "options": { "type": "array", "description": "Accepted option values for selectable fields.", "items": { "$ref": "#/components/schemas/OnboardingQuestionnaireOptionDefinition" } }, "validationRules": { "type": "array", "description": "Validation rules applied to the field.", "items": { "$ref": "#/components/schemas/OnboardingQuestionnaireValidationRule" } } } }, "OnboardingQuestionnaireOptionDefinition": { "type": "object", "description": "Selectable option for a questionnaire field.", "required": [ "value" ], "properties": { "value": { "type": "string", "description": "Option value submitted in questionnaire responses.", "example": "INCOME_100K_TO_250K" }, "label": { "type": "string", "description": "Display label for the option." } } }, "OnboardingQuestionnaireValidationRule": { "type": "object", "description": "Validation rule for a questionnaire field.", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "Validation rule type.", "example": "REQUIRED" }, "value": { "type": "string", "description": "Optional rule parameter value.", "nullable": true }, "message": { "type": "string", "description": "Validation error message." } } }, "OnboardingStatusAgreement": { "type": "object", "required": [ "id", "name", "status", "declinable" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "PENDING", "ACCEPTED", "DECLINED" ] }, "declinable": { "type": "boolean" } } }, "OnboardingCompanyDocumentsUploadRequest": { "type": "object", "required": [ "metadata", "files" ], "properties": { "metadata": { "type": "string", "description": "JSON array (string) of company document metadata entries with `type`, `filename`, and optional `description`.\n\nSupported company document types:\n\n| Type | Description | When required |\n| --- | --- | --- |\n| `CERTIFICATE_OF_INCORPORATION` | Certificate of incorporation or business formation document. | Mandatory (US + EU BVNK-Managed, US Partner-managed) |\n| `MEMORANDUM` | Memorandum of Association. | Mandatory (BVNK-Managed) |\n| `ARTICLE_OF_ASSOCIATION` | Articles of Association. | Mandatory (BVNK-Managed) |\n| `PROOF_OF_DIRECTORSHIP` | Registry extract or certified register of directors. | Mandatory (BVNK-Managed) |\n| `CORPORATE_STRUCTURE` | Ownership chart showing all shareholders through to UBOs. | Mandatory (BVNK-Managed) |\n| `PROOF_OF_OPERATIONAL_ADDRESS` | Utility bill, lease, or official correspondence. Dated within 3 months. | Required if operational address differs from registered |\n| `SOURCE_OF_FUNDS` | Bank statements (3 months activity) or equivalent. | May be requested during compliance review (RFI) |\n| `SOURCE_OF_WEALTH` | Audited accounts, financial statements, loan agreements. | Conditional: triggered by high-risk rating or EDD |\n| `PROOF_OF_REGULATORY_LICENSE` | Current regulatory licence for the declared jurisdiction. | Conditional: required for regulated entities |\n| `AML_POLICY` | AML policy signed by Director/MLRO. | Conditional: required for regulated entities |\n| `SHAREHOLDER_OWNERSHIP` | Ownership documentation for complex structures. | Conditional: trusts, nominees, >3 layers, offshore |", "example": "[{\"type\":\"CERTIFICATE_OF_INCORPORATION\",\"filename\":\"certificate.png\",\"description\":\"Certificate of Incorporation\"},{\"type\":\"MEMORANDUM\",\"filename\":\"memorandum.png\",\"description\":\"Memorandum of Association\"},{\"type\":\"ARTICLE_OF_ASSOCIATION\",\"filename\":\"articles.png\",\"description\":\"Articles of Association\"},{\"type\":\"PROOF_OF_DIRECTORSHIP\",\"filename\":\"directorship.png\",\"description\":\"Proof of Directorship\"},{\"type\":\"CORPORATE_STRUCTURE\",\"filename\":\"corporate_structure.png\",\"description\":\"Corporate Structure Chart\"},{\"type\":\"PROOF_OF_OPERATIONAL_ADDRESS\",\"filename\":\"address_proof.png\",\"description\":\"Proof of Operational Address\"}]" }, "files": { "type": "array", "description": "One file per metadata entry, in matching order.", "items": { "type": "string", "format": "binary" } } } }, "OnboardingCompanyDocumentsUploadResponse": { "type": "object", "required": [ "onboardingApplicationId", "documentCount", "message" ], "properties": { "onboardingApplicationId": { "type": "string", "format": "uuid" }, "documentCount": { "type": "integer" }, "message": { "type": "string" } } }, "OnboardingAssociateIdentificationDocumentsUploadRequest": { "type": "object", "required": [ "metadata", "files" ], "properties": { "metadata": { "type": "string", "description": "JSON array (string) of associate identification document metadata entries with `type`, `name`, and `countryCode`. You need to submit any document of the following as an ID: `PASSPORT`, `ID_CARD`, `DRIVERS`, `RESIDENCE_PERMIT`.\n\nSupported associate document types:\n\n| Type | Description | When required |\n| --- | --- | --- |\n| `PASSPORT` | Passport. | Identity document required |\n| `ID_CARD` | National identity card. | Alternative to passport |\n| `DRIVERS` | Driver's licence. | Alternative to passport |\n| `RESIDENCE_PERMIT` | Residence permit. | Alternative to passport |\n| `UTILITY_BILL` | Proof of residential address. Must be dated within the last three months. | EU: Mandatory. US: Conditional |\n| `SELFIE` | Biometric selfie / liveness capture. | EU: Mandatory. US: Optional |", "example": "[{\"type\":\"PASSPORT\",\"name\":\"passport.png\",\"countryCode\":\"DE\"},{\"type\":\"UTILITY_BILL\",\"name\":\"poa.png\",\"countryCode\":\"DE\"},{\"type\":\"SELFIE\",\"name\":\"selfie.jpeg\",\"countryCode\":\"DE\"}]" }, "files": { "type": "array", "description": "One file per metadata entry, in matching order.", "items": { "type": "string", "format": "binary" } } } }, "OnboardingAssociateIdentificationDocumentsUploadResponse": { "type": "object", "required": [ "associateId", "acceptedDocumentCount", "message" ], "properties": { "associateId": { "type": "string", "format": "uuid" }, "acceptedDocumentCount": { "type": "integer" }, "message": { "type": "string" } } }, "OnboardingAssociateQuestionnairesSubmitRequest": { "type": "object", "required": [ "questionnaires" ], "properties": { "questionnaires": { "type": "array", "description": "Questionnaires to submit. Structure should match `questionnaireDefinitions` from status response.", "items": { "type": "object", "additionalProperties": true } } } }, "OnboardingAssociateQuestionnairesSubmitResponse": { "type": "object", "required": [ "success", "message", "submittedCount" ], "properties": { "success": { "type": "boolean" }, "message": { "type": "string" }, "submittedCount": { "type": "integer" } } }, "OnboardingAssignedAgreement": { "type": "object", "required": [ "id", "applicationId", "agreement", "status", "createdAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "applicationId": { "type": "string", "format": "uuid" }, "agreement": { "$ref": "#/components/schemas/OnboardingAgreementDetails" }, "status": { "type": "string", "enum": [ "PENDING", "ACCEPTED", "DECLINED" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "example": { "id": "06d119bc-64f6-46b2-aea2-3ff94c4c616f", "applicationId": "810fd34b-54d3-4a95-9d87-28804c3353b9", "agreement": { "id": "c83a528b-8c7a-4d95-9fbb-3fbe14332f7b", "name": "Partner Platform Agreement (Non-US)", "description": "Terms and conditions for Partner Platform customers outside the US", "urn": "urn:agreement:epc-partner-platform-non-us", "agreementType": "EXTERNAL_LINK", "externalUrl": "https://help.bvnk.com/hc/en-us/sections/example", "declinable": false }, "status": "PENDING", "createdAt": "2026-03-25T10:57:38.145505Z" } }, "OnboardingAgreementDetails": { "type": "object", "required": [ "id", "name", "description", "urn", "agreementType", "declinable" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": "string" }, "urn": { "type": "string" }, "agreementType": { "type": "string", "enum": [ "EXTERNAL_LINK" ] }, "externalUrl": { "type": "string", "format": "uri" }, "declinable": { "type": "boolean" } } }, "OnboardingAssignedAgreementAcceptResponse": { "type": "object", "required": [ "status", "respondedAt", "respondedBy" ], "properties": { "status": { "type": "string", "enum": [ "ACCEPTED" ] }, "respondedAt": { "type": "string", "format": "date-time" }, "respondedBy": { "type": "object", "required": [ "type", "username" ], "properties": { "type": { "type": "string", "example": "USER" }, "username": { "type": "string", "example": "partner@example.com" } } } } }, "V2Address": { "type": "object", "description": "Postal address. `stateCode` is planned for future mandatory use in US addresses.", "properties": { "addressLine1": { "type": "string", "maxLength": 255, "description": "First line of the street address.", "example": "Heidestrasse 19" }, "addressLine2": { "type": "string", "maxLength": 255, "description": "Second line of the street address. Optional." }, "city": { "type": "string", "maxLength": 255, "description": "City or locality.", "example": "Koeln" }, "postalCode": { "type": "string", "maxLength": 255, "description": "Postal or ZIP code.", "example": "51247" }, "stateCode": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-2 subdivision code (US state).", "example": "NY" }, "countryCode": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code.", "example": "DE" } } }, "V2TaxIdentification": { "type": "object", "description": "Tax identification details.", "required": [ "number", "taxResidenceCountryCode" ], "properties": { "number": { "type": "string", "maxLength": 255, "description": "Tax identification number. For US residents, SSN or ITIN; for the rest of the world, the local tax number.", "example": "21/815/08150" }, "taxResidenceCountryCode": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Tax residence country as an ISO 3166-1 alpha-2 country code.", "example": "DE" } } }, "V2ContactInfo": { "type": "object", "description": "Contact details.", "properties": { "emailAddress": { "type": "string", "format": "email", "description": "Email address.", "example": "freya.krause@krause-fintech.de" }, "phoneNumber": { "type": "string", "description": "Phone number in international format.", "example": "+4915112345678" } } }, "V2Ownership": { "type": "object", "required": [ "percentage", "type" ], "description": "Ownership breakdown for an associate person.", "properties": { "percentage": { "type": "string", "format": "number", "minimum": 0, "maximum": 100, "description": "Ownership percentage held by the associate. A value between `0` and `100`.", "example": "100" }, "type": { "type": "string", "description": "Type of ownership:\n\n- `DIRECT`: Directly held ownership\n\n- `INDIRECT`: Ownership held through an intermediary entity", "enum": [ "DIRECT", "INDIRECT" ], "example": "DIRECT" } } }, "V2JurisdictionAllocation": { "type": "object", "required": [ "country", "percentage" ], "properties": { "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2 country code.", "example": "DE" }, "percentage": { "type": "integer", "minimum": 25, "maximum": 100, "description": "Portfolio allocation percentage for the jurisdiction.", "example": 45 } } }, "V2RegulatorInformation": { "type": "object", "description": "Regulator information. Required when `isRegulated` is true.", "properties": { "regulatorName": { "type": "string", "description": "Name of the financial regulator overseeing the company.", "example": "BaFin" }, "regulatorJurisdiction": { "type": "string", "description": "Jurisdiction of the regulator as an ISO 3166-1 alpha-2 country code.", "example": "DE" } } }, "V2PublicInformation": { "type": "object", "description": "Public-listing information. Required when `isPubliclyListed` is true.", "properties": { "listedExchange": { "type": "string", "description": "Name of the stock exchange where the company is listed.", "example": "NYSE" }, "tickerSymbol": { "type": "string", "description": "The company's ticker symbol on the exchange.", "example": "ACME" } } }, "V2BusinessProfile": { "type": "object", "description": "Business context, CDD data, and nature-of-business information.", "properties": { "description": { "type": "string", "maxLength": 255, "description": "Short description of the company and its business activities.", "example": "German fintech company specializing in payment solutions and financial software" }, "naicsCode": { "type": "string", "minLength": 2, "maxLength": 6, "pattern": "^\\d+$", "description": "Code from the North American Industry Classification System (NAICS).", "example": "5411" }, "monthlyExpectedVolumes": { "type": "string", "description": "Business's expected monthly transaction volume:\n\n- `FROM_0_TO_10K`: 0 to 10,000 USD equivalent\n\n- `FROM_10K_TO_50K`: 10,000 to 50,000 USD equivalent\n\n- `FROM_50K_TO_100K`: 50,000 to 100,000 USD equivalent\n\n- `FROM_100K_TO_1M`: 100,000 to 1,000,000 USD equivalent\n\n- `FROM_1M_TO_10M`: 1,000,000 to 10,000,000 USD equivalent\n\n- `ABOVE_10M`: Above 10,000,000 USD equivalent", "enum": [ "FROM_0_TO_10K", "FROM_10K_TO_50K", "FROM_50K_TO_100K", "FROM_100K_TO_1M", "FROM_1M_TO_10M", "ABOVE_10M" ], "example": "FROM_100K_TO_1M" }, "website": { "type": "string", "format": "uri", "description": "Website URL of the company.", "example": "https://www.krause-fintech.de" }, "customerTypes": { "type": "string", "description": "Types of customers the business serves:\n\n- `Individuals`: Individual customers only\n\n- `Businesses`: Business customers only\n\n- `Both`: Both individual and business customers", "enum": [ "Individuals", "Businesses", "Both" ], "example": "Both" }, "prohibitedJurisdictionsExposure": { "type": "boolean", "description": "Whether the business has exposure to prohibited jurisdictions.", "example": false }, "annualIncomingTransactionValue": { "type": "string", "maxLength": 50, "description": "Expected annual incoming transaction value.", "example": "500000" }, "annualOutgoingTransactionValue": { "type": "string", "maxLength": 50, "description": "Expected annual outgoing transaction value.", "example": "250000" }, "jurisdictionalPortfolioDistribution": { "type": "array", "maxItems": 4, "description": "Breakdown of the company's portfolio allocation across jurisdictions. Up to four entries.", "items": { "$ref": "#/components/schemas/V2JurisdictionAllocation" } }, "isRegulated": { "type": "boolean", "description": "Whether the company is regulated by a financial authority. If `true`, `regulatorInformation` is required.", "example": true }, "regulatorInformation": { "$ref": "#/components/schemas/V2RegulatorInformation" }, "isPubliclyListed": { "type": "boolean", "description": "Whether the company is publicly listed on a stock exchange. If `true`, `publicInformation` is required.", "example": false }, "publicInformation": { "$ref": "#/components/schemas/V2PublicInformation" }, "sourceOfFunds": { "type": "string", "description": "Business's source of funds:\n\n- `COMMERCIAL_ACTIVITIES`: Revenue from commercial activities\n\n- `SHAREHOLDER_CAPITAL`: Shareholder capital contributions\n\n- `VENTURE_CAPITAL`: Venture capital funding\n\n- `SALE_OF_ASSETS`: Proceeds from sale of assets\n\n- `CRYPTO_FUNDRAISING`: Crypto fundraising proceeds\n\n- `CRYPTO_TRADING_REVENUE`: Revenue from crypto trading\n\n- `CORPORATE_LOANS`: Corporate loans\n\n- `OTHER`: Other sources", "enum": [ "COMMERCIAL_ACTIVITIES", "SHAREHOLDER_CAPITAL", "VENTURE_CAPITAL", "SALE_OF_ASSETS", "CRYPTO_FUNDRAISING", "CRYPTO_TRADING_REVENUE", "CORPORATE_LOANS", "OTHER" ], "example": "COMMERCIAL_ACTIVITIES" }, "intendedUseOfAccount": { "type": "string", "description": "Purpose of the business account:\n\n- `SUPPLIER_VENDOR_PAYMENTS`: Supplier and vendor payments\n\n- `INTERCOMPANY_TRANSFERS`: Intercompany transfers\n\n- `PAYROLL`: Payroll\n\n- `CUSTOMER_PAYMENTS_RECEIVED`: Customer payments received\n\n- `CUSTOMER_PAYOUTS_REFUNDS_SETTLEMENTS`: Customer payouts, refunds, and settlements\n\n- `OPERATING_EXPENSES`: Operating expenses\n\n- `DIVIDEND_PROFIT_DISTRIBUTIONS`: Dividend and profit distributions\n\n- `LOAN_REPAYMENT_FINANCIAL_ACTIVITIES`: Loan repayment and financial activities", "enum": [ "SUPPLIER_VENDOR_PAYMENTS", "INTERCOMPANY_TRANSFERS", "PAYROLL", "CUSTOMER_PAYMENTS_RECEIVED", "CUSTOMER_PAYOUTS_REFUNDS_SETTLEMENTS", "OPERATING_EXPENSES", "DIVIDEND_PROFIT_DISTRIBUTIONS", "LOAN_REPAYMENT_FINANCIAL_ACTIVITIES" ], "example": "SUPPLIER_VENDOR_PAYMENTS" } } }, "V2AssociatePerson": { "type": "object", "description": "Natural person associated with a corporate customer.", "required": [ "address", "dateOfBirth", "nationality" ], "properties": { "firstName": { "type": "string", "description": "First name of the associate.", "example": "Freya" }, "lastName": { "type": "string", "description": "Last name of the associate.", "example": "Krause" }, "dateOfBirth": { "type": "string", "format": "date", "description": "Date of birth in ISO-8601 format (`YYYY-MM-DD`).", "example": "1982-03-24" }, "nationality": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Primary nationality as an ISO 3166-1 alpha-2 country code.", "example": "DE" }, "secondNationality": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Second nationality as an ISO 3166-1 alpha-2 country code. Optional." }, "birthCountryCode": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Birth country as an ISO 3166-1 alpha-2 country code.", "example": "DE" }, "address": { "allOf": [ { "$ref": "#/components/schemas/V2Address" }, { "description": "Residential address of the associate." } ] }, "contactInfo": { "allOf": [ { "$ref": "#/components/schemas/V2ContactInfo" }, { "description": "Contact details of the associate." } ] }, "taxIdentification": { "allOf": [ { "$ref": "#/components/schemas/V2TaxIdentification" }, { "description": "Tax identification details of the associate." } ] }, "position": { "type": "string", "maxLength": 255, "description": "Position or job title of the associate within the company.", "example": "Geschaeftsfuehrer" } } }, "V2CorporateCustomerAssociate": { "type": "object", "description": "An associate of a corporate customer, with titles and optional ownership.", "required": [ "person", "titles" ], "properties": { "person": { "$ref": "#/components/schemas/V2AssociatePerson" }, "titles": { "type": "array", "minItems": 1, "description": "Associate titles. At least one is required:\n\n- `UBO`: Ultimate Beneficial Owner\n\n- `CONTROL_PERSON`: Person with control over the entity\n\n- `SIGNATORY`: Authorized signatory\n\n- `DIRECTOR`: Company director\n\n- `ACCOUNT_REPRESENTATIVE`: Primary point of contact for the account", "items": { "type": "string", "enum": [ "UBO", "CONTROL_PERSON", "SIGNATORY", "DIRECTOR", "ACCOUNT_REPRESENTATIVE" ] } }, "ownership": { "$ref": "#/components/schemas/V2Ownership" } } }, "V2CreateCompanyRequest": { "type": "object", "description": "Corporate customer details. Required when creating a company customer.", "required": [ "businessOperationsStartDate", "incorporationDate" ], "properties": { "name": { "type": "string", "description": "Legal name of the company.", "maxLength": 255, "example": "Krause Fintech GmbH" }, "entityType": { "type": "string", "description": "Business entity type:\n\n- `LIMITED_LIABILITY_COMPANY`: Limited Liability Company\n\n- `CORPORATION`: Corporation\n\n- `PARTNERSHIP`: Partnership\n\n- `SOLE_PROPRIETOR`: Sole proprietor\n\n- `PUBLICLY_LISTED_COMPANY`: Publicly listed company\n\n- `TRUST`: Trust\n\n- `PRIVATE_FOUNDATION`: Private foundation\n\n- `CHARITY`: Charity\n\n- `NON_PROFIT_ORGANIZATION`: Non-profit organization\n\n- `PUBLIC_AGENCIES_OR_AUTHORITIES`: Public agencies or authorities", "enum": [ "LIMITED_LIABILITY_COMPANY", "CORPORATION", "PARTNERSHIP", "SOLE_PROPRIETOR", "PUBLICLY_LISTED_COMPANY", "TRUST", "PRIVATE_FOUNDATION", "CHARITY", "NON_PROFIT_ORGANIZATION", "PUBLIC_AGENCIES_OR_AUTHORITIES" ], "example": "CORPORATION" }, "taxIdentification": { "allOf": [ { "$ref": "#/components/schemas/V2TaxIdentification" }, { "description": "Tax identification details of the company." } ] }, "registrationNumber": { "type": "string", "description": "Official company registration number.", "example": "HRB 123456" }, "businessProfile": { "allOf": [ { "$ref": "#/components/schemas/V2BusinessProfile" }, { "description": "Business context, customer due diligence data, and nature-of-business information." } ] }, "address": { "allOf": [ { "$ref": "#/components/schemas/V2Address" }, { "description": "Registered address of the company." } ] }, "isOperationalAddressDifferent": { "type": "boolean", "description": "Whether the operational address of the company differs from the registered address. If `true`, `operationalAddress` is required.", "example": false }, "operationalAddress": { "allOf": [ { "$ref": "#/components/schemas/V2Address" }, { "description": "Operational address of the company. Optional. Specify if different from `address`." } ] }, "incorporationDate": { "type": "string", "format": "date", "description": "Incorporation date of the company in the ISO-8601 format (`YYYY-MM-DD`).", "example": "2019-01-15" }, "businessOperationsStartDate": { "type": "string", "format": "date", "description": "Actual date when the company began conducting its business activities or commercial operations. ISO-8601 format (`YYYY-MM-DD`).", "example": "2019-02-01" }, "associates": { "type": "array", "description": "Associates of the corporate customer, such as UBOs, directors, signatories, control persons, and account representatives.", "items": { "$ref": "#/components/schemas/V2CorporateCustomerAssociate" } } } }, "V2IndividualCustomerDueDiligence": { "type": "object", "description": "Customer due-diligence answers for an individual customer.", "properties": { "employmentStatus": { "type": "string", "description": "Employment status:\n\n- `SALARIED`: Salaried\n\n- `SELF_EMPLOYED`: Self employed and freelancer\n\n- `UNEMPLOYED`: Unemployed\n\n- `RETIRED`: Retired", "enum": [ "SALARIED", "SELF_EMPLOYED", "UNEMPLOYED", "RETIRED" ], "example": "SALARIED" }, "sourceOfFunds": { "type": "string", "description": "Source of funds:\n\n- `SALARY`: Salary and employment income\n\n- `PENSION`: Pension and retirement income\n\n- `SAVINGS`: Savings and investments\n\n- `SELF_EMPLOYMENT`: Self employment and business income\n\n- `CRYPTO_TRADING`: Crypto trading\n\n- `GAMBLING`: Gambling and lottery winnings\n\n- `REAL_ESTATE`: Real estate sales", "enum": [ "SALARY", "PENSION", "SAVINGS", "SELF_EMPLOYMENT", "CRYPTO_TRADING", "GAMBLING", "REAL_ESTATE" ], "example": "SALARY" }, "pepStatus": { "type": "string", "description": "Politically Exposed Person status:\n\n- `NOT_PEP`: Not a PEP\n\n- `FORMER_PEP_2_YEARS`: Former or inactive PEP (within 2 years)\n\n- `FORMER_PEP_OLDER`: Former or inactive PEP (older than 2 years)\n\n- `DOMESTIC_PEP`: Domestic PEP\n\n- `FOREIGN_PEP`: Foreign PEP\n\n- `CLOSE_ASSOCIATES`: Close associates\n\n- `FAMILY_MEMBERS`: Family members\n\n- `STATE_OWNED`: State-owned entity (entity only)", "enum": [ "NOT_PEP", "FORMER_PEP_2_YEARS", "FORMER_PEP_OLDER", "DOMESTIC_PEP", "FOREIGN_PEP", "CLOSE_ASSOCIATES", "FAMILY_MEMBERS", "STATE_OWNED" ], "example": "NOT_PEP" }, "intendedUseOfAccount": { "type": "string", "description": "Purpose of the account:\n\n- `TRANSFERS_OWN_WALLET`: Transfers to or from own wallet including bank accounts\n\n- `TRANSFERS_FAMILY_FRIENDS`: Transfers to or from family and friends\n\n- `INVESTMENTS`: Investments\n\n- `GOODS_SERVICES`: Purchases of goods and services\n\n- `DONATIONS`: Donations", "enum": [ "TRANSFERS_OWN_WALLET", "TRANSFERS_FAMILY_FRIENDS", "INVESTMENTS", "GOODS_SERVICES", "DONATIONS" ], "example": "GOODS_SERVICES" }, "expectedMonthlyVolume": { "type": "string", "description": "Individual's expected monthly transaction volume:\n\n- `FROM_0_TO_10K`: 0 to 10,000 USD equivalent\n\n- `FROM_10K_TO_50K`: 10,000 to 50,000 USD equivalent\n\n- `FROM_50K_TO_100K`: 50,000 to 100,000 USD equivalent\n\n- `FROM_100K_TO_1M`: 100,000 to 1,000,000 USD equivalent\n\n- `FROM_1M_TO_10M`: 1,000,000 to 10,000,000 USD equivalent\n\n- `ABOVE_10M`: Above 10,000,000 USD equivalent", "enum": [ "FROM_0_TO_10K", "FROM_10K_TO_50K", "FROM_50K_TO_100K", "FROM_100K_TO_1M", "FROM_1M_TO_10M", "ABOVE_10M" ], "example": "FROM_0_TO_10K" } } }, "V2CreateIndividualRequest": { "type": "object", "description": "Individual customer details. Required when creating an individual customer.", "required": [ "address", "dateOfBirth", "firstName", "lastName" ], "properties": { "firstName": { "type": "string", "description": "First name.", "example": "Jane" }, "lastName": { "type": "string", "description": "Last name.", "example": "Mueller" }, "emailAddress": { "type": "string", "format": "email", "description": "Email address.", "example": "jane.mueller@example.com" }, "phoneNumber": { "type": "string", "maxLength": 255, "description": "Phone number in international format. Optional.", "example": "+49301234567" }, "description": { "type": "string", "maxLength": 255, "description": "Additional notes or description of this individual customer. This field can include relevant background information, special requirements, customer preferences, account purpose, or any other details that may be helpful for future reference." }, "dateOfBirth": { "type": "string", "format": "date", "description": "Date of birth in ISO-8601 format (`YYYY-MM-DD`).", "example": "1990-06-15" }, "placeOfBirth": { "type": "string", "maxLength": 255, "description": "Place of birth (city or locality).", "example": "Berlin" }, "documentNumber": { "type": "string", "description": "Identification document number (for example, passport or national ID)." }, "nationality": { "type": "string", "minLength": 2, "maxLength": 2, "description": "Nationality as an ISO 3166-1 alpha-2 country code. **Required for EU customers**.", "example": "DE" }, "address": { "allOf": [ { "$ref": "#/components/schemas/V2Address" }, { "description": "Residential address of the individual." } ] }, "taxIdentification": { "allOf": [ { "$ref": "#/components/schemas/V2TaxIdentification" }, { "description": "Tax identification details. **Required for US residents** (SSN/ITIN); tax number for rest of the world." } ] }, "cdd": { "allOf": [ { "$ref": "#/components/schemas/V2IndividualCustomerDueDiligence" }, { "description": "Customer Due Diligence (CDD) details for the individual." } ] } } }, "V2CreateCustomerRequest": { "type": "object", "description": "Create-customer request payload.", "required": [ "useCase" ], "properties": { "useCase": { "type": "string", "enum": [ "FIAT", "CRYPTO", "STABLECOIN_PAYOUTS", "EMBEDDED_STABLECOIN_WALLETS", "EMBEDDED_FIAT_ACCOUNTS" ], "example": "STABLECOIN_PAYOUTS" }, "company": { "$ref": "#/components/schemas/V2CreateCompanyRequest" }, "individual": { "$ref": "#/components/schemas/V2CreateIndividualRequest" }, "reference": { "type": "string", "description": "Partner-supplied reference. Unique within the caller's account.", "example": "b3a4c1e2-9a1f-4c2b-8f11-7c2e5d4f9a01" } } }, "V2AuthenticatedLinkResponse": { "type": "object", "description": "Authenticated deep-link for the customer.", "properties": { "link": { "type": "string", "description": "Authenticated link URL." }, "expiresAt": { "type": "string", "format": "date-time", "description": "Link expiration timestamp." } } }, "V2RequiredAction": { "type": "object", "description": "An action a partner or customer must take to progress onboarding.", "properties": { "type": { "type": "string", "enum": [ "DATA", "USER_ROLE", "BLOCKER" ], "description": "Kind of action required." }, "code": { "type": "string", "description": "Stable machine-readable identifier (UPPER_SNAKE_CASE)." }, "category": { "type": "string", "description": "Category of data being requested. Present only for `type=DATA`." }, "description": { "type": "string", "description": "Human-readable label, when available." } } }, "V2CustomerResponse": { "type": "object", "description": "Customer details.", "properties": { "id": { "type": "string", "format": "uuid", "example": "0a184641-30e2-4414-871f-3db1c683900e" }, "reference": { "type": "string", "example": "b3a4c1e2-9a1f-4c2b-8f11-7c2e5d4f9a01" }, "status": { "type": "string", "enum": [ "INFO_REQUIRED", "PENDING", "ACTIONS_REQUIRED", "VERIFIED", "REJECTED", "TERMINATED" ], "example": "PENDING" }, "type": { "type": "string", "enum": [ "COMPANY", "INDIVIDUAL" ], "example": "COMPANY" }, "model": { "type": "string", "enum": [ "CUSTOMER_VIRTUAL_ACCOUNTS", "EMBEDDED_BVNK_MANAGED", "EMBEDDED_SELF_MANAGED", "DOUBLE_EMBEDDED" ], "example": "EMBEDDED_BVNK_MANAGED" }, "useCase": { "type": "string", "enum": [ "FIAT", "CRYPTO", "STABLECOIN_PAYOUTS", "EMBEDDED_STABLECOIN_WALLETS", "EMBEDDED_FIAT_ACCOUNTS" ], "example": "STABLECOIN_PAYOUTS" }, "name": { "type": "string", "example": "Krause Fintech GmbH" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "authenticatedLink": { "$ref": "#/components/schemas/V2AuthenticatedLinkResponse" }, "requiredActions": { "type": "array", "description": "Actions the partner or customer must take to progress onboarding. Empty when the customer is in a terminal state or no actions are pending. Omitted when the upstream status is temporarily unavailable.", "items": { "$ref": "#/components/schemas/V2RequiredAction" } } } }, "V2CustomerDetailResponse": { "type": "object", "description": "Customer details including the submitted onboarding body. `requiredActions`, `company`, `individual`, and `company.associates` are each omitted when the corresponding upstream call is temporarily unavailable. Business-registration associates are not inlined; fetch them via GET /platform/v2/customers/{customerId}/associates/{associateId}.", "properties": { "id": { "type": "string", "format": "uuid" }, "reference": { "type": "string" }, "status": { "type": "string", "enum": [ "INFO_REQUIRED", "PENDING", "ACTIONS_REQUIRED", "VERIFIED", "REJECTED", "TERMINATED" ] }, "type": { "type": "string", "enum": [ "COMPANY", "INDIVIDUAL" ] }, "model": { "type": "string", "enum": [ "CUSTOMER_VIRTUAL_ACCOUNTS", "EMBEDDED_BVNK_MANAGED", "EMBEDDED_SELF_MANAGED", "DOUBLE_EMBEDDED" ] }, "useCase": { "type": "string", "enum": [ "FIAT", "CRYPTO", "STABLECOIN_PAYOUTS", "EMBEDDED_STABLECOIN_WALLETS", "EMBEDDED_FIAT_ACCOUNTS" ] }, "name": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "authenticatedLink": { "$ref": "#/components/schemas/V2AuthenticatedLinkResponse" }, "requiredActions": { "type": "array", "items": { "$ref": "#/components/schemas/V2RequiredAction" } }, "company": { "$ref": "#/components/schemas/V2CreateCompanyRequest", "description": "Submitted corporate body, including any linked person associates under `company.associates`. Present when `type=COMPANY` and the upstream record could be fetched. Business-registration associates are filtered out of the inline list and remain accessible via GET /platform/v2/customers/{customerId}/associates/{associateId}." }, "individual": { "$ref": "#/components/schemas/V2CreateIndividualRequest", "description": "Submitted individual body. Present when `type=INDIVIDUAL` and the upstream record could be fetched." } } }, "V2CustomerSummaryResponse": { "type": "object", "description": "Customer search result.", "properties": { "id": { "type": "string", "format": "uuid" }, "reference": { "type": "string" }, "status": { "type": "string", "enum": [ "INFO_REQUIRED", "PENDING", "ACTIONS_REQUIRED", "VERIFIED", "REJECTED", "TERMINATED" ] }, "type": { "type": "string", "enum": [ "COMPANY", "INDIVIDUAL" ] }, "model": { "type": "string", "enum": [ "CUSTOMER_VIRTUAL_ACCOUNTS", "EMBEDDED_BVNK_MANAGED", "EMBEDDED_SELF_MANAGED", "DOUBLE_EMBEDDED" ] }, "name": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "authenticatedLink": { "$ref": "#/components/schemas/V2AuthenticatedLinkResponse" } } }, "V2Pageable": { "type": "object", "properties": { "pageNumber": { "type": "integer", "minimum": 0 }, "pageSize": { "type": "integer", "minimum": 1, "maximum": 500 } } }, "V2PaginatedCustomerSummaryResponse": { "type": "object", "properties": { "totalElements": { "type": "integer", "format": "int64" }, "totalPages": { "type": "integer" }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/V2CustomerSummaryResponse" } }, "pageable": { "$ref": "#/components/schemas/V2Pageable" }, "hasNext": { "type": "boolean" } } }, "V2CustomerDocumentMetadata": { "type": "object", "description": "Metadata for a single uploaded company document.", "required": [ "filename", "type" ], "properties": { "type": { "type": "string", "maxLength": 50, "description": "Document type.\n\nSupported company document types:\n\n| Type | Description | When required |\n| --- | --- | --- |\n| `CERTIFICATE_OF_INCORPORATION` | Certificate of incorporation or business formation document. | Mandatory (US + EU BVNK-Managed, US Partner-managed) |\n| `MEMORANDUM` | Memorandum of Association. | Mandatory (BVNK-Managed) |\n| `ARTICLE_OF_ASSOCIATION` | Articles of Association. | Mandatory (BVNK-Managed) |\n| `PROOF_OF_DIRECTORSHIP` | Registry extract or certified register of directors. | Mandatory (BVNK-Managed) |\n| `CORPORATE_STRUCTURE` | Ownership chart showing all shareholders through to UBOs. | Mandatory (BVNK-Managed) |\n| `PROOF_OF_OPERATIONAL_ADDRESS` | Utility bill, lease contract, or equivalent (dated within 3 months). | Required if operational address differs from registered |\n| `SOURCE_OF_FUNDS` | Bank statements (3 months activity) or equivalent SoF evidence. | May be requested during compliance review |\n| `SOURCE_OF_WEALTH` | Audited accounts, tax returns, loan agreements. | Conditional (high risk or EDD) |\n| `PROOF_OF_REGULATORY_LICENSE` | Current regulatory licence. | Conditional (regulated entities) |\n| `AML_POLICY` | AML policy signed by Director/MLRO/Compliance Officer. | Conditional (regulated entities) |\n| `SHAREHOLDER_OWNERSHIP` | Ownership documentation for complex structures. | Conditional |\n| `PASSPORT` / `ID_CARD` / `DRIVERS` / `RESIDENCE_PERMIT` | Government-issued ID for associates. | Required for associate verification |\n| `SELFIE` | Biometric selfie/liveness for associate verification. | Required for associate verification |\n| `UTILITY_BILL` | Proof of residential address for associates. | Required for associate verification |", "enum": [ "CERTIFICATE_OF_INCORPORATION", "MEMORANDUM", "ARTICLE_OF_ASSOCIATION", "PROOF_OF_DIRECTORSHIP", "CORPORATE_STRUCTURE", "PROOF_OF_OPERATIONAL_ADDRESS", "SOURCE_OF_FUNDS", "SOURCE_OF_WEALTH", "PROOF_OF_REGULATORY_LICENSE", "AML_POLICY", "SHAREHOLDER_OWNERSHIP", "PASSPORT", "ID_CARD", "DRIVERS", "RESIDENCE_PERMIT", "SELFIE", "UTILITY_BILL" ], "example": "CERTIFICATE_OF_INCORPORATION" }, "filename": { "type": "string", "maxLength": 255, "example": "certificate.pdf" }, "description": { "type": "string", "maxLength": 1000, "example": "Certificate of Incorporation" } } }, "V2CustomerDocumentsUploadRequest": { "type": "object", "required": [ "files", "metadata" ], "properties": { "metadata": { "type": "array", "description": "One metadata entry per uploaded file. Order must match `files`.", "items": { "$ref": "#/components/schemas/V2CustomerDocumentMetadata" } }, "files": { "type": "array", "description": "One file per metadata entry, in matching order.", "items": { "type": "string", "format": "binary" } } } }, "V2CustomerDocumentResult": { "type": "object", "description": "Per-file outcome in a customer-documents upload batch.", "properties": { "documentId": { "type": "string", "format": "uuid", "description": "Persistent document id. Use this handle for follow-up document calls." }, "type": { "type": "string" }, "filename": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "STORED", "FAILED" ] }, "uploadedAt": { "type": "string", "format": "date-time" }, "errorMessage": { "type": "string", "description": "Error message when `status=FAILED`; null when `STORED`." } } }, "V2UploadCustomerDocumentsResponse": { "type": "object", "description": "Batch response for a company-document upload.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Batch correlation id for tracing; not a persistent lookup key." }, "customerId": { "type": "string", "format": "uuid" }, "totalDocuments": { "type": "integer" }, "successCount": { "type": "integer" }, "failureCount": { "type": "integer" }, "documents": { "type": "array", "items": { "$ref": "#/components/schemas/V2CustomerDocumentResult" } }, "createdAt": { "type": "string", "format": "date-time" } } }, "V2CustomerDocumentSummaryResponse": { "type": "object", "description": "Compact descriptor for a customer document.", "properties": { "id": { "type": "string", "format": "uuid" }, "filename": { "type": "string" }, "type": { "type": "string" }, "status": { "type": "string", "enum": [ "NOT_STARTED", "IN_PROGRESS", "COMPLETE", "ERROR" ] }, "createdAt": { "type": "string", "format": "date-time" } } }, "V2PaginatedCustomerDocumentSummaryResponse": { "type": "object", "properties": { "totalElements": { "type": "integer", "format": "int64" }, "totalPages": { "type": "integer" }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/V2CustomerDocumentSummaryResponse" } }, "pageable": { "$ref": "#/components/schemas/V2Pageable" }, "hasNext": { "type": "boolean" } } }, "V2CustomerDocumentResponse": { "type": "object", "description": "Full customer-document resource.", "properties": { "id": { "type": "string", "format": "uuid" }, "filename": { "type": "string" }, "type": { "type": "string" }, "checksum": { "type": "string", "description": "SHA-256 hex checksum of the uploaded content." }, "status": { "type": "string", "enum": [ "NOT_STARTED", "IN_PROGRESS", "COMPLETE", "ERROR" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "V2PersonAddress": { "type": "object", "description": "Postal address in nested form.", "properties": { "addressLine1": { "type": "string", "maxLength": 255 }, "addressLine2": { "type": "string", "maxLength": 255 }, "city": { "type": "string", "maxLength": 255 }, "postalCode": { "type": "string", "maxLength": 255 }, "stateCode": { "type": "string", "minLength": 2, "maxLength": 2 }, "countryCode": { "type": "string", "minLength": 2, "maxLength": 2 } } }, "V2PersonControlOptions": { "type": "object", "description": "Declared control rights of a natural-person associate.", "required": [ "canAppointDirectors", "controlsCorporateBody", "controlsManagement", "hasSignificantControl" ], "properties": { "canAppointDirectors": { "type": "boolean" }, "hasSignificantControl": { "type": "boolean" }, "controlsManagement": { "type": "boolean" }, "controlsCorporateBody": { "type": "boolean" } } }, "V2PersonCreateEntity": { "type": "object", "description": "Create a natural-person associate. `type` must be `PERSON`.", "required": [ "type", "email", "firstName", "lastName" ], "properties": { "type": { "type": "string", "enum": [ "PERSON" ] }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "email": { "type": "string", "format": "email" }, "phoneNumber": { "type": "string", "description": "Phone number in E.164." }, "dateOfBirth": { "type": "string", "format": "date" }, "nationality": { "type": "string", "minLength": 2, "maxLength": 2 }, "secondNationality": { "type": "string", "minLength": 2, "maxLength": 2 }, "birthCountryCode": { "type": "string", "minLength": 2, "maxLength": 2 }, "taxIdentificationNumber": { "type": "string" }, "taxResidence": { "type": "string", "minLength": 2, "maxLength": 2 }, "position": { "type": "string" }, "isPoliticallyExposedPerson": { "type": "boolean" }, "percentageOfOwnership": { "type": "string", "format": "number", "minimum": 0, "maximum": 100 }, "ownershipType": { "type": "string", "enum": [ "DIRECT", "INDIRECT" ] }, "controlOptions": { "$ref": "#/components/schemas/V2PersonControlOptions" }, "address": { "$ref": "#/components/schemas/V2PersonAddress" } } }, "V2BusinessRegistrationCreateEntity": { "type": "object", "description": "Create a registered-business associate. `type` must be `BUSINESS_REGISTRATION`.", "required": [ "type", "entityName", "registrationCountry", "registrationNumber" ], "properties": { "type": { "type": "string", "enum": [ "BUSINESS_REGISTRATION" ] }, "entityName": { "type": "string" }, "registrationCountry": { "type": "string", "minLength": 2, "maxLength": 2 }, "registrationNumber": { "type": "string" }, "percentageOfOwnership": { "type": "string", "format": "number", "minimum": 0, "maximum": 100 }, "typeOfOwnership": { "type": "string", "enum": [ "DIRECT", "INDIRECT" ] } } }, "V2AssociateCreateEntity": { "description": "Create-time associate entity. `type` discriminates between `PERSON` and `BUSINESS_REGISTRATION`.", "oneOf": [ { "$ref": "#/components/schemas/V2PersonCreateEntity" }, { "$ref": "#/components/schemas/V2BusinessRegistrationCreateEntity" } ], "discriminator": { "propertyName": "type", "mapping": { "PERSON": "#/components/schemas/V2PersonCreateEntity", "BUSINESS_REGISTRATION": "#/components/schemas/V2BusinessRegistrationCreateEntity" } } }, "V2CreateAssociateRequest": { "type": "object", "description": "Create an associate under a customer onboarding application.", "required": [ "entity", "types" ], "properties": { "types": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "UBO", "CONTROL_PERSON", "SIGNATORY", "DIRECTOR", "ACCOUNT_REPRESENTATIVE" ] } }, "entity": { "$ref": "#/components/schemas/V2AssociateCreateEntity" } } }, "V2ValidationIssue": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } }, "V2ValidationStatus": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "COMPLETE", "INCOMPLETE" ] }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/V2ValidationIssue" } } } }, "V2AssociateSummaryResponse": { "type": "object", "description": "Compact associate representation used in list responses.", "properties": { "id": { "type": "string", "format": "uuid" }, "types": { "type": "array", "items": { "type": "string", "enum": [ "UBO", "CONTROL_PERSON", "SIGNATORY", "DIRECTOR", "ACCOUNT_REPRESENTATIVE" ] } }, "displayName": { "type": "string" }, "validation": { "$ref": "#/components/schemas/V2ValidationStatus" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "V2PaginatedAssociateSummaryResponse": { "type": "object", "properties": { "totalElements": { "type": "integer", "format": "int64" }, "totalPages": { "type": "integer" }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/V2AssociateSummaryResponse" } }, "pageable": { "$ref": "#/components/schemas/V2Pageable" }, "hasNext": { "type": "boolean" } } }, "V2IdentificationDocument": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "PASSPORT", "NATIONAL_ID", "DRIVING_LICENSE", "RESIDENCE_PERMIT", "UTILITY_BILL", "TAX_DOCUMENT", "SELFIE", "OTHER" ] }, "country": { "type": "string" }, "documentNumber": { "type": "string" }, "firstName": { "type": "string" }, "firstNameEn": { "type": "string" }, "lastName": { "type": "string" }, "lastNameEn": { "type": "string" }, "middleName": { "type": "string" }, "middleNameEn": { "type": "string" }, "gender": { "type": "string" }, "dateOfBirth": { "type": "string", "format": "date" }, "address": { "$ref": "#/components/schemas/V2PersonAddress" }, "issueAuthority": { "type": "string" }, "issuedDate": { "type": "string", "format": "date" }, "validUntil": { "type": "string", "format": "date" }, "termless": { "type": "boolean" } } }, "V2ProofOfAddress": { "type": "object", "properties": { "documentType": { "type": "string" }, "address": { "$ref": "#/components/schemas/V2PersonAddress" } } }, "V2IdentityVerification": { "type": "object", "description": "Hosted identity-verification session metadata.", "properties": { "link": { "type": "string" }, "status": { "type": "string", "enum": [ "PENDING", "COMPLETE", "RESUBMISSION_REQUESTED" ] } } }, "V2AssociateDocument": { "type": "object", "description": "A document record associated with an associate.", "properties": { "id": { "type": "string", "format": "uuid" }, "externalId": { "type": "string" }, "type": { "type": "string", "enum": [ "AGREEMENT", "ARBITRARY_DOC", "BANK_CARD", "CONTRACT", "COVID_VACCINATION_FORM", "DRIVERS", "DRIVERS_TRANSLATION", "ID_CARD", "ID_DOC_PHOTO", "INCOME_SOURCE", "INVESTOR_DOC", "PASSPORT", "PAYMENT_SOURCE", "PROFILE_IMAGE", "RESIDENCE_PERMIT", "SELFIE", "UTILITY_BILL", "UTILITY_BILL2", "VEHICLE_REGISTRATION_CERTIFICATE", "VIDEO_SELFIE", "OTHER" ] }, "subType": { "type": "string", "enum": [ "FRONT_SIDE", "BACK_SIDE", "DIRECTORS_REGISTRY", "GOOD_STANDING_CERT", "INCORPORATION_ARTICLES", "INCORPORATION_CERT", "INCUMBENCY_CERT", "INFORMATION_STATEMENT", "POWER_OF_ATTORNEY", "PROOF_OF_ADDRESS", "SHAREHOLDER_REGISTRY", "STATE_REGISTRY", "TRUST_AGREEMENT", "OTHER" ] }, "deactivated": { "type": "boolean" } } }, "V2PersonAssociateEntity": { "type": "object", "description": "Natural-person associate entity returned by the API.", "properties": { "type": { "type": "string", "enum": [ "PERSON" ] }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "middleName": { "type": "string" }, "gender": { "type": "string", "description": "Gender (free text)." }, "email": { "type": "string" }, "phoneNumber": { "type": "string" }, "dateOfBirth": { "type": "string", "format": "date" }, "nationality": { "type": "string" }, "secondNationality": { "type": "string" }, "birthCountryCode": { "type": "string" }, "taxIdentificationNumber": { "type": "string" }, "taxResidence": { "type": "string" }, "position": { "type": "string" }, "isPoliticallyExposedPerson": { "type": "boolean" }, "percentageOfOwnership": { "type": "string", "format": "number" }, "ownershipType": { "type": "string", "enum": [ "DIRECT", "INDIRECT" ] }, "estimatedYearlyIncome": { "type": "string", "enum": [ "INCOME_0_TO_50K", "INCOME_50K_TO_100K", "INCOME_100K_TO_250K", "INCOME_250K_TO_500K", "INCOME_500K_TO_750K", "INCOME_750K_TO_1M", "INCOME_ABOVE_1M" ] }, "controlOptions": { "$ref": "#/components/schemas/V2PersonControlOptions" }, "address": { "$ref": "#/components/schemas/V2PersonAddress" }, "identificationDocuments": { "type": "array", "items": { "$ref": "#/components/schemas/V2IdentificationDocument" } }, "proofOfAddresses": { "type": "array", "items": { "$ref": "#/components/schemas/V2ProofOfAddress" } }, "documents": { "type": "array", "description": "Other documents.", "items": { "$ref": "#/components/schemas/V2AssociateDocument" } }, "identityVerification": { "$ref": "#/components/schemas/V2IdentityVerification" } } }, "V2BusinessRegistrationAssociateEntity": { "type": "object", "description": "Registered-business associate entity returned by the API.", "required": [ "name", "registrationCountry", "registrationNumber" ], "properties": { "type": { "type": "string", "enum": [ "BUSINESS_REGISTRATION" ] }, "name": { "type": "string" }, "tradingName": { "type": "string" }, "registrationNumber": { "type": "string" }, "registrationCountry": { "type": "string" }, "percentageOfOwnership": { "type": "string", "format": "number" }, "typeOfOwnership": { "type": "string", "enum": [ "DIRECT", "INDIRECT" ] } } }, "V2AssociateEntity": { "description": "Associate entity. `type` discriminates between `PERSON` and `BUSINESS_REGISTRATION`.", "oneOf": [ { "$ref": "#/components/schemas/V2PersonAssociateEntity" }, { "$ref": "#/components/schemas/V2BusinessRegistrationAssociateEntity" } ], "discriminator": { "propertyName": "type", "mapping": { "PERSON": "#/components/schemas/V2PersonAssociateEntity", "BUSINESS_REGISTRATION": "#/components/schemas/V2BusinessRegistrationAssociateEntity" } } }, "V2AssociateResponse": { "type": "object", "description": "Associate resource.", "properties": { "id": { "type": "string", "format": "uuid" }, "types": { "type": "array", "items": { "type": "string", "enum": [ "UBO", "CONTROL_PERSON", "SIGNATORY", "DIRECTOR", "ACCOUNT_REPRESENTATIVE" ] } }, "entity": { "$ref": "#/components/schemas/V2AssociateEntity" }, "validation": { "$ref": "#/components/schemas/V2ValidationStatus" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "V2IdentificationDocumentMetadata": { "type": "object", "required": [ "countryCode", "name", "type" ], "properties": { "type": { "type": "string", "enum": [ "PASSPORT", "NATIONAL_ID", "DRIVING_LICENSE", "RESIDENCE_PERMIT", "UTILITY_BILL", "TAX_DOCUMENT", "SELFIE", "OTHER" ], "description": "Document type.\n\nSupported associate document types:\n\n| Type | Description | When required |\n| --- | --- | --- |\n| `PASSPORT` | Passport. | Identity document required |\n| `NATIONAL_ID` | National identity card. | Alternative to passport |\n| `DRIVING_LICENSE` | Driver's licence. | Alternative to passport |\n| `RESIDENCE_PERMIT` | Residence permit. | Alternative to passport |\n| `UTILITY_BILL` | Proof of residential address, dated within the last three months. | EU: Mandatory; US: Conditional |\n| `TAX_DOCUMENT` | Government-issued tax document. | Conditional |\n| `OTHER` | Other supporting document. | Conditional |" }, "subType": { "type": "string" }, "name": { "type": "string", "minLength": 1, "example": "passport.png" }, "countryCode": { "type": "string", "pattern": "^[A-Z]{2,3}$", "example": "DE" } } }, "V2IdentificationDocumentsUploadRequest": { "type": "object", "required": [ "files", "metadata" ], "properties": { "metadata": { "type": "array", "items": { "$ref": "#/components/schemas/V2IdentificationDocumentMetadata" } }, "files": { "type": "array", "items": { "type": "string", "format": "binary" } } } }, "V2UploadIdentificationDocumentsResponse": { "type": "object", "description": "Accepted-batch receipt for an identification-documents upload.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Trace handle for the batch; not a persistent lookup key." }, "associateId": { "type": "string", "format": "uuid" }, "acceptedDocumentCount": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" } } }, "V2AgreementSummary": { "type": "object", "description": "Compact agreement descriptor.", "properties": { "version": { "type": "string", "description": "Version of the agreement." }, "title": { "type": "string", "description": "Human-readable title." }, "locale": { "type": "string", "description": "Locale tag (e.g. en-GB)." } } }, "V2AssignedAgreementResponse": { "type": "object", "description": "An agreement assigned to a customer for acceptance.", "properties": { "id": { "type": "string", "format": "uuid" }, "agreement": { "$ref": "#/components/schemas/V2AgreementSummary" }, "status": { "type": "string", "enum": [ "PENDING", "ACCEPTED", "REJECTED" ] }, "respondedAt": { "type": "string", "format": "date-time" }, "respondedToDocumentChecksum": { "type": "string", "description": "SHA-256 hex checksum of the document the customer responded to." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "V2PaginatedAssignedAgreementResponse": { "type": "object", "properties": { "totalElements": { "type": "integer", "format": "int64" }, "totalPages": { "type": "integer" }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/V2AssignedAgreementResponse" } }, "pageable": { "$ref": "#/components/schemas/V2Pageable" }, "hasNext": { "type": "boolean" } } }, "V2AgreementContentResponse": { "type": "object", "description": "Presigned URL for downloading an agreement document.", "properties": { "downloadUrl": { "type": "string" }, "expiresAt": { "type": "string", "format": "date-time" }, "filename": { "type": "string" } } }, "V2AgreementActionRequest": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "ACCEPT", "REJECT" ] } } }, "V2BulkAgreementAction": { "type": "object", "required": [ "assignedAgreementId", "type" ], "properties": { "assignedAgreementId": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "ACCEPT", "REJECT" ] } } }, "V2BulkAgreementActionsRequest": { "type": "object", "required": [ "actions" ], "properties": { "actions": { "type": "array", "maxItems": 50, "items": { "$ref": "#/components/schemas/V2BulkAgreementAction" } } } }, "V2PreCustomerAgreement": { "type": "object", "description": "A single agreement within a pre-customer working set.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the pre-customer agreement entry." }, "name": { "type": "string", "description": "Human-readable agreement title." }, "description": { "type": "string", "description": "Short summary of what the agreement covers." }, "declinable": { "type": "boolean", "description": "Whether the customer may reject the agreement. When `false`, only `ACCEPT` is valid." }, "status": { "type": "string", "description": "Current state of the agreement entry.", "enum": [ "PENDING", "ACCEPTED", "REJECTED" ] }, "respondedAt": { "type": "string", "format": "date-time", "description": "Timestamp at which the customer responded. Absent while `status` is `PENDING`." }, "expiresAt": { "type": "string", "format": "date-time", "description": "Timestamp after which the agreement entry itself expires. The agreement must be accepted before this time." } } }, "V2PreCustomerAgreementsResponse": { "type": "object", "description": "Agreement working set returned by the create and list-by-reference endpoints.", "properties": { "reference": { "type": "string", "description": "Partner-supplied identifier that scopes the working set." }, "agreements": { "type": "array", "description": "Agreements in the working set.", "items": { "$ref": "#/components/schemas/V2PreCustomerAgreement" } } } }, "V2PreCustomerAgreementContentResponse": { "type": "object", "description": "Short-TTL presigned URL for downloading a pre-customer agreement document.", "properties": { "downloadUrl": { "type": "string", "description": "Presigned URL for downloading the agreement document." }, "filename": { "type": "string", "description": "Suggested filename for the downloaded document." } } }, "V2AgreementActionResult": { "type": "object", "description": "Outcome of a single action within a bulk-respond call.", "properties": { "agreementId": { "type": "string", "format": "uuid", "description": "Identifier of the agreement entry the action targeted." }, "status": { "type": "string", "description": "Resulting status if the action succeeded.", "enum": [ "ACCEPTED", "REJECTED" ] }, "error": { "type": "string", "description": "Error code explaining why the action failed. Present only when the action did not succeed." } } }, "V2PaginatedAgreementActionResultResponse": { "type": "object", "description": "Paginated per-item outcomes for a bulk-respond call.", "properties": { "totalElements": { "type": "integer", "format": "int64" }, "totalPages": { "type": "integer" }, "content": { "type": "array", "items": { "$ref": "#/components/schemas/V2AgreementActionResult" } }, "pageable": { "$ref": "#/components/schemas/V2Pageable" }, "hasNext": { "type": "boolean" } } } }, "responses": { "Unauthorized": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFound": { "description": "The specified resource was not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "OKCurrencies": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CurrencyDto" } } } } }, "OKCurrenciesFiat": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CurrencyFiatDto" } } } } }, "OKExchange": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExchangeDto" } } } }, "BadRequestMessage": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientValidationErrorDto" } } } }, "BadRequestNoMessage": { "description": "Bad Request" }, "UnexpectedErrorMessage": { "description": "Unexpected Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServerErrorDto" } } } }, "AccountsValidationErrorMessage": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountsValidationErrorDto" } } } }, "AccountsErrorContractMessage": { "description": "Unexpected Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountsServerErrorDto" } } } } }, "parameters": { "OffsetNumber": { "name": "offset", "in": "query", "description": "Where to start fetching records.", "schema": { "type": "number", "minimum": 0, "default": 0 } }, "MaxNumber": { "name": "max", "in": "query", "description": "Maximum number of items in response.", "schema": { "type": "number", "minimum": 1, "default": 200 } }, "OffsetString": { "name": "offset", "in": "query", "description": "Where to start fetching records.", "schema": { "type": "string", "example": "0" } }, "MaxString": { "name": "max", "in": "query", "description": "Maximum number of items in response.", "schema": { "type": "string", "example": "10" } }, "FromDate": { "name": "fromDate", "in": "query", "description": "The start date in format 'YYYY-MM-dd'.", "schema": { "type": "string", "example": "2023-03-30" } }, "ToDate": { "name": "toDate", "in": "query", "description": "The end date in format 'YYYY-MM-dd'.", "schema": { "type": "string", "example": "2023-03-30" } }, "Order": { "name": "order", "in": "query", "description": "Ordering direction.", "schema": { "$ref": "#/components/schemas/SortOrder" } }, "IdempotencyKey": { "name": "X-Idempotency-Key", "in": "header", "required": true, "description": "Unique request identifier (any string, preferably in UUID format).", "schema": { "type": "string", "format": "uuid", "minLength": 8, "maxLength": 36, "example": "1e74002e-74a1-48fd-b707-147c3187a3e1" } }, "IdempotencyKeyNew": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Client-generated unique identifier for the request in UUID format. Ensures that retried requests are not processed more than once.", "schema": { "type": "string", "format": "uuid", "minLength": 36, "maxLength": 36, "example": "1e74002e-74a1-48fd-b707-147c3187a3e1" } }, "Page": { "name": "page", "in": "query", "description": "Page number for pagination. Starts from 0.", "schema": { "type": "integer", "minimum": 0 }, "example": 1 }, "Size": { "name": "size", "in": "query", "description": "Number of items to return per page.", "schema": { "type": "integer", "minimum": 1 }, "example": 20 }, "PageNumber": { "name": "pageNumber", "in": "query", "description": "Page number for pagination. Starts from 0.", "schema": { "type": "integer", "minimum": 0 }, "example": 0 }, "PageSize": { "name": "pageSize", "in": "query", "description": "Number of items to return per page.", "schema": { "type": "integer", "minimum": 1 }, "example": 20 }, "OffsetInteger": { "name": "offset", "in": "query", "description": "Starting point for pagination, used instead of `page. Useful for cursor-based pagination.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, "MaxInteger": { "name": "max", "in": "query", "description": "Maximum number of items in response.", "schema": { "type": "integer", "minimum": 1, "default": 10 } } }, "examples": {}, "requestBodies": {}, "headers": {}, "securitySchemes": { "Hawk": { "description": "Hawk Payload (see: https://github.com/hueniverse/hawk)", "type": "apiKey", "name": "Authorization", "in": "header" }, "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Bearer token for authentication." }, "ApiKeyAuth": { "type": "http", "scheme": "basic", "description": "HTTP Basic authentication using your API credentials. Provide your API ID as the username and your API Key as the password; the client sends `Authorization: Basic base64(API_ID:API_KEY)`." } }, "links": {}, "callbacks": {} }, "tags": [ { "name": "Customers", "description": "Manage customers" }, { "name": "Agreements", "description": "Manage pre-customer and assigned customer agreements" }, { "name": "Manage Documents", "description": "Add documents to customer accounts" }, { "name": "Onboarding", "description": "Onboard customers" }, { "name": "Wallets", "description": "Manage wallets" }, { "name": "Fees", "description": "Add and manage fees" }, { "name": "Reports", "description": "Generate reports" }, { "name": "Crypto Payments", "description": "Cryptocurrency payment operations" }, { "name": "Crypto Channels", "description": "Cryptocurrency channel operations" }, { "name": "Fiat Payments", "description": "Fiat payment operations" }, { "name": "Payouts", "description": "Payout operations" }, { "name": "Refunds", "description": "Refund operations" }, { "name": "Internal Transfers", "description": "Internal transfer operations" }, { "name": "Trading and Conversions", "description": "Trading and currency conversion operations" }, { "name": "Currencies", "description": "Currency management operations" }, { "name": "Merchant IDs", "description": "Merchant ID management operations" }, { "name": "Embedded Express", "description": "Embedded Express operations" } ], "x-readme": { "explorer-enabled": true, "proxy-enabled": true } }