Allows you to submit one or more payouts using a batch file as input for the API request.
Use this endpoint to make payouts to existing or new recipients.
Important
Ensure the following for this endpoint:
- The header content-type must be
multipart/form-data.- The batch file must be in a location that is accessible by the server making this API request.
Note
For the payout provider Interchecks, if you pass a value for one of the
recipientIdNumbersparameters when creating a new recipient, you cannot update any recipient information with Update recipient endpoint.
Try It
Due to technical limitations, it is not possible to use the Try It feature with this endpoint. Instead, use Postman or your own server (along with the credentials for your Sandbox API user) to make the request.
Batch file parameters
The following table shows the required and optional parameters for making payouts using a batch file.
For more information about each parameter, see the Submit payouts endpoint.
To use your own field headers from your batch file, contact Integrations Support for assistance.
| Parameter | Name in batch file | Notes |
|---|---|---|
| batchRef | batchRef | If you include this parameter, the system only uses the first instance of it in the batch file. Other instances are ignored. If you want multiple batches to display as a single group in a report, specify the same value for each batch. Using this option allows you to easily view money sent to different payout providers so that you can properly fund those accounts. |
| currency | currency | Required for each payout. |
| amount | amount | Required for each payout. |
| description | description | Optional. |
| payoutRef | payoutRef | Optional. |
| recipient.recipientId | recipientId | Conditionally required for payout to an existing recipient when neither `recipientRef` nor `email` is included. This parameter is prioritized if more than one of those is included. Not allowed for payout to a new recipient. |
| recipient.recipientRef | recipientRef | Conditionally required for payout to an existing recipient when neither `recipientId` nor `email` is included. This parameter is prioritized over email if that value is included. Otherwise, it is ignored if `recipientId` is included. Required for payout to a new recipient. Important: We strongly recommend that you include this value in your request instead of recipientId in order to facilitate payment reconciliation. |
| recipient.email | Conditionally required for payout to an existing recipient when neither `recipientId` nor `recipientRef` is included. This parameter is only prioritized if neither of the other two are included. Otherwise, it is ignored. Required for payout to a new recipient. | |
| recipient.firstName | firstName | Required for payout to a new recipient. Ignored for payout to an existing recipient. |
| recipient.lastName | lastName | Required for payout to a new recipient. Ignored for payout to an existing recipient. |
| recipient.country | country | Required for payout to a new recipient. Ignored for payout to an existing recipient. |
| recipient.providerId | providerId | Optional for payout to a new recipient. Ignored for payout to an existing recipient. |
| recipient.userType | userType | Optional for payout to a new recipient. Ignored for payout to an existing recipient. |
| recipient.gender | gender | Optional for payout to a new recipient. Ignored for payout to an existing recipient. |
| recipient.birthDate | birthDate | Optional for payout to a new recipient. Ignored for payout to an existing recipient. |
| recipient.countryOfBirth | countryOfBirth | Optional for payout to a new recipient. Ignored for payout to an existing recipient. |
| recipient.countryOfNationality | countryOfNationality | Optional for payout to a new recipient. Ignored for payout to an existing recipient. |
| recipient.addressType | addressType | Optional for payout to a new recipient. Ignored for payout to an existing recipient. |
| recipient.addressLine1 | addressLine1 | Optional for payout to a new recipient. Ignored for payout to an existing recipient. |
| recipient.addressLine2 | addressLine2 | Optional for payout to a new recipient. Ignored for payout to an existing recipient. |
| recipient.city | city | Optional for payout to a new recipient. Ignored for payout to an existing recipient. |
| recipient.region | region | Optional for payout to a new recipient. Ignored for payout to an existing recipient. |
| recipient.postalCode | postalCode | Optional for payout to a new recipient. Ignored for payout to an existing recipient. |
| recipient.phoneNumber | phoneNumber | Optional for payout to a new recipient. Ignored for payout to an existing recipient. |
| recipient.phoneNumberCountry | phoneNumberCountry | Optional for payout to a new recipient. Ignored for payout to an existing recipient. |
| recipient.mobileNumber | mobileNumber | Optional for payout to a new recipient. Ignored for payout to an existing recipient. |
| recipient.mobileNumberCountry | mobileNumberCountry | Optional for payout to a new recipient. Ignored for payout to an existing recipient. |
| recipient.governmentIdType | governmentIdType | Optional for payout to a new recipient. Ignored for payout to an existing recipient. |
| governmentId (in recipient.recipientIdNumbers) | governmentId | Optional for payout to a new recipient. Ignored for payout to an existing recipient. |
| passportId (in recipient.recipientIdNumbers) | passportId | Optional for payout to a new recipient. Ignored for payout to an existing recipient. |
| driversLicenseId (in recipient.recipientIdNumbers) | driversLicenseId | Optional for payout to a new recipient. Ignored for payout to an existing recipient. |
| employerId (in recipient.recipientIdNumbers) | employerId | Optional for payout to a new recipient. Ignored for payout to an existing recipient. |
Batch file format and examples
The batch file needs to be in CSV format. The first line contains a comma-separated list of the parameters to use. Each subsequent line must have the same number of commas as the first line but does not have to have content for each parameter (except where the parameter is required for the payout request).
For the possible required, conditionally required, and optional parameters to include, see the previous section.
To use your own field headers from your batch file, contact Integrations Support for assistance.
Simple batch file example
firstName,lastName,recipientRef,email,country,amount,currency
Yiseme,Gordman,9348rwf2,[email protected],US,15,USD
John,Johnson,123456r3,[email protected],CA,140,CAD
,,,,,,
Download sample file (in ZIP)
(To download, click the link and then select the option to "download".)
Batch file with all parameters example
batchRef,currency,amount,description,payoutRef,recipientId,recipientRef,email,firstName,lastName,country,providerId,userType,gender,birthDate,countryOfBirth,countryOfNationality,addressType,addressLine1,addressLine2,city,region,postalCode,phoneNumber,phoneNumberCountry,mobileNumber,mobileNumberCountry,governmentIdType,governmentId,passportId,driversLicenseId,employerId
batch006,USD,1314.27,June commission payment,113e9ee19a-9c5f-49ca-9a92-3e39e64219c01,98198452,DS1125345,[email protected],Judith,Callie,US,12695,INDIVIDUAL,FEMALE,12/5/90,US,US,RESIDENTIAL,123 Somewhere St,,Somewhere,AK,99885,801111111,US,8012222222,US,NATIONALIDCARD,999999999,,DL12343234,
batch006,USD,125,June commission payment,Z12345 June 15th compensation pay1,98468985,Z11223456,[email protected],Merchnat,LLC,ES,12686,BUSINESS,MALE,11/19/91,ES,ES,BUSINESS,"C. del Pozo, 8",,Madrid,,28012,34915223894,ES,34915223895,ES,NATIONALIDCARD,,,,111111111
batch006,CAD,161.13,June commission payment,11a5ff4a13d4381,,RR12234346,[email protected],Wilimina,Manning,CA,12696,INDIVIDUAL,FEMALE,1/15/93,CA,CA,RESIDENTIAL,800 Benevenuto Ave,,Brentwood Bay,BC,V8M 1J8,2506524422,CA,2506524421,CA,PASSPORT,,789546512,,
Download sample batch file (in ZIP)
(To download, click the link and then select the option to "download".)