Initiating a Payment - PCX Developer Docs

Endpoint

POST https://prod-api.pcxpay.com/v1/payments-init/initiate

Both auth headers are always required. Set whichever you are not using to the literal string NONE.

Header	Value
`X-Api-Key`	Your API key
`Authorization`	`NONE` (for API key flows)

Request

The pay_by_link: true flag in the metadata object is required for H2H. Without it the request defaults to iFrame integration.

{
  "amount": 100.00,
  "target_amount": 100.00,
  "target_currency": "GBP",
  "currency": "GBP",
  "country": "GB",
  "payment_method": "bank_transfer",
  "org_id": "your-org-id",
  "payer_details": {
    "email": "customer@example.com",
    "name": "John Doe"
  },
  "metadata": {
    "beneficiary_name": "Recipient Name",
    "user_id": "user-uuid",
    "transaction_type": "bank",
    "reason": "Payment for services",
    "pay_by_link": true
  }
}

Response

{
  "success": true,
  "status": "initiated",
  "next_action": "pay_by_link",
  "payment_link": "https://pay.pcxpay.com/pay/abc123xyz...",
  "payment_intent_id": "pi_xyz789",
  "expiry_time": "2024-01-15T12:00:00Z",
  "provider_payment_id": "pay_abc123",
  "message": "Payment link created. Share link with customer to complete payment."
}

Response fields

Field	Type	Description
`success`	boolean	Whether the request was successful
`status`	string	Payment status — always `initiated` on creation
`next_action`	string	Always `pay_by_link` for H2H integration
`payment_link`	string	Direct payment link to share with the customer
`payment_intent_id`	string	Unique identifier for this payment intent — store this for tracking
`expiry_time`	string	ISO 8601 timestamp when the link expires (typically 24 hours)
`provider_payment_id`	string	PCX payment identifier
`message`	string	Human-readable status message

Once you receive payment_link, deliver it to the customer via SMS, email, in-app message, or push notification.

Expiry — the link expires after 24 hours. Check expiry_time in the response. If it expires, create a new payment request.
Tracking — store payment_intent_id against the order in your system for status tracking.
Confirmation — do not rely on the customer returning to your app to confirm payment. Always use webhooks for confirmation. See Payment Status & Webhooks.
Expired links — if the customer tries to pay after expiry, surface a clear message and allow them to request a new link.

​Endpoint

​Request

​Response

​Response fields

​Sharing the link

Endpoint

Request

Response

Response fields

Sharing the link