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": {}
}
'

import requests

url = "https://prod-api.pcxpay.com/v1/payments-init/ramp"

payload = {
    "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": {}
}
headers = {
    "Authorization": "<authorization>",
    "X-Api-Key": "<x-api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    Authorization: '<authorization>',
    'X-Api-Key': '<x-api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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: {}
  })
};

fetch('https://prod-api.pcxpay.com/v1/payments-init/ramp', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://prod-api.pcxpay.com/v1/payments-init/ramp",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: application/json",
    "X-Api-Key: <x-api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://prod-api.pcxpay.com/v1/payments-init/ramp"

	payload := strings.NewReader("{\n  \"user_id\": \"<string>\",\n  \"org_id\": \"<string>\",\n  \"fiat_currency\": \"NGN\",\n  \"fiat_amount\": 10000,\n  \"client_rate\": 0.00000645,\n  \"crypto_currency\": \"USDC\",\n  \"crypto_network\": \"ethereum\",\n  \"country\": \"NG\",\n  \"payer_details\": {\n    \"email\": \"jane@example.com\",\n    \"name\": \"Jane Kamau\",\n    \"phone\": \"+2348122603628\"\n  },\n  \"customer_type\": \"retail\",\n  \"business_id\": \"<string>\",\n  \"business_name\": \"<string>\",\n  \"wallet_address\": \"0xABC123...your-wallet-address\",\n  \"mobile_money_details\": {\n    \"provider\": \"MTN\",\n    \"phone_number\": \"+2348122603628\"\n  },\n  \"bank_details\": {\n    \"account_number\": \"<string>\",\n    \"bank_code\": \"<string>\",\n    \"bank_name\": \"<string>\"\n  },\n  \"beneficiary_id\": \"<string>\",\n  \"beneficiary_name\": \"<string>\",\n  \"destination\": {\n    \"accountNumber\": \"<string>\",\n    \"bankCode\": \"<string>\",\n    \"bankName\": \"<string>\"\n  },\n  \"metadata\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("X-Api-Key", "<x-api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

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

require 'uri'
require 'net/http'

url = URI("https://prod-api.pcxpay.com/v1/payments-init/ramp")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["X-Api-Key"] = '<x-api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"user_id\": \"<string>\",\n  \"org_id\": \"<string>\",\n  \"fiat_currency\": \"NGN\",\n  \"fiat_amount\": 10000,\n  \"client_rate\": 0.00000645,\n  \"crypto_currency\": \"USDC\",\n  \"crypto_network\": \"ethereum\",\n  \"country\": \"NG\",\n  \"payer_details\": {\n    \"email\": \"jane@example.com\",\n    \"name\": \"Jane Kamau\",\n    \"phone\": \"+2348122603628\"\n  },\n  \"customer_type\": \"retail\",\n  \"business_id\": \"<string>\",\n  \"business_name\": \"<string>\",\n  \"wallet_address\": \"0xABC123...your-wallet-address\",\n  \"mobile_money_details\": {\n    \"provider\": \"MTN\",\n    \"phone_number\": \"+2348122603628\"\n  },\n  \"bank_details\": {\n    \"account_number\": \"<string>\",\n    \"bank_code\": \"<string>\",\n    \"bank_name\": \"<string>\"\n  },\n  \"beneficiary_id\": \"<string>\",\n  \"beneficiary_name\": \"<string>\",\n  \"destination\": {\n    \"accountNumber\": \"<string>\",\n    \"bankCode\": \"<string>\",\n    \"bankName\": \"<string>\"\n  },\n  \"metadata\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "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"
    }
  }
}

{
  "message": "<string>",
  "status": "error"
}

{
  "message": "<string>",
  "status": "error"
}

{
  "statusCode": 422,
  "error": "RATE_STALE",
  "message": "Rate has drifted. Please re-fetch the exchange rate."
}

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": {}
}
'

import requests

url = "https://prod-api.pcxpay.com/v1/payments-init/ramp"

payload = {
    "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": {}
}
headers = {
    "Authorization": "<authorization>",
    "X-Api-Key": "<x-api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    Authorization: '<authorization>',
    'X-Api-Key': '<x-api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    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: {}
  })
};

fetch('https://prod-api.pcxpay.com/v1/payments-init/ramp', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://prod-api.pcxpay.com/v1/payments-init/ramp",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <authorization>",
    "Content-Type: application/json",
    "X-Api-Key: <x-api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://prod-api.pcxpay.com/v1/payments-init/ramp"

	payload := strings.NewReader("{\n  \"user_id\": \"<string>\",\n  \"org_id\": \"<string>\",\n  \"fiat_currency\": \"NGN\",\n  \"fiat_amount\": 10000,\n  \"client_rate\": 0.00000645,\n  \"crypto_currency\": \"USDC\",\n  \"crypto_network\": \"ethereum\",\n  \"country\": \"NG\",\n  \"payer_details\": {\n    \"email\": \"jane@example.com\",\n    \"name\": \"Jane Kamau\",\n    \"phone\": \"+2348122603628\"\n  },\n  \"customer_type\": \"retail\",\n  \"business_id\": \"<string>\",\n  \"business_name\": \"<string>\",\n  \"wallet_address\": \"0xABC123...your-wallet-address\",\n  \"mobile_money_details\": {\n    \"provider\": \"MTN\",\n    \"phone_number\": \"+2348122603628\"\n  },\n  \"bank_details\": {\n    \"account_number\": \"<string>\",\n    \"bank_code\": \"<string>\",\n    \"bank_name\": \"<string>\"\n  },\n  \"beneficiary_id\": \"<string>\",\n  \"beneficiary_name\": \"<string>\",\n  \"destination\": {\n    \"accountNumber\": \"<string>\",\n    \"bankCode\": \"<string>\",\n    \"bankName\": \"<string>\"\n  },\n  \"metadata\": {}\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<authorization>")
	req.Header.Add("X-Api-Key", "<x-api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

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

require 'uri'
require 'net/http'

url = URI("https://prod-api.pcxpay.com/v1/payments-init/ramp")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<authorization>'
request["X-Api-Key"] = '<x-api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"user_id\": \"<string>\",\n  \"org_id\": \"<string>\",\n  \"fiat_currency\": \"NGN\",\n  \"fiat_amount\": 10000,\n  \"client_rate\": 0.00000645,\n  \"crypto_currency\": \"USDC\",\n  \"crypto_network\": \"ethereum\",\n  \"country\": \"NG\",\n  \"payer_details\": {\n    \"email\": \"jane@example.com\",\n    \"name\": \"Jane Kamau\",\n    \"phone\": \"+2348122603628\"\n  },\n  \"customer_type\": \"retail\",\n  \"business_id\": \"<string>\",\n  \"business_name\": \"<string>\",\n  \"wallet_address\": \"0xABC123...your-wallet-address\",\n  \"mobile_money_details\": {\n    \"provider\": \"MTN\",\n    \"phone_number\": \"+2348122603628\"\n  },\n  \"bank_details\": {\n    \"account_number\": \"<string>\",\n    \"bank_code\": \"<string>\",\n    \"bank_name\": \"<string>\"\n  },\n  \"beneficiary_id\": \"<string>\",\n  \"beneficiary_name\": \"<string>\",\n  \"destination\": {\n    \"accountNumber\": \"<string>\",\n    \"bankCode\": \"<string>\",\n    \"bankName\": \"<string>\"\n  },\n  \"metadata\": {}\n}"

response = http.request(request)
puts response.read_body

{
  "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"
    }
  }
}

{
  "message": "<string>",
  "status": "error"
}

{
  "message": "<string>",
  "status": "error"
}

{
  "statusCode": 422,
  "error": "RATE_STALE",
  "message": "Rate has drifted. Please re-fetch the exchange rate."
}

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