# Change history This page summarizes notable changes made to Payments Direct. This change history is arranged in order from the most recent change and it corresponds to the month and year the enhancements and fixed issues were made available. ### August 2026 details summary Click to expand **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_CFXPS` (USD payments to China), 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`](/products/payments-direct-2/api-docs/error-handling/api-errors). `internalId` remains your own reference key for an identity. It is not the originator's account number. For what to send, see [China (USD) Transaction Data Requirements](/products/payments-direct-2/api-docs/integration-resources/apac/cn/usd#originator-account-number) and [The originator's account number](/products/payments-direct-2/introduction/concepts/payment-identities#the-originators-account-number). **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](/products/payments-direct-2/api-docs/get-started/authentication#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](/products/payments-direct-2/api-docs/error-handling/payments-direct-api-errors): - `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](/products/payments-direct-2/introduction/concepts/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](/products/payments-direct-2/api-docs/error-handling/api-errors). ### July 2026 details summary Click to expand **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](/products/payments-direct-2/introduction/concepts/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](/products/payments-direct-2/introduction/concepts/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](/products/payments-direct-2/introduction/concepts/payment-identities#accepted-document-types-by-corridor). ### June 2026 details summary Click to expand **New financial instrument types: China** A new financial instrument type supports an additional China payout scenario: - `CN_CFXPS` (`cnCfxps`) — USD payouts to China via Cross-Border 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. Supported use case: C2B2C only. - `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](/products/payments-direct-2/introduction/concepts/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](/products/payments-direct-2/api-docs/integration-resources/ripple-bank-codes). ### April 2026 details summary Click to expand **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](/products/payments-direct-2/introduction/concepts/quotes#funding-model-payincategory) and [Payment states](/products/payments-direct-2/introduction/concepts/payment-lifecycle). **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](/products/payments-direct-2/introduction/concepts/payment-lifecycle). **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](/products/payments-direct-2/introduction/concepts/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](/products/payments-direct-2/api-docs/developer-guides/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](/products/payments-direct-2/introduction/concepts/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](/products/payments-direct-2/api-docs/integration-resources/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. ### March 2026 details summary Click to expand **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**. ### January 2026 details summary Click to expand **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](/products/payments-direct-2/introduction/concepts/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](/products/payments-direct-2/introduction/concepts/payment-lifecycle) and [Payment returns](/products/payments-direct-2/introduction/concepts/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. ### November 2025 details summary Click to expand **Enhancements and payout network expansions** - Released the Transaction Memo feature for EUR/GBP payouts - Payouts enabled: PHP, CN-USD, and INR ### October 2025 details summary Click to expand **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 ### September 2025 details summary Click to expand **Enhancements** - Released FedWire payouts with Lead Bank - Released FX benchmark improvements to reduce price gaps with stablecoins ### August 2025 details summary Click to expand **Enhancements** - Released Maker/Checker feature in Payments Direct, enabling payment approval workflows - Released the OpenAPI specification for Payments Direct, available for download [here](https://github.com/ripple/payments-direct/blob/main/openapi_spec/rpd2_spec.yml). ### July 2025 details summary Click to expand **Enhancements** - Released off-ramp capabilities to deliver RLUSD ### June 2025 details summary Click to expand **Additional payout markets enabled** - RTP payouts enabled in the US - EUR/GBP payouts enabled ### May 2025 details summary Click to expand **Additional payout markets enabled** - Payouts enabled for BRL, CNY, GHS, NGN, RWF, ZAR, UGX, and ZMW ### April 2025 details summary Click to expand **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 ### March 2025 details summary Click to expand **Off-ramps Beta launched** Off-ramps beta launched for Payments Direct customers, allow customers to pay-in stablecoins in key payout markets ### February 2025 details summary Click to expand **Offical 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.