Change history

validatePayoutRails is now validated when you create an identity

POST /v3/identities now validates every value in validatePayoutRails, matching the behavior of PUT /v3/identities/{identity-id}. A value that is not a currently offered payment rail fails with 400 Bad Request (USR_111).

Create previously accepted unrecognized values without complaint, and validated identity fields only for the rails it recognized. If you send a rail name that is misspelled or no longer offered, a request that used to succeed now fails. Check the values you send in validatePayoutRails against the financialInstrumentType list before you rely on this endpoint.

Turkey (TRY) payouts are paused

Payouts to Turkey in TRY are paused while regulatory review is pending. The corridor stays listed in the payout network with a paused indicator, and its transaction limits and payment rail entry remain published, but payments cannot be submitted while the pause is in effect.

Corrected payment idempotency and retry guidance

The guidance on retrying a create payment request was incorrect. It described internalId as an idempotency key and told you to check for an existing payment with GET /v3/payments, an operation that does not exist. /v3/payments has only POST (Create payment), and payment search is POST /v3/payments/filter.

No API behavior changed. Payment creation has always been deduplicated on quoteId: one quote produces at most one payment, and resending a request for a quote that already has a payment returns that payment with 201, even after the quote has expired. Payment internalId values have never been checked for uniqueness, so two requests carrying the same internalId with different quoteId values create two payments.

If you built retry handling from the previous guidance, review it. Retrying with a fresh quote after a timeout can create a duplicate payment, and a retry check against GET /v3/payments cannot succeed. See Idempotency and safe retries.

The Polling page was corrected in the same pass: bulk search was described as POST /v3/payments, which is Create payment. The request bodies shown were already correct for search; only the path was wrong.

Japan (JPY) is available again

The Japan (JPY) corridor, JP_ZENGIN, has been restored to the documentation and to the API specification after being withdrawn earlier in September 2026. financialInstrumentType and validatePayoutRails accept it again, and its payload schema, data requirements page, and bank code lookup are published.

The page now lists every data requirement for the corridor: the beneficiary and originator identities, the beneficiary financial instrument, and the transaction itself.

See the Japan (JPY) data requirements page.

The other corridors withdrawn in September 2026 remain withdrawn.

Identity documents required for organizations in the Brazil (BR) jurisdiction

If your organization is configured for the Brazil (BR) jurisdiction, identityDocuments is now required on every ORIGINATOR identity, on every corridor, including corridors that do not otherwise require it. Omitting it fails identity create and update with 400 Bad Request (USR_111).

Jurisdiction is a property of your organization that Ripple records against your account. It is not a value you send in a request, and it is independent of the corridors in validatePayoutRails.

The rule applies to updates as well as creates. An update validates the body you send, not the record already stored, so an update that omits identityDocuments fails even when you are changing something unrelated. Identities created before this change are affected the same way.

Business originator identities are not affected, because business identities do not carry identityDocuments.

See Jurisdiction-based requirements.

Thailand (THB) is available again

The Thailand (THB) corridor, TH_PROMPTPAY, has been restored to the documentation and to the API specification after being withdrawn earlier in September 2026. financialInstrumentType and validatePayoutRails accept TH_PROMPTPAY again, and its payload schema, transaction data requirements page, and bank code lookup are published.

See the Thailand (THB) transaction data requirements page for the fields, valid values, and validation rules for this corridor.

China (USD) is available again

The China (USD) corridor, CN_CFXPS, has been restored to the documentation and to the API specification after being withdrawn earlier in September 2026. financialInstrumentType and validatePayoutRails accept CN_CFXPS again, and its payload schema, transaction data requirements page, and bank code lookup are published.

originatorAccountNumber is required on ORIGINATOR identities validated against CN_CFXPS. See The originator's account number.

Review the known limitations on the China (USD) transaction data requirements page before you send on this corridor, and test with a low-value payment before increasing volume.

Bank Codes lookup: more countries, and uppercase bank names

The Bank Codes lookup now covers Japan, Thailand, China (CNY), Indonesia, Singapore, and Vietnam, alongside the countries it already served.

Japan and Thailand are available corridors. The others are published for reference ahead of their corridors: CN_BANK_PAYOUT, ID_BIFAST and the Singapore and Vietnam rails are not currently accepted values for financialInstrumentType or validatePayoutRails. Singapore lists SWIFT/BIC codes and Vietnam lists Ripple Bank Codes.

Bank names are now shown in uppercase across every country, which were previously a mix of uppercase and title case.

Corridors no longer available in this release

The following corridors have been removed from the documentation and from the API specification:

• China (CNY), CN_BANK_PAYOUT
• China (USD), CN_CFXPS (restored later in September 2026, see above)
• Hong Kong (HKD), HK_BANK_PAYOUT
• Indonesia (IDR), ID_BIFAST
• Japan (JPY), JP_ZENGIN (restored later in September 2026, see above)
• Philippines (PHP), PH_NRPS
• Thailand (THB), TH_PROMPTPAY (restored later in September 2026, see above)
• Turkey (TRY), TR_FAST
• Malaysia (MYR), Singapore (SGD), and Vietnam (VND), which had transaction data requirements but no financial instrument type

At the time of this change, those eight financial instrument types stopped being accepted values for financialInstrumentType and validatePayoutRails, and their payload schemas and bank code datasets were removed, leaving financialInstrumentType with 25 values. China (USD), Thailand (THB) and Japan (JPY) have since been restored, so five remain withdrawn and financialInstrumentType now accepts 28 values. Some bank code lookups are published for corridors that remain withdrawn, as described above.

originatorAccountNumber was optional on every available corridor at the time of this change. It became required again for ORIGINATOR identities on CN_CFXPS when China (USD) was restored. It remains available on ORIGINATOR identities, keeps its uniqueness rule across all active identities, and is still forwarded to the payout partner when you send it.

Entries further down this page that announced these corridors are left in place as a record of what was published at the time.

Searching payments by beneficiary nickname now matches through the identity service

When you filter payments with beneficiaryIdentityNickname, the nickname is now matched by the identity service rather than against a copy held by the payments service. Two things follow:

• If a nickname matches more than one beneficiary identity, the response includes the payments of every identity it matches. Previously the match was made against a single stored value per payment.
• Matching follows the identity service's own semantics, so results may differ from the substring behavior you saw before.

To target specific beneficiaries, filter on beneficiaryIdentityIds instead. See Create and manage identities for finding the identity behind a nickname.

Nicknames on payment responses reflect the identity version the payment references

originatorIdentityNickName and beneficiaryIdentityNickName on payment responses return the nickname as it was at the identity version the payment references. Editing a nickname afterwards does not change the value returned for an existing payment.

Longer nicknames accepted on payment fields

The maximum length of originatorIdentityNickName, beneficiaryIdentityNickName, and the beneficiaryIdentityNickname search filter increased from 100 to 256 characters. This is additive: existing values are unaffected.

Reduced data requirements: African corridors

Several identity fields are no longer required for NG_BANK_PAYOUT, GH_BANK_PAYOUT, RW_BANK_PAYOUT, UG_BANK_PAYOUT, ZA_BANK_PAYOUT, and ZM_BANK_PAYOUT:

• citizenship and gender — no longer required for INDIVIDUAL BENEFICIARY identities
• identityDocuments — no longer required for INDIVIDUAL BENEFICIARY identities
• countryOfBirth — no longer required for INDIVIDUAL ORIGINATOR identities
• registration — no longer required for BUSINESS ORIGINATOR or BUSINESS BENEFICIARY identities

address.stateOrProvince and address.postalCode are now required by corridor

Both fields were previously required on every identity. They are now required only for the corridors that need them, which excludes the African corridors listed above. If you send them everywhere today, nothing changes.

African corridors accept the Ripple Bank Code

bankCode on NG_BANK_PAYOUT, GH_BANK_PAYOUT, RW_BANK_PAYOUT, UG_BANK_PAYOUT, ZA_BANK_PAYOUT, and ZM_BANK_PAYOUT now accepts the Ripple Bank Code (RBC) form, for example RPL:NG:GTBINGLA:BNK. Use the Bank Codes lookup to find it.

Additional identity document types for CNY payments to China

CN_BANK_PAYOUT now accepts two further identityDocuments.idType values: HKID and HMTP for INDIVIDUAL ORIGINATOR identities, and HMTP for INDIVIDUAL BENEFICIARY identities.

Reduced data requirements: business registration on China USD and crypto payouts

registration is no longer required on BUSINESS BENEFICIARY identities for the following financial instrument types:

• CN_CFXPS (USD payments to China)
• ETH_WALLET, TRON_WALLET, SOL_WALLET (crypto payouts)

registration remains required on BUSINESS ORIGINATOR identities for CN_CFXPS, and is unchanged for all other corridors. Where you do send it, the accepted registration.type values are unchanged.

No action is needed if you already send registration. For the current required fields by corridor and role, use the Payload Schema Utility.

New documentation: registering bank accounts and crypto wallets

From Settings > Transfers, you can register your organization's own bank accounts and crypto wallets with Ripple. The capability is not new, but it was undocumented. Four new pages cover it:

• Bank accounts and Add a bank account
• Crypto wallets and Add a crypto wallet

Each pair covers what the page shows and how to complete the task, including what to expect while Ripple reviews a wallet you register.

New guidance on your first production deposit

Deposit funds now covers two prerequisites that were previously undocumented:

• Fiat. Automated crediting is not enabled when your account first reaches production. Contact your Ripple liaison before you send your first production deposit so the one-time setup can be completed. Only the first deposit is affected.
• Crypto. The wallet you send from must be registered with Ripple and approved by compliance before you fund your account.

Corrected withdrawal destination guidance

Withdrawals previously said to contact Ripple support to register a withdrawal destination. Users with permission to manage their organization's onboarding details can register destinations themselves in Settings > Transfers. The page now points to the self-service pages and keeps the support path for users without that permission.

New financial instrument type: China CNY

CN_BANK_PAYOUT (cnBankPayout) is now available for CNY payouts to Chinese bank accounts. The payout partner selects between CNAPS (bank account) and CUP (UnionPay card) at execution, so you do not choose the rail.

The instrument takes bankName, bankCode, accountNumber, and accountHolderName. Send the Ripple Bank Code in bankCode; use the Bank Codes lookup to find it. accountHolderName is the account name in Chinese Hanzi characters.

Identities used on this corridor have additional requirements:

• Individual beneficiaries need their name in Chinese Hanzi characters, in the new localized.hanzi.firstName and localized.hanzi.lastName fields
• Business registration (registration) is required for both originators and beneficiaries
• Individual originators need identityDocuments and citizenship; beneficiary idType is restricted to NATIONAL_ID_NUMBER

For the full field list, see Financial instruments and the Payload Schema Utility.

New identity field: localized

Identities now carry a localized object for values in a non-Latin script, alongside the Latin-script values elsewhere on the identity. The localized.hanzi block holds Chinese Hanzi characters (汉字) and is used by CNY payments to China.

Some fields in this block are enforced at payment time rather than at identity create. Those are marked Required at payment in the Payload Schema Utility: the identity is accepted without them, but a payment that needs them is rejected.

New identity field: originatorAccountNumber

Identities now carry a dedicated originatorAccountNumber field for the originator's own account number. Ripple forwards this value to the payout partner.

The field is required on ORIGINATOR identities validated against CN_BANK_PAYOUT (CNY payments to China), CN_CFXPS (USD payments to China), or HK_BANK_PAYOUT (HKD payments to Hong Kong), where omitting it fails with 400 USR_111. It is optional on all other corridors. Values must be unique across all active identities in your organization, including beneficiary identities, and duplicates now return the new 409 error USR_122.

internalId remains your own reference key for an identity. It is not the originator's account number.

For what to send, see The originator's account number. The China and Hong Kong corridor pages referenced by this entry were removed when those corridors were withdrawn.

New authentication error: 403 unauthorized_client

The token endpoint (POST /v2/oauth/token) can now return a 403 response with error: unauthorized_client when the caller is not authorized to request a token. This is in addition to the existing 403 with error: access_denied, which indicates the service is not enabled for the requested domain. This change is additive and does not affect authorized integrations. Base your authentication error handling on the HTTP status code rather than the error string. For more information, see Authentication errors.

Corrected error response documentation for payment operations

The documented shape of payment API error responses was incorrect. The errors field is an array of error objects, and status is an integer at the top level of the response rather than a field of each error object.

No API behavior changed. Payment operations have always returned this shape. These corrections bring the specification and documentation into line with what the API returns. Corrected across the API reference and API errors overview:

• errors is now correctly typed as an array of error objects
• status is now correctly typed as an integer at the response level
• Error examples now show accurate type, title, and description values matching the published error codes

If you generate a client from the Payments Direct specification, regenerate it to pick up the corrected error models. Previously generated clients could not deserialize error responses.

Corrected ledger transactions and balances response schema

The documented types for several fields on GET /v2/ledger-transactions and GET /v2/balances were incorrect. Monetary and pagination fields are returned as strings, not numbers, and the page-size query parameter has no server-applied default.

No API behavior changed. These endpoints have always returned these values as strings and have always required page-size. These corrections bring the specification and documentation into line with what the API returns:

• amount, availableBalanceBefore, and availableBalanceAfter (ledger transactions) and availableBalance and reservedBalance (balances) are now correctly typed as decimal strings (for example, "100.00")
• offset, pageSize, pageElements, and total (pagination metadata) are now correctly typed as strings (for example, "25")
• The page-size query parameter no longer documents a default value; it remains required, with a minimum of 1 and a maximum of 50
• The txnReference description no longer includes an inaccurate claim about when the field is populated

If you generate a client from the Payments Direct specification, regenerate it to pick up the corrected models. For more information, see Ledger transactions.

Newly documented responses for payment operations

Two responses that the API already returns are now documented:

• 415 on Create payment, Search payments, and Update payment labels, returned when the Content-Type header is missing or unsupported
• 403 on Create payment, returned when the payment exists but belongs to a different tenant

Both are additive documentation of existing behavior. For the full list, see API error codes.

New financial instrument types: Japan and Australia

Two new financial instrument types are now available:

• JP_ZENGIN (jpZengin) — JPY payouts to Japanese bank accounts via Zengin, with Zengin Prompt Service for real-time low-value transfers
• AU_NPP (auNpp) — AUD payouts to Australian bank accounts via NPP, with Direct Entry (BECS) fallback for high-value and batch

For field-level details, see Financial instruments.

New financial instrument types: Middle East, Asia-Pacific, Europe, and Latin America

Ten new financial instrument types are now available:

• AE_IPI (aeIpi) — AED payouts to UAE bank accounts via IPI, with FTS fallback for larger transfers
• IN_NEFT (inNeft) — INR payouts to Indian bank accounts via NEFT
• ID_BIFAST (idBifast) — IDR payouts to Indonesian bank accounts via BI-FAST
• TR_FAST (trFast) — TRY payouts to Turkish bank accounts via FAST, with EFT fallback for larger transfers
• PH_NRPS (phNrps) — PHP payouts to Philippine bank accounts via InstaPay, with PESONet fallback for larger transfers
• CL_TEF (clTef) — CLP payouts to Chilean bank accounts via TEF
• TH_PROMPTPAY (thPromptpay) — THB payouts to Thai bank accounts via PromptPay
• KR_KFTC (krKftc) — KRW payouts to South Korean bank accounts via KFTC
• PE_LBTR (peLbtr) — PEN payouts to Peruvian bank accounts via LBTR
• AR_INTERBANKING (arInterbanking) — ARS payouts to Argentine bank accounts via Interbanking

For field-level details on all new instrument types, see Financial instruments.

Corridor-specific identity document type restrictions

Some corridors now accept only a subset of the identity document-type enum for a given payment role. Requests that use an unsupported value for identityDocuments.type / idType (individual) or registration.type (business) are rejected with a 400 error. Enforcement is based on the corridors in validatePayoutRails (at identity creation) or the financial instrument type (at instrument creation). For example, business beneficiaries on the ETH_WALLET, SOL_WALLET, and TRON_WALLET corridors must use INCORPORATION_CERTIFICATE. For the accepted values per corridor and role, see Accepted document types by corridor.

New financial instrument types: China

A new financial instrument type supports an additional China payout scenario:

• CN_CFXPS (cnCfxps) — USD payouts to China via China Foreign Exchange Payment System (CFXPS)

New financial instrument types: Crypto wallets

Three new financial instrument types support stablecoin payouts to crypto wallet addresses:

• ETH_WALLET (ethWallet) — USDT, USDC, and RLUSD payouts on the Ethereum network
• TRON_WALLET (tronWallet) — USDT payouts on the Tron network
• SOL_WALLET (solWallet) — USDC payouts on the Solana network

All crypto wallet instruments return ZZ for the country metadata field.

New financial instrument type: Hong Kong bank payout

HK_BANK_PAYOUT (hkBankPayout) enables HKD payouts to Hong Kong bank accounts via CHATS. Required fields include bankName, accountNumber, accountHolderName, and swiftCode. Pre-clearance is required for all senders.

New financial instrument types: Africa bank payouts

Five new financial instrument types for African bank payouts are now available, enabling NGN-era corridor expansion to additional markets:

• GH_BANK_PAYOUT (ghBankPayout) — Ghana (GHS), via GIS
• RW_BANK_PAYOUT (rwBankPayout) — Rwanda (RWF), via RSwitch
• ZA_BANK_PAYOUT (zaBankPayout) — South Africa (ZAR), via PayShap. Supported use case: C2B2C only.
• UG_BANK_PAYOUT (ugBankPayout) — Uganda (UGX)
• ZM_BANK_PAYOUT (zmBankPayout) — Zambia (ZMW), via ZECHL

For field-level details on all new instrument types, see Financial instruments.

Bank Codes lookup

The Bank Codes lookup utility now covers all supported bank code corridors in a single interface. Select the destination country to view supported bank codes; for countries with multiple currencies, select the currency to narrow results.

• Nigeria (NGN): Returns Ripple Bank Codes (RBCs) in the format RPL:NG:[ALIAS]:BNK.
• China (CNY): Returns CNAPS codes (China National Advanced Payment System).
• China (USD): Returns SWIFT/BIC codes.

For more information, see Bank Codes.

New funding model: Just-in-time (JIT) funding

A new payinCategory value, JIT_FUNDING, is now available when creating quotes. JIT-funded payments enter a new AWAITING_FUNDING state after creation and proceed once funds are received in your Ripple ledger account before the jitFundingExpiresAt deadline. For more information, see Funding model and Payment states.

New payinCategory values: PRE_FUNDING and CREDIT_FUNDING

Two new payinCategory values are introduced as the preferred replacements for the deprecated values:

• PRE_FUNDING replaces FUNDED
• CREDIT_FUNDING replaces T_PLUS_ONE

The deprecated values FUNDED and T_PLUS_ONE continue to be accepted on v2 quote endpoints and are not being removed at this time. New integrations should use the new values.

New payment state: AWAITING_FUNDING

A new non-terminal payment state, AWAITING_FUNDING, is introduced for JIT-funded payments. For more information, see Payment states.

New payment response fields: payoutExecutionDetails and jitFundingExpiresAt

The GET /v3/payments/{paymentId} response now includes two new fields:

• payoutExecutionDetails (optional): metadata about how a payment was executed, including paymentRailUsed, payoutStartTime, payoutEndTime, and trackingReferences (network-specific identifiers such as IMAD/OMAD for Fedwire). Coverage varies by corridor and partner. For more information, see Payment execution details.
• jitFundingExpiresAt: present on JIT-funded payments; indicates the deadline by which funds must be transferred to your Ripple ledger account for the payment to proceed.

New API endpoint: GET /v3/identities/by-internal-id/{internal-id}

You can now retrieve an active identity using your own client-provided internalId, without needing the Ripple-generated identityId. The endpoint returns only identities in the ACTIVE state and always returns the latest version. For more information, see Create and manage identities.

Renamed financial instrument type: AFRICA_BANK_PAYOUT is now NG_BANK_PAYOUT

The Africa bank payout financial instrument type has been renamed from AFRICA_BANK_PAYOUT to NG_BANK_PAYOUT. Update any integration code, identity validatePayoutRails arrays, or internal tooling that references the old value. For more information, see Financial instruments.

Reduced data requirements for US ACH

Based on customer feedback, the following identity fields are no longer required when creating identity tokens for US ACH payments:

• registration — no longer required for BUSINESS ORIGINATOR and BUSINESS BENEFICIARY identities
• identityDocuments — no longer required for INDIVIDUAL BENEFICIARY identities

For an updated list of required fields by corridor, use the Payload Schema Utility.

Corrected GET /v2/ledger-transactions response schema

The response schema for GET /v2/ledger-transactions was incorrectly defined as an array. It has been corrected to an object containing pagination metadata (offset, pageSize, pageElements, total) and a statementTransactions array. Customers using OpenAPI generators against a previous version of this spec may need to regenerate their client code. The text/csv response schema has also been corrected and now includes column documentation and an example row.

Documentation versioning: v2026.03 and v2025.11

The Payments Direct documentation is now versioned. Use the version selector to switch between versions:

• v2026.03 (this version) - Documents the Payments Direct API with Identity Management v3, including the v3 identity and financial instrument endpoints.
• v2025.11 - Documents the Payments Direct API with Identity Management v2.

New API endpoint: GET /v2/ledger-transactions

Provides a paginated list of ledger transactions and running balances for a specified UTC time range, supporting customer reconciliation and operational reporting. For more information, see Ledger transactions.

New payment state: RETURNED

Payments that were previously marked as COMPLETED but later reversed by the payout partner or network are now marked as RETURNED. For more information, see Payment lifecycle and Payment returns.

Feature enhancement: Tax transparency

We have introduced a detailed tax breakdown structure to both Quote and Payment responses to support transparent reporting of tax liabilities and service fees.

Enhancements and payout network expansions

• Released the Transaction Memo feature for EUR/GBP payouts
• Payouts enabled: PHP, CN-USD, and INR

Enhancements and payout network expansions

• Released the Transaction Memo feature for USD payouts
• Payouts enabled: AED, AUD, CLP, COP, JPY, IDR, KRW, PEN, THB, and VND

Enhancements

• Released FedWire payouts with Lead Bank
• Released FX benchmark improvements to reduce price gaps with stablecoins

Enhancements

• Released Maker/Checker feature in Payments Direct, enabling payment approval workflows
• Released the OpenAPI specification for Payments Direct, available for download here.

Enhancements

• Released off-ramp capabilities to deliver RLUSD

Additional payout markets enabled

• RTP payouts enabled in the US
• EUR/GBP payouts enabled

Additional payout markets enabled

• Payouts enabled for BRL, CNY, GHS, NGN, RWF, ZAR, UGX, and ZMW

Enhancements and network expansions

• ACH payouts enabled using iPayout
• Payments Direct on-ramps launched for customers to send in stablecoins, beginning with USDC and USDT
• Re-designed payment flow in Payments Direct to simplify and enhance the user experience

Off-ramps Beta launched

Off-ramps beta launched for Payments Direct customers, allow customers to pay-in stablecoins in key payout markets

Official launch of Payments Direct

Payments Direct, allows you to connect to Ripple as a payments provider. Ripple takes care of delivering payments to beneficiaries, managing payout partners, providing funds to payout partners, and paying charges in exchange for payment delivery to the beneficiaries. With Payments Direct, you can send payments and manage beneficiaries using the Payments Direct UI.