Initiate Payouts (ver. 2)

🚧

A new flow is coming!

The Initiate Payouts (ver. 2) page will soon replace Make a Fiat Payout as the go-to guide for making payouts. This update will roll out in the coming weeks and introduces a new, streamlined flow designed to support Verification of Payee (VoP) and other regulatory requirements.

For the list of changes and migration tips, refer to Migrate to Payouts (ver. 2).

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": "DE89 3704 0044 0532 0130 00",
            "accountType": "CHECKING",
            "bank": {
                "identificationCode": "CHASUS33",
                "nid": "021000021",
                "address": {
                    "addressLine1": "Bank Address",
                    "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"
        }
    }
}

{
    "walletId": "a:24092324785677:o6rhCEZ:1",
    "amount": 5000,
    "currency": "EUR",
    "method": "SEPA_INST",
    "reference": "CORPORATE-PAYOUT-001",
    "beneficiary": {
        "remittanceInformation": "Invoice payment #INV-2024-001",
        "entity": {
            "type": "COMPANY",
            "legalName": "Acme Corporation Ltd",
            "relationshipType": "SELF_OWNED",
            "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": "BUSINESS_CHECKING",
            "bank": {
                "identificationCode": "AIBKIE2D",
                "address": {
                    "addressLine1": "Allied Irish Bank",
                    "city": "Dublin",
                    "country": "IE"
                }
            }
        }
    },
    "fees": {
        "customerFee": {
            "amount": 15,
            "currency": "EUR"
        }
    }
}

Note the following fields:

In the successful response, you receive 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.00,
      "currency": "EUR"
    },
    "processingFee": {
      "amount": 1.00,
      "currency": "EUR"
    }
  },
  "originator": {
    "amount": 1000.50,
    "currency": "EUR",
    "walletId": "a:24092324785677:o6rhCEZ:1"
  },
  "beneficiary": {
    "remittanceInformation": "Payment for services",
    "amount": 1000.50,
    "currency": "EUR",
    "entity": {
      "type": "INDIVIDUAL",
      "firstName": "John",
      "lastName": "Dove",
      "relationshipType": "BENEFICIARY"
    },
    "bankAccount": {
      "accountNumber": "DE89370400440532013000",
      "bank": {
        "identificationCode": "CHASUS33"
      }
    }
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:35:00Z",
  "metadata": {
    "source": "api",
    "merchantId": "merchantOne"
  },
}

{
  "id": "660f9511-f30c-52e5-b827-557766551111",
  "method": "SEPA_INST",
  "reference": "CORPORATE-PAYOUT-001",
  "status": "COMPLETED",
  "type": "payment:payout:fiat",
  "direction": "OUT",
  "fees": {
    "customerFee": {
      "amount": 15.00,
      "currency": "EUR"
    },
    "processingFee": {
      "amount": 1.00,
      "currency": "EUR"
    }
  },
  "originator": {
    "amount": 5000.00,
    "currency": "EUR",
    "walletId": "a:24092324785677:o6rhCEZ:1"
  },
  "beneficiary": {
    "remittanceInformation": "Invoice payment #INV-2024-001",
    "amount": 4985.00,
    "currency": "EUR",
    "entity": {
      "type": "COMPANY",
      "legalName": "Acme Corporation Ltd",
      "relationshipType": "BENEFICIARY"
    },
    "bankAccount": {
      "accountNumber": "IE29 AIBK 9311 5212 3456 78",
      "bank": {
        "identificationCode": "AIBKIE2D"
      }
    }
  },
  "createdAt": "2024-01-15T09:00:00Z",
  "updatedAt": "2024-01-15T11:30:00Z"
}

In case of payment in Euro, the transaction is subject to Verification of Payee (VoP).

Request VoP

VoP is a SEPA (Single Euro Payments Area) service 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 will check the provided name and IBAN with the beneficiary's bank and report the result (Match, Close match, or No match) back to the originator. This is a regulatory requirement under the Instant Payments Regulation to enhance security for euro transfers within the SEPA zone.

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.

All results, except for the successful verification, indicate that if the beneficiary's name in the request doesn't match the name in the beneficiary's bank account, the bank will issue a warning about the inconsistency. In this case, the status 202 is returned.

{
  "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"
  }
}

{
  "id": "UUID",
  "requiredAction": "CONFIRM_BENEFICIARY",
  "status": "PAYEE_VERIFICATION_REQUIRED",
  "verificationResult": {
    "matchStatus": "NO_MATCH",
    "providedName": "Gerorge Colline"
  }
}

{
  "id": "UUID",
  "requiredAction": "CONFIRM_BENEFICIARY",
  "status": "PAYEE_VERIFICATION_REQUIRED",
  "verificationResult": {
    "matchStatus": "TECHNICAL_ERROR",
    "providedName": "Gerorge Colline"
  }
}

{
  "id": "UUID",
  "requiredAction": "CONFIRM_BENEFICIARY",
  "status": "PAYEE_VERIFICATION_REQUIRED",
  "verificationResult": {
    "matchStatus": "NOT_POSSIBLE", 
    "providedName": "Gerorge 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 also test how verification works in the Sandbox. For that, use the following names and IBANs, when sending the payment request:

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 this inconsistency and would like to proceed with the payment anyway, send a POST /payment/v2/payouts/{id}/actions request with id of the transaction received in the 202 response and the following body.

{
    "type": "CONFIRM_BENEFICIARY"
}

In the successful response, you receive the standard payout details, as shown earlier.

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

If you provide the wrong transaction ID or send the confirmation request after its expiration, an error is returned. In this case, you will have to create a new payout.

Integrate two-step verification

Alternatively, you can verify the beneficiary's name using the verification endpoint. Note that in case you follow this approach, step 1 of the following procedure must be completed before creating the payout.

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

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

   Example Request

   {
     "accountNumber":  "GB29NWBK60161331926819",
     "bankCode": "NWBKGB2L",
     "firstName":  "John", 
     "lastName": "Smith", 
     "businessName":  "Acme Corporation Ltd", 
     "currency": "EUR"
   }

   In the request body, provide the following fields:

   • accountNumber: The beneficiary's bank account number.
   • bankCode: The beneficiary's bank code.
   • firstName: The beneficiary's first name. Only for "type": "INDIVIDUAL".
   • lastName: The beneficiary's last name. Only for "type": "INDIVIDUAL".
   • businessName: The beneficiary's business name. Only for "type": "COMPANY".
   • currency: The currency of the beneficiary's bank account.

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

   Example Response

   {
     "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
   }

   Note the following fields:

   • matchStatus: Status of the name verification. The following name statuses are available:
     • MATCH
     • PARTIAL_MATCH
     • NO_MATCH
     • NOT_REQUIRED
     • NOT_POSSIBLE
     • TECHNICAL_ERROR
   • validUntil: Time period during which the verification request is valid. By default, five minutes.

2. Send the POST /payment/v2/payouts request as described earlier. Remember to include the verification Id, acquired on 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.