On-ramp Routes
An on-ramp route gives your customer dedicated bank details in their own name. Every fiat deposit that arrives is reconciled to the customer, converted to a stablecoin and sent to the wallet you set on the route.
It is a Payment Route with workflow_type: "fiat_to_crypto", the default when workflow_type is omitted. It is the same resource as Off-ramp Routes (crypto_to_fiat). You create it once and your customer reuses the same bank details for every payment.
How it works
- Create the route for a verified customer: the currency the customer pays in, and the stablecoin, network and wallet address every deposit is delivered to.
- Stables returns the deposit details in
source_deposit_instructions: an account number and routing details, or an IBAN, depending on the rail. - Your customer pays in from their bank on a supported local rail, any amount above the minimum, as often as they like.
- Stables receives and reconciles each deposit, converts it at the rate when it is confirmed, and sends the stablecoin to the route's wallet.
- Each deposit is a route transaction. It appears in the route's history with the fees, the rate and the payout amount, and is reported with
virtual_account.activity.*webhooks.
Currencies
| Currency | Deposit details | Rails | Entitlement |
|---|---|---|---|
| USD | U.S. account and routing numbers | ACH, domestic wire (Fedwire) | usd_virtual_account |
| AED | UAE local bank account details | IPP, UAEFTS | aed_local |
| SWIFT collection (businesses) | An IBAN that receives international SWIFT transfers in 18 currencies | SWIFT | base_pay_in |
EUR and GBP local accounts are in the works. Limits, minimums and cut-offs per currency are on Supported currencies.
The customer needs the entitlement for the currency before the route can be created. A USD account also needs the customer's financial profile, including expected monthly payment volume, sent with PATCH /api/v1/customers/{customer_id}/entitlements/usd_virtual_account/requirements. See Entitlements.
Create an on-ramp route
Request
curl -L \
--request POST \
--url 'https://api.stables.money/api/v1/customers/{customerId}/payment-routes' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--header 'Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000' \
--header 'Content-Type: application/json' \
--data '{
"source": {
"currency": "USD"
},
"metadata": {
"internal_reference": "client-2041"
},
"destination": {
"currency": "usdt",
"payment_rail": "tron",
"address": "TUVPATBKPjUuN5pBkigmfQtUR9yoYFhvv7",
"wallet_type": "hosted",
"vasp_name": "Binance"
}
}'Set destination.wallet_type to hosted when the address belongs to an exchange or other provider, and name it in vasp_name. Use self_hosted when your customer holds the keys. Omitted means self_hosted. See Travel Rule.
Response
status is typically pending immediately after creation while the provider activates the account (this can take a few seconds), then transitions to activated once confirmed. Poll the virtual account or listen for status-change events rather than assuming activated on creation.
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"status": "pending",
"customer_id": "123e4567-e89b-12d3-a456-426614174000",
"created_at": "2026-04-01T01:12:37.384Z",
"source_deposit_instructions": {
"currency": "USD",
"payment_rails": [
"ach_push",
"wire"
],
"bank_name": "Example Bank",
"bank_address": "123 Smith Street",
"bank_beneficiary_name": "John Smith",
"bank_beneficiary_address": "321 Smith Street",
"bank_account_number": "1111111111",
"bank_routing_number": "111111111",
"account_holder_name": "John Smith"
},
"deposit_handling_mode": "auto_payout",
"destination": {
"currency": "usdt",
"payment_rail": "tron",
"address": "TUVPATBKPjUuN5pBkigmfQtUR9yoYFhvv7",
"wallet_type": "hosted",
"vasp_name": "Binance"
}
}Deposits and webhooks
Read a route's deposits with GET /api/v1/customers/{customerId}/payment-routes/{virtualAccountId}/history, and one route with Get Payment Route. Deposits are reported with virtual_account.activity.created when they arrive and virtual_account.activity.updated.status_transitioned as the payout progresses.
In sandbox, create a deposit without a real bank transfer with Simulate deposit.
SWIFT collection accounts
A SWIFT collection account gives a business customer an IBAN that receives international SWIFT transfers. Each deposit is converted and paid out in USDT to the route's wallet, like any other Payment Route.
Use it when your business customers are paid by overseas clients, or in a currency with no local Payment Route.
Who can open one
- Business customers only. A request for an individual is refused.
- The business's verification (
business_base) must be approved. - The customer needs the
base_pay_inentitlement.
Currencies
AED, AUD, CAD, CHF, CZK, DKK, EUR, GBP, GEL, HKD, HUF, JPY, NZD, PLN, SEK, SGD, THB and USD, settling in USDT on Tron. See Supported currencies.
How it differs from a local account
- The account is not in your customer's name. The account holder is a Stables entity, returned in
account_holder_nameandbank_beneficiary_name. Each account has its own IBAN, which is how a deposit is matched to your customer. payment_railsis["swift"], and the deposit details includeibanandbicin place of a local account and routing number.- SWIFT transfers take longer than local payments, and the sender's and intermediary banks may deduct their own charges before the funds arrive.
Open a SWIFT collection account
Set source.payment_rail to swift. Without it, the account is opened on the currency's local rail, or refused if the currency has none.
curl -L \
--request POST \
--url 'https://api.stables.money/api/v1/customers/{customerId}/payment-routes' \
--header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
--header 'Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000' \
--header 'Content-Type: application/json' \
--data '{
"source": {
"currency": "EUR",
"payment_rail": "swift"
},
"workflow_type": "fiat_to_crypto",
"destination": {
"currency": "usdt",
"payment_rail": "tron",
"address": "TUVPATBKPjUuN5pBkigmfQtUR9yoYFhvv7"
}
}'Response
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"status": "activated",
"customer_id": "123e4567-e89b-12d3-a456-426614174000",
"created_at": "2026-11-16T04:30:27.206Z",
"source_deposit_instructions": {
"currency": "eur",
"payment_rails": [
"swift"
],
"bank_name": "Example Bank",
"bank_address": "1 Example Street, Example City",
"bank_beneficiary_name": "Stables Entity Ltd.",
"bank_beneficiary_address": "2 Example Avenue, Example City",
"iban": "XX00EXAM00000000000000",
"bic": "EXAMPLEXXXX",
"account_holder_name": "Stables Entity Ltd."
},
"deposit_handling_mode": "auto_payout",
"workflow_type": "fiat_to_crypto",
"destination": {
"currency": "usdt",
"payment_rail": "tron",
"address": "TUVPATBKPjUuN5pBkigmfQtUR9yoYFhvv7"
}
}Give your customer's payers every field in source_deposit_instructions, exactly as returned.
Errors
| Status | Message | What to do |
|---|---|---|
| 400 | SWIFT collection accounts are only available for business customers | Use a local Payment Route for individuals. |
| 400 | SWIFT collection accounts are available once the business's verification is approved | Wait for business_base to be approved, then retry. |
| 400 | SWIFT collection is not available for {currency} | The currency or destination network has no SWIFT route. |
| 422 | ROUTING_ENTITLEMENT_MISSING naming base_pay_in | Request base_pay_in for the customer, then retry. |