Ripple USD 백서

Ripple USD

원문

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
프로젝트로 돌아가기