Payouts

Submit payouts using batch file

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:<ul style='margin-top: -5px; margin-bottom: -5px'><li>The header content-type must be multipart/form-data.</li><li>The batch file must be in a location that is accessible by the server making this API request.</li></ul>

📘 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.

⚠️ 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.

<table> <tr> <th align='center'>Parameter</th> <th align='center'>Name in batch file</th> <th align='center'>Notes</th> </tr> <tr> <td>batchRef</td> <td>batchRef</td> <td>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.</td> </tr> <tr> <td>currency</td> <td>currency</td> <td>Required for each payout.</td> </tr> <tr> <td>amount</td> <td>amount</td> <td>Required for each payout.</td> </tr> <tr> <td>description</td> <td>description</td> <td>Optional.</td> </tr> <tr> <td>payoutRef</td> <td>payoutRef</td> <td>Optional.</td> </tr> <tr> <td>recipient.recipientId</td> <td>recipientId</td> <td>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.</td> </tr> <tr> <td>recipient.recipientRef</td> <td>recipientRef</td> <td>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.</td> </tr> <tr> <td>recipient.email</td> <td>email</td> <td>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.</td> </tr> <tr> <td>recipient.firstName</td> <td>firstName</td> <td>Required for payout to a new recipient. Ignored for payout to an existing recipient.</td> </tr> <tr> <td>recipient.lastName</td> <td>lastName</td> <td>Required for payout to a new recipient. Ignored for payout to an existing recipient.</td> </tr> <tr> <td>recipient.country</td> <td>country</td> <td>Required for payout to a new recipient. Ignored for payout to an existing recipient.</td> </tr> <tr> <td>recipient.providerId</td> <td>providerId</td> <td>Optional for payout to a new recipient. Ignored for payout to an existing recipient.</td> </tr> <tr> <td>recipient.userType</td> <td>userType</td> <td>Optional for payout to a new recipient. Ignored for payout to an existing recipient.</td> </tr> <tr> <td>recipient.gender</td> <td>gender</td> <td>Optional for payout to a new recipient. Ignored for payout to an existing recipient.</td> </tr> <tr> <td>recipient.birthDate</td> <td>birthDate</td> <td>Optional for payout to a new recipient. Ignored for payout to an existing recipient.</td> </tr> <tr> <td>recipient.countryOfBirth</td> <td>countryOfBirth</td> <td>Optional for payout to a new recipient. Ignored for payout to an existing recipient.</td> </tr> <tr> <td>recipient.countryOfNationality</td> <td>countryOfNationality</td> <td>Optional for payout to a new recipient. Ignored for payout to an existing recipient.</td> </tr> <tr> <td>recipient.addressType</td> <td>addressType</td> <td>Optional for payout to a new recipient. Ignored for payout to an existing recipient.</td> </tr> <tr> <td>recipient.addressLine1</td> <td>addressLine1</td> <td>Optional for payout to a new recipient. Ignored for payout to an existing recipient.</td> </tr> <tr> <td>recipient.addressLine2</td> <td>addressLine2</td> <td>Optional for payout to a new recipient. Ignored for payout to an existing recipient.</td> </tr> <tr> <td>recipient.city</td> <td>city</td> <td>Optional for payout to a new recipient. Ignored for payout to an existing recipient.</td> </tr> <tr> <td>recipient.region</td> <td>region</td> <td>Optional for payout to a new recipient. Ignored for payout to an existing recipient.</td> </tr> <tr> <td>recipient.postalCode</td> <td>postalCode</td> <td>Optional for payout to a new recipient. Ignored for payout to an existing recipient.</td> </tr> <tr> <td>recipient.phoneNumber</td> <td>phoneNumber</td> <td>Optional for payout to a new recipient. Ignored for payout to an existing recipient.</td> </tr> <tr> <td>recipient.phoneNumberCountry</td> <td>phoneNumberCountry</td> <td>Optional for payout to a new recipient. Ignored for payout to an existing recipient.</td> </tr> <tr> <td>recipient.mobileNumber</td> <td>mobileNumber</td> <td>Optional for payout to a new recipient. Ignored for payout to an existing recipient.</td> </tr> <tr> <td>recipient.mobileNumberCountry</td> <td>mobileNumberCountry</td> <td>Optional for payout to a new recipient. Ignored for payout to an existing recipient.</td> </tr> <tr> <td>recipient.governmentIdType</td> <td>governmentIdType</td> <td>Optional for payout to a new recipient. Ignored for payout to an existing recipient.</td> </tr> <tr> <td>governmentId (in recipient.recipientIdNumbers)</td> <td>governmentId</td> <td>Optional for payout to a new recipient. Ignored for payout to an existing recipient.</td> </tr> <tr> <td>passportId (in recipient.recipientIdNumbers)</td> <td>passportId</td> <td>Optional for payout to a new recipient. Ignored for payout to an existing recipient.</td> </tr> <tr> <td>driversLicenseId (in recipient.recipientIdNumbers)</td> <td>driversLicenseId</td> <td>Optional for payout to a new recipient. Ignored for payout to an existing recipient.</td> </tr> <tr> <td>employerId (in recipient.recipientIdNumbers)</td> <td>employerId</td> <td>Optional for payout to a new recipient. Ignored for payout to an existing recipient.</td> </tr> </table>

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,ygordman@testdata123.com,US,15,USD
John,Johnson,123456r3,jj@123.com,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,recipientemail112@payoutnow.com,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,recipientemai1l21@payoutnow.com,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,recipientemail132@payoutnow.com,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".)

post/payout/v3/batch

Request

Base URL
https://api.nexiopaysandbox.com
URL
https://api.nexiopaysandbox.com/payout/v3/batch
Auth
HTTP basic

Request body multipart/form-data

filestring binary required

Directory location and name for the batch file. Must be accessible from the server that runs this API endpoint.

Example request

{
  "file": "@\"{path_to_file}/{your_batch_file}.csv\""
}

Response

messagestring

Message indicates success or failure for processing the batch file.

Example response

{
  "message": "success"
}

Changes

No recorded changes to this operation across all 1 revision of this API.