--- title: "Submit payouts using batch file" method: POST path: "/payout/v3/batch" tags: ["Payouts"] --- # Submit payouts using batch file `POST /payout/v3/batch` ## Request - Base URL: `https://api.nexiopaysandbox.com` - URL: `https://api.nexiopaysandbox.com/payout/v3/batch` - Auth: HTTP basic 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: > 📘 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](ref:updaterecipient) 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](doc:sandbox-environments)) 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](ref:submitpayouts) endpoint. To use your own field headers from your batch file, contact [Integrations Support](page:contact-us) 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 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](page:contact-us) 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)](https://drive.google.com/file/d/1rR_knD7aBeCUnTvbHATOrPsW5lsuz-BI/view?usp=sharing)
(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)](https://drive.google.com/file/d/1JYmaQCyfQRy6ioMn5mZPVvFTGk2xgySC/view?usp=sharing)
(To download, click the link and then select the option to "download".) ## Request body `multipart/form-data` - object - `file` string, binary, required: Directory location and name for the batch file. Must be accessible from the server that runs this API endpoint. ## Response `200` OK - object - `message` string: Message indicates success or failure for processing the batch file. ## Other responses - `401`: Unauthorized. For help with this error and other error codes, see [Common errors](doc:common-errors) in the Guides area. --- [API](https://skmtc.dev/nexiopay/apis/payouts-api-reference.md) - [All operations](https://skmtc.dev/nexiopay/apis/payouts-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/nexiopay/apis/payouts-api-reference/revisions/36c088967d63?raw)