Payment Initiation - PCX Developer Docs

Before rendering the iFrame, your platform must initiate a payment with PCX. PCX returns a redirect_url containing base64-encoded payment data. Pass this URL to your front end to use as the iFrame src.

Why platform-side initiation matters

Payment parameters — amount, currency, payer details — are set on your platform and sent directly to PCX. The returned redirect_url carries an encoded reference to the payment record. This means the payer cannot modify the payment amount or currency before the iFrame loads.

Initiate a payment

Call the PCX payment initiation endpoint from your platform:

curl -X POST https://prod-api.pcxpay.com/v1/payments-init/initiate \
  -H "Authorization: NONE" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100.00,
    "currency": "GBP",
    "target_amount": 100.00,
    "target_currency": "GBP",
    "country": "GB",
    "payment_method": "bank_transfer",
    "direction": "payin",
    "org_id": "your-org-id",
    "client_reference": "your-unique-reference",
    "description": "Payment description",
    "payer_details": {
      "email": "payer@example.com",
      "name": "John Doe"
    },
    "metadata": {
      "beneficiary_name": "Recipient Name",
      "reason": "Payment reason"
    }
  }'

Response:

{
  "statusCode": 200,
  "payment_id": "34751905-725f-4e1a-a0e6-998666aabee3",
  "transaction_id": "835de352-cf44-4330-8a90-d835a169e895",
  "response": {
    "success": true,
    "status": "initiated",
    "next_action": "redirect",
    "redirect_url": "https://remittances.pcxpay.com/xxxx?ref=eyJwYXltZW50X2lkIjoiMzQ3NTE5MDUtNzI1Zi00ZTFhLWEwZTYtOTk4NjY2YWFiZWUzIiwiYW1vdW50IjoxMDAuMCwiY3VycmVuY3kiOiJHQlAifQ==",
    "message": "Payment initiated. Redirect user to complete payment."
  }
}

Use response.redirect_url as the src of the iFrame. Do not construct this URL yourself — always use the value returned by PCX.

Request headers

Header	Required	Description
`Authorization`	Yes	`Bearer <JWT>` if using JWT auth; set to `NONE` when using API key
`X-Api-Key`	Yes	Your organisation’s API key; set to `NONE` when using JWT auth
`Content-Type`	Yes	`application/json`

Both headers must always be present. Set whichever one you are not using to the literal string NONE.

Request fields

Field	Type	Required	Description
`amount`	number	Yes	Payment amount in source currency
`currency`	string	Yes	Source currency code (e.g. `GBP`)
`target_amount`	number	Yes	Amount in target/settlement currency
`target_currency`	string	Yes	Target currency code (e.g. `GBP`)
`country`	string	Yes	Country code (e.g. `GB`)
`payment_method`	string	Yes	Must be `bank_transfer`
`direction`	string	Yes	Must be `payin`
`org_id`	string	Yes	Your organisation ID
`client_reference`	string	No	Your unique reference for this payment
`description`	string	No	Human-readable payment description
`payer_details.email`	string	No	Payer’s email address
`payer_details.name`	string	No	Payer’s full name
`metadata`	object	No	Arbitrary key-value pairs stored with the payment

Response fields

Field	Description
`payment_id`	PCX’s unique payment identifier — use to look up payment status
`transaction_id`	PCX transaction identifier
`response.redirect_url`	URL to set as the iFrame `src`
`response.next_action`	Will be `redirect` for iFrame flows
`response.status`	Initial status — `initiated`

The redirect URL

The redirect_url contains a base64-encoded ref parameter with the payment identifiers:

https://remittances.pcxpay.com/xxxx?ref=<base64_encoded_data>

Decoded ref structure:

{
  "payment_id": "34751905-725f-4e1a-a0e6-998666aabee3",
  "amount": 100.0,
  "currency": "GBP"
}

Do not modify the ref parameter. The payment details are validated against the database when the payment is processed. Tampering with the parameter will cause the payment to fail.

Do not expose your API key in client-side code. The payment initiation call must always originate from your platform.

​Why platform-side initiation matters

​Initiate a payment

​Request headers

​Request fields

​Response fields

​The redirect URL

Why platform-side initiation matters

Initiate a payment

Request headers

Request fields

Response fields

The redirect URL