Create Outbound Beneficiary

This route creates a new beneficiary account for outbound remittance operations. Beneficiary accounts are required for sending international transfers to recipients.

POST{{Environment_URL}}/customers/v1/partner/legal/:cnpj/beneficiaries/outbound/:currency

Headers

Name

Value

Authorization

Bearer <token>

client-key

123ABCD456

Path Params

Key

Description

Required

Data Type

Example

cnpj

cnpj in format 10111101000101

true

String

10111101000101

currency

Currency Code

true

String

USD

Beneficiary Object

Attribute

Description

Type

Required

The unique identifier for the beneficiary (returned upon creation).

String

fullName

The complete legal name of the beneficiary.

String

Yes

address

The complete address information of the beneficiary. See Address object below.

Address

Yes

currency

The transaction currency in ISO 4217 alpha-3 format.

String

subType

The purpose of the remittance. Default: PERSON_TRANSFER

String

personType

The legal classification of the beneficiary. Default: PHYSICAL

String

account

The bank account information of the beneficiary. See Account object below.

Account

Yes

Address Object

Attribute

Description

Type

Required

country

The country of residence (ISO 3166-1 alpha-2 format).

String

Yes

state

The state/province of residence.

String

Yes

city

The city of residence.

String

Yes

neighborhood

The neighborhood/district.

String

Yes

street

The street address.

String

Yes

number

The address number.

Integer

Yes

complement

Additional address information.

String

nickname

A descriptive name for the address.

String

Yes

zipCode

The postal code. - USA: Max 16 characters - Europe: Max 12 characters

String

Yes

default

Whether this is the default address for the beneficiary.

Boolean

Yes

Account Object

Attribute

Description

Type

Required

bankName

The name of the bank. Must be alphanumeric and may include: ()&`’" -,. and spaces. Must be encoded using encodeURI****.

String

Yes

number

The bank account number. - Euro Zone: Alphanumeric, may include \ or /. Min 4, Max 50 chars. - USA: Numeric only. Min 4, Max 50 chars. Must be encoded using encodeURI****.

String

Yes

iban

The IBAN code. Required and validated only for EUR currency.

String

bankCountry

The country of the bank in ISO 3166-1 alpha-3 format.

String

Yes

bankCode

The bank code. Alphanumeric, 3 characters. Required only for CAD currency.

String

Yes

code

An object containing the routing code information. See Code below.

Code

Code Object

Attribute

Description

Type

Required

option

The type of routing code. Must be one of: ACH, SWIFT_BIC, SORT_CODE, TRANSIT, BSB_CODE.

String

Yes

value

The value of the routing code. See validation rules below.

String

Yes

Default Values & Validation Rules

Default Values

currency: Defaults to USD if bankCountry is USA, otherwise EUR
subType: Defaults to PERSON_TRANSFER
personType: Defaults to PHYSICAL

Currency-Specific Validations

Currency

Required code.option

code.value Validation

Additional Requirements

USD

ACH

Numeric, 9 characters.

EUR

SWIFT_BIC

Uppercase alphanumeric, 8 or 11 characters. Must start with letters.

iban is required.

GBP

SORT_CODE

Numeric, 6 characters.

CAD

TRANSIT

Numeric, 5 characters.

bankCode is required.

AUD

BSB_CODE

Numeric, 6 characters.

subType and personType Validation

subType

Valid personType Values

PERSON_TRANSFER

PHYSICAL

SERVICES

PHYSICAL, LEGAL

STUDIES

EDUCATIONAL

INVESTMENTS

LEGAL

Note: We recommend using the iban library to validate IBAN codes for EUR transactions.

Request Body

{
  "fullName": "Paula Cruickshank III",
  "email": "[email protected]",
  "phone": "+14155552671",
  "cpf": "12345678901",
  "currency": "USD",
  "address": {
    "nickname": "Home",
    "street": "123 Main Street",
    "number": 456,
    "complement": "Apt 12B",
    "neighborhood": "Downtown",
    "city": "New York",
    "state": "NY",
    "zipCode": "10001",
    "country": "US",
    "default": true
  },
  "studyDocuments": [
    {
      "key": "passport"
    }
  ],
  "subType": "SERVICES",
  "personType": "PHYSICAL",
  "account": {
    "bankName": "Bank of America",
    "bankBranch": "001",
    "name": "Ms. Johnnie DuBuque",
    "beneficiaryDocument": {
      "beneficiaryDocType": "PASSPORT",
      "value": "A1234567"
    },
    "number": "1234567890",
    "iban": "US12345678901234567890",
    "bankCountry": "USA",
    "bankCode": "026009593",
    "bankAccountType": "CH",
    "code": {
      "option": "ACH",
      "value": "123456789"
    },
    "currency": "USD"
  }
}

{
  "fullName": "{{$randomFullName}}",
  "email": "{{$randomExampleEmail}}",
  "phone": "+14165551234",
  "cpf": "98765432100",
  "currency": "CAD",
  "address": {
    "nickname": "Office",
    "street": "456 Queen Street",
    "number": 789,
    "complement": "Suite 300",
    "neighborhood": "Financial District",
    "city": "Toronto",
    "state": "ON",
    "zipCode": "M5H 2N2",
    "country": "CA",
    "default": true
  },
  "studyDocuments": [
    {
      "key": "driver_license"
    }
  ],
  "subType": "PERSON_TRANSFER",
  "personType": "PHYSICAL",
  "account": {
    "bankName": "Royal Bank of Canada",
    "bankBranch": "12345",
    "name": "{{$randomFullName}}",
    "beneficiaryDocument": {
      "beneficiaryDocType": "PASSPORT",
      "value": "Z9876543"
    },
    "number": "123456789",
    "iban": "CA1234567890123456789",
    "bankCountry": "CAN",
    "bankCode": "003",
    "bankAccountType": "CH",
    "code": {
      "option": "TRANSIT",
      "value": "12345"
    },
    "currency": "CAD"
  }
}

{
  "fullName": "{{$randomFullName}}",
  "email": "{{$randomExampleEmail}}",
  "phone": "+4915123456789",
  "cpf": "98765432100",
  "currency": "EUR",
  "address": {
    "nickname": "Home",
    "street": "Unter den Linden",
    "number": 42,
    "complement": "Apt 12",
    "neighborhood": "Mitte",
    "city": "Berlin",
    "state": "BE",
    "zipCode": "10117",
    "country": "DE",
    "default": true
  },
  "studyDocuments": [
    {
      "key": "passport"
    }
  ],
  "subType": "PERSON_TRANSFER",
  "personType": "PHYSICAL",
  "account": {
    "bankName": "Deutsche Bank",
    "bankBranch": "10070000",
    "name": "{{$randomFullName}}",
    "beneficiaryDocument": {
      "beneficiaryDocType": "PASSPORT",
      "value": "C9876543"
    },
    "iban": "DE89370400440532013000",
    "bankCountry": "DEU",
    "bankCode": "100",
    "bankAccountType": "CH",
    "code": {
      "option": "SWIFT_BIC",
      "value": "DEUTDEFF"
    },
    "currency": "EUR"
  }
}

{
    "fullName": "{{$randomFullName}}",
    "email": "{{$randomExampleEmail}}",
    "phone": "+447911123456",
    "cpf": "98765432100",
    "currency": "GBP",
    "address": {
        "nickname": "London Office",
        "street": "221B Baker Street",
        "number": 221,
        "complement": "Flat B",
        "neighborhood": "Marylebone",
        "city": "London",
        "state": "LN",
        "zipCode": "NW1 6XE",
        "country": "GB",
        "default": true
    },
    "studyDocuments": [
        {
            "key": "passport"
        }
    ],
    "subType": "PERSON_TRANSFER",
    "personType": "PHYSICAL",
    "account": {
        "bankName": "HSBC UK",
        "bankBranch": "400302",
        "name": "{{$randomFullName}}",
        "beneficiaryDocument": {
            "beneficiaryDocType": "PASSPORT",
            "value": "GB9876543"
        },
        "number": "1234-5678-90",
        "iban": "GB29NWBK60161331926819",
        "bankCountry": "GBR",
        "bankCode": "400",
        "bankAccountType": "CH",
        "code": {
            "option": "SORT_CODE",
            "value": "123456"
        },
        "currency": "GBP"
    }
}

{
    "fullName": "{{$randomFullName}}",
    "email": "{{$randomExampleEmail}}",
    "phone": "+61412345678",
    "cpf": "98765432100",
    "currency": "AUD",
    "address": {
        "nickname": "Sydney Office",
        "street": "200 George Street",
        "number": 200,
        "complement": "Level 10",
        "neighborhood": "CBD",
        "city": "Sydney",
        "state": "NSW",
        "zipCode": "2000",
        "country": "AU",
        "default": true
    },
    "studyDocuments": [
        {
            "key": "passport"
        }
    ],
    "subType": "PERSON_TRANSFER",
    "personType": "PHYSICAL",
    "account": {
        "bankName": "Commonwealth Bank of Australia",
        "bankBranch": "062000",
        "name": "{{$randomFullName}}",
        "beneficiaryDocument": {
            "beneficiaryDocType": "PASSPORT",
            "value": "AU1234567"
        },
        "number": "123456789",
        "iban": "AU123456789012345",
        "bankCountry": "AUS",
        "bankCode": "062",
        "bankAccountType": "CH",
        "code": {
            "option": "BSB_CODE",
            "value": "062000"
        },
        "currency": "AUD"
    }
}

{
    "fullName": "{{$randomFullName}}",
    "email": "{{$randomExampleEmail}}",
    "phone": "+541123456789",
    "cpf": "98765432100",
    "currency": "ARS",
    "address": {
        "nickname": "Buenos Aires Office",
        "street": "Avenida Corrientes",
        "number": 1234,
        "complement": "Piso 7",
        "neighborhood": "Centro",
        "city": "Buenos Aires",
        "state": "CABA",
        "zipCode": "C1043AAY",
        "country": "AR",
        "default": true
    },
    "studyDocuments": [
        {
            "key": "dni"
        }
    ],
    "subType": "PERSON_TRANSFER",
    "personType": "PHYSICAL",
    "account": {
        "bankName": "Banco de la Nación Argentina",
        "bankBranch": "0001",
        "name": "{{$randomFullName}}",
        "beneficiaryDocument": {
            "beneficiaryDocType": "DNI",
            "value": "12345678"
        },
        "number": "2850590940090418135201",
        "bankCountry": "ARG",
        "bankCode": "285",
        "bankAccountType": "CH",
        "code": {
            "option": "SWIFT_BIC",
            "value": "BNPAARBA"
        },
        "currency": "ARS"
    }
}

{
  "fullName": "{{$randomFullName}}",
  "email": "{{$randomExampleEmail}}",
  "phone": "+51123456789",
  "cpf": "98765432100",
  "currency": "PEN",
  "address": {
    "nickname": "Lima Office",
    "street": "Avenida Larco",
    "number": 890,
    "complement": "Oficina 501",
    "neighborhood": "Miraflores",
    "city": "Lima",
    "state": "LMA",
    "zipCode": "15074",
    "country": "PE",
    "default": true
  },
  "studyDocuments": [
    {
      "key": "dni"
    }
  ],
  "subType": "PERSON_TRANSFER",
  "personType": "PHYSICAL",
  "account": {
    "bankName": "Banco de Crédito del Perú",
    "bankBranch": "0001",
    "name": "{{$randomFullName}}",
    "beneficiaryDocument": {
      "beneficiaryDocType": "DNI",
      "value": "12345678"
    },
    "number": "00112345678901234567",
    "bankCountry": "PER",
    "bankCode": "002",
    "bankAccountType": "CH",
    "code": {
      "option": "SWIFT_BIC",
      "value": "BCPLPEPL"
    },
    "currency": "PEN"
  }
}

Response

[
    {
        "fullName": "John Doe",
        "email": "[email protected]",
        "phone": "+14155552671",
        "cpf": "12345678901",
        "currency": "USD",
        "address": {
            "country": "US",
            "state": "NY",
            "city": "New York",
            "neighborhood": "Downtown",
            "street": "123 Main Street",
            "number": 456,
            "complement": "Apt 12B",
            "zipCode": "10001",
            "default": true,
            "nickname": "Home"
        },
        "type": "OUTBOUND",
        "studyDocuments": [
            {
                "key": "passport"
            }
        ],
        "subType": "SERVICES",
        "personType": "PHYSICAL",
        "account": {
            "name": "John Doe",
            "type": "OUTBOUND",
            "beneficiaryDocument": {
                "beneficiaryDocType": "PASSPORT",
                "value": "A1234567"
            },
            "bankName": "Bank of America",
            "bankBranch": "001",
            "bankCode": "026009593",
            "bankCountry": "USA",
            "bankAccountType": "CH",
            "iban": "US12345678901234567890",
            "number": "1234567890",
            "code": {
                "option": "ACH",
                "value": "123456789"
            },
            "currency": "USD",
            "paymentMethod": "BANK_ACCOUNT",
            "createdAt": "2025-09-10T13:52:36.476Z"
        }
    }
]

[
    {
        "fullName": "Jane Smith",
        "email": "[email protected]",
        "phone": "+14165551234",
        "cpf": "98765432100",
        "currency": "CAD",
        "address": {
            "country": "CA",
            "state": "ON",
            "city": "Toronto",
            "neighborhood": "Financial District",
            "street": "456 Queen Street",
            "number": 789,
            "complement": "Suite 300",
            "zipCode": "M5H 2N2",
            "default": true,
            "nickname": "Office"
        },
        "type": "OUTBOUND",
        "studyDocuments": [
            {
                "key": "driver_license"
            }
        ],
        "subType": "PERSON_TRANSFER",
        "personType": "PHYSICAL",
        "account": {
            "name": "Jane Smith",
            "type": "OUTBOUND",
            "beneficiaryDocument": {
                "beneficiaryDocType": "PASSPORT",
                "value": "Z9876543"
            },
            "bankName": "Royal Bank of Canada",
            "bankBranch": "12345",
            "bankCode": "003",
            "bankCountry": "CAN",
            "bankAccountType": "CH",
            "iban": "CA1234567890123456789",
            "number": "123456789",
            "code": {
                "option": "TRANSIT",
                "value": "12345"
            },
            "currency": "CAD",
            "paymentMethod": "BANK_ACCOUNT",
            "createdAt": "2025-09-10T18:10:40.210Z"
        }
    }
]

[
    {
        "fullName": "Rosemarie Brakus",
        "email": "[email protected]",
        "phone": "+4915123456789",
        "cpf": "98765432100",
        "currency": "EUR",
        "address": {
            "country": "DE",
            "state": "BE",
            "city": "Berlin",
            "neighborhood": "Mitte",
            "street": "Unter den Linden",
            "number": 42,
            "complement": "Apt 12",
            "zipCode": "10117",
            "default": true,
            "nickname": "Home"
        },
        "type": "OUTBOUND",
        "studyDocuments": [
            {
                "key": "passport"
            }
        ],
        "subType": "PERSON_TRANSFER",
        "personType": "PHYSICAL",
        "account": {
            "name": "Dr. Deborah Bahringer",
            "type": "OUTBOUND",
            "beneficiaryDocument": {
                "beneficiaryDocType": "PASSPORT",
                "value": "C9876543"
            },
            "bankName": "Deutsche Bank",
            "bankBranch": "10070000",
            "bankCode": "100",
            "bankCountry": "DEU",
            "bankAccountType": "CH",
            "iban": "DE89370400440532013000",
            "code": {
                "option": "SWIFT_BIC",
                "value": "DEUTDEFF"
            },
            "currency": "EUR",
            "paymentMethod": "BANK_ACCOUNT",
            "createdAt": "2025-09-10T18:20:44.713Z"
        }
    }
]

[
    {
        "fullName": "Dianna Bogan",
        "email": "[email protected]",
        "phone": "+447911123456",
        "cpf": "98765432100",
        "currency": "GBP",
        "address": {
            "country": "GB",
            "state": "LN",
            "city": "London",
            "neighborhood": "Marylebone",
            "street": "221B Baker Street",
            "number": 221,
            "complement": "Flat B",
            "zipCode": "NW1 6XE",
            "default": true,
            "nickname": "London Office"
        },
        "type": "OUTBOUND",
        "studyDocuments": [
            {
                "key": "passport"
            }
        ],
        "subType": "PERSON_TRANSFER",
        "personType": "PHYSICAL",
        "account": {
            "name": "Tomas Hayes",
            "type": "OUTBOUND",
            "beneficiaryDocument": {
                "beneficiaryDocType": "PASSPORT",
                "value": "GB9876543"
            },
            "bankName": "HSBC UK",
            "bankBranch": "400302",
            "bankCode": "400",
            "bankCountry": "GBR",
            "bankAccountType": "CH",
            "iban": "GB29NWBK60161331926819",
            "number": "1234-5678-90",
            "code": {
                "option": "SORT_CODE",
                "value": "123456"
            },
            "currency": "GBP",
            "paymentMethod": "BANK_ACCOUNT",
            "createdAt": "2025-09-10T18:23:43.583Z"
        }
    }
]

[
    {
        "fullName": "Tamara Kerluke",
        "email": "[email protected]",
        "phone": "+61412345678",
        "cpf": "98765432100",
        "currency": "AUD",
        "address": {
            "country": "AU",
            "state": "NSW",
            "city": "Sydney",
            "neighborhood": "CBD",
            "street": "200 George Street",
            "number": 200,
            "complement": "Level 10",
            "zipCode": "2000",
            "default": true,
            "nickname": "Sydney Office"
        },
        "type": "OUTBOUND",
        "studyDocuments": [
            {
                "key": "passport"
            }
        ],
        "subType": "PERSON_TRANSFER",
        "personType": "PHYSICAL",
        "account": {
            "name": "Dr. Joshua Heaney",
            "type": "OUTBOUND",
            "beneficiaryDocument": {
                "beneficiaryDocType": "PASSPORT",
                "value": "AU1234567"
            },
            "bankName": "Commonwealth Bank of Australia",
            "bankBranch": "062000",
            "bankCode": "062",
            "bankCountry": "AUS",
            "bankAccountType": "CH",
            "iban": "AU123456789012345",
            "number": "123456789",
            "code": {
                "option": "BSB_CODE",
                "value": "062000"
            },
            "currency": "AUD",
            "paymentMethod": "BANK_ACCOUNT",
            "createdAt": "2025-09-10T18:26:42.345Z"
        }
    }
]

[
    {
        "fullName": "Gabriel Kirlin",
        "email": "[email protected]",
        "phone": "+541123456789",
        "cpf": "98765432100",
        "currency": "ARS",
        "address": {
            "country": "AR",
            "state": "CABA",
            "city": "Buenos Aires",
            "neighborhood": "Centro",
            "street": "Avenida Corrientes",
            "number": 1234,
            "complement": "Piso 7",
            "zipCode": "C1043AAY",
            "default": true,
            "nickname": "Buenos Aires Office"
        },
        "type": "OUTBOUND",
        "studyDocuments": [
            {
                "key": "dni"
            }
        ],
        "subType": "PERSON_TRANSFER",
        "personType": "PHYSICAL",
        "account": {
            "name": "Marty Bernier-Hermiston",
            "type": "OUTBOUND",
            "beneficiaryDocument": {
                "beneficiaryDocType": "DNI",
                "value": "12345678"
            },
            "bankName": "Banco de la Nación Argentina",
            "bankBranch": "0001",
            "bankCode": "285",
            "bankCountry": "ARG",
            "bankAccountType": "CH",
            "number": "2850590940090418135201",
            "code": {
                "option": "SWIFT_BIC",
                "value": "BNPAARBA"
            },
            "currency": "ARS",
            "paymentMethod": "BANK_ACCOUNT",
            "createdAt": "2025-09-10T18:33:25.261Z"
        }
    }
]

[
    {
        "fullName": "Lucas Emard III",
        "email": "[email protected]",
        "phone": "+51123456789",
        "cpf": "98765432100",
        "currency": "PEN",
        "address": {
            "country": "PE",
            "state": "LMA",
            "city": "Lima",
            "neighborhood": "Miraflores",
            "street": "Avenida Larco",
            "number": 890,
            "complement": "Oficina 501",
            "zipCode": "15074",
            "default": true,
            "nickname": "Lima Office"
        },
        "type": "OUTBOUND",
        "studyDocuments": [
            {
                "key": "dni"
            }
        ],
        "subType": "PERSON_TRANSFER",
        "personType": "PHYSICAL",
        "account": {
            "name": "Lynette Larkin",
            "type": "OUTBOUND",
            "beneficiaryDocument": {
                "beneficiaryDocType": "DNI",
                "value": "12345678"
            },
            "bankName": "Banco de Crédito del Perú",
            "bankBranch": "0001",
            "bankCode": "002",
            "bankCountry": "PER",
            "bankAccountType": "CH",
            "number": "00112345678901234567",
            "code": {
                "option": "SWIFT_BIC",
                "value": "BCPLPEPL"
            },
            "currency": "PEN",
            "paymentMethod": "BANK_ACCOUNT",
            "createdAt": "2025-09-10T18:36:40.285Z"
        }
    }
]

PreviousLegal Person NextList Outbound Beneficiaries