BVbvnk
Fiat Payments

Initiate payout

Changed on

Creates a payout to business or individual customers.

In 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. For the details, refer to the Initiate Payouts guide.

We recommend sending as much beneficiary and bank information as you can. Complete details help correspondent banks and payment networks process the payout and reduce the risk of delays or rejections.

post/payment/v2/payouts

Request

Headers

Idempotency-Keystring uuid required
Example:1e74002e-74a1-48fd-b707-147c3187a3e1

Client-generated unique identifier for the request in UUID format. Ensures that retried requests are not processed more than once.

X-Verification-Idstring uuid
Example:550e8400-e29b-41d4-a716-446655440000

Optional. Verification ID acquired from the beneficiary verification request via POST /platform/v1/beneficiaries/verification. Include this header to use a previously verified beneficiary for the payout.

When using this header, you can skip further confirmation of the beneficiary's name as BVNK already attempted to verify it.

If you don't add the header, you may need to confirm the name.

Request body

walletIdstring required

Identifier for your debit wallet associated with the transaction

amountnumber float required

Payout amount in major currency units

currency'USD' | 'EUR' | 'GBP' required

Three-letter ISO-4217 currency code. The following payment method is supported for each currency:

  • USD: ACH, ACH_SAME_DAY, FEDWIRE, FEDNOW, SWIFT, or RTP. Use SWIFT for international payouts and the other methods for domestic transactions.

  • EUR: SEPA_CT, SEPA_INST, or SWIFT

  • GBP: FASTER_PAYMENT

BOOK is also available for all three currencies, for transfers between accounts within the same financial institution.

referencestring

Internal identifier that is shown in the CSV reports for custom use cases. Can be a UUID or any string to identify the payment.

The field is for information purposes only. It will be fully supported in future releases.

method'ACH' | 'ACH_SAME_DAY' | 'SEPA_CT' | 'SEPA_INST' | 'FEDWIRE' | 'FASTER_PAYMENT' | 'BOOK' | 'SWIFT' | 'RTP' | 'FEDNOW'

Payment method when sending out of USA.

The field is mandatory for the USD payouts and optional for other currencies.

If not provided, the optimal payment method is selected automatically based on dynamically determined attributes.

If 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.

When EUR is set in currency, you can select the following payment method:

  • SEPA_CT: Standard SEPA bank transfer. Payment processing time is 1-2 business days.

  • SEPA_INST: Instant bank transfer. Funds arrive in seconds, 24/7. May incur a small fee.

metadataMetadata

Custom metadata key-value pairs. Structure: key: value. Restrictions:

  • Maximum five keys.

  • Each key maximum length 50 characters.

  • Each value maximum length 100 characters.

  • Keys and values must be simple strings.

Example request

{
  "currency": "USD",
  "beneficiary": {
    "entity": {
      "dateOfBirth": "15-01-1990",
      "address": {
        "addressLine1": "123 Main St",
        "addressLine2": "Apt 4B",
        "region": "CA",
        "city": "Los Angeles",
        "country": "US",
        "postCode": "90001"
      }
    },
    "bankAccount": {
      "bank": {
        "address": {
          "addressLine1": "123 Bank St",
          "addressLine2": "Suite 100",
          "region": "NY",
          "city": "New York",
          "country": "US",
          "postCode": "10001"
        }
      },
      "intermediaryBanks": [
        {
          "address": {
            "addressLine1": "123 Bank St",
            "addressLine2": "Suite 100",
            "region": "NY",
            "city": "New York",
            "country": "US",
            "postCode": "10001"
          }
        }
      ]
    }
  },
  "metadata": {
    "source": "api",
    "orderId": "ORD-48213"
  },
  "requestDetails": {
    "originator": {
      "ipAddress": "172.16.0.1"
    }
  }
}

Response

Payment accepted for processing.

idstring uuid required

Unique payout identifier.

method'SEPA_CT' | 'SEPA_INST' | 'FASTER_PAYMENT' | 'BACS' | 'TARGET2' | 'TIPS' | 'SWIFT' | 'ACH' | 'ACH_SAME_DAY' | 'FEDWIRE' | 'FEDNOW' | 'RTP' | 'BOOK' | 'UNKNOWN' | 'BANK_TRANSFER' | 'WIRE' | 'SEPA' required

Payment method used in the transaction. Note: This list can be changed in the future.

referencestring

Free text reference provided during payout creation (used mostly for reconciliation reasons).

status'PENDING' | 'PROCESSING' | 'PENDING_APPROVAL' | 'ON_HOLD' | 'COMPLETED' | 'EXPIRED' | 'CANCELLED' | 'FAILED' | 'RETURNED' required

Current payout status:

  • PENDING_APPROVAL: Payouts from the wallet require approval. The payout stays in this status until all approvals are received, then moves to PROCESSING. Only relevant for fiat payouts.

  • PROCESSING: Waiting for a final response from BVNK's processing partners.

  • ON_HOLD: Screening is taking longer than anticipated.

  • COMPLETED: The payout is complete on BVNK's side. The beneficiary bank may still reject the funds.

  • FAILED: The processing partners couldn't complete the payout. The funds remain in your wallet.

  • CANCELLED: The payout was cancelled, for example because a four-eyes approval was rejected or timed out. The funds are returned to your wallet.

  • RETURNED: The funds came back after the processing partners responded. The funds are returned to your wallet.

metadataMetadata required

Custom metadata key-value pairs. Structure: key: value. Restrictions:

  • Maximum five keys.

  • Each key maximum length 50 characters.

  • Each value maximum length 100 characters.

  • Keys and values must be simple strings.

createdAtstring date-time required

Creation timestamp.

updatedAtstring date-time required

Last update timestamp.

type'payment:payout:fiat' required

Payment type constant.

direction'OUT' required

Payment direction constant.

Example response

{
  "fees": {
    "customerFee": {
      "amount": 100.5,
      "currency": "USD"
    },
    "processingFee": {
      "amount": 100.5,
      "currency": "USD"
    }
  },
  "originator": {
    "entity": {
      "dateOfBirth": "15-01-1990",
      "address": {
        "addressLine1": "123 Main St",
        "addressLine2": "Apt 4B",
        "region": "CA",
        "city": "Los Angeles",
        "country": "US",
        "postCode": "90001"
      }
    }
  },
  "beneficiary": {
    "entity": {
      "dateOfBirth": "15-01-1990",
      "address": {
        "addressLine1": "123 Main St",
        "addressLine2": "Apt 4B",
        "region": "CA",
        "city": "Los Angeles",
        "country": "US",
        "postCode": "90001"
      }
    },
    "bankAccount": {
      "bank": {
        "address": {
          "addressLine1": "123 Bank St",
          "addressLine2": "Suite 100",
          "region": "NY",
          "city": "New York",
          "country": "US",
          "postCode": "10001"
        }
      },
      "intermediaryBanks": [
        {
          "address": {
            "addressLine1": "123 Bank St",
            "addressLine2": "Suite 100",
            "region": "NY",
            "city": "New York",
            "country": "US",
            "postCode": "10001"
          }
        }
      ]
    }
  },
  "metadata": {
    "source": "api",
    "orderId": "ORD-48213"
  },
  "trackingDetails": [
    {
      "externalTransactionId": "123e4567-e89b-12d3-a456-426614174000",
      "imad": "20260304ABCDXXXX012345",
      "omad": "20260304QMQP021000080",
      "traceNumber": "021000080123456",
      "uetr": "550e8400-e29b-41d4-a716-446655440000"
    }
  ]
}

Changes

  • c386d436bf2cRevision changes
    • breaking

      removed from the / request property oneOf list

    • breaking

      the ////// response's property format changed from date to no format for status

    • breaking

      the ////// response's property format changed from date to no format for status

    • breaking

      removed the required property from the response with the status

    • warning

      removed the request property ///

    • warning

      removed the request property ////

    • warning

      removed the optional property /// from the response with the status

    • warning

      removed the optional property //// from the response with the status

    • warning

      added the new EXPIRED enum value to the response property for the response status

    • info

      mapped value for discriminator key COMPANY changed from to for / request property

    • info

      mapped value for discriminator key INDIVIDUAL changed from to for / request property

    • info

      added to the / request property oneOf list

    • info

      added the required property to the response with the status

  • 97d6c0d2fe2eRevision changes
    • breaking

      for the header request parameter Idempotency-Key, the minLength was increased from 3 to 36

    • breaking

      the / request property's maxLength was decreased to 34

    • warning

      changed the pattern of the request property / from ^[A-Za-z0-9.,\-\s]+$ to ^[a-zA-Z0-9\s,.-]{5,34}$

    • info

      added the media type application/json for the response with the status

    • info

      added the media type application/json for the response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      removed the non-success response with the status