Execute a conversion

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

{
  "status": true,
  "message": "Conversion executed successfully",
  "code": "ok",
  "data": {
    "id": "con_01KPBH8MD6R7YDJ82T4D6M3V1T",
    "reference": "INV-2026-001",
    "status": "created",
    "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"
    },
    "source_wallet": {
      "id": "wal_seed_alice_usdc",
      "currency": "USDC",
      "label": "USDC Wallet"
    },
    "destination_wallet": {
      "id": "wal_seed_alice_usdc",
      "currency": "USDC",
      "label": "USDC Wallet"
    },
    "source_amount": "1.000000",
    "source_currency": "USDC",
    "destination_currency": "NGN",
    "rate": "0.000000",
    "metadata": {
      "payout_batch": "batch_001"
    },
    "created_at": "2026-04-16T16:16:24.000Z",
    "updated_at": "2026-04-16T16:16:26.000Z",
    "destination_amount": "0.00",
    "failure_reason": null
  },
  "meta": {
    "request_id": "req_01HXYZ4K5ABCDEFGHJKLMNPQRS",
    "timestamp": "2026-05-14T15:43:55.732Z",
    "version": "1"
  }
}

Conversions

Execute a conversion

Execute a conversion from a previously created conversion quote: converts the balance of the quote’s source wallet into the quote’s destination wallet.

Supply the quote_id returned by POST /v1/conversions/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. reference is required and must be unique within your integration.

The quote must belong to the calling integration, be of type conversion, and be unexpired. 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. A given quote can be executed at most once.

Note: rate and destination_amount are placeholders in the current release and will be populated once FX Engine conversion execution lands.

POST

conversions

Execute a conversion

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

{
  "status": true,
  "message": "Conversion executed successfully",
  "code": "ok",
  "data": {
    "id": "con_01KPBH8MD6R7YDJ82T4D6M3V1T",
    "reference": "INV-2026-001",
    "status": "created",
    "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"
    },
    "source_wallet": {
      "id": "wal_seed_alice_usdc",
      "currency": "USDC",
      "label": "USDC Wallet"
    },
    "destination_wallet": {
      "id": "wal_seed_alice_usdc",
      "currency": "USDC",
      "label": "USDC Wallet"
    },
    "source_amount": "1.000000",
    "source_currency": "USDC",
    "destination_currency": "NGN",
    "rate": "0.000000",
    "metadata": {
      "payout_batch": "batch_001"
    },
    "created_at": "2026-04-16T16:16:24.000Z",
    "updated_at": "2026-04-16T16:16:26.000Z",
    "destination_amount": "0.00",
    "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

ExecuteConversionDto

quote_id

string

required

Maximum string length: 64

reference

string

required

Maximum string length: 128

source_currency

string

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

destination_currency

string

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

metadata

object

Response

Conversion executed successfully

status

enum<boolean>

required

Available options:

true

Example:

true

message

string

required

Human-readable summary

Example:

"Conversion executed successfully"

code

enum<string>

required

Available options:

ok

Example:

"ok"

data

object

required

Show child attributes