{ "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\nFor sandbox, only Ethereum (ETH) is fully functional.", "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 mid market exchange rate 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" ] } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantDto" } } } }, "400": { "$ref": "#/components/responses/BadRequestMessage" } }, "security": [ { "Hawk": [ "merchant" ] } ] }, "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": [ { "Hawk": [ "merchant" ] } ] } }, "/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": { "Crypto Payment": { "summary": "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", "twoStep": true, "payInDetails": { "currency": "ETH", "network": "ETHEREUM" }, "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": "GB", "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" } } } } } }, "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" } } } }, "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" } } } }, "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" } } } }, "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" ] } ] } }, "/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" } } } }, "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": "456 Business Park", "addressLine2": "Level 5", "city": "Dublin", "postalCode": "D02 XY45", "countryCode": "GB" } }, "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-4001", "status": "400", "message": "Validation error.", "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-4003", "status": "403", "message": "Forbidden.", "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.0, "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-4001", "status": "400", "message": "Validation error.", "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-4003", "status": "403", "message": "Forbidden.", "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-4001", "status": "400", "message": "Validation error.", "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-4003", "status": "403", "message": "Forbidden.", "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" } } } } } } } }, "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-4001", "status": "400", "message": "Validation error.", "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-4003", "status": "403", "message": "Forbidden.", "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 (ver. 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 (ver. 2)](https://docs.bvnk.com/docs/initiate-payment-2#/) guide.", "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": "CHASUS33", "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": "CHASUS33" } } }, "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" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "security": [ { "Hawk": [ "withdrawal", "otc" ] } ] } }, "/payment/v2/payouts/{transactionId}": { "get": { "summary": "Retrieve Payout (ver. 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-4003", "status": "403", "message": "Forbidden.", "details": { "documentLink": "https://docs.bvnk.com/reference/errors#/" } } } } } } }, "404": { "description": "TransactionId not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "500": { "description": "Internal server error" } }, "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": "GB29NWBK60161331926819" }, "bankCode": { "type": "string", "description": "Beneficiary's bank code (BIC/SWIFT code).", "example": "NWBKGB2L" }, "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": "GB29NWBK60161331926819" }, "bankCode": { "type": "string", "description": "Beneficiary's bank code (BIC/SWIFT code).", "example": "NWBKGB2L" }, "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": "GB29NWBK60161331926819", "bankCode": "NWBKGB2L", "firstName": "John", "lastName": "Smith", "currency": "EUR" } }, "company": { "summary": "Company Beneficiary Verification", "value": { "accountNumber": "GB29NWBK60161331926819", "bankCode": "NWBKGB2L", "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.", "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" } } } } } } } } } }, "responses": { "201": { "description": "Success" }, "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 (ver. 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.", "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.50 }, "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.00, "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.00, "currency": "USD", "originator": { "name": "Acme Corporation Ltd", "bankAccount": { "accountNumber": "000123456789", "accountNumberFormat": "ABA", "bankCode": "CHASUS33" } } } } } } } }, "responses": { "201": { "description": "Success" }, "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" } } } }, "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 (ver. 2)", "description": "Creates an internal stablecoin and fiat transfer between EPC and EP 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.0, "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 (ver. 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 Wallet", "description": "Creates a wallet on the BVNK platform.", "operationId": "walletCreate", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletRequestDto" } } } }, "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 Wallets", "description": "Retrieves a list of wallets on your account. Displays the first 10 wallets without max set to higher", "operationId": "walletList", "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 Wallet", "description": "Retrieves detailed information about a specific wallet.", "operationId": "walletRead", "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 Wallet Balances", "description": "Retrieves the balances of your wallets on platform.", "operationId": "walletBalanceList", "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" ] } ] } }, "/ledger/v1/reports": { "post": { "tags": [ "Wallets" ], "summary": "Transactions Report", "description": "Creates a report of all transactions from a wallet in the specified format and sends it via the preferred delivery method: WEBHOOK or EMAIL.\n\n**Note**: Reports are delivered instantly but the data has a one-hour lag for 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\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.", "example": "2023-01-15T10:30:00Z" }, "to": { "type": "string", "format": "date-time", "description": "Final date of the period in the ISO format.", "example": "2025-12-15T10:30:00Z" }, "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": "Transaction type code. Use 'TRANSACTION' to get the transactions report.", "example": "TRANSACTION" } } } } } }, "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" ] } ] } }, "/api/transaction/v2/report": { "get": { "tags": [ "Wallets" ], "summary": "Transactions Report V2", "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/transactions": { "get": { "tags": [ "Wallets" ], "summary": "List 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" ] }, "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." } } }, "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." }, "walletId": { "type": "string", "description": "Unique identifier of the beneficiary's wallet." } } }, "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." } } } } }, "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." } } }, "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": { "Sample": { "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 } }, "CryptoSample": { "summary": "Crypto Transactions", "value": { "content": [ { "transactionId": "7c3a882c-7944-11f0-8a69-33e607d5def0", "paymentId": "0198aa0b-a848-7401-a4b7-0e97a9da341f", "paymentReference": "MoneyGram-45678943", "type": "paymentOut", "status": "COMPLETED", "amount": { "value": -7, "currencyCode": "USD" }, "runningBalance": { "value": 100009.79, "currencyCode": "USD" }, "originator": { "entity": { "type": "COMPANY", "name": "" }, "bankAccount": null, "walletId": "a:25080665987403:Nmid8OR:1" }, "beneficiary": { "entity": { "type": "COMPANY", "name": "Checkout Ltd" }, "bankAccount": null, "walletId": "a:67667667667667:ZKH9YrP:1" }, "details": { "fxRate": { "baseCurrency": "USD", "counterCurrency": "USDT", "merchantFxRate": 0.997660795329588, "baseFxRate": 0.9996601155607093, "merchantSpread": 0.002 }, "complianceDetail": {}, "hash": "0x1c0740bde29b30a05da98930b6549006ac97734bcb0b5dd99916ed2acdba36d1" }, "createdAt": "2025-08-14T19:25:49.824835Z" }, { "transactionId": "e3c17a3e-7cd9-11f0-b744-8b3c3177bf35", "paymentId": "0198c145-8ddf-7e02-b6ec-a78e55dd4706", "paymentReference": "Heldtest2", "type": "reversal", "status": "CANCELLED", "amount": { "value": 11, "currencyCode": "USD" }, "runningBalance": { "value": 505.75, "currencyCode": "USD" }, "originator": { "entity": { "type": "COMPANY", "name": "" }, "bankAccount": null, "walletId": "a:67667667667667:ZKH9YrP:1" }, "beneficiary": { "entity": { "type": "INDIVIDUAL", "name": "Vladimir ALEXEYEV" }, "bankAccount": null, "walletId": "a:24072237783989:Unkx9kW:1" }, "details": { "fxRate": { "baseCurrency": "USD", "counterCurrency": "USDT", "merchantFxRate": 0.9977106639074669, "baseFxRate": 0.9997100840756181, "merchantSpread": 0.002 }, "complianceDetail": {} }, "createdAt": "2025-08-19T08:52:51.976678Z" } ] } }, "ChannelSample": { "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/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" } } } }, "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": { "content": { "application/json": { "schema": { "type": "object", "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}}" } } } } } }, "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": "GB" } } ], "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/v1/wallets": { "post": { "tags": [ "Fiat Payments" ], "summary": "Create Wallet", "description": "Creates a fiat or crypto wallet for a specific Embedded Partner 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](https://docs.bvnk.com/docs/step-2-creating-a-customer-wallet-and-virtual-account#/create-a-customer-wallet) guide.", "operationId": "createCustomerWallet", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWalletRequest" } } } }, "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 all Customer Wallets", "description": "Retrieves a list of wallets for your Embedded Partner Customers (EPCs).\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`.", "operationId": "ledgerWalletList", "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.50, "currencyCode": "EUR" }, "ledgers": [ { "type": "FIAT", "accountHolderName": "System Pay Services (Malta) Limited", "accountNumber": "ES8201828510940200010371", "code": "BBVAESMMXXX", "accountNumberFormat": "SWIFT", "paymentReference": "REF DZ0XJL4", "bank": { "identificationCode": "BBVAESMMXXX", "name": "Banco Bilbao Vizcaya Argentaria, S.A.", "address": { "addressLine1": "De San Nicolas 4", "city": "Bilbao", "postCode": "48005", "country": "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.00, "currencyCode": "USDT" }, "ledgers": [ { "type": "CRYPTO", "address": "0x1234567890abcdef1234567890abcdef12345678", "network": "ETHEREUM" } ], "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/{id}": { "get": { "tags": [ "Fiat Payments" ], "summary": "Get Wallet", "description": "Retrieves a specific wallet by its ID", "operationId": "ledgerWalletRead", "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.50, "currencyCode": "EUR" }, "ledgers": [ { "type": "FIAT", "accountHolderName": "System Pay Services (Malta) Limited", "accountNumber": "ES8201828510940200010371", "code": "BBVAESMMXXX", "accountNumberFormat": "SWIFT", "paymentReference": "REF DZ0XJL4", "bank": { "identificationCode": "BBVAESMMXXX", "name": "Banco Bilbao Vizcaya Argentaria, S.A.", "address": { "addressLine1": "De San Nicolas 4", "city": "Bilbao", "postCode": "48005", "country": "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.00, "currencyCode": "USDT" }, "ledgers": [ { "type": "CRYPTO", "address": "0x1234567890abcdef1234567890abcdef12345678", "network": "ETHEREUM" } ], "capabilities": "SAFEGUARDED" } } } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "examples": { "example1": { "summary": "Resource Not Found", "value": { "code": "BVNK-5001", "status": "404", "message": "Could not find wallet with id: a:24092328494070:G5i4XZ9:1" } } } } } } }, "security": [ { "Hawk": [ "merchant" ] } ] } }, "/ledger/v1/wallets/profiles": { "get": { "summary": "List Wallet Profiles", "description": "Returns available wallet profiles based on optional filters for currency codes and payment methods.\n\n---\n\nFor more information, how to apply it in the Embedded Wallets flow, refer to the [Assign a wallet profile](https://docs.bvnk.com/docs/step-2-creating-a-customer-wallet-and-virtual-account#/assign-a-wallet-profile) guide.", "operationId": "walletProfiles", "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" ] } } } } } } }, "/platform/v1/customers": { "get": { "tags": [ "Customers" ], "summary": "List Customers", "description": "Retrieves 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": "Creates 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": { "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": "221B Baker Street", "city": "London", "postalCode": "NW1 6XE", "countryCode": "GB" }, "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 } }, "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": "GB", "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": "GB" }, "ownership": { "type": "DIRECT", "percentage": 100 } }, "titles": [ "ACCOUNT_REPRESENTATIVE", "DIRECTOR" ] } ] } } }, "Individual": { "summary": "Individual payload", "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": "GB", "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" } } } } } }, "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": "Attach 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": "Document for business customer (company-level or associate-level)", "properties": { "customerPersonReference": { "type": "string", "format": "uuid", "description": "Unique identifier of associate (beneficial owner, etc.). If omitted, document is attached to the company.", "example": "9b2c3d4e-567f-48f0-abc1-03a4e3df12ab" }, "type": { "type": "string", "description": "Document type for business, e.g., COMPANY_DOC.", "example": "COMPANY_DOC" }, "subType": { "type": "string", "description": "Subtype of document, e.g., INCORPORATION_CERT.", "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": "GB" }, "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 for individual, e.g., PASSPORT.", "example": "PASSPORT" }, "subType": { "type": "string", "description": "Subtype of document, for example, FRONT_SIDE.\n\nRequired when uploading two-sided documents, such as ID card. Also, always upload `subType: FRONT_SIDE` before `subType: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 front side" }, "countryCode": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 country code.", "example": "GB" }, "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": [ { "customerPersonReference": "9b2c3d4e-567f-48f0-abc1-03a4e3df1209", "type": "COMPANY_DOC", "subType": "INCORPORATION_CERT", "name": "Company Structure.pdf", "description": "Company incorporation certificate", "countryCode": "GB", "externalReference": "2b8d8bde-eef5-408a-9228-96bef24865ad", "content": "JVBERi0xLjUKJeLjz9MKMSAwIG9iago8PC9UeXBlIC9QYWdl..." }, { "customerPersonReference": "9b2c3d4e-567f-48f0-abc1-03a4e3df12ab", "type": "PASSPORT", "subType": "FRONT_SIDE", "name": "John Smith Passport.pdf", "description": "Passport front side of associate", "countryCode": "GB", "externalReference": "8eabc8f2-7f76-4d2e-9fa6-0a11e94d3dcd", "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": "Retrieves 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": "COMPANY_DOC", "subType": "INCORPORATION_CERT", "name": "Company Structure.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": "Deletes 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": "Retrieves 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", "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": "Updates 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": "Retrieves 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", "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": "GB" }, "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" } } } } } }, "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": "Updates 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": "Returns 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": "GB", "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": "GB", "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": "Fetches 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": "Submit questionnaire answers provided by EPCs. 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 EPC 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": "Returns 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": "EPC 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": "EPC 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": { "reference": { "type": "string", "format": "uuid", "description": "Unique industry identifier", "example": "b59c2055-7655-43bb-923d-0005928301d7" }, "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" }, "children": { "type": "array", "description": "Further sub-industries", "items": { "type": "object" } } } } } } } }, "example": [ { "reference": "b59c2055-7655-43bb-923d-0005928301d7", "name": "Finance", "children": [ { "reference": "c6a1d2e3-4f56-7890-abcd-ef1234567890", "name": "Banking", "children": [] }, { "reference": "d7b2e3f4-5678-9012-cdef-ab3456789012", "name": "Insurance", "children": [] } ] }, { "reference": "e8c3f4a5-6789-0123-def0-cd4567890123", "name": "Technology", "children": [ { "reference": "f9d4a5b6-7890-1234-ef01-de5678901234", "name": "Software", "children": [] } ] } ] } } }, "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" } } } } } }, "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 } } } } } } } }, "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": "GB" }, "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": "GB" }, "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": "Document type (e.g., PASSPORT, ID_CARD)", "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": "Declared intended use for the account", "example": "TRANSFERS_OWN_WALLET" }, "pepStatus": { "type": "string", "description": "Politically Exposed Person (PEP) status", "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": "Current employment status", "example": "SALARIED" }, "sourceOfFunds": { "type": "string", "description": "Primary source of the customer's funds", "example": "SALARY" }, "estimatedYearlyIncome": { "type": "string", "description": "Estimate of customer's yearly income", "example": "INCOME_750K_TO_1M" }, "employmentIndustrySector": { "type": "string", "description": "Industry sector of employment, per NAICS or similar classification", "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" ] } ] }, "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 vary depending on the used payment method or currency.\n\nCannot be \"null\" or empty string.", "pattern": "^[A-Za-z0-9.,\\-\\s]+$", "minLength": 5, "maxLength": 140 }, "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": { "$ref": "#/components/schemas/Address" } } }, "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 an EPC'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 you want to assign to the virtual account.", "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 } } }, "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": "ES8201828510940200010371" }, "code": { "type": "string", "description": "Bank identification code (BIC/SWIFT code).", "example": "BBVAESMMXXX" }, "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": "BBVAESMMXXX" }, "name": { "type": "string", "description": "Name of the bank.", "example": "Banco Bilbao Vizcaya Argentaria, 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" ], "properties": { "code": { "type": "string", "description": "Error code representing the specific error type.", "example": "BVNK-5001" }, "status": { "type": "string", "description": "The HTTP status related to the error.", "example": "404" }, "message": { "type": "string", "description": "A human-readable message providing more details about the error.", "example": "The requested resource was not found." }, "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": "object", "description": "A map containing specific errors related to different fields.", "properties": { "requestBody": { "type": "array", "description": "Specific information about the missing or malformed field.", "items": { "type": "string" } } }, "additionalProperties": { "type": "array", "items": { "type": "string" } }, "example": { "requestBody": [ "Address country required" ] } } } }, "PayRequestDto": { "description": "The request data required to create a payment in or a payment 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. For more information, refer to [Minimum deposit amount](https://help.bvnk.com/hc/en-us/articles/19392395655826-Minimum-deposit-amount).", "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": { "$ref": "#/components/schemas/DirectionDto" }, "twoStep": { "description": "Variable to activate 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 Embedded Partner Customers (EPCs). These fees are separate from the transaction amount and transaction fees, and are collected from the EPC's wallet.\n\nCurrently supported only for outgoing payments (`type: OUT`).\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 EPC's wallet has sufficient funds to cover this fee in addition to the transaction amount.", "example": 1 } }, "required": [ "currency", "amount" ] } } }, "payInDetails": { "$ref": "#/components/schemas/PayInDetailDto" }, "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": [ "amount", "currency", "type", "reference", "customerId", "complianceDetails", "walletId" ] }, "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": "GB" }, "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" ] }, "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", "example": "" }, "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": "GB" }, "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": "GB" }, "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": "GB", "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": "GB", "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", "CLOSED" ] }, "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": { "$ref": "#/components/schemas/ExchangeRateDto" }, "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": 140, "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": "GB29NWBK60161331926819", "bankCode": "NWBKGB2L", "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": "GB29NWBK60161331926819", "bankCode": "NWBKGB2L", "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": "GB29NWBK60161331926819", "bankCode": "NWBKGB2L", "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`\n\n - EUR EASY_EP: `country` is mandatory\n\n - GBP and EUR LOCAL: `address` is optional", "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 currency mid market 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": "GB" }, "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": "GB" }, "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", "externalCustomerId" ], "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": "GB" }, "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": "GB" }, "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, Canada, 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" } } }, "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 a 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. **Required if your customers are individuals domiciled in a US state**.", "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 Reliance Onboarding model.", "properties": { "identityDocumentMetadata": { "type": "object", "description": "Details of the ID document that you have already verified. 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.", "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": "GB" }, "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. Values:\n\n - DOC: verified by a document \n\n - NON_DOC: verified via a database or registry", "properties": { "type": { "type": "string", "description": "Proof of Address type.", "enum": [ "DOC", "NON_DOC" ], "example": "NON_DOC" } }, "required": [ "type" ] }, "attestation": { "$ref": "#/components/schemas/RelianceAttestation" } }, "required": [ "identityDocumentMetadata", "biometricLiveness", "addressVerification", "attestation" ] }, "RelianceAttestation": { "type": "object", "description": "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 Reliance Onboarding model 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": [ "PAYROLL", "TREASURY_MANAGEMENT", "VENDOR_PAYMENTS", "INTERCOMPANY_TRANSFERS", "CUSTOMER_COLLECTIONS" ], "description": "Purpose of the account:\n\n- `PAYROLL`: Payroll and salary payments\n\n - `TREASURY_MANAGEMENT`: Treasury management\n\n - `VENDOR_PAYMENTS`: Vendor and supplier payments\n\n - `INTERCOMPANY_TRANSFERS`: Intercompany transfers\n\n - `CUSTOMER_COLLECTIONS`: Customer collections and receivables", "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" }, "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" ] }, "ownership": { "type": "object", "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": 50 } } }, "reliance": { "$ref": "#/components/schemas/Reliance" } } }, "titles": { "type": "array", "description": "Job title or position", "items": { "type": "string", "enum": [ "BUSINESS_OWNER", "ACCOUNT_REPRESENTATIVE", "DIRECTOR" ] } } } } }, "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." } }, "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": "Unique request identifier (any string, preferably in UUID format).", "schema": { "type": "string", "format": "uuid", "minLength": 3, "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 }, "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." } }, "links": {}, "callbacks": {} }, "tags": [ { "name": "Customers", "description": "Manage customers" }, { "name": "Sign Agreements", "description": "Manage agreement sessions" }, { "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 } }