China (USD) Data Requirements

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 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.

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.

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.

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.

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.

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.