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

# Fetch an offramp

> Fetches a single offramp by its external id (prefixed `ofr_`).

### Path parameter

- `id` — required. The offramp's external id (e.g. `ofr_01KPBH887CCT3A53EW3F8R0VQG`).
  A value that is not a valid `ofr_…` id returns `400`. An id that does not exist returns `404`.

### Example

```
GET /v1/offramps/ofr_01KPBH887CCT3A53EW3F8R0VQG
```




## OpenAPI

````yaml /api-reference/openapi.json get /v1/offramps/{offrampId}
openapi: 3.0.0
info:
  title: GlobalStack API
  version: 1.0.0
  description: >
    # Introduction


    GlobalStack API for cross-border payments powered by stablecoin rails.


    Getting started: authenticate with a Bearer token, make your first call to

    `GET /v1/currencies`, and explore.


    **Key operations:**


    - **Onramp** — convert external fiat into crypto credited to a wallet.

    - **Offramp** — convert crypto from a wallet into fiat delivered to a
    beneficiary.

    - **Conversion** — move value between two wallets belonging to the same
    customer.

    - **Transfer** — send crypto from a wallet to an external address.

    - **Deposit** — receive external crypto into a wallet via a deposit address.


    See the sections below for authentication, response shape, idempotency,

    references, metadata, and webhooks.


    ## Authentication


    All API requests require a Bearer token in the `Authorization` header:


    ```

    Authorization: Bearer gsa_sk_live_your_api_key

    ```


    API keys use the `gsa_sk_live_` prefix.


    API keys are scoped to a single merchant account. All resources created with

    a key belong to that merchant. Keep your keys secret — do not expose them in

    client-side code or public repositories.


    To rotate a key, generate a new one from your dashboard and update your

    integration before revoking the old key.


    ## API Response Shape


    Every response — success or failure — follows the same envelope:


    ```json

    {
      "status": true,
      "message": "Onramp created successfully",
      "code": "ok",
      "data": { },
      "meta": {
        "request_id": "req_01ABC...",
        "timestamp": "2026-04-22T02:00:00Z",
        "version": "1"
      }
    }

    ```


    **Fields:**


    - `status` (boolean) — whether the HTTP call succeeded. This is not the
      business status of the underlying resource.
    - `message` (string) — human-readable explanation for developers and logs.
      Do not show to end users.
    - `code` (string) — stable machine-readable result. `ok` on success, or an
      error code like `bad_request`.
    - `data` — the resource payload on success (object, array, or scalar).
    `null`
      on failure.
    - `meta` — request-scoped metadata, always present. Includes `request_id`
      (quote this in support tickets), `timestamp`, and `version`. On list
      endpoints, also includes `page`, `per_page`, `total`, `has_more`. On
      validation errors, includes `errors` array and `next_steps`.

    Error responses include `next_steps` in `meta` with an `action` string and a

    `docs_url` link:


    ```json

    {
      "status": false,
      "message": "Your request has validation errors.",
      "code": "bad_request",
      "data": null,
      "meta": {
        "request_id": "req_01ABC...",
        "timestamp": "2026-04-22T02:00:00Z",
        "version": "1",
        "errors": [
          { "field": "amount", "code": "required", "message": "Amount is required." }
        ],
        "next_steps": {
          "action": "Review the request and retry with corrected parameters.",
          "docs_url": "https://docs.globalstack.io/errors#bad_request"
        }
      }
    }

    ```


    ## Idempotency


    Pass an `Idempotency-Key` header on any create endpoint to make the request

    safely retryable:


    ```

    Idempotency-Key: your-unique-key-here

    ```


    **Rules:**


    - Same key + same body = returns the original response (no side effects).

    - Same key + different body = returns `idempotency_conflict` (409).

    - Keys are scoped to your merchant account.

    - Keys expire after 24 hours.


    Use idempotency keys for any operation that creates a resource or moves

    money. This protects against network retries, duplicate webhooks, and

    client-side retry loops.


    ## Rate Limits


    Requests over the rate limit are rejected with HTTP `429` and the error code

    `rate_limited`:


    ```json

    {
      "status": false,
      "message": "Too many requests. Slow down and retry shortly.",
      "code": "rate_limited"
    }

    ```


    **Money-movement writes** (creating transfers, offramps, conversions, or

    wallet operations) are limited **per merchant account** — the budget is

    shared across all of your API keys and dashboard sessions. Reads are not

    limited.


    On a `429`, back off and retry with jitter; for money movement, reuse the

    same `Idempotency-Key` so the retry stays safe.


    ## Reference


    Every money movement operation (onramp, offramp, conversion, transfer)

    accepts an optional `reference` field — a merchant-supplied identifier that

    is unique per merchant account.


    ```json

    {
      "reference": "INV-2026-001",
      "wallet_id": "wal_..."
    }

    ```


    If you omit `reference`, the API generates one automatically (prefixed

    `ref_`).


    References are unique per merchant — attempting to create two operations

    with the same reference returns the existing operation (same behavior as

    idempotency, but permanent and not time-limited).


    Use `reference` to correlate GlobalStack operations with your own system

    records (invoices, orders, payouts).


    ## Metadata


    Most create endpoints accept an optional `metadata` object — a flat set of

    string key/value pairs stored on the resource:


    ```json

    {
      "metadata": {
        "order_id": "ord_12345",
        "customer_email": "alice@example.com"
      }
    }

    ```


    Metadata is returned on every GET response and in webhook payloads. It is

    not used by GlobalStack for processing — it exists for your own

    record-keeping.


    Resources that accept metadata: customers, wallets, senders, beneficiaries,

    wallet credentials, deposit addresses, onramps, offramps, conversions, and

    transfers.


    ## Webhook Signatures


    Every webhook delivery is signed so you can verify it came from GlobalStack
    and

    was not tampered with in transit. Signatures follow the

    [Svix](https://docs.svix.com/receiving/verifying-payloads/how) standard, so
    you

    can verify them with any Svix library — or manually with the construction
    below.


    Each delivery carries three headers:


    ```

    svix-id: msg_2gT8sV...          # unique message id (the body's event_id,
    prefixed msg_)

    svix-timestamp: 1718960400      # unix seconds when the delivery was signed

    svix-signature: v1,g0hM9SsE...  # space-separated list of
    v1,<base64-signature>

    ```


    Your signing secret (prefixed `whsec_`) is returned in plaintext **exactly

    once** — when you create a webhook endpoint or rotate its secret. Store it

    securely; you cannot retrieve it again.


    **Verify with a Svix library (recommended):**


    ```python

    from svix.webhooks import Webhook


    wh = Webhook(signing_secret)                            # the whsec_...
    value

    payload = wh.verify(raw_request_body, request_headers)  # raises on a bad
    signature

    ```


    **Verify manually:**


    1. Build the signed content by joining the id, timestamp, and the **raw**
       request body with dots:

       ```
       signed_content = svix_id + "." + svix_timestamp + "." + raw_body
       ```

    2. Take your signing secret, drop the `whsec_` prefix, and base64-decode the
       remainder — those bytes are your HMAC key.

    3. Compute `base64(HMAC-SHA256(key, signed_content))`.


    4. The `svix-signature` header is a space-separated list of `v1,<signature>`
       entries (an endpoint can have more than one valid secret during a rotation).
       Compare your computed value against each entry's signature — the part after
       `v1,` — using a constant-time comparison, and accept if any matches.

    5. Reject deliveries whose `svix-timestamp` differs from your current time
    by
       more than a few minutes, to guard against replay.

    The body's `event_id` equals the `svix-id` without its `msg_` prefix, so you
    can

    use either to deduplicate redelivered events.


    ## Request IDs


    Every response carries an `X-Request-Id` header (also surfaced in

    `meta.request_id`). Include the value when reporting issues — it scopes

    backend logs to your specific request.


    You may also send your own `X-Request-Id` header. Values matching

    `^[A-Za-z0-9_-]{1,128}$` are honored verbatim; anything else is replaced
    with

    a generated id.


    ## Versioning


    Public endpoints are versioned under `/v1/`. Breaking changes ship under a
    new

    major version; additive changes (new fields, new endpoints) ship under the

    existing version.
  contact:
    name: Paystack Cross-Border
    url: https://globalstack.io
servers:
  - url: https://api.globalstack.io
    description: Production
security:
  - BearerAuth: []
tags:
  - name: Supported Countries
  - name: Supported Currencies
  - name: Customers
  - name: Wallets
  - name: Beneficiaries
  - name: Quotes
  - name: Onramps
  - name: Offramps
  - name: Conversions
  - name: Transfers
  - name: Transactions
  - name: Notification Webhooks
  - name: Me
paths:
  /v1/offramps/{offrampId}:
    get:
      tags:
        - Offramps
      summary: Fetch an offramp
      description: >
        Fetches a single offramp by its external id (prefixed `ofr_`).


        ### Path parameter


        - `id` — required. The offramp's external id (e.g.
        `ofr_01KPBH887CCT3A53EW3F8R0VQG`).
          A value that is not a valid `ofr_…` id returns `400`. An id that does not exist returns `404`.

        ### Example


        ```

        GET /v1/offramps/ofr_01KPBH887CCT3A53EW3F8R0VQG

        ```
      operationId: OfframpController.getOfframp
      parameters:
        - in: path
          name: offrampId
          required: true
          schema:
            pattern: '[^\/#\?]+?'
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiSuccessEnvelope'
                  - type: object
                    required:
                      - data
                      - meta
                    properties:
                      message:
                        type: string
                        example: Offramp fetched successfully
                      data:
                        $ref: '#/components/schemas/OfframpResponse'
                      meta:
                        $ref: '#/components/schemas/ApiResponseMetaSchema'
          description: Offramp fetched successfully
        '400':
          description: The id path segment is not a valid ofr_… id
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiErrorEnvelope'
                  - type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - invalid_input
        '401':
          description: Unauthorized — invalid or missing API key
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiErrorEnvelope'
                  - type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - authentication_failed
        '404':
          description: Offramp not found, or it belongs to a different integration
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiErrorEnvelope'
                  - type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - not_found
components:
  schemas:
    ApiSuccessEnvelope:
      properties:
        status:
          type: boolean
          enum:
            - true
          example: true
        message:
          type: string
          description: Human-readable summary
          example: Resource fetched successfully
        code:
          type: string
          enum:
            - ok
          example: ok
      type: object
      required:
        - status
        - message
        - code
    OfframpResponse:
      properties:
        id:
          type: string
          description: Offramp external id (prefixed ofr_).
          example: ofr_01KPBH887CCT3A53EW3F8R0VQG
        reference:
          type: string
          example: INV-2026-001
        status:
          type: string
          enum:
            - created
            - processing
            - temporary_failure
            - success
            - failed
            - returned
          example: created
        retry_on_failure:
          type: boolean
          description: Whether the payout retries on a temporary failure.
          example: false
        quote_id:
          type: string
          description: Originating quote external id (prefixed quo_).
          example: quo_01KPBK123456789ABCDEFG
        rate_source:
          type: string
          description: Rate source; 'quoted' when executed from a quote.
          example: quoted
        customer:
          $ref: '#/components/schemas/OfframpCustomerResponse'
        wallet:
          $ref: '#/components/schemas/OfframpWalletResponse'
        beneficiary:
          $ref: '#/components/schemas/BeneficiaryResponse'
        narration:
          type: string
          nullable: true
          example: Payment for Invoice INV-2026-001
        payment_instrument:
          $ref: '#/components/schemas/PaymentInstrumentResponse'
        source_amount:
          type: string
          description: Source amount, formatted to the source currency precision.
          example: '1.000000'
        source_currency:
          type: string
          example: USDC
        destination_amount:
          type: string
          nullable: true
          description: >-
            Destination amount, formatted to the destination currency precision.
            Null on rows where FX Engine has not yet supplied final economics.
          example: '0.00'
        destination_currency:
          type: string
          example: NGN
        rate:
          type: string
          description: Exchange rate (destination per source), 6 dp.
          example: '0.000000'
        rate_locked_until:
          type: string
          format: date-time
          description: Quote expiry; the window the rate is locked for.
          example: '2026-04-16T16:46:07.000Z'
        failure_reason:
          type: string
          nullable: true
          description: Stable machine-readable failure code; null unless failed.
          example: null
        failure_reason_message:
          type: string
          nullable: true
          description: Human-readable failure explanation; null unless failed.
          example: null
        metadata:
          type: object
          description: Merchant-supplied opaque metadata.
          additionalProperties:
            type: string
          example: {}
        created_at:
          type: string
          format: date-time
          example: '2026-04-16T16:16:12.000Z'
        updated_at:
          type: string
          format: date-time
          example: '2026-04-16T16:16:13.000Z'
      type: object
      required:
        - id
        - reference
        - status
        - retry_on_failure
        - quote_id
        - rate_source
        - customer
        - wallet
        - beneficiary
        - payment_instrument
        - source_amount
        - source_currency
        - destination_currency
        - rate
        - rate_locked_until
        - metadata
        - created_at
        - updated_at
    ApiResponseMetaSchema:
      properties:
        request_id:
          type: string
          description: ULID-prefixed identifier for this request
          example: req_01HXYZ4K5ABCDEFGHJKLMNPQRS
        timestamp:
          type: string
          format: date-time
          example: '2026-05-14T15:43:55.732Z'
        version:
          type: string
          description: Major API version parsed from /vN/
          example: '1'
      type: object
      required:
        - request_id
        - timestamp
        - version
    ApiErrorEnvelope:
      properties:
        status:
          type: boolean
          enum:
            - false
          example: false
        message:
          type: string
          description: Human-readable failure summary
          example: Resource not found
        code:
          type: string
          description: Stable error code for branching logic
          example: not_found
        data:
          type: object
          nullable: true
          example: null
        meta:
          $ref: '#/components/schemas/ApiErrorMetaSchema'
      type: object
      required:
        - status
        - message
        - code
        - data
        - meta
    OfframpCustomerResponse:
      properties:
        id:
          type: string
          example: cust_seed_alice
        type:
          type: string
          enum:
            - individual
            - business
          example: individual
        name:
          type: string
          example: Alice Johnson
        email:
          type: string
          format: email
          example: alice.seed@globalstack.mock
        tier:
          type: string
          enum:
            - tier_0
            - tier_1
            - tier_2
          example: tier_2
        created_at:
          type: string
          format: date-time
          example: '2026-04-16T16:14:08.000Z'
        updated_at:
          type: string
          format: date-time
          example: '2026-04-16T16:14:08.000Z'
      type: object
      required:
        - id
        - type
        - name
        - email
        - tier
        - created_at
        - updated_at
    OfframpWalletResponse:
      properties:
        id:
          type: string
          description: Source wallet external id (prefixed wal_).
          example: wal_seed_alice_usdc
        currency:
          type: string
          example: USDC
        label:
          type: string
          nullable: true
          example: USDC Wallet
      type: object
      required:
        - id
        - currency
    BeneficiaryResponse:
      properties:
        id:
          type: string
          description: GlobalStack beneficiary external id (prefixed ben_).
          example: ben_01KPBAP7WTDKQKW5B3R31VPNX4
        customer_id:
          type: string
          description: External id of the customer this beneficiary belongs to.
          example: cust_01HXYZABC1234567890ABCDEFG
        name:
          type: string
          description: Display name
          example: Alice Bank Beneficiary
        label:
          type: string
          nullable: true
          example: Alice's salary account
        type:
          enum:
            - fiat
            - crypto
          type: string
          example: fiat
        currency:
          type: string
          description: Uppercase currency code
          example: NGN
        merchant_reference:
          type: string
          nullable: true
          description: >-
            Caller-supplied or auto-generated identifier (ref_…) unique per
            integration.
          example: ref_01HXYZ4K5ABCDEFGHJKLMNPQRS
        details:
          type: object
          description: >-
            Type-specific payout details. Fiat:
            country+network+account+provider. Crypto: chain+address.
          oneOf:
            - $ref: '#/components/schemas/BeneficiaryFiatDetailsResponse'
            - $ref: '#/components/schemas/BeneficiaryCryptoDetailsResponse'
        metadata:
          type: object
          description: Merchant-supplied opaque metadata. Values are stored as strings.
          example: {}
          additionalProperties:
            type: string
        status:
          enum:
            - pending
            - active
            - archived
          type: string
          example: pending
        created_at:
          type: string
          format: date-time
          example: '2026-04-16T16:14:08.000Z'
        updated_at:
          type: string
          format: date-time
          example: '2026-04-16T16:14:08.000Z'
      type: object
      required:
        - id
        - customer_id
        - name
        - type
        - currency
        - details
        - metadata
        - status
        - created_at
        - updated_at
    PaymentInstrumentResponse:
      properties:
        id:
          type: string
          description: Synthesized payment instrument id (prefixed pay_).
          example: pay_01KPBH895W6PH3WY1D9KZH3M5D
        beneficiary_id:
          type: string
          example: ben_seed_alice_bank
        type:
          type: string
          enum:
            - bank_account
            - mobile_money
          example: bank_account
        country_code:
          type: string
          example: NG
        provider:
          $ref: '#/components/schemas/PaymentInstrumentProviderResponse'
        account_name:
          type: string
          example: SEED BANK BENEFICIARY
        account_number:
          type: string
          example: '0039415616'
      type: object
      required:
        - id
        - beneficiary_id
        - type
        - country_code
        - provider
        - account_name
        - account_number
    ApiErrorMetaSchema:
      properties:
        next_steps:
          $ref: '#/components/schemas/NextStepsSchema'
        request_id:
          type: string
          description: ULID-prefixed identifier for this request
          example: req_01HXYZ4K5ABCDEFGHJKLMNPQRS
        timestamp:
          type: string
          format: date-time
          example: '2026-05-14T15:43:55.732Z'
        version:
          type: string
          description: Major API version parsed from /vN/
          example: '1'
      type: object
      required:
        - next_steps
        - request_id
        - timestamp
        - version
    BeneficiaryFiatDetailsResponse:
      properties:
        country_code:
          type: string
          description: ISO 3166-1 alpha-2 country
          example: NG
        network:
          type: string
          enum:
            - bank
            - mobile_money
          example: bank
        account_number:
          type: string
          example: '0039415616'
        account_name:
          type: string
          nullable: true
          example: ALICE JOHNSON
        provider:
          $ref: '#/components/schemas/BeneficiaryFiatProviderResponse'
      type: object
      required:
        - country_code
        - network
        - account_number
        - provider
    BeneficiaryCryptoDetailsResponse:
      properties:
        network:
          enum:
            - solana
            - base
            - ethereum
          type: string
          example: solana
        address:
          type: string
          example: 9wFFa...
      type: object
      required:
        - network
        - address
    PaymentInstrumentProviderResponse:
      properties:
        id:
          type: string
          example: prov_01KPBAP7WTDKQKW5B3R31VPNX4
        name:
          type: string
          example: Access Bank
        code:
          type: string
          example: '000014'
      type: object
      required:
        - id
        - name
        - code
    NextStepsSchema:
      properties:
        action:
          type: string
          description: Suggested action for the caller
          example: Verify the resource identifier and retry.
        docs_url:
          type: string
          format: uri
          example: https://docs.globalstack.io/errors#not_found
      type: object
      required:
        - action
        - docs_url
    BeneficiaryFiatProviderResponse:
      properties:
        id:
          type: string
          description: GlobalStack provider id
          example: prov_01KPBAP7WTDKQKW5B3R31VPNX4
        name:
          type: string
          example: Access Bank
        code:
          type: string
          description: Upstream provider code (may be null in source).
          example: '000014'
      type: object
      required:
        - id
        - name
        - code
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: API key issued during merchant onboarding.

````