Payment Tokens and Embedded Checkout

Payment Token Flow

Payment tokens are short-lived session tokens (60 minutes) used by embedded checkout to capture payment details securely.

Generate token

Endpoint:

GET /payment-token/:tenantId/generate

curl -X GET "${BASE_URL}/payment-token/${TENANT_ID}/generate" \
  -H "Authorization: Basic ${AUTH}"

Example response:

{ "token": "sess_abc123..." }

Use this token as sessionToken when mounting checkout.

Embedded Checkout (`@pekopay/web`)

Use @pekopay/web to render hosted credit card fields.

NPM package: @pekopay/web

End-to-end sequence:

Backend generates sessionToken.
Frontend mounts form with sessionToken.
Customer enters card details in hosted fields.
submitFormFields() tokenizes and invokes completeTransaction.
Frontend sends returned paymentToken to backend.
Backend calls PekoPay APIs using Basic auth.

Important:

Your backend never handles raw PAN/CVV.
submitFormFields() tokenizes only; it does not create a charge itself.
Treat returned payment token as short-lived and single-flow.

Vanilla JS example

<div id="credit-card-form-container"></div>
<button id="pay-button">Pay</button>
 
<script type="module">
  import { PekoCheckoutForm } from 'https://cdn.jsdelivr.net/npm/@pekopay/web@<version>/dist/index.js';
 
  const form = PekoCheckoutForm.initialize({
    sessionToken: '<PAYMENT_TOKEN_FROM_BACKEND>',
    environment: 'sandbox',
    container: document.getElementById('credit-card-form-container'),
    completeTransaction: async (data) => {
      await fetch('/api/checkout/charge', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ paymentToken: data.sessionToken })
      });
    },
    sessionTokenProvider: async () => {
      const res = await fetch('/api/payment-token/refresh');
      const json = await res.json();
      return json.token;
    }
  });
 
  form.mount();
  document.getElementById('pay-button').addEventListener('click', () => {
    form.submitFormFields();
  });
</script>

Typical frontend-to-backend payload

{
  "paymentToken": "sess_abc123...",
  "customerId": "<your_customer_reference>",
  "intent": "charge_or_subscription"
}