China (USD) Transaction Data Requirements

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 a minority of cases the beneficiary's bank credits the account promptly. In most cases it first conducts a compliance review, because Chinese foreign exchange controls require one 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. A sender cannot tell in advance which case applies.

This process is outside Ripple's control and no SLA applies. Crediting commonly takes several business days, and can take weeks where 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.

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 may arrive back as 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 leave a payment delayed or lost.

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.

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.

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.

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 with CN_CFXPS selected to see both constraints applied together for a given field.

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.

A second limit applies to address.streetAddress on its own: 70 characters per entry, enforced by the API. Where the combined limit above is larger than 70, that per-entry cap is the one you will hit first, and it returns a 400 rather than failing at payout.

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

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.