Accept Payments via our Hosted Fields SDK

Overview

Apcopay Hosted Fields provides a secure, PCI-compliant solution for collecting and tokenizing payment card details via an iframe. Merchants do not handle raw card data; instead, they receive a token to finalize payment server-side.

🧩 Integration Flow Summary

1. Backend creates a session via /api/hostedfields/createsession.
2. Frontend initializes the Hosted Fields iframe using the session token.
3. User inputs card data directly into the iframe.
4. Iframe tokenizes the card and returns a CardToken.
5. Backend uses CardToken with /api/hostedfields/pay to process the payment.

🔗 API Endpoints

🔁 Hosted Fields Payment Flow – Explained

📈 Diagram: High-Level View

This diagram outlines the end-to-end Hosted Fields integration, from page load to final payment response. Each interaction represents a step required for secure, tokenized payment processing.

🔍 Step-by-Step Flow Breakdown

🛡️ Key Considerations

• Security: The iframe is hosted from ApcoPay, ensuring no sensitive data passes through the merchant’s frontend or backend.
• Tokenization: Only a CardToken is used to complete the payment.
• Whitelisting: The domain must be whitelisted by ApcoPay for iframe access to work correctly.
• Session Expiry: Tokens expire after 5 minutes or if the transaction is declined.

🔧 Hosted Fields Technical Integration Guide

📘 Introduction

This guide provides technical instructions for integrating ApcoPay Hosted Fields, a secure, iframe-based solution for collecting and tokenizing payment card details without exposing sensitive data to the merchant's infrastructure.

This section covers the full lifecycle of a Hosted Fields transaction, including:

• Loading the Apcopay JavaScript SDK
• Creating a Hosted Fields session on the backend
• Initializing and rendering the payment fields securely in the browser
• Tokenizing card details using the JavaScript SDK
• Submitting the token to the backend for payment processing

The guide includes:

• Detailed sequence diagrams for the initialisation and payment flows
• Full integration steps with error handling

By following this guide, developers can implement a PCI-compliant card payment flow while maintaining a seamless checkout experience.

📥 1. Load the Hosted Fields Script

Place this script on the merchant’s checkout page to render the secure card form.

<script src="https://static.apcopay.tech/hostedjs/apcopay.js"></script>

🔐 2. Initialisation Flow

✅ Sequence Diagram: Initialise

🔧 Frontend Example

<div id="card-form"></div>
<button id="pay-btn">Pay Now</button>

<script>
  apcopay.hostedFields.create(
    "SESSION_TOKEN_FROM_BACKEND",
    "#card-form",
    {
      initialised: () => console.log("HostedFields ready"),
      initialisedError: (type, message) => console.error(`${type}: ${message}`),
      tokeniseSuccess: (cardToken) => {
        fetch("/pay", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({ cardToken })
        });
      },
      tokeniseError: (type, message) => console.error(`Error: ${type} - ${message}`)
    },
    {
      showSavedCards: true
    }
  );

  document.getElementById("pay-btn").addEventListener("click", () => {
    apcopay.hostedFields.tokenise();
  });
</script>

💳 3. Payment Flow

✅ Sequence Diagram: Pay

🔒 Security & Production Notes