> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tender.cash/llms.txt
> Use this file to discover all available pages before exploring further.

# Get On-ramp Status

> Retrieve the current status and stage progress of an on-ramp request

<Note>
  **Auth method: Signed (HMAC)** — this endpoint requires the full set of signed
  headers: `x-access-id`, `x-request-id`, `x-timestamp`, and an HMAC-SHA256
  `authorization` signature. See [Authentication](/api-reference/authentication#signed-hmac-authentication).
</Note>

## Overview

Returns the full on-ramp record for a given `reference`. Poll this endpoint after initiating an
on-ramp to track which stage the pipeline is on.

### Status values

| Status            | Meaning                                                          |
| ----------------- | ---------------------------------------------------------------- |
| `pending_payment` | Waiting for the customer's fiat bank transfer                    |
| `processing`      | Payment confirmed; pipeline is running                           |
| `crypto_sent`     | Crypto dispatched to `targetAddress`                             |
| `completed`       | Fully settled                                                    |
| `failed`          | Terminal failure — see `failureReason` and `stages[*].lastError` |

### Stage pipeline

Each on-ramp progresses through the following stages in order:

| Stage          | Description                                                                           |
| -------------- | ------------------------------------------------------------------------------------- |
| `payment`      | Fiat payment confirmed by the provider                                                |
| `payout`       | Fiat forwarded to JuicyWay for conversion                                             |
| `swap`         | JuicyWay swaps fiat → intermediate crypto (e.g. USDT on Tron)                         |
| `swapWithdraw` | Swapped crypto withdrawn from JuicyWay to merchant swap wallet *(skipped by default)* |
| `cryptoSend`   | Crypto sent from swap wallet to `targetAddress` (direct or via NEAR Intents bridge)   |

Each stage has its own `status`: `pending` · `in_progress` · `completed` · `failed` · `skipped`.

## Headers

<ParamField header="authorization" type="string" required>
  Base64-encoded HMAC-SHA256 signature using your API secret

  **Example:** `"5e73d044c44d733fcf819ad3409aaa..."`
</ParamField>

<ParamField header="x-timestamp" type="string" required>
  **Example:** `"2025-03-15T09:45:53.000Z"`
</ParamField>

<ParamField header="x-request-id" type="string" required>
  **Example:** `"550e8400-e29b-41d4-a716-446655440000"`
</ParamField>

<ParamField header="x-access-id" type="string" required>
  **Example:** `"your-access-id-here"`
</ParamField>

## Path Parameters

<ParamField path="reference" type="string" required>
  The `reference` returned by [Initiate On-ramp](/api-reference/endpoint/onramp/initiate)

  **Example:** `"a3f1c2d4-8e7b-4f0a-9c1d-2e3f4a5b6c7d"`
</ParamField>

## Response

<ResponseField name="status" type="string" required>
  **Example:** `"success"`
</ResponseField>

<ResponseField name="message" type="string" required>
  **Example:** `"success"`
</ResponseField>

<ResponseField name="data" type="object" required>
  <Expandable title="data properties">
    <ResponseField name="reference" type="string">
      **Example:** `"a3f1c2d4-8e7b-4f0a-9c1d-2e3f4a5b6c7d"`
    </ResponseField>

    <ResponseField name="quoteId" type="string">
      The quote ID that was used to initiate this request

      **Example:** `"b7f2a1c3-9d4e-4b2f-a8c0-1e2d3f4a5b6c"`
    </ResponseField>

    <ResponseField name="status" type="string">
      Overall pipeline status

      **Example:** `"processing"`
    </ResponseField>

    <ResponseField name="targetChain" type="string">
      **Example:** `"tron"`
    </ResponseField>

    <ResponseField name="targetAddress" type="string">
      **Example:** `"TRDFGhjkytywooiueonuoo"`
    </ResponseField>

    <ResponseField name="targetCurrency" type="string">
      **Example:** `"USDT"`
    </ResponseField>

    <ResponseField name="fiatCurrency" type="string">
      **Example:** `"NGN"`
    </ResponseField>

    <ResponseField name="fiatAmount" type="string">
      **Example:** `"50000"`
    </ResponseField>

    <ResponseField name="amountReceived" type="string">
      Fiat amount confirmed by the payment provider

      **Example:** `"50000"`
    </ResponseField>

    <ResponseField name="cryptoAmountOut" type="string">
      Amount of `targetCurrency` credited after the swap

      **Example:** `"29.87"`
    </ResponseField>

    <ResponseField name="virtualAccount" type="object">
      Bank account details presented to the customer

      <Expandable title="virtualAccount properties">
        <ResponseField name="accountNumber" type="string">
          **Example:** `"0123456789"`
        </ResponseField>

        <ResponseField name="accountName" type="string">
          **Example:** `"Tender / Ada Obi"`
        </ResponseField>

        <ResponseField name="bankName" type="string">
          **Example:** `"Wema Bank"`
        </ResponseField>

        <ResponseField name="expiresAt" type="string">
          **Example:** `"2025-06-09T11:00:00.000Z"`
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="stages" type="object">
      Per-stage progress. Each stage has the same shape.

      <Expandable title="stages properties">
        <ResponseField name="payment" type="object">
          <Expandable title="stage shape">
            <ResponseField name="status" type="string">
              `pending` · `in_progress` · `completed` · `failed` · `skipped`
            </ResponseField>

            <ResponseField name="attempts" type="number">
              **Example:** `1`
            </ResponseField>

            <ResponseField name="startedAt" type="string">
              **Example:** `"2025-06-09T10:01:00.000Z"`
            </ResponseField>

            <ResponseField name="completedAt" type="string">
              **Example:** `"2025-06-09T10:02:30.000Z"`
            </ResponseField>

            <ResponseField name="failedAt" type="string">
              Set only when status is `failed`
            </ResponseField>

            <ResponseField name="lastError" type="string">
              Error message from the last failed attempt
            </ResponseField>

            <ResponseField name="data" type="object">
              Stage-specific data (e.g. `swapId`, `withdrawId`, `txRef`)
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="payout" type="object">
          Same shape as `payment`
        </ResponseField>

        <ResponseField name="swap" type="object">
          Same shape as `payment`
        </ResponseField>

        <ResponseField name="swapWithdraw" type="object">
          Same shape as `payment`. Status is `skipped` by default.
        </ResponseField>

        <ResponseField name="cryptoSend" type="object">
          Same shape as `payment`
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="failureReason" type="string">
      Human-readable reason for terminal failure. Present only when `status` is `failed`.

      **Example:** `"Swap wallet balance too low: 12 USDT < minimum 100"`
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      **Example:** `"2025-06-09T10:00:00.000Z"`
    </ResponseField>

    <ResponseField name="updatedAt" type="string">
      **Example:** `"2025-06-09T10:05:00.000Z"`
    </ResponseField>
  </Expandable>
</ResponseField>


## OpenAPI

````yaml GET /v1/api/onramp/{reference}
openapi: 3.1.0
info:
  title: Tender API
  description: Tender Developer API for cryptocurrency payments and agent management
  version: 1.0.0
  contact:
    name: Tender Support
    url: https://tender.cash
servers:
  - url: https://secureapi.tender.cash
    description: Production Server
  - url: https://sandbox-api.tender.cash
    description: Sandbox Server
security:
  - SignedAuth: []
tags:
  - name: Agents
    description: Manage agents and sub-businesses
  - name: Transactions
    description: Payment and transaction operations
  - name: System
    description: System information and configuration
  - name: Webhooks
    description: Webhook management and logs
  - name: On-ramp
    description: Fiat-to-crypto on-ramp operations
  - name: Payouts
    description: Send crypto from merchant balance to a wallet address or payout account
  - name: Subwallets
    description: Provision and manage crypto wallet infrastructure for your end-users
paths:
  /v1/api/onramp/{reference}:
    get:
      tags:
        - On-ramp
      summary: Get On-ramp Status
      description: >-
        Retrieve the current status and per-stage progress of an on-ramp
        request.
      operationId: getOnrampStatus
      parameters:
        - name: reference
          in: path
          required: true
          description: The reference returned by Initiate On-ramp
          schema:
            type: string
            format: uuid
          example: a3f1c2d4-8e7b-4f0a-9c1d-2e3f4a5b6c7d
        - name: authorization
          in: header
          required: true
          schema:
            type: string
        - name: x-timestamp
          in: header
          required: true
          schema:
            type: string
            format: date-time
          example: '2025-03-15T09:45:53.000Z'
        - name: x-request-id
          in: header
          required: true
          schema:
            type: string
            format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        - name: x-access-id
          in: header
          required: true
          schema:
            type: string
          example: your-access-id-here
      responses:
        '200':
          description: On-ramp request retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetOnrampStatusResponse'
              example:
                status: success
                message: success
                data:
                  reference: a3f1c2d4-8e7b-4f0a-9c1d-2e3f4a5b6c7d
                  status: processing
                  targetChain: tron
                  targetAddress: TRDFGhjkytywooiueonuoo
                  targetCurrency: USDT
                  fiatCurrency: NGN
                  fiatAmount: '50000'
                  amountReceived: '50000'
                  cryptoAmountOut: '29.87'
                  virtualAccount:
                    accountNumber: '0123456789'
                    accountName: Tender / Ada Obi
                    bankName: Wema Bank
                    expiresAt: '2025-06-09T11:00:00.000Z'
                  stages:
                    payment:
                      status: completed
                      attempts: 1
                    payout:
                      status: completed
                      attempts: 1
                    swap:
                      status: in_progress
                      attempts: 1
                    swapWithdraw:
                      status: skipped
                      attempts: 0
                    cryptoSend:
                      status: pending
                      attempts: 0
                  createdAt: '2025-06-09T10:00:00.000Z'
                  updatedAt: '2025-06-09T10:04:00.000Z'
        '404':
          description: On-ramp request not found
      security:
        - SignedAuth: []
components:
  schemas:
    GetOnrampStatusResponse:
      type: object
      properties:
        status:
          type: string
        message:
          type: string
        data:
          type: object
          properties:
            reference:
              type: string
              format: uuid
            status:
              type: string
              enum:
                - pending_payment
                - processing
                - crypto_sent
                - completed
                - failed
            targetChain:
              type: string
            targetAddress:
              type: string
            targetCurrency:
              type: string
            fiatCurrency:
              type: string
            fiatAmount:
              type: string
            amountReceived:
              type: string
            cryptoAmountOut:
              type: string
            virtualAccount:
              type: object
              properties:
                accountNumber:
                  type: string
                accountName:
                  type: string
                bankName:
                  type: string
                expiresAt:
                  type: string
                  format: date-time
            stages:
              type: object
              properties:
                payment:
                  $ref: '#/components/schemas/OnrampStage'
                payout:
                  $ref: '#/components/schemas/OnrampStage'
                swap:
                  $ref: '#/components/schemas/OnrampStage'
                swapWithdraw:
                  $ref: '#/components/schemas/OnrampStage'
                cryptoSend:
                  $ref: '#/components/schemas/OnrampStage'
            failureReason:
              type: string
            createdAt:
              type: string
              format: date-time
            updatedAt:
              type: string
              format: date-time
    OnrampStage:
      type: object
      properties:
        status:
          type: string
          enum:
            - pending
            - in_progress
            - completed
            - failed
            - skipped
        attempts:
          type: integer
        startedAt:
          type: string
          format: date-time
        completedAt:
          type: string
          format: date-time
        failedAt:
          type: string
          format: date-time
        lastError:
          type: string
        data:
          type: object
  securitySchemes:
    SignedAuth:
      type: apiKey
      in: header
      name: authorization
      description: >-
        Signed (HMAC) authentication. Required headers: x-access-id,
        x-request-id (UUID v4), x-timestamp (ISO 8601), and authorization
        (Base64 HMAC-SHA256 signature of {timeStamp, requestId, accessId} using
        your access secret).

````