Initiate a crypto ramp

curl --request POST \
  --url https://prod-api.pcxpay.com/v1/payments-init/ramp \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <x-api-key>' \
  --data '
{
  "user_id": "<string>",
  "org_id": "<string>",
  "fiat_currency": "NGN",
  "fiat_amount": 10000,
  "client_rate": 0.00000645,
  "crypto_currency": "USDC",
  "crypto_network": "ethereum",
  "country": "NG",
  "payer_details": {
    "email": "jane@example.com",
    "name": "Jane Kamau",
    "phone": "+2348122603628"
  },
  "customer_type": "retail",
  "business_id": "<string>",
  "business_name": "<string>",
  "wallet_address": "0xABC123...your-wallet-address",
  "mobile_money_details": {
    "provider": "MTN",
    "phone_number": "+2348122603628"
  },
  "bank_details": {
    "account_number": "<string>",
    "bank_code": "<string>",
    "bank_name": "<string>"
  },
  "beneficiary_id": "<string>",
  "beneficiary_name": "<string>",
  "destination": {
    "accountNumber": "<string>",
    "bankCode": "<string>",
    "bankName": "<string>"
  },
  "metadata": {}
}
'

{
  "statusCode": 200,
  "response": {
    "success": true,
    "payment_id": "ea5965e4-1432-40ef-bccf-cb51455a935a",
    "transaction_id": "2a679c96-69bf-424c-89cb-c2f4a90a2738",
    "status": "pending",
    "fiat_currency": "NGN",
    "fiat_amount": 10000,
    "crypto_currency": "USDC",
    "crypto_network": "ethereum",
    "crypto_amount": 6.45,
    "expires_at": "2023-11-07T05:31:56Z",
    "next_action": "make_transfer",
    "payment_instructions": {
      "type": "bank_transfer",
      "account_name": "PCX Collections",
      "account_number": "0123456789",
      "bank_name": "Access Bank",
      "amount": 10000,
      "currency": "NGN",
      "reference": "PCX-ea5965e4"
    }
  }
}

Payment Initiation

Initiate a crypto ramp

Initiate an on-ramp (fiat → crypto) or off-ramp (crypto → fiat) conversion. PCX acts as the orchestrator — your users send or receive fiat, and PCX handles the crypto settlement automatically.

On-ramp: the customer pays in fiat using their preferred payment method. Once the fiat collection is confirmed, the crypto is settled directly to the wallet_address you provide. No further action is needed after a successful initiation.

Off-ramp: the customer sends crypto and receives fiat to a registered beneficiary’s bank or mobile money account.

You must fetch a fresh rate from GET /organizations/admin/exchange-rate immediately before presenting it to the user and before submitting this request. The rate must be fetched in the same direction the funds flow — fromCurrency=fiat&toCurrency=crypto for on_ramp, and fromCurrency=crypto&toCurrency=fiat for off_ramp. The client_rate you send is validated against the current live rate for that direction — if it has drifted more than 0.5% (or was fetched in the wrong direction), the request is rejected with RATE_STALE and you must re-fetch.

POST

payments-init

ramp

Initiate a crypto ramp

curl --request POST \
  --url https://prod-api.pcxpay.com/v1/payments-init/ramp \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <x-api-key>' \
  --data '
{
  "user_id": "<string>",
  "org_id": "<string>",
  "fiat_currency": "NGN",
  "fiat_amount": 10000,
  "client_rate": 0.00000645,
  "crypto_currency": "USDC",
  "crypto_network": "ethereum",
  "country": "NG",
  "payer_details": {
    "email": "jane@example.com",
    "name": "Jane Kamau",
    "phone": "+2348122603628"
  },
  "customer_type": "retail",
  "business_id": "<string>",
  "business_name": "<string>",
  "wallet_address": "0xABC123...your-wallet-address",
  "mobile_money_details": {
    "provider": "MTN",
    "phone_number": "+2348122603628"
  },
  "bank_details": {
    "account_number": "<string>",
    "bank_code": "<string>",
    "bank_name": "<string>"
  },
  "beneficiary_id": "<string>",
  "beneficiary_name": "<string>",
  "destination": {
    "accountNumber": "<string>",
    "bankCode": "<string>",
    "bankName": "<string>"
  },
  "metadata": {}
}
'

{
  "statusCode": 200,
  "response": {
    "success": true,
    "payment_id": "ea5965e4-1432-40ef-bccf-cb51455a935a",
    "transaction_id": "2a679c96-69bf-424c-89cb-c2f4a90a2738",
    "status": "pending",
    "fiat_currency": "NGN",
    "fiat_amount": 10000,
    "crypto_currency": "USDC",
    "crypto_network": "ethereum",
    "crypto_amount": 6.45,
    "expires_at": "2023-11-07T05:31:56Z",
    "next_action": "make_transfer",
    "payment_instructions": {
      "type": "bank_transfer",
      "account_name": "PCX Collections",
      "account_number": "0123456789",
      "bank_name": "Access Bank",
      "amount": 10000,
      "currency": "NGN",
      "reference": "PCX-ea5965e4"
    }
  }
}

Headers

Authorization

string

default:NONE

required

Bearer JWT for user-facing flows (Bearer eyJraWQ...), or the literal string NONE when authenticating via API key.

Example:

"Bearer eyJraWQ..."

X-Api-Key

string

default:NONE

required

API key for server-to-server flows, or the literal string NONE when authenticating via JWT.

Example:

"pcx_abc123_xxxx"

Body

application/json

direction

enum<string>

required

on_ramp — customer pays fiat, receives crypto to wallet_address. off_ramp — customer sends crypto, receives fiat to beneficiary.

Available options:

on_ramp,

off_ramp

user_id

string

required

ID of the initiating user.

org_id

string

required

Your organisation ID.

fiat_currency

string

required

ISO 4217 fiat currency code (e.g. NGN, KES, GHS).

Example:

"NGN"

fiat_amount

number<float>

required

Amount in fiat currency — what the customer pays (on-ramp) or receives (off-ramp).

Example:

10000

client_rate

number<float>

required

The rate you fetched from GET /organizations/admin/exchange-rate and showed to the user. Validated against the current live rate on submission — must be within 0.5% or the request is rejected with RATE_STALE.

Example:

0.00000645

crypto_currency

string

required

Crypto asset code (e.g. USDC, USDT, EURC, BTC, ETH).

Example:

"USDC"

crypto_network

string

required

Blockchain network (e.g. ethereum, polygon, tron).

Example:

"ethereum"

payment_method

enum<string>

required

Fiat payment method.

Available options:

mobile_money,

bank_transfer

country

string

required

ISO alpha-2 country code of the fiat side (e.g. NG, KE).

Example:

"NG"

payer_details

object

required

Show child attributes

customer_type

enum<string>

default:retail

Use institution for business customers. Requires business_id and business_name.

Available options:

retail,

institution

business_id

string

Required when customer_type is institution.

business_name

string

Required when customer_type is institution.

wallet_address

string

On-ramp only. The destination crypto wallet address. PCX settles crypto here directly after fiat collection.

Example:

"0xABC123...your-wallet-address"

mobile_money_details

object

Required for mobile_money payment method.

Show child attributes

bank_details

object

On-ramp bank transfer — payer's source bank account.

Show child attributes

beneficiary_id

string

Off-ramp only. ID of the registered beneficiary receiving the fiat payout.

beneficiary_name

string

Off-ramp only. Full name of the beneficiary.

destination

object

Off-ramp only. Destination routing details for the fiat payout.

Show child attributes

metadata

object

Arbitrary key-value pairs included in webhook payloads.

Response

Ramp initiated successfully

statusCode

integer

Example:

200

response

object

Show child attributes

⌘I