Embedding - PCX Developer Docs

The PCX payment UI is a hosted web application served from remittances.pcxpay.com. You embed it by rendering a standard <iframe> element pointing to the redirect_url returned by the payment initiation endpoint. PCX renders a QR code inside the frame — the payer scans it with their banking app to authorise the payment via Open Banking.

Basic embed

<iframe
  id="pcxpay-payment"
  src="REDIRECT_URL_FROM_INITIATE_RESPONSE"
  width="100%"
  height="700"
  frameborder="0"
  allow="payment"
  style="border: none; border-radius: 8px;"
></iframe>

Replace REDIRECT_URL_FROM_INITIATE_RESPONSE with the response.redirect_url value from the payment initiation response. Do not modify the URL or append additional query parameters.

React example

function PaymentIframe({ redirectUrl }) {
  return (
    <iframe
      src={redirectUrl}
      width="100%"
      height="700"
      frameBorder="0"
      allow="payment"
      style={{ border: 'none', borderRadius: '8px' }}
      title="PCXPay Payment"
    />
  );
}

How the payment UI works

The iFrame displays a QR code for the payer to complete payment via Open Banking. The payer:

Opens their banking app
Scans the QR code
Authorises the payment inside their banking app

The entire authentication flow is handled within the iFrame. No additional interaction is required from the parent page during payment. PCX confirms the payment via webhook when the bank authorises the transaction.

No authentication is required for the redirect_url itself. The ref query parameter contains the base64-encoded payment reference. Do not attempt to construct or modify this URL.

Recommended container sizing

The iFrame renders correctly across a range of heights, but we recommend a minimum height of 700px to display the QR code and payment instructions without internal scrollbars.

#pcxpay-payment {
  width: 100%;
  min-height: 700px;
  border: none;
  border-radius: 8px;
  display: block;
}

Avoid setting a fixed pixel width — the form is designed to fill its container responsively.

Mobile-responsive layout

The PCX payment form adapts to any viewport width. No separate mobile configuration is required. If you are embedding inside a mobile web app, set the viewport meta tag on your parent page:

<meta name="viewport" content="width=device-width, initial-scale=1.0">

Without this tag, some mobile browsers render the desktop layout scaled down rather than triggering responsive breakpoints.

Security attributes

The allow="payment" attribute is required to enable browser-level payment APIs inside the frame where supported.

<iframe
  src="..."
  allow="payment"
  ...
></iframe>

Do not add sandbox attributes to the iFrame. PCX’s payment form requires access to browser features (redirects, cookie handling) that sandbox restrictions would block.

Rendering without a full-page reload

You can show or hide the frame dynamically without reloading the page:

// Show the payment form after receiving the redirect_url from your server
function showPaymentForm(redirectUrl) {
  const frame = document.getElementById("pcxpay-payment");
  frame.src = redirectUrl;
  frame.style.display = "block";
}

// Hide after receiving payment confirmation via webhook
function hidePaymentForm() {
  const frame = document.getElementById("pcxpay-payment");
  frame.style.display = "none";
}

​Basic embed

​React example

​How the payment UI works

​Recommended container sizing

​Mobile-responsive layout

​Security attributes

​Rendering without a full-page reload

Basic embed

React example

How the payment UI works

Recommended container sizing

Mobile-responsive layout

Security attributes

Rendering without a full-page reload