---
title: "Submit payouts"
method: POST
path: "/payout/v3/pay"
tags: ["Payouts"]
---

# Submit payouts

`POST /payout/v3/pay`

Allows you to submit one or more payouts in the body of an API request.

Payouts can be made to existing recipients or you can create a recipient at the same time as submitting a payout by including the amount and currency for the payout as well as the required parameters for a recipient.

### Required payout parameters
The required parameters for a payout are the following:<br/>&nbsp;&nbsp;&nbsp;&nbsp;- `amount`<br/>&nbsp;&nbsp;&nbsp;&nbsp;- `currency`<br/>&nbsp;&nbsp;&nbsp;&nbsp;- The **required recipient parameters**

### Required recipient parameters
For sending a payout to an **existing recipient**, you must specify one or more of the following recipient parameters (if you specify more than one, they are prioritized in the given order):<br/>&nbsp;&nbsp;&nbsp;&nbsp;- `recipientRef`<br/>&nbsp;&nbsp;&nbsp;&nbsp;- `recipientId`<br/>&nbsp;&nbsp;&nbsp;&nbsp;- `email`<br/>**Note:** The system ignores any other recipient parameters that you include.<br/>

For sending a payout to a **new recipient**, you must include at least the following recipient parameters:<br/>&nbsp;&nbsp;&nbsp;&nbsp;- `recipientRef`<br/>&nbsp;&nbsp;&nbsp;&nbsp;- `email`<br/>&nbsp;&nbsp;&nbsp;&nbsp;- `firstName`<br/>&nbsp;&nbsp;&nbsp;&nbsp;- `lastName`<br/>&nbsp;&nbsp;&nbsp;&nbsp;- `country`<br/>You may also optionally include any of the other parameters for [creating a recipient](https://docs.nexiopay.com/reference/createrecipient).

<!-- theme: info -->
> 📘 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](https://docs.nexiopay.com/reference/updaterecipient) endpoint.

<!-- theme: warning -->
> ⚠️ Try It
> 
> To use the Try It feature for this endpoint, you must use the credentials for your [Sandbox API user](https://docs.nexiopay.com/docs/sandbox-environments).<br/><br/>Include all the required parameters for a payout and a recipient, depending on whether this is for a new or existing recipient (see above).

<div style="display:none;">

## Request parameters
- payouts
- payouts.amount
- payouts.currency
- payouts.recipient
- payouts.recipient.recipientRef
- payouts.recipient.recipientId
- payouts.recipient.email
- payouts.recipient.firstName
- payouts.recipient.lastName
- payouts.recipient.country
- payouts.recipient.providerId
- payouts.recipient.userType
- payouts.recipient.gender
- payouts.recipient.birthDate
- payouts.recipient.countryOfBirth
- payouts.recipient.countryOfNationality
- payouts.recipient.currency
- payouts.recipient.addressType
- payouts.recipient.addressLine1
- payouts.recipient.addressLine2
- payouts.recipient.city
- payouts.recipient.region
- payouts.recipient.postalCode
- payouts.recipient.phoneNumber
- payouts.recipient.phoneNumberCountry
- payouts.recipient.mobileNumber
- payouts.recipient.mobileNumberCountry
- payouts.recipient.governmentIdType
- payouts.recipient.recipientIdNumbers
- payouts.recipient.recipientIdNumbers.governmentId
- payouts.recipient.recipientIdNumbers.passportId
- payouts.recipient.recipientIdNumbers.employerId
- payouts.recipient.recipientIdNumbers.driversLicenseId
- payouts.description
- payouts.payoutRef
- batchRef

## Response parameters
- message

</div>

## Request body

- union
  - object
    - `payouts` object[], required — Array of payouts to submit.
      - `amount` Amount, required — unresolved $ref
      - `currency` Currency, required — unresolved $ref
      - `recipient` object, required — <!-- theme: warning --> > #### Important > For sending a payout to an **existing recipient**, you must specify one or more of the following recipient parameters (if you specify more than one, they are prioritized in the given order):<br/> - `payouts.recipient.recipientRef`<br/> - `payouts.recipient.recipientId`<br/> - `payouts.recipient.email`<br/> > **Note:** The system ignores any other recipient parameters that you include.
        - `recipientRef` string, required — Your unique identifier for a recipient. This allows for easier synchronization across different systems. <!-- theme: warning --> > #### Important > We strongly recommend that you include this value in your request in order to facilitate payment reconciliation. If specified in the payout request for an existing recipient, this value takes precedence over values for `recipientId` and `email`. Only required if neither `recipientId` nor `email` are specified in the request for an existing recipient. Optional parameter for a payout request for a new recipient. However, if not included, the system automatically generates a value for this parameter.
      - `description` string — Payer's description information for the payout to the specified recipient.
      - `payoutRef` string — Payer's unique reference value for a payout to the specified recipient. This allows for easier synchronization and searching across different systems.
    - `batchRef` string — Reference value for the payout request. You can use your own reference value for the payout request. If you want multiple batches to display as a single group in a report, specify the same value. Using this option allows you to easily view money sent to different payout providers so that you can properly fund those accounts. If you do not specify a value, the system generates one that includes "batch" and the UTC date and time of the submit payout request.
  - object
    - `payouts` object[], required — Array of payouts to submit.
      - `amount` Amount, required — unresolved $ref
      - `currency` Currency, required — unresolved $ref
      - `recipient` object, required — <!-- theme: warning --> > #### Important > For sending a payout to an **existing recipient**, you must specify one or more of the following recipient parameters (if you specify more than one, they are prioritized in the given order):<br/> - `payouts.recipient.recipientRef`<br/> - `payouts.recipient.recipientId`<br/> - `payouts.recipient.email`<br/> > **Note:** The system ignores any other recipient parameters that you include.
        - `recipientId` integer, required — The Nexio-generated ID for an existing recipient to send a payout to. If specified in the payout request for an existing recipient, this value takes precedence over the value for `email`. If `recipientRef` is specified in the request, this value is ignored. Only required if neither `recipientRef` nor `email` are specified in the request for an existing recipient. Not allowed for a payout request for a new recipient.
      - `description` Description — unresolved $ref
      - `payoutRef` PayoutRef — unresolved $ref
    - `batchRef` BatchRef — unresolved $ref
  - object
    - `payouts` object[], required — Array of payouts to submit.
      - `amount` Amount, required — unresolved $ref
      - `currency` Currency, required — unresolved $ref
      - `recipient` object, required — <!-- theme: warning --> > #### Important > For sending a payout to an **existing recipient**, you must specify one or more of the following recipient parameters (if you specify more than one, they are prioritized in the given order):<br/> - `payouts.recipient.recipientRef`<br/> - `payouts.recipient.recipientId`<br/> - `payouts.recipient.email`<br/> > **Note:** The system ignores any other recipient parameters that you include.
        - `email` string, required — The recipient's email address. If either `recipientId` or `recipientRef` is specified in the request for an existing recipient, this value is ignored. Only required if neither `recipientId` nor `recipientRef` are specified in the request for an existing recipient. Required for a payout request for a new recipient.
      - `description` Description — unresolved $ref
      - `payoutRef` PayoutRef — unresolved $ref
    - `batchRef` BatchRef — unresolved $ref
  - object
    - `payouts` object[], required — Array of payouts to submit.
      - `amount` Amount, required — unresolved $ref
      - `currency` Currency, required — unresolved $ref
      - `recipient` object, required — <!-- theme: warning --> > #### Important > For sending a payout to an **existing recipient**, you must specify one or more of the following recipient parameters (if you specify more than one, they are prioritized in the given order):<br/> - `payouts.recipient.recipientRef`<br/> - `payouts.recipient.recipientId`<br/> - `payouts.recipient.email`<br/> > **Note:** The system ignores any other recipient parameters that you include.
        - `recipientRef` RecipientRef — unresolved $ref
        - `recipientId` RecipientId — unresolved $ref
        - `email` Email — unresolved $ref
      - `description` Description — unresolved $ref
      - `payoutRef` PayoutRef — unresolved $ref
    - `batchRef` BatchRef — unresolved $ref
  - object
    - `payouts` object[], required — Array of payouts to submit.
      - `amount` Amount, required — unresolved $ref
      - `currency` Currency, required — unresolved $ref
      - `recipient` object, required — <!-- theme: warning --> > #### Important > For sending a payout to a **new recipient**, you must include at least the following recipient parameters:<br/> - `payouts.recipient.recipientRef` <br/> - `payouts.recipient.email` <br/> - `payouts.recipient.firstName`<br/> - `payouts.recipient.lastName`<br/> - `payouts.recipient.country` <br/> > You may also optionally include any of the other parameters for creating a recipient.
        - `recipientRef` RecipientRef, required — unresolved $ref
        - `email` Email, required — unresolved $ref
        - `firstName` FirstName, required — unresolved $ref
        - `lastName` LastName, required — unresolved $ref
        - `country` Country, required — unresolved $ref
        - `providerId` ProviderId — unresolved $ref
        - `userType` UserType — unresolved $ref
        - `gender` Gender — unresolved $ref
        - `birthDate` BirthDate — unresolved $ref
        - `countryOfBirth` CountryOfBirth — unresolved $ref
        - `countryOfNationality` CountryOfNationality — unresolved $ref
        - `currency` Currency — unresolved $ref
        - `addressType` AddressType — unresolved $ref
        - `addressLine1` AddressLine1 — unresolved $ref
        - `addressLine2` AddressLine2 — unresolved $ref
        - `city` City — unresolved $ref
        - `region` Region — unresolved $ref
        - `postalCode` PostalCode — unresolved $ref
        - `phoneNumber` PhoneNumber — unresolved $ref
        - `phoneNumberCountry` PhoneNumberCountry — unresolved $ref
        - `mobileNumber` MobileNumber — unresolved $ref
        - `mobileNumberCountry` MobileNumberCountry — unresolved $ref
        - `governmentIdType` GovernmentIdType — unresolved $ref
        - `recipientIdNumbers` RecipientIdNumbers — unresolved $ref
      - `description` Description — unresolved $ref
      - `payoutRef` PayoutRef — unresolved $ref
    - `batchRef` BatchRef — unresolved $ref
  - object — You can submit payouts for one or more recipients. There can be a mix of new and existing recipients. <!-- theme: warning --> > #### Important > For sending a payout to an **existing recipient**, you must specify one or more of the following recipient parameters (if you specify more than one, they are prioritized in the given order):<br/> - `payouts.recipient.recipientRef`<br/> - `payouts.recipient.recipientId`<br/> - `payouts.recipient.email`<br/> > **Note:** The system ignores any other recipient parameters that you include.<br/><br/> > > For sending a payout to a **new recipient**, you must include at least the following recipient parameters:<br/> - `payouts.recipient.recipientRef` <br/> - `payouts.recipient.email` <br/> - `payouts.recipient.firstName`<br/> - `payouts.recipient.lastName`<br/> - `payouts.recipient.country` <br/> > You may also optionally include any of the other parameters for creating a recipient.
    - `payouts` object[], required — Array of payouts to submit.
      - `amount` Amount, required — unresolved $ref
      - `currency` Currency, required — unresolved $ref
      - `recipient` object, required — <!-- theme: warning --> > #### Important > For sending a payout to an **existing recipient**, you must specify one or more of the following recipient parameters (if you specify more than one, they are prioritized in the given order):<br/> - `payouts.recipient.recipientRef`<br/> - `payouts.recipient.recipientId`<br/> - `payouts.recipient.email`<br/> > **Note:** The system ignores any other recipient parameters that you include.<br/><br/> > > For sending a payout to a **new recipient**, you must include at least the following recipient parameters:<br/> - `payouts.recipient.recipientRef` <br/> - `payouts.recipient.email` <br/> - `payouts.recipient.firstName`<br/> - `payouts.recipient.lastName`<br/> - `payouts.recipient.country` <br/> > You may also optionally include any of the other parameters for creating a recipient.
        - `recipientRef` RecipientRef — unresolved $ref
        - `recipientId` RecipientId — unresolved $ref
        - `email` Email — unresolved $ref
        - `providerId` ProviderId — unresolved $ref
        - `userType` UserType — unresolved $ref
        - `firstName` FirstName — unresolved $ref
        - `lastName` LastName — unresolved $ref
        - `gender` Gender — unresolved $ref
        - `birthDate` BirthDate — unresolved $ref
        - `countryOfBirth` CountryOfBirth — unresolved $ref
        - `countryOfNationality` CountryOfNationality — unresolved $ref
        - `currency` Currency — unresolved $ref
        - `addressType` AddressType — unresolved $ref
        - `addressLine1` AddressLine1 — unresolved $ref
        - `addressLine2` AddressLine2 — unresolved $ref
        - `city` City — unresolved $ref
        - `region` Region — unresolved $ref
        - `postalCode` PostalCode — unresolved $ref
        - `country` Country — unresolved $ref
        - `phoneNumber` PhoneNumber — unresolved $ref
        - `phoneNumberCountry` PhoneNumberCountry — unresolved $ref
        - `mobileNumber` MobileNumber — unresolved $ref
        - `mobileNumberCountry` MobileNumberCountry — unresolved $ref
        - `governmentIdType` GovernmentIdType — unresolved $ref
        - `recipientIdNumbers` RecipientIdNumbers — unresolved $ref
      - `description` Description — unresolved $ref
      - `payoutRef` PayoutRef — unresolved $ref
    - `batchRef` BatchRef — unresolved $ref

## Response `200`

OK

- object
  - `message` string — Message indicates the number of payouts successfully submitted.

## Other responses

- `401` — Unauthorized. For help with this error and other error codes, see [Common errors](https://docs.nexiopay.com/docs/common-errors) in the Guides area.

---

[API](https://skmtc.dev/nexiopay/apis/payments-api-reference.md) · [All operations](https://skmtc.dev/nexiopay/apis/payments-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/nexiopay/payments-api-reference/revisions/b414b73979e5/schema)