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