Execute an onramp

curl --request POST \
  --url https://api.paystack.com/v1/onramps \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "quote_id": "<string>",
  "source_currency": "<string>",
  "destination_currency": "<string>",
  "reference": "<string>",
  "metadata": {}
}
'

{
  "status": true,
  "message": "Onramp executed successfully",
  "code": "ok",
  "data": {
    "id": "onr_01KPBH802PXQQXT8ASJGE0QX2K",
    "reference": "INV-2026-001",
    "status": "awaiting_deposit",
    "quote_id": "quo_01KPBK123456789ABCDEFG",
    "rate_source": "quoted",
    "customer": {
      "id": "cust_seed_alice",
      "type": "individual",
      "name": "Alice Johnson",
      "email": "alice.seed@globalstack.mock",
      "tier": "tier_2",
      "created_at": "2026-04-16T16:14:08.000Z",
      "updated_at": "2026-04-16T16:14:08.000Z"
    },
    "wallet": {
      "id": "wal_seed_alice_usdc",
      "currency": "USDC",
      "label": "USDC Wallet"
    },
    "source_amount": "10000.00",
    "source_currency": "NGN",
    "destination_currency": "USDC",
    "rate": "0.000000",
    "deposit_instruction": {
      "version": 1,
      "type": "fiat",
      "accountName": "GLOBALSTACK / FX ENGINE",
      "accountNumber": "0123456789",
      "bankName": "Access Bank",
      "bankCode": "000014",
      "expiresAt": "2026-06-03T16:14:08.000Z"
    },
    "metadata": {
      "order_id": "ord_demo_001"
    },
    "created_at": "2026-04-16T16:16:03.000Z",
    "updated_at": "2026-04-16T16:16:03.000Z",
    "payment_instrument": null,
    "destination_amount": "0.000000",
    "rate_locked_until": null,
    "failure_reason": null
  },
  "meta": {
    "request_id": "req_01HXYZ4K5ABCDEFGHJKLMNPQRS",
    "timestamp": "2026-05-14T15:43:55.732Z",
    "version": "1"
  }
}

Onramps

Execute an onramp

Execute an onramp from a previously created onramp quote to convert external fiat into crypto in a GlobalStack wallet.

Supply the quote_id returned by POST /v1/onramps/quotes. source_currency and destination_currency are optional; when provided they must match the quote’s currencies exactly, otherwise the request is rejected with 400 invalid_input.

An expired quote returns 409 invalid_status.

Send an Idempotency-Key header to make retries safe: an identical key with an identical body within 24h replays the original response.

POST

onramps

Execute an onramp

curl --request POST \
  --url https://api.paystack.com/v1/onramps \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "quote_id": "<string>",
  "source_currency": "<string>",
  "destination_currency": "<string>",
  "reference": "<string>",
  "metadata": {}
}
'

{
  "status": true,
  "message": "Onramp executed successfully",
  "code": "ok",
  "data": {
    "id": "onr_01KPBH802PXQQXT8ASJGE0QX2K",
    "reference": "INV-2026-001",
    "status": "awaiting_deposit",
    "quote_id": "quo_01KPBK123456789ABCDEFG",
    "rate_source": "quoted",
    "customer": {
      "id": "cust_seed_alice",
      "type": "individual",
      "name": "Alice Johnson",
      "email": "alice.seed@globalstack.mock",
      "tier": "tier_2",
      "created_at": "2026-04-16T16:14:08.000Z",
      "updated_at": "2026-04-16T16:14:08.000Z"
    },
    "wallet": {
      "id": "wal_seed_alice_usdc",
      "currency": "USDC",
      "label": "USDC Wallet"
    },
    "source_amount": "10000.00",
    "source_currency": "NGN",
    "destination_currency": "USDC",
    "rate": "0.000000",
    "deposit_instruction": {
      "version": 1,
      "type": "fiat",
      "accountName": "GLOBALSTACK / FX ENGINE",
      "accountNumber": "0123456789",
      "bankName": "Access Bank",
      "bankCode": "000014",
      "expiresAt": "2026-06-03T16:14:08.000Z"
    },
    "metadata": {
      "order_id": "ord_demo_001"
    },
    "created_at": "2026-04-16T16:16:03.000Z",
    "updated_at": "2026-04-16T16:16:03.000Z",
    "payment_instrument": null,
    "destination_amount": "0.000000",
    "rate_locked_until": null,
    "failure_reason": null
  },
  "meta": {
    "request_id": "req_01HXYZ4K5ABCDEFGHJKLMNPQRS",
    "timestamp": "2026-05-14T15:43:55.732Z",
    "version": "1"
  }
}

Authorizations

Authorization

string

header

required

API key issued during merchant onboarding.

Headers

Idempotency-Key

string

Optional client-supplied key. Identical key + identical body within 24h replays the original response. Identical key + different body returns 409 idempotency_conflict. The hash is over raw bytes — clients retrying must send the byte-identical body; a re-serialised JSON payload will produce a different hash and a 409. Strongly recommended for retry-safe clients.

Pattern: ^[A-Za-z0-9_\-]{8,255}$

Body

application/json

ExecuteOnrampDto

quote_id

string

required

Maximum string length: 64

source_currency

string

Pattern: ^[A-Z0-9]{2,8}$

destination_currency

string

Pattern: ^[A-Z0-9]{2,8}$

reference

string

Maximum string length: 128

metadata

object

Response

Onramp executed successfully

status

enum<boolean>

required

Available options:

true

Example:

true

message

string

required

Human-readable summary

Example:

"Onramp executed successfully"

code

enum<string>

required

Available options:

ok

Example:

"ok"

data

object

required

Show child attributes