# China (USD) Data Requirements

This page covers every data requirement for USD payments to China via CFXPS (China Foreign Exchange Payment System): the identities you create for the beneficiary and originator, the financial instrument that holds the beneficiary's account details, and the transaction-level fields sent with each payment.

The identity, financial instrument, and name and address requirements apply to every USD payment to China. The transaction-level fields further down apply only to the use cases noted against each field.

To find the SWIFT/BIC code for the destination bank, use the [Bank Codes](/products/payments-direct-2/v2026.03/api-docs/integration-resources/ripple-bank-codes) lookup.

Known limitations on this corridor
Review these before you send on this corridor, and advise your customers accordingly. All four are
known and tracked, and no fix dates are confirmed yet.

- **Some beneficiary banks support only the B2B and B2B2B use cases.** Choosing one of them for
any other use case is not rejected when you create the payment. The payment is routed onward
anyway and may fail around 4 to 5 business days later with a generic error. The
[Bank Codes](/products/payments-direct-2/v2026.03/api-docs/integration-resources/ripple-bank-codes) lookup does not yet show which use cases each bank
supports; per-bank support is being confirmed and will be added there.
- **Beneficiary SWIFT/BIC values are not validated when you create the payment.** An invalid BIC,
or a branch-level BIC rather than a head-office one, is accepted and fails the same way.
- **The maximum lengths shown in Payments Direct UI when you create an individual
beneficiary may not match the limits documented on this page.** The limits on this page are the
ones the payout partner applies. The API does not enforce them, so a value that breaks them is
accepted at creation and fails later, at payout.
- **Send a low-value test payment for each use case before you increase volume.** Penny testing on
this corridor is constrained by local regulation, so Ripple's own coverage is still in progress.


Fields shown are those required for this corridor
The identity and financial instrument tables on this page list only the fields `CN_CFXPS`
requires, taken from the PII v3 schema. Identities and financial instruments accept further
optional fields. For the complete set, see
[Payment identities](/products/payments-direct-2/v2026.03/introduction/concepts/payment-identities) and
[Financial instruments](/products/payments-direct-2/v2026.03/introduction/concepts/financial-instruments), or use the
[Payload Schema Utility](/products/payments-direct-2/v2026.03/api-docs/integration-resources/payload-schema-utility).

## How payments behave on this corridor

Three aspects of this corridor are worth understanding before you integrate.

COMPLETED does not always mean the beneficiary has the funds
For USD payments to China, `COMPLETED` means the funds have reached the beneficiary's bank. It does not always mean the beneficiary's account has been credited.

In most cases the beneficiary's bank first reviews the payment for compliance, because Chinese foreign exchange controls require a review for every inbound USD payment regardless of amount. The bank contacts the beneficiary directly to collect supporting documentation, such as an invoice, shipping or customs proof, an employment contract, or proof of relationship. In a minority of cases it credits the account promptly instead. You cannot tell in advance which will happen.

This process is outside Ripple's control and no SLA applies. Crediting commonly takes several business days, and can take weeks if the bank escalates to enhanced due diligence. The timeline depends on when the beneficiary provides satisfactory documentation. Set expectations with your beneficiaries accordingly, and do not treat `COMPLETED` as proof of receipt.

Payments cannot be recalled or amended
Once a payment is initiated, you cannot cancel it, amend it, or request a refund or return. Only the beneficiary's bank can initiate a return, which it does when the payment fails its compliance review.

A returned payment can be worth less than the amount sent, because the returning bank may deduct a handling fee. Fees vary by bank and branch, so budget for a shortfall when reconciling returns.

Because a payment cannot be corrected after submission, verify the beneficiary's details before sending. Funds sent to an unintended beneficiary are generally unrecoverable, and incorrect or incomplete details can delay a payment or lose it altogether.

Operating hours and cutoff
The CFXPS rail runs on business days only, Monday to Friday, excluding Chinese public holidays. The cutoff is **5:00 PM CST, and it varies by bank**, so confirm the cutoff that applies to your beneficiary's bank. Payments submitted after it are processed on the next business day.

Submitting before the cutoff does **not** guarantee same-day completion. The cutoff governs when a payment enters processing, not when it finishes. Payments routed to a manual validation queue can take an additional business day or more. The beneficiary bank's compliance review then adds further time on top of that.

## Beneficiary identity

Create the beneficiary identity before the financial instrument, then reference it when you create the payment. See [Create and manage identities](/products/payments-direct-2/v2026.03/api-docs/developer-guides/create-and-manage-identities) for the API workflow.

The required fields depend on whether the beneficiary is a **business** or an **individual**.

### Business beneficiary

Applies to **B2B**, **B2B2B**, and **C2B2B** use cases. Submit a `business` identity.

| Field  | Required | Type | Constraints  |
|  --- | --- | --- | --- |
| `businessName` | Required | STRING | 1–140 characters accepted by the API. CFXPS truncates the combined name and address above its own limit, so keep this to 60 characters. See [Name and address field length limits](#name-and-address-field-length-limits). |
| `address.streetAddress` | Required | ARRAY of STRING | One or more free-form address lines. Send exactly one line for this corridor; see [Name and address field length limits](#name-and-address-field-length-limits). |
| `address.city` | Required | STRING | 1–140 characters. Letters, spaces, and `. ' -` only, so no digits. |
| `address.stateOrProvince` | Required | STRING | 1–140 characters. Letters, digits, spaces, and `. ' -`. |
| `address.postalCode` | Required | STRING | 3–15 characters. If no postal code applies to the address, send `000000`. |
| `address.country` | Required | STRING | Two-letter uppercase ISO 3166-1 alpha-2 country code. |


### Individual beneficiary

Applies to **B2C**, **B2B2C**, and **C2B2C** use cases. Submit an `individual` identity.

| Field  | Required | Type | Constraints  |
|  --- | --- | --- | --- |
| `firstName` | Required | STRING | 1–140 characters. Letters, spaces, and `. ' -` only, so no digits. |
| `lastName` | Required | STRING | 1–140 characters. Letters, spaces, and `. ' -` only, so no digits. |
| `address.streetAddress` | Required | ARRAY of STRING | One or more free-form address lines. Send exactly one line for this corridor; see [Name and address field length limits](#name-and-address-field-length-limits). |
| `address.city` | Required | STRING | 1–140 characters. Letters, spaces, and `. ' -` only, so no digits. |
| `address.stateOrProvince` | Required | STRING | 1–140 characters. Letters, digits, spaces, and `. ' -`. |
| `address.postalCode` | Required | STRING | 3–15 characters. If no postal code applies to the address, send `000000`. |
| `address.country` | Required | STRING | Two-letter uppercase ISO 3166-1 alpha-2 country code. |


## Beneficiary financial instrument

Set `financialInstrumentType: CN_CFXPS` and `currency: USD`. Provide the following fields in the `cnCfxps` payment rail object. See [Create and manage financial instruments](/products/payments-direct-2/v2026.03/api-docs/developer-guides/create-and-manage-financial-instruments) for the API workflow.

| Field  | Required | Type | Constraints  |
|  --- | --- | --- | --- |
| `swiftCode` | Required | STRING | 8 or 11 characters, matching `/^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$/`. Use the [Bank Codes](/products/payments-direct-2/v2026.03/api-docs/integration-resources/ripple-bank-codes) lookup and select China to find it. |
| `bankName` | Required | STRING | 2–140 characters. The beneficiary's bank name, which corresponds to the `swiftCode` above. |
| `accountNumber` | Required | STRING | 1–34 characters, letters and digits only. |
| `accountHolderName` | Required | STRING | 1–140 characters, in English. The API and CFXPS accept slightly different punctuation on this field, so keep to letters, digits, spaces, and `. , ' / ( ) -`, which both allow. The API also accepts `&`; CFXPS does not. |


## Originator identity

The originator identity represents the party funding the payment. See [Create and manage identities](/products/payments-direct-2/v2026.03/api-docs/developer-guides/create-and-manage-identities) for the API workflow.

### Business originator

Submit a `business` identity.

| Field  | Required | Type | Constraints  |
|  --- | --- | --- | --- |
| `businessName` | Required | STRING | 1–140 characters accepted by the API. Keep this to 60 characters for CFXPS. See [Name and address field length limits](#name-and-address-field-length-limits). |
| `address.streetAddress` | Required | ARRAY of STRING | One or more free-form address lines. Send exactly one line for this corridor; see [Name and address field length limits](#name-and-address-field-length-limits). |
| `address.city` | Required | STRING | 1–140 characters. Letters, spaces, and `. ' -` only, so no digits. |
| `address.stateOrProvince` | Required | STRING | 1–140 characters. Letters, digits, spaces, and `. ' -`. |
| `address.postalCode` | Required | STRING | 3–15 characters. If no postal code applies to the address, send `000000`. |
| `address.country` | Required | STRING | Two-letter uppercase ISO 3166-1 alpha-2 country code. |
| `registration[].number` | Required | STRING | The unique identifier of the organization. 3–35 characters. Must match `^(?![ .'-\/])(?!.*[ .'-\/]{2})([A-Za-z0-9 .'-\/]+)(?<![ .'-\/])\/?$`. |
| `registration[].type` | Required | STRING | One of `INCORPORATION_CERTIFICATE`, `TAX_ID`. |
| `originatorAccountNumber` | Required | STRING | See [Originator account number](#originator-account-number) below. |


### Individual originator

Submit an `individual` identity.

| Field  | Required | Type | Constraints  |
|  --- | --- | --- | --- |
| `firstName` | Required | STRING | 1–140 characters. Letters, spaces, and `. ' -` only, so no digits. |
| `lastName` | Required | STRING | 1–140 characters. Letters, spaces, and `. ' -` only, so no digits. |
| `address.streetAddress` | Required | ARRAY of STRING | One or more free-form address lines. Send exactly one line for this corridor; see [Name and address field length limits](#name-and-address-field-length-limits). |
| `address.city` | Required | STRING | 1–140 characters. Letters, spaces, and `. ' -` only, so no digits. |
| `address.stateOrProvince` | Required | STRING | 1–140 characters. Letters, digits, spaces, and `. ' -`. |
| `address.postalCode` | Required | STRING | 3–15 characters. If no postal code applies to the address, send `000000`. |
| `address.country` | Required | STRING | Two-letter uppercase ISO 3166-1 alpha-2 country code. |
| `originatorAccountNumber` | Required | STRING | See [Originator account number](#originator-account-number) below. |


## Originator account number

CFXPS requires the originator's account number on every USD payment to China. Send it in the `originatorAccountNumber` field on the **ORIGINATOR** identity. Ripple forwards that value to the payout partner.

`originatorAccountNumber` is required whenever you validate an originator identity against `CN_CFXPS`. Creating or updating the identity without it fails with **400 Bad Request** (`USR_111`). The value must be a real account number or customer identifier, not an arbitrary reference such as a randomly generated UUID:

| If the originator is  | Send |
|  --- | --- |
| A bank or other financial institution | The originator's bank account number |
| A payment service provider | Your customer identifier for the originator, in a numeric or number-like form |


Use a value that looks like an account number
Prefer digits. The beneficiary's bank applies its own validation to this value, separately from the character and length limits below, and may reject a value that does not resemble an account number.

This matters most if you are a payment service provider sending your own customer identifier. An internal reference in an obviously non-account format, such as a CRM record ID mixing letters and punctuation, can be rejected by the beneficiary's bank even though Ripple accepts it and the payment reaches the corridor. Where you have a choice, send a numeric customer or account identifier.

originatorAccountNumber format for CFXPS
For USD payments to China, `originatorAccountNumber` must:

- Be no longer than **34 characters**.
- Match `/^[A-Za-z0-9/?:().,'+ -]+$/`, the same character set as the name and address fields described below.


The API accepts any string in this field by design, so neither limit is validated when you create the identity. A value that breaks either one fails at payout instead. A standard 36-character UUID exceeds the length limit, which is why an autogenerated identifier cannot be used here.

`originatorAccountNumber` must also be unique across all ACTIVE identities in your organization. Creating or updating a second active identity with the same value fails with **409 Conflict** (`USR_122`). Uniqueness spans both roles, so a beneficiary identity that already carries a value blocks a later originator from using it. Each originator needs its own value: you cannot reuse a single shared account number across multiple active identities.

Omitting it sends your internalId to the payout partner
`originatorAccountNumber` and `internalId` are different fields, and the difference matters here. If you leave `originatorAccountNumber` empty, Ripple sends `internalId` to the payout partner in its place, as the originator's account number.

That is rarely what you want. `internalId` is your own reference key, and in Payments Direct UI it is generated for you as a UUID that you never see. A 36-character UUID also exceeds the 34-character limit above.

Send the account number in `originatorAccountNumber`. Do not send it in `internalId`, which has its own separate uniqueness rule.

For general `internalId` behavior, including how to handle 409 responses, see [Payment identities](/products/payments-direct-2/v2026.03/introduction/concepts/payment-identities#idempotency-and-deduplication-with-internalid).

### Validate the originator against `CN_CFXPS`

Include `CN_CFXPS` in `validatePayoutRails` when you create or update the originator identity. Doing so makes Ripple check the corridor's required fields at that point, so a missing `originatorAccountNumber` fails immediately with **400 Bad Request** (`USR_111`).

Leave the rail out and nothing checks the field when you create the identity. The first sign of a problem is the payment being rejected. See [Validating identities for specific payment rails](/products/payments-direct-2/v2026.03/introduction/concepts/payment-identities#validating-identities-for-specific-payment-rails).

### If the payment is rejected

A USD payment to China is rejected at creation when the originator's `originatorAccountNumber` is missing or holds a UUID. `POST /v3/payments` returns **400 Bad Request** before the payment reaches a payment state, so no funds are reserved or debited and there is nothing to reverse.

| Code  | Cause  | Message |
|  --- | --- | --- |
| `USR_090` | The field is missing or empty | Field 'originator.originatorAccountNumber' is required but missing or empty. Provide the originating customer's account number (DbtrAcct.Id.Othr.Id), and not a UUID. |
| `USR_068` | The field holds a UUID | Field value validation error for request field: originator.originatorAccountNumber. Error message: must not be a UUID — provide the originating customer's account number. Try again with valid input value. |


To recover, add a valid account number to the originator identity and create the payment again.

## Name and address field formatting

Name and address values for USD payments to China via CFXPS must use **letters (`A-Z`, `a-z`), digits (`0-9`), spaces, and the punctuation marks `/ ? : ( ) . , ' + -`**. Any other character causes the payout to be rejected. Chinese characters and other non-English scripts are not supported, and neither are common punctuation marks outside the set above, such as `&`, `#`, `"`, and `_`.

Keep the values in each field below as concise as possible. For each party, the combined name and postal address has a **total maximum of 139 characters**. This total applies separately to the beneficiary and the originator, and the per-field limits below are an allocation of it.

The two limits fail in different ways
Neither of these limits is validated by the API. Both are applied by CFXPS after the payment is sent, and they behave differently:

- **An unsupported character rejects the payment.** CFXPS returns it, so you find out.
- **An over-length name or address is truncated, not rejected.** CFXPS shortens the combined name and address to fit and forwards the payment. Nothing tells you it happened, and the beneficiary's bank may return or misroute a payment that arrives with a shortened name or address.


Truncation is the more damaging of the two, because the money moves with incorrect data. Treat the length limits below as hard requirements even though nothing enforces them on the way in.

Applies to both beneficiary and originator identities
All name and address fields must use the character set described above, which is expressed as this regular expression:

`/^[A-Za-z0-9/?:().,'+ -]+$/`

The API applies its own, separate validation to these fields, and on some of them it is stricter than CFXPS. Personal names and city, for example, reject digits. So a value can satisfy the character set above and still be rejected by the API with a 400, and a value the API accepts can still be rejected by CFXPS. Use the [Payload Schema Utility](/products/payments-direct-2/v2026.03/api-docs/integration-resources/payload-schema-utility) with `CN_CFXPS` selected to see both constraints applied together for a given field.

## Name and address field length limits

| Field  | Applies to  | Max length |
|  --- | --- | --- |
| `businessName` | Beneficiary and originator (business) | 60 |
| `firstName`, `lastName` | Beneficiary and originator (individual) | 15 each |
| `address.city` | Beneficiary | 16 |
| `address.country` | Beneficiary and originator | 2 |
| Combined address line | Beneficiary (business) | 61 |
| Combined address line | Beneficiary (individual) | 76 |
| Combined address line | Originator (business) | 77 |
| Combined address line | Originator (individual) | 92 |


What counts toward the combined address line
Before sending a payment, Ripple combines several of the address fields you supply into the address line, separated by `, `. The limits above apply to the **combined result**, not to `address.streetAddress` on its own.

For a **beneficiary**, the combined line is:

`streetAddress` + `stateOrProvince` + `postalCode`

so the values must satisfy:

`len(streetAddress) + len(stateOrProvince) + len(postalCode) + 4 <= 61` (business) or `<= 76` (individual)

For an **originator**, `city` is also folded in, because CFXPS has no separate city field for the originator:

`streetAddress` + `city` + `stateOrProvince` + `postalCode`

so the values must satisfy:

`len(streetAddress) + len(city) + len(stateOrProvince) + len(postalCode) + 6 <= 77` (business) or `<= 92` (individual)

The added constants are the separators: 2 characters for each join.

**The schema also declares a 70-character limit on each `address.streetAddress` entry, but the API does not enforce it.** A longer value is accepted and stored in full. Where a combined limit above is larger than 70, the per-entry limit is the tighter of the two and the one to design to. Like the combined limits, nothing checks it when you create the identity, so treat both as requirements you have to meet yourself.

`stateOrProvince` and `postalCode` are required on every identity, so budget for them even though they have no individual limit on this corridor.

Send exactly one address line
`address.streetAddress` is an array, so the API accepts more than one entry. **Only the first entry is delivered on this corridor.** Anything in a second or later entry is dropped in transit.

This is worse than losing an address line. The state or province and postal code are appended to the **last** entry, so with two or more entries they are appended to a line that is never delivered, and the beneficiary's bank receives an address with no state and no postal code. The Ripple UI sends a single line for this reason, and API senders should do the same.

Put the whole street address in the first entry and send no others.

How the 139-character total works
The limits above are an allocation of the 139-character total for a party. For a business beneficiary they use it exactly: legal name (60) + combined address line (61) + city (16) + country (2) = 139. For a business originator: legal name (60) + combined address line (77) + country (2) = 139.

For individuals the allocation reserves 15 characters for a middle name, which this API does not expose, so the fields you can send reach 124 rather than 139. The remaining 15 characters are not available to other fields. Using fewer characters in one field never increases the maximum allowed in another.

## Transaction data requirements

| Field  | Description  | Required | Type | Constraints  |
|  --- | --- | --- | --- | --- |
| `purposeCode` | Purpose of payment | Required for **B2B** and **B2B2B** | ENUM | See [valid values](#purpose-of-payment-codes) below. Not required for other use cases |


purposeCode applies to business-to-business use cases only
`purposeCode` is required when both the originator and the beneficiary are businesses, meaning the **B2B** and **B2B2B** use cases. It is not required for **B2C**, **B2B2C**, **C2B2B**, or **C2B2C**, and the routes serving those use cases do not consume it.

## Purpose of payment codes

| Code | Description |
|  --- | --- |
| `GDDS` | Purchase or sale of goods |
| `SCVE` | Purchase or sale of services |