Ripple USD 백서

Ripple USD

원문

bitpro가 원문에서 글자만 모은 내용이에요. 표·그림·수식은 빠지거나 깨질 수 있어요. 전체 9쪽 중 2쪽

rized transactions. Key features The main features of the Wallet-as-a-Service platform are: Self-custody security - Multi-layered protection with MPC and HSM technology; your organization holds the keys Policy engine - Automated transaction approval workflows Multi-asset support - Support for a wide range of digital assets Compliance - Built-in compliance and risk management tools API access - Comprehensive API for programmatic access Use cases Wallet-as-a-Service supports various digital asset use cases: Digital asset custody and trading CeFi and DeFi integration Tokenization and asset management Treasury management Institutional custody services Get started with Wallet-as-a-Service To get started with Wallet-as-a-Service: Set up your organization - We will create your organization on the Wallet-as-a-Service platform and send you an invitation email Complete your first transaction - Follow our getting started guide to send your first transaction Explore the platform - Learn about vaults , wallets , and policies Integrate with the API - Use our API documentation to integrate Wallet-as-a-Service into your systems For questions or support, please contact Ripple Support . ## /products/payments-direct-2/introduction/ripple-payments-direct Payments Direct 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 Payments Direct is Ripple's cross-border payment service for financial institutions and businesses. With a direct commercial arrangement with Ripple, you can send payments to 60+ destination countries without managing foreign exchange, payout partner relationships, or last-mile delivery logistics. Ripple handles all of that on your behalf. You can access Payments Direct through: Payments Direct UI : a purpose-built web application for creating, managing, and tracking payments. Payments Direct API: a REST API for programmatic integration into your own systems. How it works A typical Payments Direct payment follows these steps: Create identities and financial instruments: Register originator and beneficiary records, including verified identity data and bank account or wallet details, that can be reused across payments. Request a quote: Get a real-time view of the exchange rate, fees, and deliverable amount for your proposed payment. Submit the payment: Create the payment using the accepted quote. Track the payment: Monitor status as your payment moves through its lifecycle: Initiated → Validating → Transferring → Completed. For a step-by-step walkthrough, see Create a payment . Use cases Payments Direct supports six use case types, covering direct and intermediated payment flows for both business and individual parties: Use case Description B2B Your organization sends funds directly to another business. B2C Your organization sends funds directly to an individual. B2B2B Your organization sends funds to a business on behalf of a business customer. B2B2C Your organization sends funds to an individual on behalf of a business customer. C2B2B Your organization sends funds to a business on behalf of an individual customer. C2B2C Your organization sends funds to an individual on behalf of an individual customer. Payout network Payments Direct supports payments to 60+ destination countries across Africa, Asia-Pacific, Europe, the Middle East, Latin America, and North America. Ripple manages the full payout partner network on your behalf. You specify the destination and Ripple handles routing and delivery. For the full list of supported corridors and use case availability by country and currency, see Payout network . Key features Real-time quotes: Preview exchange rates, fees, and deliverable amounts before committing to a payment. Compliance built-in: Ripple handles sanctions screening, AML checks, and corridor-specific regulatory requirements, including purpose codes and enhanced due diligence where required. Reusable identities: With Identity Management v3, store originator and beneficiary records once and reference them across payments, reducing PII handling in each request. Multiple access methods: Operate through the Payments Direct UI UI or integrate directly via the Payments Direct API. Payment tracking and webhooks: Monitor each payment through its lifecycle with real-time status updates and webhook notifications for key state transitions. Core concepts To build your integration, start with these core concepts: Payment identities : Structured records representing originators and beneficiaries in a payment. Financial instruments : Bank account and wallet details associated with an identity. Quotes : Real-time pricing for a proposed payment, including exchange rate, fees, and taxes. Payment lifecycle : The lifecycle stages a payment moves through from initiation to completion. Getting started To use Payments Direct : Sign a service agreement with Ripple. Work with your Ripple representative to configure your corridors and access. Set up your users and API credentials in Payments Direct UI , see Getting started . Contact sales If you're interested in getting started with Payments Direct , use the Contact the Sales Team form. ## /products/payments-direct-2/introduction/payout-network Payout network 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 Payments Direct supports payouts to countries across six regions. Select a region to view supported corridors, use cases, and payment limits. ## /products/payments-direct-2/introduction/concepts Concepts 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 The following articles explain some of the key concepts at work in the Ripple Payments cross-border payment system: ## /products/payments-direct-2/user-interface/features Features 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 The following pages describe each feature of the Payments Direct interface: what it does, what functions it provides, and how it relates to other features. ## /products/payments-direct-2/user-interface/user-guides User guides 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 The following guides provide step-by-step instructions for completing common tasks in the Payments Direct interface. ## /products/payments-direct-2/api-docs/getting-started Getting started 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 Before you start the process of integrating with the Payments Direct API, you should review the following items: GitHub Repository Tooling User creation API credentials GitHub repository The official Payments Direct GitHub repository is the single source of truth for everything you need to integrate with Payments Direct API v2026.03 : OpenAPI Specification: The canonical definition of the Payments Direct API. SDKs: Client libraries in multiple languages, available in the repository and through standard package managers. Examples: End-to-end sample code for common payment flows (create a quote, submit a payment, check status). Releases: Tagged versions that align the spec, SDKs, and examples with specific API releases. See the repository README for installation instructions and usage examples. Tooling To prepare for integrating with the Payments Direct API: Install Postman (as an alternative, curl examples are provided in documentation). Use Postman to generate a collection from the Payments Direct API specification. For guidance on how to do this, see Generate collections from you API specification . Set up a password manager for API keys. Confirm with your Ripple liaison that your test instance is ready. User creation To set up accounts for developers, your organization administrator must: Access the Payments Direct UI . Navigate to Settings and then select Users . Select New User . Check Can Read API Credentials permission. Check Can Edit API Credentials permission. Save the user and repeat the process for each developer on the team. API credentials To set up API credentials, each developer must: Access the Payments Direct UI , click Settings , and then click API Credentials in the Integration section. Click New Credential . Enter a name for your new credential. Click Save & Generate Key . Copy the credential and store it in a secure location to use for API calls. To finish credential creation, click Close . ## /products/payments-direct-2/api-docs/developer-guides Developer guides 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 The following guides provide step-by-step instructions for common integration tasks with the Payments Direct API. ## /products/payments-direct-2/api-docs/integration-resources Integration resources 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 ## /products/payments-direct-2/api-docs/payment-monitoring Monitor and track payments 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 After creating a payment, you need to know when it completes, fails, or requires action. Payments Direct provides two approaches for tracking payment state: Webhooks : Ripple sends a notification to your endpoint each time a payment transitions to a new state. This is the recommended approach for production integrations. Polling : Your application periodically queries the API to check the current payment state. Use this approach for low-volume scenarios or when a publicly reachable webhook endpoint is not available. ## /products/payments-direct-2/api-docs/error-handling Error handling and retry strategy 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 Payments Direct returns a standardized error response for every failed API request. Building a reliable integration means classifying errors correctly, retrying safely, and escalating promptly when retrying won't help. This topic covers: How to classify errors using the code and type fields Which errors are safe to retry, and how to retry them Recommended exponential backoff parameters Handling authentication errors Handling payment failures (FAILED, DECLINED, RETURNED states) What to log and monitor Classify before you act Every error response includes a code field (for example, USR_067 ) and a type field (for example, USER_ERROR ). Always use the code field as your primary signal, not the HTTP status code alone. Two errors can share an HTTP status but require completely different handling. Error type reference Type Prefix What it means General action USER_ERROR or NOT_FOUND USR_ The request itself is the problem: missing fields, invalid values, or a resource that doesn't exist. Fix the request and resubmit. Do not retry the same request. AUTH_ERROR AUTH_ The request was rejected due to an authentication or authorization problem. See Handling authentication errors below. SYSTEM_ERROR SYS_ An internal error occurred in Ripple's infrastructure. Retry with exponential backoff. Escalate to Ripple technical support if the condition persists. CONFIGURATION_ERROR CFG_ An account or service configuration issue prevents the request from completing. Do not retry. Contact Ripple technical support. Transient vs. permanent errors Before retrying, confirm that the error is transient (a condition that may resolve itself) rather than permanent. Error type HTTP status Retryable? Recommended action USER_ERROR 400, 404, 415 No Fix the request and resubmit. USER_ERROR 402 Not until resolved Resolve the underlying condition (insufficient balance, credit limit, or past-due invoice) before retrying. NOT_FOUND 404 No Verify the resource ID and resubmit. AUTH_ERROR 401 Yes (after token refresh) Regenerate your access token and retry. AUTH_ERROR 403 No Verify your token has the required scopes. Contact Ripple technical support if the issue persists. SYSTEM_ERROR 500 Yes (with backoff) Retry with exponential backoff. Contact Ripple technical support if the issue persists. CONFIGURATION_ERROR 500 No Contact Ripple technical support. Retry strategy Exponential backoff with jitter When a request fails with a retryable error ( SYSTEM_ERROR / 500, or AUTH_ERROR / 401 after a token refresh), use exponential backoff with jitter rather than retrying immediately or at a fixed interval. Immediate or synchronized retries amplify load on an already stressed system and can trigger rate limiting. Recommended approach: On the first failure, wait a short base interval. On each subsequent failure, double the wait time. Add random jitter (±10–20% of the interval) to desynchronize retries across clients. Cap the maximum wait at a reasonable ceiling. After a configurable number of attempts, stop retrying and alert your on-call team. Example backoff schedule: Retry attempt Base wait With jitter (±20%) 1 2s 1.6s – 2.4s 2 4s 3.2s – 4.8s 3 8s 6.4s – 9.6s 4 16s 12.8s – 19.2s 5 32s 25.6s – 38.4s 6+ 60s (cap) 48s – 72s Use a maximum retry count Set a hard limit on the number of retries (for example, 5 attempts). After that limit is reached without a successful response, stop retrying, record the failure, and alert your team. Continuing to retry indefinitely can mask a persistent issue and delay investigation. Idempotency and safe retries A timeout or connection error on a create payment request does not mean the payment was not created. Ripple may have received and processed the request even though you did not receive the response. The quoteId is the idempotency key Payment creation is deduplicated on quoteId , and one quote can produce at most one payment. If a payment already exists for the quoteId in a POST /v3/payments request, Ripple returns that payment instead of creating a new one. When you resend a request for a quote that already has a payment: The response is 201 Created , the same as for a new payment. The status code does not tell you whether this request created the payment or returned an existing one. The payment is returned as it was stored. Ripple does not compare the rest of the request body against it, so changing a field on a resend has no effect. Resend the original request unchanged. The payment is returned even if the quote has expired since the first request. internalId is not an idempotency key for payments. Ripple does not check payment internalId values for uniqueness, so two requests with the same internalId and different quoteId values create two payments. This differs from identities, where internalId must be unique across your ACTIVE identities. See Payment identities . Retrying after a timeout Retry with the same quoteId, never a new quote If a create payment request times out or fails with a connection error, resend it with the same quoteId . If the first request created the payment, the resend returns it. If it did not, the resend creates it. Do not get a new quote and submit it in place of the first. A new quoteId is a new payment, and Ripple cannot tell that it duplicates the first one, even if both requests carry the same internalId . Space resends out using the backoff described in Retry strategy . If a resend is rejected with HTTP 400 and USR_058 (quote expired), no payment was stored for that quote when the resend was processed. Before you get a new quote, check that the original request did not create a payment, as described below. Checking whether a payment was created To reconcile payments against your own records, search with POST /v3/payments/filter and your internalId . This is still a valid check, with two limits: Search results are updated asynchronously. A payment created moments ago may not appear yet, so an empty result immediately after a timeout does not prove that the payment was not created. The internalId filter is not an exact-match lookup. Confirm that the internalId on each returned payment matches yours exactly. Because of these limits, resending with the same quoteId is the reliable way to recover from a timeout. Use the search to reconcile, not to decide whether to resend. Handling authentication errors 401 Unauthorized (AUTH_001, AUTH_003) A 401 error typically means your access token is expired or invalid. Access tokens have a 1-hour TTL. Recommended handling: Generate a new access token using your client_id and client_secret . Retry the original request with the new token. Do not cache tokens beyond their expires_in value. For guidance on token generation and caching, see Authentication . 403 Forbidden (AUTH_002) A 403 error means your token is valid but lacks the required scopes for the requested operation. Recommended handling: Do not retry with the same token. A new token with the same credentials will have the same scopes. Review the required scopes for the operation in the API reference. Contact Ripple technical support if you believe your credentials should have the required permissions. 403 Unauthorized (AUTH_051) AUTH_051 occurs when a request references a payment created by a different organization. This is a permanent error. Do not retry. Handling payment failures Payment failures are distinct from API errors. A payment failure occurs after a payment is created successfully (HTTP 201) but later transitions to a terminal state of FAILED , DECLINED , or RETURNED . These are not errors in the API response. They are paymentState values you observe when polling or receiving webhooks. How to detect a payment failure Payment failure details, including the error code and reason, are available on the payment object at GET /v3/payments/{paymentId} after the payment reaches a terminal state. Webhook payloads include the new paymentState but not the error code. Always fetch the full payment record to get failure details. Terminal states State Retryable? Action FAILED Possibly Fetch the payment record to get the error code. Check the API payment failures reference and API error codes reference for the specific code. Some FAILED states are caused by transient issues and can be retried with a new payment; others indicate a permanent condition. DECLINED Not until resolved Fetch the payment record to get the error code. DECLINED usually indicates a business rule violation or account condition (insufficient balance, credit limit, etc.) that must be resolved before resubmitting. RETURNED Consult Ripple The payment was returned by a downstream institution after completing. This is not a retry scenario. Contact Ripple technical support to investigate the return reason. For a full list of payment failure codes and their descriptions, see API payment failures . For background on payment states and the payment lifecycle, see Payment states . What to log and monitor Log the following fields from every error response: code — the specific error code; use this for alerting rules and dashboards type — the error category; use this
프로젝트로 돌아가기