Initiate a payment (deprecated)

curl --request POST \
  --url https://prod-api.pcxpay.com/v1/payments-init/initiate/public-payin \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <x-api-key>' \
  --data '
{
  "amount": 123,
  "target_amount": 123,
  "currency": "KES",
  "target_currency": "KES",
  "country": "KE",
  "client_reference": "<string>",
  "description": "<string>",
  "payer_details": {
    "name": "<string>",
    "email": "jsmith@example.com",
    "phone": "<string>"
  },
  "mobile_money_details": {
    "provider": "<string>",
    "phone_number": "<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/public-payin"

payload = {
    "amount": 123,
    "target_amount": 123,
    "currency": "KES",
    "target_currency": "KES",
    "country": "KE",
    "client_reference": "<string>",
    "description": "<string>",
    "payer_details": {
        "name": "<string>",
        "email": "jsmith@example.com",
        "phone": "<string>"
    },
    "mobile_money_details": {
        "provider": "<string>",
        "phone_number": "<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: 'KES',
    target_currency: 'KES',
    country: 'KE',
    client_reference: '<string>',
    description: '<string>',
    payer_details: {name: '<string>', email: 'jsmith@example.com', phone: '<string>'},
    mobile_money_details: {provider: '<string>', phone_number: '<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/public-payin', 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/public-payin",
  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' => 'KES',
    'target_currency' => 'KES',
    'country' => 'KE',
    'client_reference' => '<string>',
    'description' => '<string>',
    'payer_details' => [
        'name' => '<string>',
        'email' => 'jsmith@example.com',
        'phone' => '<string>'
    ],
    'mobile_money_details' => [
        'provider' => '<string>',
        'phone_number' => '<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/public-payin"

	payload := strings.NewReader("{\n  \"amount\": 123,\n  \"target_amount\": 123,\n  \"currency\": \"KES\",\n  \"target_currency\": \"KES\",\n  \"country\": \"KE\",\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\": \"<string>\",\n    \"phone_number\": \"<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/public-payin")
  .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\": \"KES\",\n  \"target_currency\": \"KES\",\n  \"country\": \"KE\",\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\": \"<string>\",\n    \"phone_number\": \"<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/public-payin")

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\": \"KES\",\n  \"target_currency\": \"KES\",\n  \"country\": \"KE\",\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\": \"<string>\",\n    \"phone_number\": \"<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": {}
    }
  }
}

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

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

POST

payments-init

initiate

public-payin

Initiate a payment (deprecated)

curl --request POST \
  --url https://prod-api.pcxpay.com/v1/payments-init/initiate/public-payin \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <x-api-key>' \
  --data '
{
  "amount": 123,
  "target_amount": 123,
  "currency": "KES",
  "target_currency": "KES",
  "country": "KE",
  "client_reference": "<string>",
  "description": "<string>",
  "payer_details": {
    "name": "<string>",
    "email": "jsmith@example.com",
    "phone": "<string>"
  },
  "mobile_money_details": {
    "provider": "<string>",
    "phone_number": "<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/public-payin"

payload = {
    "amount": 123,
    "target_amount": 123,
    "currency": "KES",
    "target_currency": "KES",
    "country": "KE",
    "client_reference": "<string>",
    "description": "<string>",
    "payer_details": {
        "name": "<string>",
        "email": "jsmith@example.com",
        "phone": "<string>"
    },
    "mobile_money_details": {
        "provider": "<string>",
        "phone_number": "<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: 'KES',
    target_currency: 'KES',
    country: 'KE',
    client_reference: '<string>',
    description: '<string>',
    payer_details: {name: '<string>', email: 'jsmith@example.com', phone: '<string>'},
    mobile_money_details: {provider: '<string>', phone_number: '<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/public-payin', 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/public-payin",
  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' => 'KES',
    'target_currency' => 'KES',
    'country' => 'KE',
    'client_reference' => '<string>',
    'description' => '<string>',
    'payer_details' => [
        'name' => '<string>',
        'email' => 'jsmith@example.com',
        'phone' => '<string>'
    ],
    'mobile_money_details' => [
        'provider' => '<string>',
        'phone_number' => '<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/public-payin"

	payload := strings.NewReader("{\n  \"amount\": 123,\n  \"target_amount\": 123,\n  \"currency\": \"KES\",\n  \"target_currency\": \"KES\",\n  \"country\": \"KE\",\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\": \"<string>\",\n    \"phone_number\": \"<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/public-payin")
  .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\": \"KES\",\n  \"target_currency\": \"KES\",\n  \"country\": \"KE\",\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\": \"<string>\",\n    \"phone_number\": \"<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/public-payin")

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\": \"KES\",\n  \"target_currency\": \"KES\",\n  \"country\": \"KE\",\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\": \"<string>\",\n    \"phone_number\": \"<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": {}
    }
  }
}

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

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

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

Same as PaymentInitiationRequest but org_id and user_id are injected from the authenticated API key — do not include them. Only same-currency flows are supported on this endpoint.

amount

number<float>

required

target_amount

number<float>

required

Must equal amount (same-currency only).

currency

string

required

Example:

"KES"

target_currency

string

required

Must equal currency.

Example:

"KES"

country

string

required

Example:

"KE"

payment_method

enum<string>

required

Available options:

mobile_money,

bank_transfer,

card

direction

enum<string>

Available options:

payin,

payout

client_reference

string | null

description

string | null

payer_details

object

Show child attributes

mobile_money_details

object | null

Show child attributes

bank_details

object | null

Show child attributes

bank_account

object | null

Show child attributes

beneficiary_id

string | null

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