Initiate a payment

curl --request POST \
  --url https://prod-api.pcxpay.com/v1/payments-init/initiate \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <x-api-key>' \
  --data '
{
  "amount": 123,
  "target_amount": 123,
  "currency": "NGN",
  "target_currency": "KES",
  "user_id": "<string>",
  "org_id": "<string>",
  "country": "NG",
  "org_rate_id": "<string>",
  "client_reference": "<string>",
  "description": "<string>",
  "payer_details": {
    "name": "<string>",
    "email": "jsmith@example.com",
    "phone": "<string>"
  },
  "mobile_money_details": {
    "provider": "Mobile Wallet (M-PESA)",
    "phone_number": "<string>"
  },
  "card_details": {
    "card_number": "<string>",
    "expiry_month": "<string>",
    "expiry_year": "<string>",
    "cvv": "<string>",
    "card_holder_name": "<string>"
  },
  "bank_details": {
    "account_name": "<string>",
    "account_number": "<string>",
    "bank_name": "<string>",
    "country": "<string>",
    "bank_code": "<string>"
  },
  "bank_account": {
    "account_number": "<string>",
    "bank_code": "<string>",
    "bank_name": "<string>"
  },
  "beneficiary_id": "<string>",
  "return_url": "<string>",
  "metadata": {}
}
'

import requests

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

payload = {
    "amount": 123,
    "target_amount": 123,
    "currency": "NGN",
    "target_currency": "KES",
    "user_id": "<string>",
    "org_id": "<string>",
    "country": "NG",
    "org_rate_id": "<string>",
    "client_reference": "<string>",
    "description": "<string>",
    "payer_details": {
        "name": "<string>",
        "email": "jsmith@example.com",
        "phone": "<string>"
    },
    "mobile_money_details": {
        "provider": "Mobile Wallet (M-PESA)",
        "phone_number": "<string>"
    },
    "card_details": {
        "card_number": "<string>",
        "expiry_month": "<string>",
        "expiry_year": "<string>",
        "cvv": "<string>",
        "card_holder_name": "<string>"
    },
    "bank_details": {
        "account_name": "<string>",
        "account_number": "<string>",
        "bank_name": "<string>",
        "country": "<string>",
        "bank_code": "<string>"
    },
    "bank_account": {
        "account_number": "<string>",
        "bank_code": "<string>",
        "bank_name": "<string>"
    },
    "beneficiary_id": "<string>",
    "return_url": "<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({
    amount: 123,
    target_amount: 123,
    currency: 'NGN',
    target_currency: 'KES',
    user_id: '<string>',
    org_id: '<string>',
    country: 'NG',
    org_rate_id: '<string>',
    client_reference: '<string>',
    description: '<string>',
    payer_details: {name: '<string>', email: 'jsmith@example.com', phone: '<string>'},
    mobile_money_details: {provider: 'Mobile Wallet (M-PESA)', phone_number: '<string>'},
    card_details: {
      card_number: '<string>',
      expiry_month: '<string>',
      expiry_year: '<string>',
      cvv: '<string>',
      card_holder_name: '<string>'
    },
    bank_details: {
      account_name: '<string>',
      account_number: '<string>',
      bank_name: '<string>',
      country: '<string>',
      bank_code: '<string>'
    },
    bank_account: {account_number: '<string>', bank_code: '<string>', bank_name: '<string>'},
    beneficiary_id: '<string>',
    return_url: '<string>',
    metadata: {}
  })
};

fetch('https://prod-api.pcxpay.com/v1/payments-init/initiate', 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/initiate",
  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([
    'amount' => 123,
    'target_amount' => 123,
    'currency' => 'NGN',
    'target_currency' => 'KES',
    'user_id' => '<string>',
    'org_id' => '<string>',
    'country' => 'NG',
    'org_rate_id' => '<string>',
    'client_reference' => '<string>',
    'description' => '<string>',
    'payer_details' => [
        'name' => '<string>',
        'email' => 'jsmith@example.com',
        'phone' => '<string>'
    ],
    'mobile_money_details' => [
        'provider' => 'Mobile Wallet (M-PESA)',
        'phone_number' => '<string>'
    ],
    'card_details' => [
        'card_number' => '<string>',
        'expiry_month' => '<string>',
        'expiry_year' => '<string>',
        'cvv' => '<string>',
        'card_holder_name' => '<string>'
    ],
    'bank_details' => [
        'account_name' => '<string>',
        'account_number' => '<string>',
        'bank_name' => '<string>',
        'country' => '<string>',
        'bank_code' => '<string>'
    ],
    'bank_account' => [
        'account_number' => '<string>',
        'bank_code' => '<string>',
        'bank_name' => '<string>'
    ],
    'beneficiary_id' => '<string>',
    'return_url' => '<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/initiate"

	payload := strings.NewReader("{\n  \"amount\": 123,\n  \"target_amount\": 123,\n  \"currency\": \"NGN\",\n  \"target_currency\": \"KES\",\n  \"user_id\": \"<string>\",\n  \"org_id\": \"<string>\",\n  \"country\": \"NG\",\n  \"org_rate_id\": \"<string>\",\n  \"client_reference\": \"<string>\",\n  \"description\": \"<string>\",\n  \"payer_details\": {\n    \"name\": \"<string>\",\n    \"email\": \"jsmith@example.com\",\n    \"phone\": \"<string>\"\n  },\n  \"mobile_money_details\": {\n    \"provider\": \"Mobile Wallet (M-PESA)\",\n    \"phone_number\": \"<string>\"\n  },\n  \"card_details\": {\n    \"card_number\": \"<string>\",\n    \"expiry_month\": \"<string>\",\n    \"expiry_year\": \"<string>\",\n    \"cvv\": \"<string>\",\n    \"card_holder_name\": \"<string>\"\n  },\n  \"bank_details\": {\n    \"account_name\": \"<string>\",\n    \"account_number\": \"<string>\",\n    \"bank_name\": \"<string>\",\n    \"country\": \"<string>\",\n    \"bank_code\": \"<string>\"\n  },\n  \"bank_account\": {\n    \"account_number\": \"<string>\",\n    \"bank_code\": \"<string>\",\n    \"bank_name\": \"<string>\"\n  },\n  \"beneficiary_id\": \"<string>\",\n  \"return_url\": \"<string>\",\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/initiate")
  .header("Authorization", "<authorization>")
  .header("X-Api-Key", "<x-api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": 123,\n  \"target_amount\": 123,\n  \"currency\": \"NGN\",\n  \"target_currency\": \"KES\",\n  \"user_id\": \"<string>\",\n  \"org_id\": \"<string>\",\n  \"country\": \"NG\",\n  \"org_rate_id\": \"<string>\",\n  \"client_reference\": \"<string>\",\n  \"description\": \"<string>\",\n  \"payer_details\": {\n    \"name\": \"<string>\",\n    \"email\": \"jsmith@example.com\",\n    \"phone\": \"<string>\"\n  },\n  \"mobile_money_details\": {\n    \"provider\": \"Mobile Wallet (M-PESA)\",\n    \"phone_number\": \"<string>\"\n  },\n  \"card_details\": {\n    \"card_number\": \"<string>\",\n    \"expiry_month\": \"<string>\",\n    \"expiry_year\": \"<string>\",\n    \"cvv\": \"<string>\",\n    \"card_holder_name\": \"<string>\"\n  },\n  \"bank_details\": {\n    \"account_name\": \"<string>\",\n    \"account_number\": \"<string>\",\n    \"bank_name\": \"<string>\",\n    \"country\": \"<string>\",\n    \"bank_code\": \"<string>\"\n  },\n  \"bank_account\": {\n    \"account_number\": \"<string>\",\n    \"bank_code\": \"<string>\",\n    \"bank_name\": \"<string>\"\n  },\n  \"beneficiary_id\": \"<string>\",\n  \"return_url\": \"<string>\",\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"amount\": 123,\n  \"target_amount\": 123,\n  \"currency\": \"NGN\",\n  \"target_currency\": \"KES\",\n  \"user_id\": \"<string>\",\n  \"org_id\": \"<string>\",\n  \"country\": \"NG\",\n  \"org_rate_id\": \"<string>\",\n  \"client_reference\": \"<string>\",\n  \"description\": \"<string>\",\n  \"payer_details\": {\n    \"name\": \"<string>\",\n    \"email\": \"jsmith@example.com\",\n    \"phone\": \"<string>\"\n  },\n  \"mobile_money_details\": {\n    \"provider\": \"Mobile Wallet (M-PESA)\",\n    \"phone_number\": \"<string>\"\n  },\n  \"card_details\": {\n    \"card_number\": \"<string>\",\n    \"expiry_month\": \"<string>\",\n    \"expiry_year\": \"<string>\",\n    \"cvv\": \"<string>\",\n    \"card_holder_name\": \"<string>\"\n  },\n  \"bank_details\": {\n    \"account_name\": \"<string>\",\n    \"account_number\": \"<string>\",\n    \"bank_name\": \"<string>\",\n    \"country\": \"<string>\",\n    \"bank_code\": \"<string>\"\n  },\n  \"bank_account\": {\n    \"account_number\": \"<string>\",\n    \"bank_code\": \"<string>\",\n    \"bank_name\": \"<string>\"\n  },\n  \"beneficiary_id\": \"<string>\",\n  \"return_url\": \"<string>\",\n  \"metadata\": {}\n}"

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

{
  "statusCode": 200,
  "response": {
    "success": true,
    "payment_id": "<string>",
    "transaction_id": "<string>",
    "status": "<string>",
    "next_action": "redirect",
    "redirect_url": "<string>",
    "provider": "<string>",
    "message": "<string>",
    "payment_data": {
      "amount": 123,
      "currency": "<string>",
      "target_amount": 123,
      "target_currency": "<string>",
      "metadata": {}
    }
  }
}

{
  "error": "<string>",
  "message": "<string>",
  "code": "RATE_MISMATCH"
}

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

{
  "error": "<string>",
  "message": "No routing configuration found for this payment corridor",
  "code": "ROUTING_CONFIG_NOT_FOUND"
}

{
  "error": "<string>",
  "message": "<string>",
  "code": "ALL_PROVIDERS_FAILED"
}

POST

payments-init

initiate

Initiate a payment

curl --request POST \
  --url https://prod-api.pcxpay.com/v1/payments-init/initiate \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <x-api-key>' \
  --data '
{
  "amount": 123,
  "target_amount": 123,
  "currency": "NGN",
  "target_currency": "KES",
  "user_id": "<string>",
  "org_id": "<string>",
  "country": "NG",
  "org_rate_id": "<string>",
  "client_reference": "<string>",
  "description": "<string>",
  "payer_details": {
    "name": "<string>",
    "email": "jsmith@example.com",
    "phone": "<string>"
  },
  "mobile_money_details": {
    "provider": "Mobile Wallet (M-PESA)",
    "phone_number": "<string>"
  },
  "card_details": {
    "card_number": "<string>",
    "expiry_month": "<string>",
    "expiry_year": "<string>",
    "cvv": "<string>",
    "card_holder_name": "<string>"
  },
  "bank_details": {
    "account_name": "<string>",
    "account_number": "<string>",
    "bank_name": "<string>",
    "country": "<string>",
    "bank_code": "<string>"
  },
  "bank_account": {
    "account_number": "<string>",
    "bank_code": "<string>",
    "bank_name": "<string>"
  },
  "beneficiary_id": "<string>",
  "return_url": "<string>",
  "metadata": {}
}
'

import requests

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

payload = {
    "amount": 123,
    "target_amount": 123,
    "currency": "NGN",
    "target_currency": "KES",
    "user_id": "<string>",
    "org_id": "<string>",
    "country": "NG",
    "org_rate_id": "<string>",
    "client_reference": "<string>",
    "description": "<string>",
    "payer_details": {
        "name": "<string>",
        "email": "jsmith@example.com",
        "phone": "<string>"
    },
    "mobile_money_details": {
        "provider": "Mobile Wallet (M-PESA)",
        "phone_number": "<string>"
    },
    "card_details": {
        "card_number": "<string>",
        "expiry_month": "<string>",
        "expiry_year": "<string>",
        "cvv": "<string>",
        "card_holder_name": "<string>"
    },
    "bank_details": {
        "account_name": "<string>",
        "account_number": "<string>",
        "bank_name": "<string>",
        "country": "<string>",
        "bank_code": "<string>"
    },
    "bank_account": {
        "account_number": "<string>",
        "bank_code": "<string>",
        "bank_name": "<string>"
    },
    "beneficiary_id": "<string>",
    "return_url": "<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({
    amount: 123,
    target_amount: 123,
    currency: 'NGN',
    target_currency: 'KES',
    user_id: '<string>',
    org_id: '<string>',
    country: 'NG',
    org_rate_id: '<string>',
    client_reference: '<string>',
    description: '<string>',
    payer_details: {name: '<string>', email: 'jsmith@example.com', phone: '<string>'},
    mobile_money_details: {provider: 'Mobile Wallet (M-PESA)', phone_number: '<string>'},
    card_details: {
      card_number: '<string>',
      expiry_month: '<string>',
      expiry_year: '<string>',
      cvv: '<string>',
      card_holder_name: '<string>'
    },
    bank_details: {
      account_name: '<string>',
      account_number: '<string>',
      bank_name: '<string>',
      country: '<string>',
      bank_code: '<string>'
    },
    bank_account: {account_number: '<string>', bank_code: '<string>', bank_name: '<string>'},
    beneficiary_id: '<string>',
    return_url: '<string>',
    metadata: {}
  })
};

fetch('https://prod-api.pcxpay.com/v1/payments-init/initiate', 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/initiate",
  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([
    'amount' => 123,
    'target_amount' => 123,
    'currency' => 'NGN',
    'target_currency' => 'KES',
    'user_id' => '<string>',
    'org_id' => '<string>',
    'country' => 'NG',
    'org_rate_id' => '<string>',
    'client_reference' => '<string>',
    'description' => '<string>',
    'payer_details' => [
        'name' => '<string>',
        'email' => 'jsmith@example.com',
        'phone' => '<string>'
    ],
    'mobile_money_details' => [
        'provider' => 'Mobile Wallet (M-PESA)',
        'phone_number' => '<string>'
    ],
    'card_details' => [
        'card_number' => '<string>',
        'expiry_month' => '<string>',
        'expiry_year' => '<string>',
        'cvv' => '<string>',
        'card_holder_name' => '<string>'
    ],
    'bank_details' => [
        'account_name' => '<string>',
        'account_number' => '<string>',
        'bank_name' => '<string>',
        'country' => '<string>',
        'bank_code' => '<string>'
    ],
    'bank_account' => [
        'account_number' => '<string>',
        'bank_code' => '<string>',
        'bank_name' => '<string>'
    ],
    'beneficiary_id' => '<string>',
    'return_url' => '<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/initiate"

	payload := strings.NewReader("{\n  \"amount\": 123,\n  \"target_amount\": 123,\n  \"currency\": \"NGN\",\n  \"target_currency\": \"KES\",\n  \"user_id\": \"<string>\",\n  \"org_id\": \"<string>\",\n  \"country\": \"NG\",\n  \"org_rate_id\": \"<string>\",\n  \"client_reference\": \"<string>\",\n  \"description\": \"<string>\",\n  \"payer_details\": {\n    \"name\": \"<string>\",\n    \"email\": \"jsmith@example.com\",\n    \"phone\": \"<string>\"\n  },\n  \"mobile_money_details\": {\n    \"provider\": \"Mobile Wallet (M-PESA)\",\n    \"phone_number\": \"<string>\"\n  },\n  \"card_details\": {\n    \"card_number\": \"<string>\",\n    \"expiry_month\": \"<string>\",\n    \"expiry_year\": \"<string>\",\n    \"cvv\": \"<string>\",\n    \"card_holder_name\": \"<string>\"\n  },\n  \"bank_details\": {\n    \"account_name\": \"<string>\",\n    \"account_number\": \"<string>\",\n    \"bank_name\": \"<string>\",\n    \"country\": \"<string>\",\n    \"bank_code\": \"<string>\"\n  },\n  \"bank_account\": {\n    \"account_number\": \"<string>\",\n    \"bank_code\": \"<string>\",\n    \"bank_name\": \"<string>\"\n  },\n  \"beneficiary_id\": \"<string>\",\n  \"return_url\": \"<string>\",\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/initiate")
  .header("Authorization", "<authorization>")
  .header("X-Api-Key", "<x-api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": 123,\n  \"target_amount\": 123,\n  \"currency\": \"NGN\",\n  \"target_currency\": \"KES\",\n  \"user_id\": \"<string>\",\n  \"org_id\": \"<string>\",\n  \"country\": \"NG\",\n  \"org_rate_id\": \"<string>\",\n  \"client_reference\": \"<string>\",\n  \"description\": \"<string>\",\n  \"payer_details\": {\n    \"name\": \"<string>\",\n    \"email\": \"jsmith@example.com\",\n    \"phone\": \"<string>\"\n  },\n  \"mobile_money_details\": {\n    \"provider\": \"Mobile Wallet (M-PESA)\",\n    \"phone_number\": \"<string>\"\n  },\n  \"card_details\": {\n    \"card_number\": \"<string>\",\n    \"expiry_month\": \"<string>\",\n    \"expiry_year\": \"<string>\",\n    \"cvv\": \"<string>\",\n    \"card_holder_name\": \"<string>\"\n  },\n  \"bank_details\": {\n    \"account_name\": \"<string>\",\n    \"account_number\": \"<string>\",\n    \"bank_name\": \"<string>\",\n    \"country\": \"<string>\",\n    \"bank_code\": \"<string>\"\n  },\n  \"bank_account\": {\n    \"account_number\": \"<string>\",\n    \"bank_code\": \"<string>\",\n    \"bank_name\": \"<string>\"\n  },\n  \"beneficiary_id\": \"<string>\",\n  \"return_url\": \"<string>\",\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"amount\": 123,\n  \"target_amount\": 123,\n  \"currency\": \"NGN\",\n  \"target_currency\": \"KES\",\n  \"user_id\": \"<string>\",\n  \"org_id\": \"<string>\",\n  \"country\": \"NG\",\n  \"org_rate_id\": \"<string>\",\n  \"client_reference\": \"<string>\",\n  \"description\": \"<string>\",\n  \"payer_details\": {\n    \"name\": \"<string>\",\n    \"email\": \"jsmith@example.com\",\n    \"phone\": \"<string>\"\n  },\n  \"mobile_money_details\": {\n    \"provider\": \"Mobile Wallet (M-PESA)\",\n    \"phone_number\": \"<string>\"\n  },\n  \"card_details\": {\n    \"card_number\": \"<string>\",\n    \"expiry_month\": \"<string>\",\n    \"expiry_year\": \"<string>\",\n    \"cvv\": \"<string>\",\n    \"card_holder_name\": \"<string>\"\n  },\n  \"bank_details\": {\n    \"account_name\": \"<string>\",\n    \"account_number\": \"<string>\",\n    \"bank_name\": \"<string>\",\n    \"country\": \"<string>\",\n    \"bank_code\": \"<string>\"\n  },\n  \"bank_account\": {\n    \"account_number\": \"<string>\",\n    \"bank_code\": \"<string>\",\n    \"bank_name\": \"<string>\"\n  },\n  \"beneficiary_id\": \"<string>\",\n  \"return_url\": \"<string>\",\n  \"metadata\": {}\n}"

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

{
  "statusCode": 200,
  "response": {
    "success": true,
    "payment_id": "<string>",
    "transaction_id": "<string>",
    "status": "<string>",
    "next_action": "redirect",
    "redirect_url": "<string>",
    "provider": "<string>",
    "message": "<string>",
    "payment_data": {
      "amount": 123,
      "currency": "<string>",
      "target_amount": 123,
      "target_currency": "<string>",
      "metadata": {}
    }
  }
}

{
  "error": "<string>",
  "message": "<string>",
  "code": "RATE_MISMATCH"
}

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

{
  "error": "<string>",
  "message": "No routing configuration found for this payment corridor",
  "code": "ROUTING_CONFIG_NOT_FOUND"
}

{
  "error": "<string>",
  "message": "<string>",
  "code": "ALL_PROVIDERS_FAILED"
}

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

amount

number<float>

required

Source amount

target_amount

number<float>

required

Destination amount. For same-currency flows must equal amount. For cross-currency flows must match amount × rate from the locked org_rate_id.

currency

string

required

ISO 4217 source currency

Example:

"NGN"

target_currency

string

required

ISO 4217 destination currency. Must equal currency for single-currency flows.

Example:

"KES"

payment_method

enum<string>

required

Available options:

mobile_money,

bank_transfer,

card

direction

enum<string>

required

Available options:

payin,

payout

user_id

string

Injected automatically from the authenticated API key or session — you do not need to include it.

org_id

string

Injected automatically from the authenticated API key or session — you do not need to include it.

country

string

Optional ISO alpha-2 country code of the payin origin

Example:

"NG"

org_rate_id

string | null

Rate ID from the exchange rate lookup. Required when currency ≠ target_currency.

client_reference

string | null

Your own idempotency reference for this transaction.

description

string | null

payer_details

object

Required for payin flows.

Show child attributes

mobile_money_details

object | null

Required when payment_method is mobile_money.

Show child attributes

card_details

object | null

Required when payment_method is card.

Show child attributes

bank_details

object | null

Payer's source bank account. Required for bank transfer flows.

Show child attributes

bank_account

object | null

Destination bank account. Required for bank transfer flows.

Show child attributes

beneficiary_id

string | null

Required for payout flows.

return_url

string<uri> | null

URL the customer is redirected back to after completing payment. When next_action is redirect, the hosted checkout carries this URL through the flow and sends the customer to it once checkout finishes. PCX appends status (completed or failed) and reference (your client_reference, or a payment ID prefix) query parameters to this URL on the return redirect.

metadata

object | null

Response

Payment initiated

statusCode

integer

Example:

200

response

object

When the provider returns funding instructions (for example a bank transfer flow), the instruction fields are merged into this object at the top level alongside the fields below.

Show child attributes