Change history

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 payinCategory values (preferred) and deprecation notice

Two new preferred payinCategory values are now available on v2 quote and payment endpoints:

• PRE_FUNDING — replaces the deprecated FUNDED value.
• CREDIT_FUNDING — replaces the deprecated T_PLUS_ONE value.
• JIT_FUNDING — for just-in-time funded payments (see below).

The legacy values FUNDED and T_PLUS_ONE continue to be accepted on v2 endpoints but are deprecated and will be removed in a future release. New integrations should use the new values. For details, see Quotes.

New field: jitFundingExpiresAt

Payment objects now include an optional jitFundingExpiresAt field (date-time, UTC) indicating the deadline by which funds must arrive for a JIT_FUNDING payment. This field is present only on JIT-funded payments.

New field: payoutExecutionDetails

GET /v2/payments/{paymentId} responses now include an optional payoutExecutionDetails object when available. This object provides:

• paymentRailUsed — the payment rail used to execute the payout (for example, ACH, Fedwire, SEPA).
• payoutStartTime / payoutEndTime — payout timing in UTC.
• trackingReferences — network-specific identifiers such as IMAD/OMAD for Fedwire, useful for audit and reconciliation.

This field is informational only. Availability varies by corridor and payout partner. For details, see Create a v2 payment.

New optional field: paymentMemo

The paymentMemo field is now documented on the payment request body. It is an optional transaction-specific memo forwarded with the payment for beneficiary reconciliation. Validation rules (allowed characters, maximum length) vary by corridor.

Deprecated ledger operations

The ledger operations VOID_PREFUND_BALANCE and OVERRIDE_PREFUND_BALANCE are deprecated. They may appear in historical ledger records but are no longer generated for new transactions. For details, see Ledger transactions.

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

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.