Skip to main content
BVNK

Send payments

To initiate a fiat payout using local payment rails, ensure you have the following information:

  • Recipient's account number.
  • Recipient's bank account details:
    • For GBP payments: SCAN and IBAN
    • For EUR payments: IBAN
    • For USD payments: ABA routing number

If you provide invalid bank details, such as an incorrect bank code or account number, the payout request will be rejected, and an error message will be returned.

To initiate a fiat payout for international payments via SWIFT, gather the following information:

  • Payee's full name or company name and address.
  • Bank Account Number (IBAN or other, depending on the currency)
  • Name and address of the payee's bank
  • Payee's SWIFT or Bank identifier Code (BIC) bank code.

When choosing between SWIFT and Fedwire:

  • Use SWIFT if the beneficiary is outside the US. If you specify an intermediary bank in your payment instruction, this must be in the US.
  • Use Fedwire only if the beneficiary is within the US.

For SWIFT settlement and cut-off times, see Payment schemes. Outbound SWIFT transfers use the SHA (Shared) fee model, so intermediary and beneficiary banks may deduct their own fees from the transfer amount. Contact your Account Manager for SWIFT fee details.

The following diagram illustrates the fiat payout process.

StatusDescription
PENDING_APPROVALOptional. This state is returned if payouts from the wallet require approvals. The payout will remain in this state until all approvals are received. After that, the PROCESSING webhook is emitted. Only relevant for fiat transactions.
PROCESSINGPayouts will remain in this state until a final response has been received from our processing partners.
COMPLETEDOnce a payout has been successfully completed from the side of BVNK, the payout will transition to COMPLETED. Note that the beneficiary bank may still reject the funds.
FAILEDIf, for any reason, our processing partners are unable to complete the payout, the payout will transition to FAILED, and funds will remain in the merchant's wallet.
CANCELLEDIf the payment is cancelled, the status will transition to CANCELLED. This can occur in scenarios such as when a four-eyes approval is rejected or the request for a four-eyes approval times out. Funds will be returned to the merchant's wallet.
RETURNEDOptional. If funds are returned after we receive a response from our processing partners, the payout will be marked as returned, and the funds will be returned to the merchant's wallet.
ON_HOLDThis status is shown when screening takes longer than anticipated.

Create payout​

To create a payout, send the POST /payment/v2/payouts request with the payload:

{
    "walletId": "a:24092324785677:o6rhCEZ:1",
    "amount": 1000.5,
    "currency": "EUR",
    "method": "SEPA_CT",
    "reference": "PAYOUT-2025-001",
    "beneficiary": {
        "remittanceInformation": "Payment for services",
        "entity": {
            "type": "INDIVIDUAL",
            "firstName": "John",
            "lastName": "Dove",
            "dateOfBirth": "15-01-1990",
            "relationshipType": "SELF_OWNED",
            "address": {
                "addressLine1": "123 Main St",
                "city": "New York",
                "region": "NY",
                "postCode": "10001",
                "country": "US"
            }
        },
        "bankAccount": {
            "accountNumber": "000123456789",
            "accountType": "CHECKING",
            "bank": {
                "identificationCode": "ATFEUS33",
                "nid": "021000021",
                "address": {
                    "addressLine1": "383 MADISON AVENUE",
                    "city": "New York",
                    "region": "NY",
                    "postCode": "10001",
                    "country": "US"
                }
            }
        }
    },
    "fees": {
        "customerFee": {
            "amount": 5,
            "currency": "USD"
        }
    },
    "metadata": {
        "source": "api",
        "merchantId": "merchantOne"
    },
    "requestDetails": {
        "originator": {
            "ipAddress": "10.0.0.2"
        }
    }
}

EUR local transfers require fewer details. For USD payments and SWIFT transactions, provide complete information to reduce the risk of rejection by the banking partner.

A successful response returns the standard payment details.

{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "method": "SEPA_CT",
    "reference": "PAYOUT-2025-001",
    "status": "PROCESSING",
    "type": "payment:payout:fiat",
    "direction": "OUT",
    "fees": {
        "customerFee": {
            "amount": 5,
            "currency": "EUR"
        },
        "processingFee": {
            "amount": 1,
            "currency": "EUR"
        }
    },
    "originator": {
        "amount": 1000.5,
        "currency": "EUR",
        "walletId": "a:24092324785677:o6rhCEZ:1"
    },
    "beneficiary": {
        "remittanceInformation": "Payment for services",
        "amount": 1000.5,
        "currency": "EUR",
        "entity": {
            "type": "INDIVIDUAL",
            "firstName": "John",
            "lastName": "Dove",
            "relationshipType": "BENEFICIARY"
        },
        "bankAccount": {
            "accountNumber": "000123456789",
            "bank": {
                "identificationCode": "ATFEUS33"
            }
        }
    },
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:35:00Z",
    "metadata": {
        "source": "api",
        "merchantId": "merchantOne"
    }
}

For Euro payments, the transaction is subject to Verification of Payee (VoP).

Verification of Payee (VoP)​

VoP is a SEPA (Single Euro Payments Area) security measure that verifies a beneficiary's name against their IBAN to prevent fraud and errors. Before a SEPA Credit Transfer (SCT) or SEPA Instant Transfer (SCT inst) is authorised, the originator's bank checks the provided name and IBAN with the beneficiary's bank and reports the result (Match, Close match, or No match) back to the originator. This is a regulatory requirement under the Instant Payments Regulation (mandatory from 5 October 2025) to enhance security for euro transfers within the SEPA zone.

VoP flow

When performing VoP, the system may return one of the following results:

  • Successful verification: The beneficiary's name matches. The payment proceeds automatically.
  • Partial match: The provided name is similar to the one associated with the IBAN, but not an exact match. You may still send the payment at your own risk, but there is a chance it may not be processed successfully.
  • No match: The beneficiary's name does not match at all. You may still attempt to send the payment, but the likelihood of rejection increases.
  • Failed verification due to other reasons:
    • For instance, technical issues may arise if the verification service is unavailable.
    • Others, for example, if a beneficiary's bank decides not to conduct verification.

If the beneficiary's name in the request does not match the name on the bank account, the bank will issue a warning and return status 202, except in cases of successful verification.

{
  "id": "UUID",
  "requiredAction": "CONFIRM_BENEFICIARY",
  "status": "PAYEE_VERIFICATION_REQUIRED",
  "verificationResult": {
    "matchStatus": "PARTIAL_MATCH",
    "actualName": "George D Collins", // Only present if status is Partial Match
    "providedName": "George Colline"
  }
}
🚧 Your transaction is not created yet.

Status 202 means that you must send another request to confirm the operation. See Send confirmation below.

You can test verification in the sandbox by using the following test names and IBANs when submitting a payment request:

  • First Name: John Smith
  • Last Name: Doe
  • IBAN: MT45SYPL39480744067217548372015
  • BIC: SYPLMTM2XXX

There are two ways of verifying the beneficiary's name:

  • As part of the Payout process: by calling another endpoint to confirm the payout operation. See Confirm payout.
  • As a separate two-step process, where you verify a beneficiary via a separate endpoint and then make the payout using the received verificationId. See Integrate two-step verification.

Confirm payout​

You can use this method after making a payout in euros described earlier and receive a response with any of the following status values :

  • PARTIAL_MATCH
  • NO_MATCH
  • NOT_POSSIBLE
  • TECHNICAL_ERROR

The statuses indicate that the beneficiary's name doesn't match the one associated with the beneficiary's bank account or cannot be verified.

If you are aware of the inconsistency and would like to proceed with the payment anyway, send a POST /payment/v2/payouts/{id}/actions request using the transaction id from the 202 response and the following body.

{
    "type": "CONFIRM_BENEFICIARY"
}

A successful response returns the standard payout details, as shown earlier.

If the operation is not confirmed within five minutes, it will expire.

If you provide an incorrect transaction ID or send the confirmation request after expiration, an error will be returned. You will then need to create a new payout.

Integrate two-step verification​

Alternatively, you can verify the beneficiary's name using the verification endpoint. If you choose this approach, complete step 1 below before creating the payout.

To verify the beneficiary's name, do the following:

  1. Send the POST /platform/v1/beneficiaries/verification request.

    {
      "accountNumber":  "GB29MDTR60000131926819",
      "bankCode": "MDTRGB2L",
      "firstName":  "John",
      "lastName": "Smith",
      "businessName":  "Acme Corporation Ltd",
      "currency": "GBP"
    }

    In the successful response, you receive the name match status and validation period:

    {
      "id" :  "550e8400-e29b-41d4-a716-446655440000",
      "matchStatus" : "MATCH",
      "providedName" :  "John Smith",
      "actualName": "J. Smith", // only present for partial match
      "validUntil" : "2025-01-15T14:30:00Z" // when the verification will expire
    }

  2. Send the POST /payment/v2/payouts request as described earlier. Remember to include the verification Id acquired in step 1 in the response as the X-Verification-Id header.

    If you provide a valid verificationId, regardless of status, BVNK verifies that it exists in the records and is not expired, then executes the payment regardless of the matchStatus value.

    The following outcomes are possible:

    • If the verification session is still valid, the payout will be created, and there will be no need to verify the beneficiary.
    • If the verification session is expired or verificationId is not found within BVNK records, the payout will not be created, and you will receive a 400 error.

Verification of Payee can be performed through two main channels:

Check payout status​

To check the status of a payout, send the GET /payment/v2/payouts/{transactionReference} request.

In a successful response, you receive the transaction details and status.

{
    "transactionReference": "123e4567-e89b-12d3-a456-426614174000",
    "paymentReference": "Payment for invoice #12345",
    "amount": {
        "value": 1000,
        "currency": "GBP"
    },
    "fee": {
        "value": 0.00,
        "currency": "GBP"
    },
    "walletId": "a:24071743003474:xE95Oq7:1",
    "status": "PROCESSING",
    "createdAt": "2024-09-26T14:30:00Z",
    "details": {
        "type": "FIAT",
        "beneficiary": {
            "entityType": "COMPANY",
            "businessDetails": {
                "businessName": "Doe Corp"
            },
            "address": {
                "addressLine1": "123 Main St",
                "addressLine2": "Apt 4B",
                "region": "London",
                "city": "London",
                "country": "DE",
                "postCode": "EC2R 8AH",
                "fullAddress": "123 Main St Suite 500"
            },
            "bankAccount": {
                "format": "IBAN",
                "bankName": "Meridian Trust Bank",
                "accountNumber": "GB29MDTR60000131926819",
                "bankCode": "MDTRGB2L",
                "bankAddress": {
                    "addressLine1": "123 Main St",
                    "addressLine2": "Suite 500",
                    "region": "London",
                    "city": "London",
                    "country": "DE",
                    "postCode": "12345",
                    "fullAddress": "123 Main St Suite 500"
                }
            },
            "correspondentBic": "ABCDEF12"
        }
    },
    "metadata": {
        "field1": "field1 value",
        "field2": "field2 value"
    }
}

You can also subscribe to the following webhooks to receive notifications when the payment status changes:

Was this page helpful?
Last updated on