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.

To create a fiat payout for local payment rails, you must have the following:

Recipient's account number.
Recipient's bank account details:
- For GBP payments: SORT
- For EUR payments: IBAN
- For USD payments: ABA routing number

If invalid bank details are provided, such as an incorrect bank code or account number, the payout request will be rejected with an error message returned.

To create a fiat payout for international payments via SWIFT, you must first acquire 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.

Create payout

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

Request examples

{
    "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",
            "accountNumberFormat": "IBAN",
            "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",
            "accountNumberFormat": "IBAN",
            "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:

Parameter	Required	Description
`reference`		Optional. The internal reference 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`		Payment method. Mandatory for payouts in USD and optional for other currencies. We recommend leaving it blank, so that the fastest method is selected automatically. Depending on the specific wallet and currency, not all methods can be available for the transaction. Available options: SEPA_INST (EUR) SEPA_CT (EUR) ACH (USD) ACH_SAME_DAY (USD) FASTER_PAYMENT (GBP) SWIFT (USD, EUR, GBP) FEDWIRE (USD) BOOK (USD) RTP (USD) FEDNOW (USD)
`beneficiary.remittanceInformation`	✔️	Payment reference that beneficiaries see in their bank statements when receiving the payment. Can contain only alphanumeric characters (a-z, A-Z, 0-9), whitespaces, or the `.,-` symbols. Other allowed characters vary depending on the used payment method or currency.
`bankAccount.accountType`		Type of the account. Optional. Only for US banks.
`bankAccount.bank.identificationCode`	✔️	Bank's identification number, for example, BIC for UK banks, SORT code, ABA routing number, and so on. Optional for local payouts in EUR.
`bankAccount.bank.nid`		National bank identification code: country-specific code assigned to a financial institution by its central bank or banking authority. In most cases, used for SWIFT payments to US accounts.
`requestDetails.originator.ipAddress`		IP address of the customer initiating the payout. Required when you make a payment from an EPC's wallet.

In the successful response, you receive the standard payment details.

Response examples

{
  "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",
      "accountNumberFormat": "IBAN",
      "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",
      "accountNumberFormat": "IBAN",
      "bank": {
        "identificationCode": "AIBKIE2D"
      }
    }
  },
  "createdAt": "2024-01-15T09:00:00Z",
  "updatedAt": "2024-01-15T11:30:00Z"
}

Parameter	Description
`type`	Type of the response.
`originator.amount`	Amount of funds sent to the beneficiary. For fiat transactions, it will always be the same as `beneficiary.amount`.

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

VoP is a SEPA (Single Euro Payments Area) payment service that verifies a beneficiary's name against their IBAN to prevent fraud. 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 down.
- Others, for example, if a beneficiary's bank decides not to conduct verification.

All results, except the successful verification, mean that if the beneficiary's name in the request doesn't match the name in the beneficiary's bank account, the bank will warn 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": "Gerorge 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:

Sandbox test values:

First Name: John Smith
Last Name: Doe
IBAN: MT17SYPL39480094112231274874660
BIC: SYPLMTM2XXX

Send confirmation

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

{
    "type": "CONFIRM_BENEFICIARY"
}

If the operation is not confirmed within one minute, it expires.

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

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.