API Reference

Create a recipient

post
https://api.nexiopaysandbox.com/payout/v3/recipient

Creates a recipient profile to which payments can be sent. A recipient is the individual or business receiving payments. Before paying out to a recipient, you must first create a recipient profile, either as a separate process or at the same time as the payout request.

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

To use the Try It feature for this endpoint, you must use the credentials for your Sandbox API user.

Include at least a recipientRef, recipient email, recipient firstName and lastName, and the country for the recipient.

Request parameters

  • recipientRef
  • email
  • firstName
  • lastName
  • country
  • providerId
  • userType
  • gender
  • birthDate
  • countryOfBirth
  • countryOfNationality
  • currency
  • addressType
  • addressLine1
  • addressLine2
  • city
  • region
  • postalCode
  • phoneNumber
  • phoneNumberCountry
  • mobileNumber
  • mobileNumberCountry
  • governmentIdType
  • recipientIdNumbers
  • recipientIdNumbers.governmentId
  • recipientIdNumbers.passportId
  • recipientIdNumbers.employerId
  • recipientIdNumbers.driversLicenseId

Response parameters

  • recipientRef
  • recipientId
  • payoutAccountId
  • providerId
  • providerType
  • providerRecipientRef
  • userType
  • firstName
  • lastName
  • gender
  • birthDate
  • countryOfBirth
  • countryOfNationality
  • addressLine1
  • addressLine2
  • city
  • region
  • postalCode
  • country
  • email
  • phoneNumber
  • mobileNumber
  • governmentIdType
  • recipientIdNumbers
  • recipientIdNumbers.governmentId
  • recipientIdNumbers.passportId
  • recipientIdNumbers.employerId
  • recipientIdNumbers.driversLicenseId
  • createdAt
  • updatedAt
Body Params
string
required
length ≤ 100

Your unique identifier for a recipient. This allows for easier synchronization across different systems.

Important

We strongly recommend that you include this value in your request in order to facilitate payment reconciliation.

string
required
length ≤ 200

The recipient's email address. This must be unique to the specified payout provider (where the provider is indicated in the providerId parameter).

string
required
length ≤ 200

The recipient's first name. For testing purposes with the Mock Payout account, you can trigger a timeout error by sending firstName with a value of timeout. You can trigger a server error by sending firstName with a value of server (along with the appropriate value for lastName).

string
required
length ≤ 200

The recipient's last name. For testing purposes with the Mock Payout account, you can trigger a server error by sending lastName with a value of error (along with the appropriate value for firstName).

string
required
length ≤ 2

The two-character (Alpha-2) ISO country code for the recipient's address.

integer

The Nexio ID for the provider. Indicates which payout provider to associate with this recipient profile. If no providerId is specified in the request, the system uses the first listed payout provider for the merchant account.

For information about the possible providers and provider IDs for your account, contact Integrations Support.

string
enum

The user type associated with the recipient.

Allowed:
string
enum

The recipient's gender.

Allowed:
string

The recipient's date of birth.

Use any of the following formats for the date:

  • Four-digit year and two-digit month and day, separated with hyphens: YYYY-MM-DD.
    For example, 2001-08-26
  • ISO-8601 date expressed in UTC.
    For example, 2001-08-26T13:35:00Z
  • UNIX date (as an integer representing seconds).
    For example, 998854500
string
length ≤ 50

The two-character (Alpha-2) ISO code for the country where the recipient was born.

string
length ≤ 50

The two-character (Alpha-2) ISO code for the recipient's country of citizenship or nationality.

string
length ≤ 3

The three-character ISO currency code for payouts to the specified recipient.

Note

We pass this value through to the payout provider, but we do not save or return it in the response.

string
enum

The type of address associated with this recipient for the specified address information.

Allowed:
string
length ≤ 200

The recipient's street address.

string
length ≤ 200

Additional information about the recipient's street address.

string
length ≤ 50

The recipient's city.

string
length ≤ 50

The recipient's state, province, or region.

string
length ≤ 20

The recipient's postal code.

string
length ≤ 20

The recipient's phone number.

string
length ≤ 50

The country associated with the recipient's phone number.

string
length ≤ 20

The recipient's mobile phone number.

string
length ≤ 50

The country associated with the mobile phone number.

string

Type of the government ID provided for the recipient.

The ID indicated by this value corresponds to the ID provided in the recipientIdNumbers.governmentId parameter.

recipientIdNumbers
object

Contains any specified IDs for the recipient.

Responses

Updated 7 months ago

Language
Credentials
Basic
base64
:
Response 
Click Try It! to start a request and see the response here! Or choose an example:
application/json
Updated 7 months ago