# On-ramp (https://dev.cosmospay.lat/docs/api/onramp/)

> Fiat in: quotes, payins, virtual accounts, and the trustline for the asset delivered.

Base URL: `https://api.cosmospay.lat/cosmos-api`

## Create a payin quote (expires in ~5 min)

`POST /v1/onramp/quotes`

Prices a payin through the fiat partner for one of your wallets (`blockchain_wallet_id`, a Cosmos Pay wallet id) and records the quote as yours, on the fiat partner instance your key selects (a `dev` key uses the development instance, a `prod` key production). The quote is the fiat partner's answer as is: create the payin from it before its `expires_at`. Amounts are integers in minor units, and `transfers` (AR) and `pse` (CO) need their `payer_rules`. A wallet you do not own is a 404, and one whose receiver's fiat access is disabled is `403 account_disabled`.

Requires the `onramp:write` scope.

**Request body** (`application/json`, required): `CreatePayinQuoteDto`

- `blockchain_wallet_id` (string, required): Cosmos Pay wallet id (from POST /v1/kyc/receivers/:id/wallets) that receives the minted stablecoin.
- `currency_type` (string, required): Whether `request_amount` is what the sender sends (`sender`) or what the receiver receives (`receiver`). One of: `sender`, `receiver`.
- `payment_method` (string, required): Fiat-in method. Note: payins use `spei`/`transfers`/`pse` (not the `_bitso` payout rails). One of: `ach`, `wire`, `pix`, `ted`, `spei`, `transfers`, `pse`, `international_swift`, `rtp`.
- `token` (string, required): Stablecoin the wallet receives; `USDB` is the test token of the development instance. One of: `USDC`, `USDT`, `USDB`.
- `request_amount` (number, required): Amount in minor units (integer).
- `cover_fees` (boolean, optional): When true, the sender absorbs the fees.
- `payer_rules` (PayerRulesDto, optional): Required for Transfers (AR): transfers_allowed_tax_id. Required for PSE (CO): pse_full_name, pse_document_type, pse_document_number, pse_email, pse_bank_code. Optional for other methods (e.g. pix).
- `is_otc` (boolean, optional): The fiat partner's OTC flag, forwarded as sent.
- `partner_fee_id` (string, optional): Partner fee id, forwarded as sent.
- `wallet_id` (string, optional): Optional custodial wallet id.

**Responses**

- `201` (`PayinQuoteEntity`): Created
  - `id` (string, required): Fiat partner quote id; pass it as `payin_quote_id` to `POST /v1/onramp/payins`.
  - `expires_at` (number, required): Unix expiry (~5 min out).
  - `commercial_quotation` (number, optional): The fiat partner's commercial quotation for this quote, passed through as it returned it.
  - `receiver_amount` (number, optional): Amount the receiver gets, in minor units.
  - `sender_amount` (number, optional): Amount the sender pays, in minor units.
- `400`: ValidationFailed (see Shared responses)
- `401`: Unauthorized (see Shared responses)
- `403`: Forbidden (see Shared responses)
- `429`: RateLimited (see Shared responses)
- `500`: InternalError (see Shared responses)
- `502`: UpstreamError (see Shared responses)
- `503`: UpstreamUnavailable (see Shared responses)
- `504`: UpstreamTimeout (see Shared responses)

## List the consumer's payins

`GET /v1/onramp/payins`

Reads this service's mirror only (no fiat partner call), newest first, limited to your key's fiat partner instance; payins still waiting for the fiat partner's id are left out. Paginated with `take` (default 100, max 100) and `skip`; answers `{ data, total, take, skip }`, where `total` counts every matching payin.

Requires the `onramp:read` scope.

**Query parameters**

- `take` (number, optional): Page size: how many items to return (1 to 100).
- `skip` (number, optional): How many items to skip before this page (offset).

**Responses**

- `200` (`PayinListEntity`): OK
  - `data` (PayinEntity[], required): The payins on this page.
  - `total` (number, required): Matching rows, not the page length.
  - `take` (number, required): The page size applied, from the `take` query parameter (default 100).
  - `skip` (number, required): Rows skipped before this page, from the `skip` query parameter (default 0).
- `400`: ValidationFailed (see Shared responses)
- `401`: Unauthorized (see Shared responses)
- `403`: Forbidden (see Shared responses)
- `500`: InternalError (see Shared responses)

## Create a payin from a quote; returns funding instructions

`POST /v1/onramp/payins`

Executes a quote from `POST /v1/onramp/quotes` at the fiat partner and returns the payin with the instructions the payer follows to fund it off-platform; the destination chain is the one of the quote's wallet. Idempotent per quote: a retry of the same quote reuses its row and its the fiat partner `Idempotency-Key`, so it cannot create a second payin. A quote that is not yours, is a payout quote or was minted on the other instance is `404 quote_not_found`; a lapsed one is `400 quote_expired`. Status changes arrive later as `PAYIN_UPDATED` and `PAYIN_COMPLETED` webhook events.

Requires the `onramp:write` scope.

**Request body** (`application/json`, required): `CreatePayinDto`

- `payin_quote_id` (string, required): The id returned by POST /v1/onramp/quotes.

**Responses**

- `201` (`PayinEntity`): Created
  - `id` (string, required): Cosmos Pay id of the payin.
  - `blindpayId` (string, required): The fiat partner's payin id (`pi_...`).
  - `status` (object, optional): Fiat partner status of the payin (for example `processing`); `completed`, `failed`, `refunded` and `cancelled` mean the money stopped moving.
  - `token` (object, optional): Stablecoin the payin delivers (for example `USDC`).
  - `network` (object, optional): Network the stablecoin is delivered on (for example `stellar`).
  - `paymentMethod` (object, optional): Fiat method the payer funds the payin with (for example `pix`).
  - `senderAmount` (object, optional): Amount the payer sends, in minor units, as a string.
  - `receiverAmount` (object, optional): Amount the wallet receives, in minor units, as a string.
  - `instructions` (object, optional): Funding instructions for the payer (memo/CLABE/PIX/CBU/PSE/...).
  - `createdAt` (string (date-time), required): When this service recorded the payin (ISO 8601 date-time).
- `400` (`ApiErrorBodyEntity`): `validation_failed`: The body, query or headers failed validation `quote_expired`: The quote is ours and yours, but past its expiry
  - `statusCode` (number, required): Always the HTTP status of the response itself.
  - `code` (string, required): Stable machine-readable code. Branch on this, never on the message: messages are human-facing and may be reworded; codes are never renamed once published. Each response documents the subset it can return. One of: `insufficient_scope`, `no_authenticated_consumer`, `gateway_required`, `admin_console_only`, `not_found`, `validation_failed`, `payload_too_large`, `idempotency_conflict`, `operation_in_flight`, `invalid_state_transition`, `slippage_exceeded`, `insufficient_balance`, `no_path_found`, `trustline_missing`, `invalid_amount`, `invalid_memo`, `transaction_rejected`, `transaction_already_settled`, `recipient_not_registered`, `payment_transfer_mismatch`, `fee_transfer_mismatch`, `merchant_fee_transfer_mismatch`, `payer_mismatch`, `transaction_not_found`, `expired`, `network_unsupported`, `asset_unsupported`, `merchant_fee_unsupported`, `provider_error`, `provider_unavailable`, `quote_not_found`, `quote_expired`, `kyc_state_invalid`, `kyc_review_required`, `account_disabled`, `payload_expired`, `rate_limited`, `customer_wallet_taken`, `alias_taken`, `alias_name_invalid`, `alias_challenge_invalid`, `alias_signature_invalid`, `alias_recovery_invalid`, `alias_address_conflict`, `wallet_handshake_invalid`, `wallet_verifier_invalid`, `wallet_login_code_invalid`, `wallet_login_code_cooldown`, `wallet_session_invalid`, `wallet_signature_invalid`, `wallet_backup_invalid`, `wallet_backup_limit`, `wallet_account_mismatch`, `wallet_provider_unavailable`, `wallet_return_url_not_allowed`, `wallet_recovery_setup_refused`, `easy_recovery_not_found`, `easy_recovery_already_offered`, `easy_recovery_not_offered`, `easy_recovery_code_invalid`, `easy_recovery_burned`, `plugin_not_installed`, `plugin_consent_mismatch`, `plugin_rejected`, `plugin_quota_exceeded`, `plugin_failed`, `protected_payment_buyer_mismatch`, `protected_payment_signature_invalid`, `misconfigured`, `internal_error`.
  - `error` (string, required): The HTTP reason phrase for `statusCode`.
  - `message` (string | string[], required): Human-readable detail. An array when class-validator rejected the body.
  - `details` (object, optional): Machine-readable facts about this failure, present only on the codes whose example shows it: `easy_recovery_code_invalid` carries `{ "attemptsLeft": 4 }`. Absent everywhere else.
  - `path` (string, required): The path of the request that failed.
  - `timestamp` (string, required): When the envelope was produced, ISO 8601.
- `401`: Unauthorized (see Shared responses)
- `403`: Forbidden (see Shared responses)
- `429`: RateLimited (see Shared responses)
- `500`: InternalError (see Shared responses)
- `502`: UpstreamError (see Shared responses)
- `503`: UpstreamUnavailable (see Shared responses)
- `504`: UpstreamTimeout (see Shared responses)

## Get a payin (serves the local mirror; refreshes from the fiat partner when stale)

`GET /v1/onramp/payins/{id}`

Answers from the mirror while it was updated in the last 60 seconds; an older row is refreshed from the fiat partner first, and when the fiat partner cannot answer the stored row is returned instead of an error. Only payins of your key's fiat partner instance that the fiat partner already acknowledged; anything else is 404.

Requires the `onramp:read` scope.

**Path parameters**

- `id` (string, required)

**Responses**

- `200` (`PayinEntity`): OK
- `400`: ValidationFailed (see Shared responses)
- `401`: Unauthorized (see Shared responses)
- `403`: Forbidden (see Shared responses)
- `404`: NotFound (see Shared responses)
- `500`: InternalError (see Shared responses)
- `502`: UpstreamError (see Shared responses)
- `503`: UpstreamUnavailable (see Shared responses)
- `504`: UpstreamTimeout (see Shared responses)

## Build an unsigned Stellar trustline tx (XDR) for the customer to sign

`POST /v1/onramp/trustline`

Asks the fiat partner to build the unsigned Stellar transaction that adds the trustline `address` needs to hold the onramp's stablecoin, and returns the fiat partner's answer as is. The customer signs it: this service never signs. Built on your key's fiat partner instance; nothing is stored.

Requires the `onramp:write` scope.

**Request body** (`application/json`, required): `CreateTrustlineDto`

- `address` (string, required): Stellar address that needs the asset trustline.

**Responses**

- `201`: Created
- `400`: ValidationFailed (see Shared responses)
- `401`: Unauthorized (see Shared responses)
- `403`: Forbidden (see Shared responses)
- `429`: RateLimited (see Shared responses)
- `500`: InternalError (see Shared responses)
- `502`: UpstreamError (see Shared responses)
- `503`: UpstreamUnavailable (see Shared responses)
- `504`: UpstreamTimeout (see Shared responses)

## List a receiver's virtual accounts

`GET /v1/onramp/receivers/{receiverId}/virtual-accounts`

Reads this service's mirror only (no fiat partner call), newest first. The receiver must be yours on your key's fiat partner instance, or the answer is 404. Paginated with `take` (default 100, max 100) and `skip`; answers `{ data, total, take, skip }`.

Requires the `onramp:read` scope.

**Path parameters**

- `receiverId` (string, required)

**Query parameters**

- `take` (number, optional): Page size: how many items to return (1 to 100).
- `skip` (number, optional): How many items to skip before this page (offset).

**Responses**

- `200`: OK
- `400`: ValidationFailed (see Shared responses)
- `401`: Unauthorized (see Shared responses)
- `403`: Forbidden (see Shared responses)
- `404`: NotFound (see Shared responses)
- `500`: InternalError (see Shared responses)

## Create a virtual account for a receiver

`POST /v1/onramp/receivers/{receiverId}/virtual-accounts`

Opens a virtual account at the fiat partner: a bank account in the receiver's name at `banking_partner` whose deposits are converted to `token` and sent to `blockchain_wallet_id`, a Cosmos Pay wallet id. The account is mirrored here and the mirrored row is the answer. A receiver or wallet that is not yours on your key's fiat partner instance is a 404, and the answer is `403 account_disabled` when the receiver, or the receiver that owns the wallet, has its fiat access disabled.

Requires the `onramp:write` scope.

**Path parameters**

- `receiverId` (string, required)

**Request body** (`application/json`, required): `CreateVirtualAccountDto`

- `banking_partner` (string, required): Bank the virtual account is opened at. One of: `jpmorgan`, `citi`, `hsbc`, `cfsb`.
- `token` (string, required): Stablecoin the deposits are converted to; `USDB` is the test token of the development instance. One of: `USDC`, `USDT`, `USDB`.
- `blockchain_wallet_id` (string, required): Cosmos Pay wallet id that receives the converted stablecoin.
- `signed_agreement_id` (string, optional): Id of a signed agreement, forwarded to the fiat partner.
- `sole_proprietor_doc_type` (string, optional): Type of the sole-proprietor document, forwarded to the fiat partner.
- `sole_proprietor_doc_file` (string, optional): Sole-proprietor document file, forwarded to the fiat partner.

**Responses**

- `201`: Created
- `400`: ValidationFailed (see Shared responses)
- `401`: Unauthorized (see Shared responses)
- `403`: Forbidden (see Shared responses)
- `404`: NotFound (see Shared responses)
- `500`: InternalError (see Shared responses)
- `502`: UpstreamError (see Shared responses)
- `503`: UpstreamUnavailable (see Shared responses)
- `504`: UpstreamTimeout (see Shared responses)

## Shared responses

- **ValidationFailed** (`ApiErrorBodyEntity`): The body, query or path failed validation. `message` is an array of the individual failures. Routes that reject a *valid* request for a reason of their own (an amount, a memo, a state) document the code for it on their own 400.
- **Unauthorized** (`ApiErrorBodyEntity`): `no_authenticated_consumer`: The gateway forwarded no API key identity
- **Forbidden** (`ApiErrorBodyEntity`): `insufficient_scope`: the API key does not hold the scope this route requires. The shared public API key also gets this on every route that is not marked `x-cosmos-public-key`, with a message saying so; more scopes will not help, the key is the wrong one. `gateway_required`: the request did not arrive through APISIX.
- **RateLimited** (`ApiErrorBodyEntity`): The budget in `x-cosmos-rate-limit` is spent for this caller. Honour `Retry-After`. The `ratelimit-*` triple rides along on successful responses too, so a client can pace itself instead of being refused. If the counter store itself is unreachable the guard fails closed and answers `503 provider_unavailable`.
- **InternalError** (`ApiErrorBodyEntity`): Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
- **UpstreamError** (`ApiErrorBodyEntity`): The provider named in `x-cosmos-upstream` refused the request (`provider_error`) or could not be reached at all (`provider_unavailable`). Nothing was charged; retry is safe with the same `Idempotency-Key`.
- **UpstreamUnavailable** (`ApiErrorBodyEntity`): `provider_unavailable`: the provider in `x-cosmos-upstream` is down or unreachable; the message names it. Retry. `misconfigured`: this deployment is missing configuration the route needs (a provider instance, a fee wallet, the plan header the gateway must forward). Retrying will not help; it is an operator problem.
- **UpstreamTimeout** (`ApiErrorBodyEntity`): The provider in `x-cosmos-upstream` did not answer in time. Whether it acted on the request is unknown. Retry with the same `Idempotency-Key`, never with a fresh one.
- **NotFound** (`ApiErrorBodyEntity`): No such resource, or it exists and belongs to another consumer. The two are deliberately the same answer: "exists but not yours" is an ownership oracle.
