BVbvnk
Fiat Payments

Initiate Payout

Changed on

Creates a fiat payout with an existing beneficiary or by adding a new one.

post/payment/v1/payouts

Request

Headers

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

Unique request identifier (any string, preferably in UUID format).

Request body

walletIdstring required

Your debit wallet ID associated with the transaction.

paymentReferencestring required

Custom identifier supplied for a transaction. It is used to link a transaction to a specific customer or use case. Note that the value is visible to the beneficiary. Only whitespaces, alphanumeric characters (a-z, A-Z, 0-9), commas (,) and periods (.).

For ACH and ACH_SAME_DAY payouts, the value must have a maximum length of 10 characters.

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

{
  "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",
    "orderId": "ORD-48213"
  },
  "requestDetails": {
    "originator": {
      "ipAddress": "192.168.1.1"
    }
  }
}

Response

Created

transactionReferencestring uuid

Unique identifier for the transaction.

paymentReferencestring

Unique payment reference used to link a transaction to a specific customer or use case.

The value is visible to the beneficiary.

walletIdstring

Identifier for your debit wallet associated with the transaction.

status'PENDING_APPROVAL' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'CANCELLED' | 'RETURNED' | 'ON_HOLD'

The status of the transaction.

The PENDING_APPROVAL status is only relevant for fiat payouts.

createdAtstring date-time

Timestamp when the transaction was created.

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 response

{
  "transactionReference": "123e4567-e89b-12d3-a456-426614174000",
  "paymentReference": "Invoice #12345",
  "amount": {
    "value": 1000,
    "currency": "USD"
  },
  "fee": {
    "value": 10,
    "currency": "USD"
  },
  "walletId": "a:24092328494070:G5i4XZ9:1",
  "status": "PROCESSING",
  "createdAt": "2024-09-26T14:30:00Z",
  "details": {
    "type": "FIAT",
    "beneficiary": {
      "entityType": "COMPANY",
      "companyDetails": {
        "name": "Doe Corp"
      },
      "address": {
        "addressLine1": "123 Bank St",
        "addressLine2": "Suite 500",
        "region": "New York",
        "city": "New York",
        "countryCode": "US",
        "postCode": "10001",
        "fullAddress": "123 Bank St Suite 500"
      },
      "bankAccount": {
        "format": "IBAN",
        "bankName": "ABC Bank",
        "accountNumber": "GB29MDTR60000131926819",
        "bankCode": "MDTRGB2L",
        "bankAddress": {
          "addressLine1": "123 Bank St",
          "addressLine2": "Suite 500",
          "region": "New York",
          "city": "New York",
          "countryCode": "US",
          "postCode": "10001",
          "fullAddress": "123 Bank St Suite 500"
        }
      },
      "correspondentBic": "ABCDEF12"
    }
  },
  "metadata": {
    "source": "api",
    "orderId": "ORD-48213"
  }
}

Changes