Onramp API Reference

Base URLs: https://onramp.mainnet.rubin.trade (mainnet), https://onramp.testnet.rubin.trade (testnet). All customer endpoints live under the route /v4/sbp; Rubin assigns each customer a payment provider behind it (see Overview).

Auth column: public — no signature; signed — signed request for the customer address.

An endpoint the customer's flow does not use answers 404 (after authentication and validation). Amounts are decimal strings; timestamps are ISO 8601.

Errors

Every error has the same shape:

{ "errors": [{ "code": "QUOTE_EXPIRED", "msg": "Quote expired", "retryAfterSeconds": 30 }] }

code and retryAfterSeconds are present only where they apply. Request validation errors (400) are a list of { "value", "msg", "param", "location" } without code. Pauses are reported only in retryAfterSeconds — there is no Retry-After header.

Provider errors carry a fixed msg per code. To investigate a specific failure, send us the address, the time and the response.

Authentication errors are listed on the Authentication page.

Rates

GET /v4/sbp/rates

Current rate for buying USDC with fiat (RUB). Public; sign it when the customer's flow.ratesPerCustomer is true.

{ "userRate": "81.250000", "currency": "RUB", "quoteSignature": "…", "expiresInSeconds": 165 }

Errors: NOT_VERIFIED, CUSTOMER_NOT_FOUND (personal rates only), PROVIDER_UNAVAILABLE, PROVIDER_ERROR.

Customer

GET /v4/sbp/customer

Verification state of the signing address and the steps it needs. The first call of an address assigns it a payment provider.

{
  "flow": {
    "identity": "form",
    "phoneOtp": true,
    "contacts": false,
    "ratesPerCustomer": false,
    "settlement": false,
    "poolLimited": false
  },
  "exists": true,
  "verificationLevel": 3,
  "identified": true,
  "phoneSet": true,
  "phoneMasked": "+7***1234",
  "identifyStatus": "success",
  "activeOrderId": null
}

POST /v4/sbp/customer

Attaches a phone number and sends an SMS code. Form flow.

Response: { "verificationLevel": 1, "otpSent": true, "nextStep": "verify_phone" }.

Errors: PHONE_ALREADY_REGISTERED, SMS_RATE_LIMIT, PROVIDER_ERROR (SMS could not be sent).

POST /v4/sbp/customer/resend-otp

Sends the SMS code again. Body: { "phone": "+79991234567" }. Response: { "otpSent": true }. Errors: SMS_RATE_LIMIT.

POST /v4/sbp/customer/verify-phone

Response: { "verificationLevel": 2, "identified": false, "phoneSet": true }. A 200 with verificationLevel below 2 means the code was not accepted.

Errors: OTP_INVALID, OTP_EXPIRED, SMS_RATE_LIMIT, CUSTOMER_NOT_FOUND.

POST /v4/sbp/customer/identify

Identity-document check. POST …/customer/identify/update takes the same body to correct the details of a customer already at level 3.

Response: { "verificationLevel": 3, "identified": true, "identifyStatus": "success" }. With identifyStatus: "pending" poll GET /customer.

Errors: IDENTIFY_FAILED, CUSTOMER_NOT_FOUND.

POST /v4/sbp/customer/esia

Starts a government eID (ESIA) login to raise the customer to level 4.

Response: { "redirectUrl": "https://…" } — send the user there. After they return, poll GET /customer until verificationLevel is 4.

Errors: 422 "ESIA is not enabled", 422 "redirectUrl is missing or not allowed", IDENTIFY_FAILED.

POST /v4/sbp/customer/kyc

Returns the hosted KYC page. Hosted flow.

Response: { "url": "https://…", "status": "pending" }. url is null while the page is being prepared or when KYC is already approved.

POST /v4/sbp/customer/contacts

Hosted flow with flow.contacts.

Response: { "status": "action_required", "actionUrl": "https://…" }. Open actionUrl on action_required; poll GET /customer on pending.

Errors: CONTACTS_CONFLICT.

Limits

GET /v4/sbp/limits

null means that limit is not reported. Errors: CUSTOMER_NOT_FOUND.

Orders

POST /v4/sbp/orders

Creates an order and requests a payment link.

Response: an order.

Errors: NOT_VERIFIED, QUOTE_EXPIRED, AMOUNT_BELOW_MIN, AMOUNT_ABOVE_MAX, LIMIT_EXCEEDED, PROVIDER_LIQUIDITY, CONTACTS_REQUIRED, CONTACTS_CONFLICT, CUSTOMER_NOT_FOUND, PROVIDER_UNAVAILABLE, PROVIDER_ERROR; 422 "amountCrypto must be positive".

GET /v4/sbp/orders

The customer's orders, newest first.

Response: { "orders": [ …order objects… ] }.

GET /v4/sbp/orders/{orderId}

One order of the signing customer. An open order is refreshed from the payment provider when it has not been updated recently, so this is the endpoint to poll. Response: an order; another customer's or unknown order — 404 "Order not found".

Order object

{
  "orderId": "4f0c7c7e-3a8d-4c55-9b0e-2a51c1f0a6d2",
  "provider": "sbp",
  "status": "awaiting_payment",
  "creditStatus": "none",
  "amountUser": "125.500000",
  "amountGrossFiat": "10196.88",
  "fiatCurrency": "RUB",
  "paymentLink": "https://…",
  "creditTxHash": null,
  "createdAt": "2026-10-12T09:15:02.000Z"
}

The order is complete when status is success and creditStatus is credited.

Service

GET /health

{ "ok": true, "service": "onramp" }. Public.