Validate data for a Recipient

Overview

User management

Users
User regulatory status
User e-money

User verification

User data format
KYC documents
UBO declarations

Wallets

User wallets
Client wallets

Cards

Card registrations
Cards
Metadata
Card validations

Card pay-ins

Direct card pay-ins
Recurring card pay-ins
Preauthorizations
Deposit preauthorizations
Web card pay-ins

Banking pay-ins

Bank wires
Pay by bank
Virtual IBAN
Direct debits
Web direct debits

APM pay-ins

Apple Pay
Bancontact
BLIK
Giropay
Google Pay
iDEAL
Klarna
MB WAY
Multibanco
Payconiq
PayPal
Satispay
Swish
TWINT

Transfers

Transfers

Refunds

Refunds

Disputes

Disputes
Dispute documents
Repudiations
Dispute settlement

Payouts

FX conversions

Conversion rates
Quotes
Conversions

Transactions

Transactions

Helpers

API responses
Country authorizations
Webhooks
Events
Reports

Platform account

Client
Dashboard permissions

POST

v2.01

{ClientId}

users

{UserId}

recipients

validate

{
    "DisplayName": "Alex Smith EUR international payout account",
    "PayoutMethodType": "InternationalBankTransfer",
    "RecipientType": "Business",
    "Currency": "EUR",
    "Tag": "Created using the Mangopay API Postman collection",
    "BusinessRecipient": {
        "BusinessName": "Alex Smith Consulting",
        "Address": {
            "AddressLine1": "3 rue de la Cité",
            "AddressLine2": "Appartement 7",
            "City": "Paris",
            "Region": "Ile de France",
            "PostalCode": "75001",
            "Country": "FR"
        }
    },
    "InternationalBankTransfer": {
        "IBAN": "FR7630004000031234567890143"
    }
}

// No response body

Path parameters

UserId

string

required

The unique identifier of the user.

Body parameters

DisplayName

string

required

Length: 1–50; cannot contain: &,'/ (pattern:^(?!.*[&,'/]).{1,50}$)

A user-friendly name to identify the account. This value cannot be changed once the recipient is created.

PayoutMethodType

string

required

Possible values: InternationalBankTransfer, LocalBankTransfer

The payout method of the recipient:

InternationalBankTransfer – A bank wire transfer sent via SWIFT, requiring the InternationalBankTransfer property.
LocalBankTransfer – A bank wire transfer sent via local routes, requiring the LocalBankTransfer property.

RecipientType

string

required

Possible values: Individual, Business

The recipient type:

Individual – An account held by a natural person, requiring the IndividualRecipient property.
Business – An account held by a legal entity, requiring the BusinessRecipient property.

Currency

string

required

Possible values: AUD, CAD, EUR, GBP, HKD, SGD, USD

The currency of the recipient.

RecipientScope

string

Possible values: PAYIN, PAYOUT

Default value: PAYOUT

The scope of the recipient:

PAYOUT – Usable for payouts and in pay-in use cases. A PAYOUT recipient can only be created by a user with the UserCategory OWNER and requires SCA. You need to use the returned PendingUserAction.RedirectUrl value, adding your encoded returnUrl as a query parameter, to redirect the user to the hosted SCA session so they can complete the necessary steps.
PAYIN - Usable for pay-in use cases only, such as direct debit and refunds using payouts. A PAYIN recipient can be created by a user with the UserCategory PAYER or OWNER, and does not require SCA.

Tag

string

Max. length: 255 (pattern: ^.{0,255}$)

Custom data that you can add to this object. This value cannot be changed once the recipient is created.

IndividualRecipient

object

required

The account holder if the RecipientType is Individual.

Only one of IndividualRecipient or BusinessRecipient is required.

IndividualRecipient

object

required

The account holder if the RecipientType is Individual.

Only one of IndividualRecipient or BusinessRecipient is required.

BusinessRecipient

object

required

The account holder if the RecipientType is Business.

Only one of IndividualRecipient or BusinessRecipient is required.

InternationalBankTransfer

object

required

The account details if PayoutMethodType is InternationalBankTransfer.

Only one of InternationalBankTransfer or LocalBankTransfer is required.

InternationalBankTransfer

object

required

The account details if PayoutMethodType is InternationalBankTransfer.

Only one of InternationalBankTransfer or LocalBankTransfer is required.

LocalBankTransfer

object

required

The account details if PayoutMethodType is LocalBankTransfer.

Only one of InternationalBankTransfer or LocalBankTransfer is required.

The LocalBankTransfer depends on the Currency. One of:

AUD

object

required

BSB

string

required

Format: 6 digits (pattern: ^\\d{6}$)

The branch-state-branch number of the Australian account.

AccountNumber

string

required

Format: 6–10 digits (pattern: ^\\d{6,10}$)

The account number of the Australian account.

AUD

object

required

BSB

string

required

Format: 6 digits (pattern: ^\\d{6}$)

The branch-state-branch number of the Australian account.

AccountNumber

string

required

Format: 6–10 digits (pattern: ^\\d{6,10}$)

The account number of the Australian account.

CAD

object

required

InstitutionNumber

string

required

Format: 3 digits (pattern: ^\\d{3}$)

The institution number of the Canadian account.

BankName

string

required

Length: 1–50

The bank name of the Canadian account.

BranchCode

string

required

Format: 5 digits (pattern: ^\\d{5}$)

The branch code of the Canadian account.

AccountNumber

string

required

Format: 7–35 digits (pattern: ^\\d{7,35}$)

The account number of the Canadian account.

EUR

object

required

IBAN

string

Format: A valid IBAN (pattern: ^[a-zA-Z]{2}\\d{2}\\s*(\\w{4}\\s*){2,7}\\w{1,4}\\s*$)

The IBAN of the account.

GBP

object

required

SortCode

string

required

Format: 6 digits (pattern: ^\\d{6}$)

The sort code of the UK account.

AccountNumber

string

required

Format: 8 digits (pattern: ^\\d{8}$)

The account number of the UK account.

HKD

object

required

BIC

string

required

Format: 8–11 alphanumeric characters (pattern: ^[0-9a-zA-Z]{8}([0-9a-zA-Z]{3})?$)

The BIC of the Hong Kong account.

AccountNumber

string

required

Format: 1–50 alphanumeric characters (pattern: ^[0-9a-zA-Z]{1,50}$)

The account number of the Hong Kong account.

BranchCode

string

required

Format: 3 alphanumeric characters (pattern: ^[0-9a-zA-Z]{3}$)

The branch code of the Hong Kong account.

SGD

object

required

BIC

string

required

Format: 8–11 alphanumeric characters (pattern: ^[0-9a-zA-Z]{8}([0-9a-zA-Z]{3})?$)

The BIC of the Singaporean account.

AccountNumber

string

required

Format: 6–34 alphanumeric characters (pattern: ^[0-9a-zA-Z]{6,34}$)

The account number of the Singaporean account.

USD

object

required

ABA

string

required

Format: 9 digits (pattern: ^\\d{9}$)

The ABA routing number of the US account.

AccountNumber

string

required

Format: 8–12 alphanumeric characters (pattern: ^[0-9a-zA-Z]{8,12}$)

The account number of the US account.

Responses

Example 400 error:

{
    "Id": "a1f3db88-9df5-49a8-b73c-d578ffff6e89",
    "Message": "One or several required parameters are missing or incorrect. An incorrect resource ID also raises this kind of error.",
    "Type": "param_error",
    "Date": 1739182373,
    "Errors": {
        "IndividualRecipient.Address.Region": "INVALID_FORMAT",
        "LocalBankTransfer.GBP.AccountNumber": "LENGTH_LESS_THAN_MIN"
    }
}

The following error values may be returned:

REQUIRED – Value is required but not present in the request.
LENGTH_MORE_THAN_MAX – String length is greater than required length.
LENGTH_LESS_THAN_MIN – String length is less than required length.
INVALID_FORMAT – Value doe not match expected pattern.
NOT_IN_ALLOWED_VALUES – Value is not a valid PayoutMethodType, RecipientType, or Currency.
UNSUPPORTED_CURRENCY – Currency is a valid ISO 4217 format but not yet supported for Recipients.
CLIENT_NOT_FOUND – ClientId making the request does not exist.
USER_NOT_FOUND – UserId for which the request is made does not exist.
INVALID_SORT_CODE – Sort code for this account is not valid.
INVALID_ACCOUNT_NUMBER – Account number is not valid.
INVALID_IBAN – IBAN is not valid.
INVALID_BIC – BIC is not valid.
UNSUPPORTED_IBAN – IBAN is valid but not supported:
- If LocalBankTransfer, the IBAN country is not part of SEPA and the local currency is not EUR.
- If InternationalBankTransfer, the IBAN country is not GB or is not part of SEPA and local currency is not EUR.
INVALID_ACCOUNT_NUMBER_AND_SORT_CODE_COMBINATION – GB sort code and account number combination is not valid.

// No response body

{
    "DisplayName": "Alex Smith EUR international payout account",
    "PayoutMethodType": "InternationalBankTransfer",
    "RecipientType": "Business",
    "Currency": "EUR",
    "Tag": "Created using the Mangopay API Postman collection",
    "BusinessRecipient": {
        "BusinessName": "Alex Smith Consulting",
        "Address": {
            "AddressLine1": "3 rue de la Cité",
            "AddressLine2": "Appartement 7",
            "City": "Paris",
            "Region": "Ile de France",
            "PostalCode": "75001",
            "Country": "FR"
        }
    },
    "InternationalBankTransfer": {
        "IBAN": "FR7630004000031234567890143"
    }
}

Was this page helpful?

View the schema for a Recipient Create a Recipient

{
    "DisplayName": "Alex Smith EUR international payout account",
    "PayoutMethodType": "InternationalBankTransfer",
    "RecipientType": "Business",
    "Currency": "EUR",
    "Tag": "Created using the Mangopay API Postman collection",
    "BusinessRecipient": {
        "BusinessName": "Alex Smith Consulting",
        "Address": {
            "AddressLine1": "3 rue de la Cité",
            "AddressLine2": "Appartement 7",
            "City": "Paris",
            "Region": "Ile de France",
            "PostalCode": "75001",
            "Country": "FR"
        }
    },
    "InternationalBankTransfer": {
        "IBAN": "FR7630004000031234567890143"
    }
}

// No response body

Overview

User management

User verification

Wallets

Cards

Card pay-ins

Banking pay-ins

APM pay-ins

Transfers

Refunds

Disputes

Payouts

FX conversions

Transactions

Helpers

Platform account

​Path parameters

​Body parameters

​Responses

Path parameters

Body parameters

Responses