Upload bulk payout

Early access - contact your account manager to enable bulk payouts for your organization.

Uploads a file with up to 1,000 payments and creates a bulk payout from one of your organization's accounts. Every payment in the file is sent from accountId, in the account currency, over the same paymentMethod. The internal and self payment methods are not supported.

Send the file in the file part of a multipart/form-data request, up to 5 MB:

CSV (.csv, text/csv) - UTF-8, comma-separated, a header row and one payment per row. Supported for the sepa, fasterUK, swift, ach and fedWire payment methods. The columns are listed below.

JSON (.json, application/json) - an object with an items array, see BulkPayoutFile. Each item has the same fields as an outgoing transfer, so JSON files support every payment method.

The file is validated asynchronously. The response contains the bulk payout identifier, and the bulk payout starts in the validating state. It moves to validated if every row is valid, or to validationFailed otherwise, and the result is reported with the bulkPayoutValidated or bulkPayoutValidationFailed webhook. You can also poll GET /integration/bulk-payouts/{id}. Validation errors are listed per row in GET /integration/bulk-payouts/{id}/items. A bulk payout with invalid rows cannot be submitted: fix the file and upload it again.

Uploading and validating a file does not move any money. Payments start only after POST /integration/bulk-payouts/{id}/submit.

externalId is your identifier of the bulk payout and protects against uploading the same file twice: while a bulk payout with the same externalId exists and is not validationFailed, cancelled or expired, a new upload returns 409 Conflict.

CSV columns. Column names are case-insensitive and can go in any order. Amounts use a dot as the decimal separator.

Column	Required	Description
`amount`	Yes	Payment amount in the account currency
`beneficiaryType`	Yes	`individual` or `business`
`firstName`, `lastName`	For `individual`	Beneficiary name; `middleName` is optional
`legalName`	For `business`	Legal company name
`iban`	`sepa`; `swift` without `accountNumber`	Beneficiary IBAN
`accountNumber`	`fasterUK`, `ach`, `fedWire`; `swift` without `iban`	Beneficiary account number
`accountType`	`ach`	`checking` or `savings`
`bic`, `sortCode`, `routingNumber`	Depends on the payment method	Bank details, for example `bic` for `swift`, `sortCode` for `fasterUK` and `routingNumber` for `ach` and `fedWire`
`bankName`, `bankCountry`, `bankAddress`	Depends on the payment method	Beneficiary bank
`country`, `city`, `streetLine1`, `streetLine2`, `state`, `zip`	Depends on the payment method	Beneficiary address; `country` is an ISO 3166-1 alpha-2 code
`reference`	No	Payment reference
`purpose`	No	Free-text purpose of the payment
`externalId`	No	Your identifier of the payment, unique within the file

Which bank details and address fields are required depends on the payment method and currency, the same as for a single outgoing transfer.

Errors: 400 Bad Request if the file is missing, larger than 5 MB, has more than 1,000 rows, cannot be parsed, or the payment method is not supported; 409 Conflict for a duplicate externalId; 422 Unprocessable Content if a bulk payout cannot be created for any other reason, for example when the account is not available.

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Request

Request Code Samples

Responses