Submit payouts using batch file

Allows you to submit one or more payouts using a batch file as input for the API request.

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


Use this endpoint to make payouts to existing or new recipients.

Note

For the payout provider Interchecks, if you pass a value for one of the recipientIdNumbers parameters when creating a new recipient, you cannot update any recipient information with Update recipient endpoint.

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.

ParameterName in batch fileNotes
batchRefbatchRefIf 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.
currencycurrencyRequired for each payout.
amountamountRequired for each payout.
descriptiondescriptionOptional.
payoutRefpayoutRefOptional.
recipient.recipientIdrecipientIdConditionally 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.recipientRefrecipientRefConditionally 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.emailemailConditionally 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.firstNamefirstNameRequired for payout to a new recipient.

Ignored for payout to an existing recipient.
recipient.lastNamelastNameRequired for payout to a new recipient.

Ignored for payout to an existing recipient.
recipient.countrycountryRequired for payout to a new recipient.

Ignored for payout to an existing recipient.
recipient.providerIdproviderIdOptional for payout to a new recipient.

Ignored for payout to an existing recipient.
recipient.userTypeuserTypeOptional for payout to a new recipient.

Ignored for payout to an existing recipient.
recipient.gendergenderOptional for payout to a new recipient.

Ignored for payout to an existing recipient.
recipient.birthDatebirthDateOptional for payout to a new recipient.

Ignored for payout to an existing recipient.
recipient.countryOfBirthcountryOfBirthOptional for payout to a new recipient.

Ignored for payout to an existing recipient.
recipient.countryOfNationalitycountryOfNationalityOptional for payout to a new recipient.

Ignored for payout to an existing recipient.
recipient.addressTypeaddressTypeOptional for payout to a new recipient.

Ignored for payout to an existing recipient.
recipient.addressLine1addressLine1Optional for payout to a new recipient.

Ignored for payout to an existing recipient.
recipient.addressLine2addressLine2Optional for payout to a new recipient.

Ignored for payout to an existing recipient.
recipient.citycityOptional for payout to a new recipient.

Ignored for payout to an existing recipient.
recipient.regionregionOptional for payout to a new recipient.

Ignored for payout to an existing recipient.
recipient.postalCodepostalCodeOptional for payout to a new recipient.

Ignored for payout to an existing recipient.
recipient.phoneNumberphoneNumberOptional for payout to a new recipient.

Ignored for payout to an existing recipient.
recipient.phoneNumberCountryphoneNumberCountryOptional for payout to a new recipient.

Ignored for payout to an existing recipient.
recipient.mobileNumbermobileNumberOptional for payout to a new recipient.

Ignored for payout to an existing recipient.
recipient.mobileNumberCountrymobileNumberCountryOptional for payout to a new recipient.

Ignored for payout to an existing recipient.
recipient.governmentIdTypegovernmentIdTypeOptional for payout to a new recipient.

Ignored for payout to an existing recipient.
governmentId
(in recipient.recipientIdNumbers)
governmentIdOptional for payout to a new recipient.

Ignored for payout to an existing recipient.
passportId
(in recipient.recipientIdNumbers)
passportIdOptional for payout to a new recipient.

Ignored for payout to an existing recipient.
driversLicenseId
(in recipient.recipientIdNumbers)
driversLicenseIdOptional for payout to a new recipient.

Ignored for payout to an existing recipient.
employerId
(in recipient.recipientIdNumbers)
employerIdOptional 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".)

Language
Authentication
Basic
base64
:
Click Try It! to start a request and see the response here!