> For the complete documentation index, see [llms.txt](https://docs.neox.vn/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.neox.vn/docs/global/global-collections/integration/beneficiaries/api-register-beneficiary.md). # Register Beneficiary #### Endpoint: POST /v2/gc/beneficiaries #### Description: Register or update a beneficiary (payee/supplier) for payout operations. Supports overseas suppliers, domestic suppliers, and withdrawal accounts across SWIFT and LOCAL clearing networks. ## Request #### Request Body Field Descriptions (JSON) | Field Name | Type | Required | Description | | ----------------- | ----------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | requestId | string(32) | Yes | Merchant-generated unique request ID, maintained unique by the merchant. Used for idempotency. | | type | string(32) | Yes | Beneficiary reporting business type. Enum: `OVERSEAS_SUPPLIER` \| `DOMESTIC_SUPPLIER` \| `WITHDRAW_ACCOUNT`. | | supplierType | string(32) | Yes | Beneficiary entity type. Enum: `ENTERPRISE` \| `INDIVIDUAL`. | | accountType | string(3) | Yes | Beneficiary bank account type. Enum: `PRI` (personal) \| `PUB` (enterprise, default). See: Payee Reporting Elements. | | operate | string(6) | Conditional | Operation type. Enum: `ADD` (default) \| `UPDATE`. **Required when updating an existing beneficiary.** | | subMerchantId | string(32) | Conditional | Sub-merchant identifier. **Required when initiating the request as a sub-merchant.** | | recType | string(16) | Conditional | Beneficiary account type. If not provided, the system defaults to `BANK_ACCOUNT`. Enum: `BANK_ACCOUNT` (default) \| `WALLET_ACCOUNT` \| `GFC_ACCOUNT`. **Required when `type`=`OVERSEAS_SUPPLIER`.** | | businessType | string(64) | Conditional | Nature of the business relationship with the payee. Pass one value per request. Example: `GOODS_PURCHASE`. See: Business Type reference. **Required when `type`=`OVERSEAS_SUPPLIER` or `DOMESTIC_SUPPLIER`.** | | businessDetail | string(256) | Conditional | Business type segmentation / further detail. Example: Medical devices. **Required when `businessType` is "other" / uncategorized.** | | country | string(3) | Conditional | ISO 3166-1 alpha-3 country code of the beneficiary's location. See: Country/Region list. **Required when `type`=`DOMESTIC_SUPPLIER`, `accountCurrency`=`CNY`, `supplierType`=`INDIVIDUAL`, and the individual is a foreign national.** Example: `CHN`. | | address | string(256) | Conditional | Beneficiary's address. See: Payee Reporting Elements. **Required when (`type`=`OVERSEAS_SUPPLIER` and `recType`=`BANK_ACCOUNT`/`WALLET_ACCOUNT`) or (`type`=`WITHDRAW_ACCOUNT` and `bankCountry`=`CN`).** | | clearingType | string(5) | Conditional | Clearing network to use. Enum: `SWIFT` \| `LOCAL`. **Required when (`type`=`OVERSEAS_SUPPLIER` or `WITHDRAW_ACCOUNT`) and `recType`=`BANK_ACCOUNT`/`WALLET_ACCOUNT`.** | | accountName | string(128) | Conditional | Bank account beneficiary name (when `recType`=`BANK_ACCOUNT`) or wallet account name (when `recType`=`WALLET_ACCOUNT`). See: Payee Reporting Elements. **Required when `recType`=`BANK_ACCOUNT` or `WALLET_ACCOUNT`.** | | accountNameLocal | string(64) | No | Beneficiary account name in local language (e.g. Japanese half-width Katakana for JP LOCAL clearing). See: Additional Field Validation Rules for format requirements per country. | | accountNumber | string(128) | Conditional | Bank account number (when `recType`=`BANK_ACCOUNT`) or wallet account ID (when `recType`=`WALLET_ACCOUNT`). See: Payee Reporting Elements. **Required when `recType`=`BANK_ACCOUNT` or `WALLET_ACCOUNT`.** | | accountCurrency | string(3) | Conditional | ISO 4217 currency code of the beneficiary's receiving account (e.g. `USD`, `EUR`, `CNY`). **Required when `recType`=`BANK_ACCOUNT` or `WALLET_ACCOUNT`. When `type`=`DOMESTIC_SUPPLIER`, only `CNY` is supported.** | | bankName | string(70) | Conditional | Beneficiary's bank name (when `recType`=`BANK_ACCOUNT`) or wallet provider name (when `recType`=`WALLET_ACCOUNT`). See: Payee Reporting Elements. **Required when `recType`=`BANK_ACCOUNT` or `WALLET_ACCOUNT`.** | | bankCountry | string(3) | Conditional | ISO 3166-1 alpha-3 country code of the beneficiary's bank. See: Country/Region list. **Required when (`type`=`OVERSEAS_SUPPLIER` and `recType`=`BANK_ACCOUNT`/`WALLET_ACCOUNT`) or (`type`=`WITHDRAW_ACCOUNT` and `accountCurrency`=`CNY`).** Example: `USA`. | | swiftCode | string(11) | Conditional | Bank SWIFT/BIC code. See: Payee Reporting Elements. **Required when (`type`=`OVERSEAS_SUPPLIER` and `recType`=`BANK_ACCOUNT`/`WALLET_ACCOUNT`) or (`type`=`WITHDRAW_ACCOUNT` and `bankCountry`≠`CN`).** Example: `DHBKHKHH`. | | bankCode | string(3) | Conditional | 3-digit bank code. See: Payee Reporting Elements. **Required when (`type`=`OVERSEAS_SUPPLIER` or `WITHDRAW_ACCOUNT`), `clearingType`=`LOCAL`, `bankCountry`=`JP`. Recommended when `clearingType`=`LOCAL`, `bankCountry`=`HK`.** | | branchCode | string(6) | Conditional | Branch code. See: Payee Reporting Elements. **Required when (`type`=`OVERSEAS_SUPPLIER` or `WITHDRAW_ACCOUNT`) and `bankCountry`=`BR`/`JP`/`TR`.** | | sortCode | string(64) | Conditional | 6-digit sort code. See: Payee Reporting Elements. **Required when (`type`=`OVERSEAS_SUPPLIER` or `WITHDRAW_ACCOUNT`), `bankCountry`=`GB`, `clearingType`=`LOCAL`.** | | firstName | string(64) | Conditional | Beneficiary's first name. See: Payee Reporting Elements. **Required when (`type`=`OVERSEAS_SUPPLIER`, `recType`=`BANK_ACCOUNT`/`WALLET_ACCOUNT`, `accountType`=`PRI`) or (`type`=`WITHDRAW_ACCOUNT`, `accountType`=`PRI`).** | | middleName | string(64) | Conditional | Beneficiary's middle name. See: Payee Reporting Elements. **Required when (`type`=`OVERSEAS_SUPPLIER`, `recType`=`BANK_ACCOUNT`/`WALLET_ACCOUNT`, `accountType`=`PRI`) or (`type`=`WITHDRAW_ACCOUNT`, `accountType`=`PRI`), and the beneficiary has a middle name.** | | lastName | string(64) | Conditional | Beneficiary's last name / surname. See: Payee Reporting Elements. **Required when (`type`=`OVERSEAS_SUPPLIER`, `recType`=`BANK_ACCOUNT`/`WALLET_ACCOUNT`, `accountType`=`PRI`) or (`type`=`WITHDRAW_ACCOUNT`, `accountType`=`PRI`).** | | idType | string(64) | Conditional | Beneficiary identification document type. See: Payee Reporting Elements. Enum: `PASSPORT` \| `NATIONAL_ID` \| `DRIVING_LICENSE` \| `SOCIAL_SECURITY` \| `TAX_ID` \| `SENIOR_CITIZEN_ID` \| `BIRTH_CERTIFICATE` \| `RESIDENT_CARD` \| `ALIEN_REGISTRATION` \| `PAN_CARD` \| `VOTERS_ID` \| `HEALTH_CARD` \| `EMPLOYER_ID` \| `OTHER`. **Required when (`type`=`OVERSEAS_SUPPLIER` or `WITHDRAW_ACCOUNT`), `bankCountry`=`BR`/`AR`/`CO`/`SA`, `clearingType`=`LOCAL`.** | | idNumber | string(64) | Conditional | Beneficiary identification document number. See: Payee Reporting Elements. **Required when (`type`=`OVERSEAS_SUPPLIER` or `WITHDRAW_ACCOUNT`), `bankCountry`=`AR`/`BR`/`CO`/`SA`/`NG`/`AU`/`JP`/`MX`/`PK`, `clearingType`=`LOCAL`; or `type`=`WITHDRAW_ACCOUNT`, `bankCountry`=`CN`.** | | province | string(100) | Conditional | Province/state where the beneficiary is located. **Required when:** (1) (`type`=`OVERSEAS_SUPPLIER` or `WITHDRAW_ACCOUNT`), `bankCountry`=`US`/`CA`/`AU`/`ID`, `clearingType`=`LOCAL`; or (2) `type`=`DOMESTIC_SUPPLIER`, `bankCountry`=`CN`, `accountType`=`PRI` and `accountNumber` does not start with `62`; or `type`=`DOMESTIC_SUPPLIER`, `bankCountry`=`CN`, `accountType`=`PUB` and `bankName` is not in the exempted bank list. See: Payee Reporting Elements. | | city | string(100) | Conditional | City where the beneficiary is located. **Required when:** (1) (`type`=`OVERSEAS_SUPPLIER` or `WITHDRAW_ACCOUNT`), `bankCountry`=`US`/`CA`/`AU`/`ID`, `clearingType`=`LOCAL`; or (2) `type`=`DOMESTIC_SUPPLIER`, `bankCountry`=`CN`, `accountType`=`PRI` and `accountNumber` does not start with `62`; or `type`=`DOMESTIC_SUPPLIER`, `bankCountry`=`CN`, `accountType`=`PUB` and `bankName` is not in the exempted bank list. See: Payee Reporting Elements. | | postCode | string(64) | Conditional | Postal code of the beneficiary's location. See: Payee Reporting Elements. **Required when (`type`=`OVERSEAS_SUPPLIER` or `WITHDRAW_ACCOUNT`), `bankCountry`=`US`/`SA`/`AU`/`CA`/`BR`, `clearingType`=`LOCAL`.** | | abaNumber | string(64) | Conditional | 9-digit ABA routing number. See: Payee Reporting Elements. **Required when (`type`=`OVERSEAS_SUPPLIER` or `WITHDRAW_ACCOUNT`), `bankCountry`=`CA`/`US`, `clearingType`=`LOCAL`.** | | bsbCode | string(64) | Conditional | 6-digit BSB code. See: Payee Reporting Elements. **Required when (`type`=`OVERSEAS_SUPPLIER` or `WITHDRAW_ACCOUNT`), `bankCountry`=`AU`, `clearingType`=`LOCAL`.** | | ifsCode | string(64) | Conditional | IFSC code for Indian bank routing. See: Payee Reporting Elements. **Required when (`type`=`OVERSEAS_SUPPLIER` or `WITHDRAW_ACCOUNT`), `bankCountry`=`IN`, `clearingType`=`LOCAL`.** | | accountNoType | string(64) | Conditional | Account number type. Enum: `CHECKING` \| `SAVINGS`. See: Payee Reporting Elements. **Required when (`type`=`OVERSEAS_SUPPLIER` or `WITHDRAW_ACCOUNT`), `bankCountry`=`BR`/`AR`/`CO`, `clearingType`=`LOCAL`.** | | email | string(128) | Conditional | Beneficiary's email address. See: Payee Reporting Elements. **Required when (`type`=`OVERSEAS_SUPPLIER` or `WITHDRAW_ACCOUNT`), `bankCountry`=`IN`/`EG`/`BR`, `clearingType`=`LOCAL`.** | | mobile | string(64) | Conditional | Beneficiary's mobile phone number in international format. See: Payee Reporting Elements. **Required when (`type`=`OVERSEAS_SUPPLIER` or `WITHDRAW_ACCOUNT`), `bankCountry`=`AE`/`PH`/`NG`/`IN`/`JP`/`KE`/`BR`/`CO`, `clearingType`=`LOCAL`.** | | branchName | string(256) | Conditional | Branch name. See: List of banks not requiring branch details. **Required when `type`=`DOMESTIC_SUPPLIER`, `bankCountry`=`CN`, and (`accountType`=`PRI` with `accountNumber` not starting with `62`) or (`accountType`=`PUB` with `bankName` not in the exempted bank list).** | | loginName | string(256) | Conditional | Login username for the beneficiary's account at the partner. **Required when `recType`=`GFC_ACCOUNT`.** | | merchantName | string(256) | Conditional | Contract/signing name of the beneficiary merchant. **Required when `recType`=`GFC_ACCOUNT`.** | | accountHolder | string(512) | Conditional | Account holder relationship to the contracting entity. Enum: `CONTRACT_SUBJECT` \| `DIRECTOR` \| `SHAREHOLDER` \| `LEGALPERSON`. **Required when `type`=`WITHDRAW_ACCOUNT`.** | | supplierName | string(128) | No | Beneficiary / payee name. | | alias | string(256) | No | Beneficiary alias / nickname for merchant-side reference. | | vouchers | string(512) | No | Business-related material file paths. Array of uploaded file paths. Supports `jpg`, `jpeg`, `png`, `pdf`, `zip`, `rar`, `tar` formats; max 20MB per file, max 20 files. After receiving the supplementary material notification, call the Beneficiary Supplement Material API to provide these. Example: `["gfc/UPLOAD/67a246a6-3b54-4519-9de1-bc825b3ee198.jpeg"]`. | | bankAddress | string(128) | No | Address of the beneficiary's bank. | | remark | string(128) | No | Free-text remark or note for this beneficiary. | | notifyUrl | string(256) | No | Merchant-provided URL to receive asynchronous registration status notifications. Recommended. | | fedWireNumber | string(64) | No | FedWire number. See: Payee Reporting Elements. | | iban | string(64) | No | International Bank Account Number. See: Payee Reporting Elements. | | routingNumber | string(64) | No | Bank routing number. See: Payee Reporting Elements. | | streetAddress | string(105) | No | Beneficiary's permanent / residential address. | | payeeExpiryDate | string(32) | No | Document expiration date for the beneficiary's identification. | | isHighValuePayout | string(32) | No | Whether the payout amount exceeds 300 million VND. Enum: `yes` \| `no`. Specific to certain channels and merchants; optional for others. | #### Request sample ```json { "requestId": "b2e4f6a8-5678-4321-cdef-0123456789ab", "type": "OVERSEAS_SUPPLIER", "supplierType": "ENTERPRISE", "accountType": "PUB", "operate": "ADD", "recType": "BANK_ACCOUNT", "businessType": "GOODS_PURCHASE", "accountName": "Acme Global Trading Ltd", "accountNumber": "1234567890", "accountCurrency": "USD", "bankName": "JPMorgan Chase Bank", "bankCountry": "USA", "clearingType": "LOCAL", "swiftCode": "CHASUS33", "abaNumber": "021000021", "address": "123 Business Park, New York, NY 10001", "email": "payments@acmeglobal.com", "notifyUrl": "https://merchant.example.com/webhooks/beneficiary" } ``` ### Response #### Response Field Descriptions | Field Name | Type | Description | | ------------- | ------ | -------------------------------------------------------------------------------------------------- | | code | number | Response code. Refer to [Error Codes](/docs/global/global-collections/integration/error-codes.md). | | state | number | State of the response. | | data | object | Registered beneficiary details. | | message | string | Response message. | | neoResponseId | string | Unique NeoX response identifier (UUID). | #### `data` object fields: | Field Name | Type | Description | | ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------ | | requestId | string | Echoes the merchant-provided `requestId`. | | merchantId | string | NeoX merchant identifier. | | subMerchantId | string | Sub-merchant identifier associated with this beneficiary, if applicable. | | status | string | Registration status. Enum: `SUCCESS` \| `RISK_REBUT` \| `WAIT_SUPPLEMENT_MATERIAL` \| `ACTIVATED` \| `FAILED` \| `PROCESSING`. | | beneficiaryId | string | Unique NeoX identifier for the registered beneficiary. Use this ID in subsequent payout requests. | #### Response sample ```json { "code": 1, "state": 2, "data": { "requestId": "b2e4f6a8-5678-4321-cdef-0123456789ab", "merchantId": "MERCH-00012345", "subMerchantId": "", "status": "PROCESSING", "beneficiaryId": "BEN-20240501-000456789" }, "message": "Successful", "neoResponseId": "de7750c5-772e-4136-ac78-62c57a106cce" } ``` ## Example cURL ```bash curl -X POST "https://{base_url_openapi}/v2/gc/beneficiaries" \ -H "Authorization: Bearer " \ -H "Content-Type: application/json" \ -H "Accept-Language: en" \ -d '{ "requestId": "b2e4f6a8-5678-4321-cdef-0123456789ab", "type": "OVERSEAS_SUPPLIER", "supplierType": "ENTERPRISE", "accountType": "PUB", "operate": "ADD", "recType": "BANK_ACCOUNT", "businessType": "GOODS_PURCHASE", "accountName": "Acme Global Trading Ltd", "accountNumber": "1234567890", "accountCurrency": "USD", "bankName": "JPMorgan Chase Bank", "bankCountry": "USA", "clearingType": "LOCAL", "swiftCode": "CHASUS33", "abaNumber": "021000021", "address": "123 Business Park, New York, NY 10001", "email": "payments@acmeglobal.com", "notifyUrl": "https://merchant.example.com/webhooks/beneficiary" }' ``` ### Notes * Requires Bearer token in the Authorization header. * The Accept-Language header can be used to specify the response language (Support: `vi`, `en`). * Use a unique `requestId` for each registration request to avoid duplicate beneficiary records. * To update an existing beneficiary, pass the same `requestId` used in the original registration and set `operate` to `UPDATE`. * The `beneficiaryId` returned in the response should be stored by the merchant and referenced in payout requests. * A `status` of `PROCESSING` indicates the registration is under review; poll [Get Detail Beneficiary](/docs/global/global-collections/integration/beneficiaries/get-detail-beneficiary.md) or wait for the notification at `notifyUrl` for the final status. * `recType` defaults to `BANK_ACCOUNT` if not explicitly provided. * `accountType` defaults to `PUB` (enterprise/corporate) if not explicitly provided. * `operate` defaults to `ADD` (new registration) if not provided. * **Conditional field requirements**: Many fields are conditionally required based on the combination of `type`, `bankCountry`, `clearingType`, `recType`, `accountType`, and `supplierType`. Refer to the detailed conditions in the field descriptions above. Key dependencies include: * **SWIFT clearing**: `swiftCode` is required for overseas suppliers and withdrawal accounts when `bankCountry` ≠ `CN`. * **LOCAL clearing**: Country-specific fields (`abaNumber`, `bsbCode`, `sortCode`, `ifsCode`, `bankCode`, `branchCode`, `postCode`, `accountNoType`, `idType`, `idNumber`, `email`, `mobile`) are required depending on the destination country. * **Individual payees (`accountType`=`PRI`)**: `firstName`, `lastName` are required; `middleName` is required when applicable. * **GFC accounts (`recType`=`GFC_ACCOUNT`)**: `loginName` and `merchantName` are required. * **Withdrawal accounts (`type`=`WITHDRAW_ACCOUNT`)**: `accountHolder` is always required. * `vouchers` (business-related materials) should be supplemented via the Beneficiary Supplement Material API after receiving the supplementary material notification. Supported formats: `jpg`, `jpeg`, `png`, `pdf`, `zip`, `rar`, `tar`; max 20MB per file, max 20 files. * For a list of supported beneficiary banks, use [Get List Beneficiary Banks](/docs/global/global-collections/integration/beneficiaries/get-list-beneficiary-banks.md). * Country codes follow ISO 3166-1 alpha-3 (e.g. `USA`, `GBR`, `CHN`). * Currency codes follow ISO 4217 (e.g. `USD`, `EUR`, `CNY`). ## Additional Field Validation Rules {% hint style="info" %} The tables below define per-field format constraints, length limits, and regex validation patterns for specific country and clearing type combinations. These rules supplement the field descriptions in the request body table above. Fields not listed for a given scenario are either not applicable or have no additional format constraints beyond those described in the main table. {% endhint %}
SWIFT Clearing — OVERSEAS_SUPPLIER — BANK_ACCOUNT — Overseas Payment (OVERSEA_PAYMENT) — G10 Currencies — All Countries | Field | Required | Format Constraints | | ------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | accountName | M | Max 128 characters. English letters, digits, spaces, and special chars `/ ( ) . , - ? : & ' +`. No line breaks. Regex: `^[A-Za-z0-9 /().,?:&'+-]*$` | | accountNumber | M | Max 34 characters. Digits or letters only. Regex: `^[A-Za-z0-9]+$` | | bankName | M | Must not contain Chinese characters. Regex: `^[^一-龥]{0,}$` | | swiftCode | M | 8 or 11 characters, alphanumeric. Regex: `^[A-Za-z0-9]+$` | | streetAddress | M | Max 256 characters. English letters, digits, spaces, and special chars `/ ( ) . , - ? : ' + #`. No line breaks. Cannot be purely numeric. Regex: `^(?![0-9]+$)(?=.*[a-zA-Z /().,?:'+\-#])[a-zA-Z0-9 /().,?\-:'+\s#]*$` |
SWIFT Clearing — OVERSEAS_SUPPLIER — BANK_ACCOUNT — Withdrawal (WITHDRAW) — G10 Currencies — All Countries | Field | Required | Format Constraints | | ------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | accountName | M | Max 128 characters. English letters, digits, spaces, and special chars `/ ( ) . , - ? : ' +`. No line breaks. Regex: `^[A-Za-z0-9 /().,?:'+-]*$` | | accountNumber | M | Max 34 characters. Digits or letters only. Regex: `^[A-Za-z0-9]+$` | | bankName | M | Must not contain Chinese characters. Regex: `^[^一-龥]{0,}$` | | swiftCode | M | 8 or 11 characters, alphanumeric. Regex: `^[A-Za-z0-9]+$` | | streetAddress | M | Max 256 characters. English letters, digits, spaces, and special chars `/ ( ) . , - ? : ' + #`. No line breaks. Cannot be purely numeric. Regex: `^(?![0-9]+$)(?=.*[a-zA-Z /().,?:'+\-#])[a-zA-Z0-9 /().,?\-:'+\s#]*$` |
Hong Kong (HK) — LOCAL Clearing — OVERSEAS_SUPPLIER — BANK_ACCOUNT — Individual (PRI) — HKD/USD/CNH | Field | Required | Format Constraints | | ------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | accountName | M | Max 70 characters. English letters, digits, spaces, and special chars `/ ( ) . , - ? : ' +`. No line breaks. Regex: `^[A-Za-z0-9 /().,?:'+-]*$` | | accountNumber | M | Max 34 characters. Must not contain Chinese characters. Regex: `^[^一-龥]{0,}$` | | bankName | M | No validation on bank name. Max 70 characters. | | swiftCode | M | 8 or 11 characters, alphanumeric. Regex: `^[A-Za-z0-9]+$` | | bankCode | O | Exactly 3 digits (HK bank code). Recommended. Regex: `^[0-9]+$` | | streetAddress | M | Max 256 characters. English letters, digits, spaces, and special chars `/ ( ) . , - ? : ' + #`. No line breaks. Cannot be purely numeric. Regex: `^(?![0-9]+$)(?=.*[a-zA-Z /().,?:'+\-#])[a-zA-Z0-9 /().,?\-:'+\s#]*$` |
Hong Kong (HK) — LOCAL Clearing — OVERSEAS_SUPPLIER — BANK_ACCOUNT — Enterprise (PUB) — HKD/USD/CNH | Field | Required | Format Constraints | | ------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | accountName | M | Max 70 characters. English letters, digits, spaces, and special chars `/ ( ) . , - ? : ' +`. No line breaks. Regex: `^[A-Za-z0-9 /().,?:'+-]*$` | | accountNumber | M | Max 34 characters. Must not contain Chinese characters. Regex: `^[^一-龥]{0,}$` | | bankName | M | No validation on bank name. Max 70 characters. | | swiftCode | M | 8 or 11 characters, alphanumeric. Regex: `^[A-Za-z0-9]+$` | | bankCode | O | Exactly 3 digits (HK bank code). Recommended. Regex: `^[0-9]+$` | | streetAddress | M | Max 256 characters. English letters, digits, spaces, and special chars `/ ( ) . , - ? : ' + #`. No line breaks. Cannot be purely numeric. Regex: `^(?![0-9]+$)(?=.*[a-zA-Z /().,?:'+\-#])[a-zA-Z0-9 /().,?\-:'+\s#]*$` |
United States (US) — LOCAL Clearing — OVERSEAS_SUPPLIER — BANK_ACCOUNT — Individual (PRI) — USD | Field | Required | Format Constraints | | ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | accountName | M | Max 128 characters. English letters, digits, spaces, and special chars `/ ( ) . , - ? : ' +`. No line breaks. Cannot be purely numeric. Regex: `^(?![0-9]+$)(?=.*[a-zA-Z /().,?:'+-])[a-zA-Z0-9 /().,-?:'+\s]*$` | | accountNumber | M | 3–33 characters, alphanumeric only. Regex: `^[A-Za-z0-9]+$` | | abaNumber | M | Exactly 9 digits. Regex: `^[0-9]*$` | | bankName | M | No validation on bank name. | | swiftCode | M | 8 or 11 characters, alphanumeric. Regex: `^[A-Za-z0-9]+$` | | firstName | M | Max 64 characters. English letters, digits, spaces, and special chars `/ ( ) . , - ? : ' +`. No line breaks. Cannot be purely numeric. Regex: `^(?![0-9]+$)(?=.*[a-zA-Z /().,?:'+-])[a-zA-Z0-9 /().,\-?:'+\s]*$` | | lastName | M | Max 64 characters. Same format as `firstName`. Regex: `^(?![0-9]+$)(?=.*[a-zA-Z /().,?:'+-])[a-zA-Z0-9 /().,\-?:'+\s]*$` | | province | M | Must be a valid US state. Enum: `Alabama` \| `Alaska` \| `Arizona` \| `Arkansas` \| `California` \| `Colorado` \| `Connecticut` \| `Delaware` \| `Florida` \| `Georgia` \| `Hawaii` \| `Idaho` \| `Illinois` \| `Indiana` \| `Iowa` \| `Kansas` \| `Kentucky` \| `Louisiana` \| `Maine` \| `Maryland` \| `Massachusetts` \| `Michigan` \| `Minnesota` \| `Mississippi` \| `Missouri` \| `Montana` \| `Nebraska` \| `Nevada` \| `New Hampshire` \| `New Jersey` \| `New Mexico` \| `New York` \| `North Carolina` \| `North Dakota` \| `Ohio` \| `Oklahoma` \| `Oregon` \| `Pennsylvania` \| `Rhode Island` \| `South Carolina` \| `South Dakota` \| `Tennessee` \| `Texas` \| `Utah` \| `Vermont` \| `Virginia` \| `Washington` \| `West Virginia` \| `Wisconsin` \| `Wyoming` | | city | M | Must not contain Chinese characters. Regex: `^[^一-龥]{0,}$` | | streetAddress | M | Max 256 characters. English letters, digits, spaces, and special chars `/ ( ) . , - ? : ' + #`. No line breaks. Cannot be purely numeric. Regex: `^(?![0-9]+$)(?=.*[a-zA-Z /().,?:'+\-#])[a-zA-Z0-9 /().,?\-:'+\s#]*$` | | postCode | M | Must not contain Chinese characters. Regex: `^[^一-龥]{0,}$` |
United States (US) — LOCAL Clearing — OVERSEAS_SUPPLIER — BANK_ACCOUNT — Enterprise (PUB) — USD | Field | Required | Format Constraints | | ------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | accountName | M | Max 128 characters. English letters, digits, spaces, and special chars `/ ( ) . , - ? : ' +`. No line breaks. Cannot be purely numeric. Regex: `^(?![0-9]+$)(?=.*[a-zA-Z /().,?:'+-])[a-zA-Z0-9 /().,-?:'+\s]*$` | | accountNumber | M | 3–33 characters, alphanumeric only. Regex: `^[A-Za-z0-9]+$` | | abaNumber | M | Exactly 9 digits. Regex: `^[0-9]*$` | | bankName | M | No validation on bank name. | | swiftCode | M | 8 or 11 characters, alphanumeric. Regex: `^[A-Za-z0-9]+$` | | province | M | Must be a valid US state. Enum: Same 50-state list as Individual (PRI) section above. | | city | M | Must not contain Chinese characters. Regex: `^[^一-龥]{0,}$` | | streetAddress | M | Max 256 characters. English letters, digits, spaces, and special chars `/ ( ) . , - ? : ' + #`. No line breaks. Cannot be purely numeric. Regex: `^(?![0-9]+$)(?=.*[a-zA-Z /().,?:'+\-#])[a-zA-Z0-9 /().,?\-:'+\s#]*$` | | postCode | M | Must not contain Chinese characters. Regex: `^[^一-龥]{0,}$` |
Canada (CA) — LOCAL Clearing — OVERSEAS_SUPPLIER — BANK_ACCOUNT — Individual (PRI) — CAD | Field | Required | Format Constraints | | ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | accountName | M | Max 128 characters. English letters, digits, spaces, and special chars `/ ( ) . , - ? : ' +`. No line breaks. Cannot be purely numeric. Regex: `^(?![0-9]+$)(?=.*[a-zA-Z /().,?:'+-])[a-zA-Z0-9 /().,-?:'+\s]*$` | | accountNumber | M | 3–33 characters, alphanumeric only. Regex: `^[A-Za-z0-9]+$` | | abaNumber | M | Exactly 9 digits. Regex: `^[0-9]*$` | | bankName | M | Strict validation on bank name (must match known Canadian banks). | | swiftCode | M | 8 or 11 characters, alphanumeric. Regex: `^[A-Za-z0-9]+$` | | bankCode | O | Exactly 3 digits. Regex: `^\d{3}$` | | branchCode | O | Exactly 5 digits. Regex: `^\d{5}$` | | firstName | M | Max 64 characters. English letters, digits, spaces, and special chars `/ ( ) . , - ? : ' +`. No line breaks. Cannot be purely numeric. Regex: `^(?![0-9]+$)(?=.*[a-zA-Z /().,?:'+-])[a-zA-Z0-9 /().,\-?:'+\s]*$` | | lastName | M | Max 64 characters. Same format as `firstName`. Regex: `^(?![0-9]+$)(?=.*[a-zA-Z /().,?:'+-])[a-zA-Z0-9 /().,\-?:'+\s]*$` | | province | M | Must be a valid Canadian province/territory. Enum: `Alberta (AB)` \| `British Columbia (BC)` \| `Manitoba (MB)` \| `New Brunswick (NB)` \| `Newfoundland and Labrador (NL)` \| `Nova Scotia (NS)` \| `Ontario (ON)` \| `Prince Edward Island (PE)` \| `Quebec (QC)` \| `Saskatchewan (SK)` \| `Northwest Territories (NT)` \| `Nunavut (NU)` \| `Yukon (YT)` | | city | M | Must not contain Chinese characters. Regex: `^[^一-龥]{0,}$` | | streetAddress | M | Max 256 characters. English letters, digits, spaces, and special chars `/ ( ) . , - ? : ' + #`. No line breaks. Cannot be purely numeric. Regex: `^(?![0-9]+$)(?=.*[a-zA-Z /().,?:'+\-#])[a-zA-Z0-9 /().,?\-:'+\s#]*$` | | postCode | M | No format constraint. |
Canada (CA) — LOCAL Clearing — OVERSEAS_SUPPLIER — BANK_ACCOUNT — Enterprise (PUB) — CAD | Field | Required | Format Constraints | | ------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | accountName | M | Max 128 characters. English letters, digits, spaces, and special chars `/ ( ) . , - ? : ' +`. No line breaks. Cannot be purely numeric. Regex: `^(?![0-9]+$)(?=.*[a-zA-Z /().,?:'+-])[a-zA-Z0-9 /().,-?:'+\s]*$` | | accountNumber | M | 3–33 characters, alphanumeric only. Regex: `^[A-Za-z0-9]+$` | | abaNumber | M | Exactly 9 digits. Regex: `^[0-9]*$` | | bankName | M | Strict validation on bank name (must match known Canadian banks). | | swiftCode | M | 8 or 11 characters, alphanumeric. Regex: `^[A-Za-z0-9]+$` | | bankCode | O | Exactly 3 digits. Regex: `^\d{3}$` | | branchCode | O | Exactly 5 digits. Regex: `^\d{5}$` | | province | M | Must be a valid Canadian province/territory. Enum: Same 13-item list as Individual (PRI) section above. | | city | M | Must not contain Chinese characters. Regex: `^[^一-龥]{0,}$` | | streetAddress | M | Max 256 characters. English letters, digits, spaces, and special chars `/ ( ) . , - ? : ' + #`. No line breaks. Cannot be purely numeric. Regex: `^(?![0-9]+$)(?=.*[a-zA-Z /().,?:'+\-#])[a-zA-Z0-9 /().,?\-:'+\s#]*$` | | postCode | M | No format constraint. |
Vietnam (VN) — LOCAL Clearing — OVERSEAS_SUPPLIER — BANK_ACCOUNT — Individual (PRI) — VND | Field | Required | Format Constraints | | ------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | accountName | M | Max 128 characters. English letters, digits, spaces, and special chars `/ ( ) . , - ? : ' +`. No line breaks. Cannot be purely numeric. Must not contain Chinese characters. Regex: `^[^一-龥]{0,}$` | | accountNumber | M | 3–33 characters, alphanumeric only. Regex: `^[A-Za-z0-9]+$` | | bankName | M | Strict validation on bank name (must match known Vietnamese banks). | | swiftCode | M | 8 or 11 characters, alphanumeric. Regex: `^[A-Za-z0-9]+$` | | firstName | M | Max 64 characters. Must not contain Chinese characters. Regex: `^[^一-龥]{0,}$` | | middleName | O | Max 40 characters. Must not contain Chinese characters. Regex: `^[^一-龥]{0,}$` | | lastName | M | Max 64 characters. Must not contain Chinese characters. Regex: `^[^一-龥]{0,}$` | | streetAddress | M | Max 256 characters. English letters, digits, spaces, and special chars `/ ( ) . , - ? : ' + #`. No line breaks. Cannot be purely numeric. Regex: `^(?![0-9]+$)(?=.*[a-zA-Z /().,?:'+\-#])[a-zA-Z0-9 /().,?\-:'+\s#]*$` |
Vietnam (VN) — LOCAL Clearing — OVERSEAS_SUPPLIER — BANK_ACCOUNT — Enterprise (PUB) — VND | Field | Required | Format Constraints | | ------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | accountName | M | Max 128 characters. English letters, digits, spaces, and special chars `/ ( ) . , - ? : ' +`. No line breaks. Cannot be purely numeric. Regex: `^(?![0-9]+$)(?=.*[a-zA-Z /().,?:'+-])[a-zA-Z0-9 /().,-?:'+\s]*$` | | accountNumber | M | 3–33 characters, alphanumeric only. Regex: `^[A-Za-z0-9]+$` | | bankName | M | Strict validation on bank name (must match known Vietnamese banks). | | swiftCode | M | 8 or 11 characters, alphanumeric. Regex: `^[A-Za-z0-9]+$` | | streetAddress | M | Max 256 characters. English letters, digits, spaces, and special chars `/ ( ) . , - ? : ' + #`. No line breaks. Cannot be purely numeric. Regex: `^(?![0-9]+$)(?=.*[a-zA-Z /().,?:'+\-#])[a-zA-Z0-9 /().,?\-:'+\s#]*$` |
Japan (JP) — LOCAL Clearing — OVERSEAS_SUPPLIER — BANK_ACCOUNT — Individual (PRI) — JPY | Field | Required | Format Constraints | | ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | accountNumber | M | Max 10 characters, alphanumeric only. Regex: `^[a-zA-Z0-9]+$` | | accountName | M | Max 256 characters. Supports half-width Katakana, English letters, digits, spaces, and special chars `/ ( ) . , - ? : ' +`. No line breaks. Cannot be purely numeric. Regex: `^(?![0-9]+$)(?=.*[a-zA-Zァ-ヺ /().,?:'+-])[a-zA-Z0-9ァ-ヺ /().,?:'+\s-]*$` | | accountNameLocal | O | 1–64 characters. Half-width Katakana and English spaces only. Regex: `[･-ﾟ\s]{1,64}` | | bankName | M | No validation on bank name. | | swiftCode | M | 8 or 11 characters, alphanumeric. Regex: `^[A-Za-z0-9]+$` | | bankCode | M | Exactly 4 digits. Regex: `^[0-9]+$` | | branchCode | M | Exactly 3 digits. Regex: `^[0-9]+$` | | accountNoType | M | Enum: `SAVINGS` (Savings Account) \| `CHECKING` (Checking Account) | | firstName | M | Max 64 characters. English letters, digits, spaces, and special chars `/ ( ) . , - ? : ' +`. No line breaks. Cannot be purely numeric. Regex: `^(?![0-9]+$)(?=.*[a-zA-Z /().,?:'+-])[a-zA-Z0-9 /().,\-?:'+\s]*$` | | lastName | M | Max 64 characters. Same format as `firstName`. Regex: `^(?![0-9]+$)(?=.*[a-zA-Z /().,?:'+-])[a-zA-Z0-9 /().,\-?:'+\s]*$` | | streetAddress | M | Max 256 characters. English letters, digits, spaces, and special chars `/ ( ) . , - ? : ' + #`. No line breaks. Cannot be purely numeric. Regex: `^(?![0-9]+$)(?=.*[a-zA-Z /().,?:'+\-#])[a-zA-Z0-9 /().,?\-:'+\s#]*$` | | province | O | No format constraint. | | city | O | No format constraint. | | mobile | M | No format constraint. | | postCode | O | No format constraint. |
Japan (JP) — LOCAL Clearing — OVERSEAS_SUPPLIER — BANK_ACCOUNT — Enterprise (PUB) — JPY | Field | Required | Format Constraints | | ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | accountNumber | M | Max 10 characters, alphanumeric only. Regex: `^[a-zA-Z0-9]+$` | | accountName | M | Max 256 characters. Supports half-width Katakana, English letters, digits, spaces, and special chars `/ ( ) . , - ? : ' +`. No line breaks. Cannot be purely numeric. Regex: `^(?![0-9]+$)(?=.*[a-zA-Zァ-ヺ /().,?:'+-])[a-zA-Z0-9ァ-ヺ /().,?:'+\s-]*$` | | accountNameLocal | O | 1–64 characters. Half-width Katakana and English spaces only. Regex: `[･-ﾟ\s]{1,64}` | | bankName | M | No validation on bank name. | | swiftCode | M | 8 or 11 characters, alphanumeric. Regex: `^[A-Za-z0-9]+$` | | bankCode | M | Exactly 4 digits. Regex: `^[0-9]+$` | | branchCode | M | Exactly 3 digits. Regex: `^[0-9]+$` | | accountNoType | M | Enum: `SAVINGS` (Savings Account) \| `CHECKING` (Checking Account) | | streetAddress | M | Max 256 characters. English letters, digits, spaces, and special chars `/ ( ) . , - ? : ' + #`. No line breaks. Cannot be purely numeric. Regex: `^(?![0-9]+$)(?=.*[a-zA-Z /().,?:'+\-#])[a-zA-Z0-9 /().,?\-:'+\s#]*$` | | supplierName | M | No format constraint. (Payee name) | | province | O | No format constraint. | | city | O | No format constraint. | | mobile | M | No format constraint. | | idNumber | M | No format constraint. (Payee ID document number) |
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.neox.vn/docs/global/global-collections/integration/beneficiaries/api-register-beneficiary.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.