bitpro가 원문에서 글자만 모은 내용이에요. 표·그림·수식은 빠지거나 깨질 수 있어요. 전체 9쪽 중 3쪽
to route to the correct handler
status
— the HTTP status code
timestamp
— the time the error occurred in the upstream system
The API endpoint and HTTP method that returned the error
Your request ID or correlation ID (if your integration generates one)
Alerting recommendations
Condition
Alert priority
Any
CONFIGURATION_ERROR
(
CFG_
)
High — these require Ripple involvement and will not self-resolve
Repeated
SYSTEM_ERROR
(
SYS_
) from the same endpoint
Medium — investigate after retry budget is exhausted
AUTH_ERROR
403 (
AUTH_002
,
AUTH_051
)
Medium — may indicate a configuration change or credential scope issue
Sustained
USER_ERROR
402 (
USR_062
–
USR_067
)
Medium — indicates an account condition (balance, limits, invoice) requiring attention
Next steps
For the complete list of error codes, descriptions, and HTTP statuses, see
API error codes
.
For payment-specific failure codes, see
API payment failures
.
For guidance on tracking payment state changes without polling, see
Notification webhooks
.
To poll for payment updates instead of using webhooks, see
Polling
.
For access token generation and caching details, see
Authentication
.
For payment state definitions and lifecycle details, see
Payment states
.
## /products/payments-direct-2/change-history
Change history
View as Markdown
View as Markdown
Open this page as Markdown
Copy for LLM
Copy page as Markdown for LLMs
Open in Claude
Get insights from Claude
Open in ChatGPT
Get insights from ChatGPT
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.
October 2026
Click to expand
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.
September 2026
Click to expand
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.
August 2026
Click to expand
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
.
July 2026
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
.
New financial instrument types: Middle East, Asia-Pacific, Europe, and Latin America
Ten프로젝트로 돌아가기