> 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. {% hint style="info" %} **Countries/currencies live in the Merchant Portal UI today (Phase 1):** the backend DTO itself does not restrict `country`/`bankCountry`/`accountCurrency` beyond basic 3-character codes, but the Merchant Portal UI currently only exposes countries `VNM`, `HKG`, `AUS`, `USA` with currencies `VND`, `USD`, `AUD`, mapped as `VNM → [VND, USD]`, `HKG → [USD, AUD]`, `AUS → [USD, AUD]`, `USA → [USD, AUD]`. Supported `clearingType` per country|currency in the UI: `VNM|VND → LOCAL`, `VNM|USD → SWIFT`, `HKG|USD → LOCAL, SWIFT`, `HKG|AUD → SWIFT`, `AUS|USD → SWIFT`, `AUS|AUD → LOCAL, SWIFT`, `USA|USD → LOCAL, SWIFT`, `USA|AUD → SWIFT`. If integrating directly via API for another country/currency combination, confirm end-to-end processor support with the NeoX integration team before relying on the broader per-country tables in this document. {% endhint %} ## 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. Enum (16 values): `GOODS_PURCHASE` \| `ADVERTISING_SERVICE` \| `LOGISTICS_SERVICE` \| `TAX_DECLARATION` \| `INSURANCE_FEE` \| `LEGAL_CONSULTING` \| `FINANCIAL_SERVICE` \| `TECHNICAL_SERVICE` \| `TRAVEL_PROCUREMENT` \| `STUDY_ABROAD` \| `AFFILIATED_COMPANY` \| `EMPLOYEE_COMPENSATION` \| `COMMISSION_PAYMENT` \| `OPERATION_RELATED` \| `OPERATION_AGENCY` \| `OTHERS`. **Required when `type`=`OVERSEAS_SUPPLIER`** (also required when `type`=`DOMESTIC_SUPPLIER` per this logic, though that path is currently unreachable since `DOMESTIC_SUPPLIER` is disabled in the Merchant Portal UI). | | 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`. required whenever `type`=`WITHDRAW_ACCOUNT` unconditionally (no `accountCurrency`=`CNY` restriction) — see reconciliation note below. | | 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` \| `VILLAGE_ELDER_ID` \| `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. | | webhookUrl | string(256) | No | Merchant-provided URL to receive asynchronous registration status notifications (`BENEFICIARY_REGISTRATION` webhook). 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 This is a real captured request/response pair (not a fabricated illustrative example): ```json { "requestId": "1785560724621", "type": "OVERSEAS_SUPPLIER", "supplierType": "ENTERPRISE", "accountType": "PUB", "subMerchantId": "10000002", "recType": "BANK_ACCOUNT", "businessType": "FINANCIAL_SERVICE", "businessDetail": "bs detail", "country": "CHN", "clearingType": "SWIFT", "accountName": "nguynen van doc", "accountNumber": "0123456789", "accountCurrency": "USD", "bankName": "CHARISTER", "bankCountry": "USA", "swiftCode": "TESTUS12", "address": "66 PHO DUC CHINH", "supplierName": "Supplier Ltd", "webhookUrl": "https://usewebhook.com/0389df097d05b25adfd90ebabbf7ff76" } ``` ### Response #### Response Field Descriptions | Field Name | Type | Description | | ------------- | ------ | -------------------------------------------------------------------------------------------------- | | code | number | Response code. Refer to [Error Codes](/docs/global/global-collections/integration/error-codes.md). | | data | object | Registered beneficiary details. | | message | string | Response message. | | neoResponseId | string | Unique NeoX response identifier (UUID). | {% hint style="warning" %} There is no `state` field in the response envelope. Every Global Collections response is `{code, data, message}` plus an optional `neoResponseId`. {% endhint %} #### `data` object fields: | Field Name | Type | Description | | ---------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | id | string | Unique NeoX identifier for the registered beneficiary. Use this ID in subsequent payout requests and in Get/Update/Supplement calls. | | requestId | string | Echoes the merchant-provided `requestId`. | | status | string | Registration status observed value: `PENDING`. Other status values appear in [Get Detail Beneficiary](/docs/global/global-collections/integration/beneficiaries/get-detail-beneficiary.md) and the [Webhook](/docs/global/global-collections/integration/beneficiaries/webhook.md) (e.g. `WAIT_SUPPLEMENT`, `APPROVED`). | {% hint style="warning" %} The response uses **`id`** as the beneficiary identifier on create. {% endhint %} #### Response sample ```json { "code": 1, "data": { "id": "c158e91abcce4f8fa076be3d8cc7e080", "requestId": "1785560724621", "status": "PENDING" }, "message": "Successful", "neoResponseId": "0c3585c0-a4ca-44bd-8056-161d5512578a" } ``` ## 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": "1785560724621", "type": "OVERSEAS_SUPPLIER", "supplierType": "ENTERPRISE", "accountType": "PUB", "subMerchantId": "10000002", "recType": "BANK_ACCOUNT", "businessType": "FINANCIAL_SERVICE", "businessDetail": "bs detail", "country": "CHN", "clearingType": "SWIFT", "accountName": "nguynen van doc", "accountNumber": "0123456789", "accountCurrency": "USD", "bankName": "CHARISTER", "bankCountry": "USA", "swiftCode": "TESTUS12", "address": "66 PHO DUC CHINH", "supplierName": "Supplier Ltd", "webhookUrl": "https://usewebhook.com/0389df097d05b25adfd90ebabbf7ff76" }' ``` ### 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, use `PUT /v2/gc/beneficiaries` — see [Update Beneficiary](#update-beneficiary) below. * The `id` returned in the response should be stored by the merchant and referenced in payout requests and in Get/Update/Supplement calls. * A `status` of `PENDING` indicates the registration was accepted and is under review; poll [Get Detail Beneficiary](/docs/global/global-collections/integration/beneficiaries/get-detail-beneficiary.md) or listen for the `BENEFICIARY_REGISTRATION` webhook (see [Webhook](/docs/global/global-collections/integration/beneficiaries/webhook.md)) for the final status. * `recType` defaults to `BANK_ACCOUNT` if not explicitly 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, and the `{% hint %}` notes marking where the Merchant Portal UI's own validation matrix is narrower than the documented API-level conditions. 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 `POST /v2/gc/beneficiaries/supplement` — see [Supplement Beneficiary Material](#supplement-beneficiary-material) below. Supported formats: `jpg`, `jpeg`, `png`, `pdf`, `zip`, `rar`, `tar`; max 20MB per file, max 20 files. * There is no `GET /v2/gc/beneficiary-banks` endpoint — the list of supported beneficiary banks is not exposed via API today. See the notice on [Get List Beneficiary Banks](https://github.com/neopayvn/neox-gitbook-documents-v2/tree/main/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`). ## Update Beneficiary #### Endpoint: PUT /v2/gc/beneficiaries Updates fields on a previously registered beneficiary. Only allowed when the beneficiary's current `status` is `INIT` or `APPROVED` — attempting to update a beneficiary in any other status is rejected. The request body is the same field set as registration (all fields effectively optional on update), plus `id` to locate the record. The gateway reshapes the flat body into a filter + update-data pair server-side; you don't need to construct that shape yourself. Response: ```json { "code": 1, "data": { "message": "", "id": "c158e91abcce4f8fa076be3d8cc7e080", "requestId": "1785560724621" }, "message": "Successful" } ``` No real captured sample is available for this endpoint yet — the field names/shape above are derived from the backend code; values are placeholders. ## Supplement Beneficiary Material #### Endpoint: POST /v2/gc/beneficiaries/supplement Submits supporting document(s) (`vouchers`) for a beneficiary that is `WAIT_SUPPLEMENT` after registration (see the [Webhook](/docs/global/global-collections/integration/beneficiaries/webhook.md) page for how this notification arrives). | Field Name | Type | Required | Description | | ---------- | ---------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | string | Yes | The beneficiary's `id`, as returned by the Register Beneficiary API. | | requestId | string(32) | Yes | Merchant-generated unique request ID for this supplement submission. | | vouchers | array | No | Business-related material file paths (accepts a single string or an array; coerced to an array server-side). Each element must be a `path` returned by the File Upload API (`POST /v2/gc/files/upload`). | Real captured example: ```json // Request { "id": "c158e91abcce4f8fa076be3d8cc7e080", "requestId": "1785560724621", "vouchers": ["/uploads/voucher1.pdf"] } ``` ```json // Response { "code": 1, "data": { "id": "c158e91abcce4f8fa076be3d8cc7e080", "requestId": "1785560724621", "status": "SUPPLEMENT_SUBMITTED" }, "message": "Successful", "neoResponseId": "e6813402-5c28-4bb2-b95d-794dd92ecb93" } ``` ## 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. These per-scenario tables reflect documented API-level behavior; length limits (`string(N)`) in the main field table above are hard limits enforced by the request schema. Per-country regex patterns below are enforced by the Merchant Portal UI today — API-only integrators should self-validate against them, since they are not independently confirmed to be re-validated server-side. {% endhint %} {% hint style="warning" %} **Known quirk**: the Merchant Portal UI additionally applies a blanket "digits only" rule (`^[0-9]+$`) to `accountNumber` in its own form layer, on top of whichever per-country rule is shown below. This conflicts with several rules below that explicitly allow letters (all IBAN/SEPA countries, `CA`, `TR`, `SA` alphanumeric rules). If you are integrating directly against the API (not through the Portal), follow the per-country rule in the tables below rather than assuming digits-only. {% endhint %} {% hint style="info" %} `swiftCode` is capped at 11 characters by the request schema (`string(11)`). A stricter SWIFT/BIC format regex, `^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$` (8 or 11 characters), exists in the platform's shared validators but is not confirmed to be wired directly to this specific field today — treat it as the recommended format rather than a guaranteed server-side rejection rule. {% 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) |