Skip to main content

Web Integration Overview

The PayUp Web Integration API powers the hosted checkout experience and the browser SDK. Use this guide to understand the sequence of calls and where to find schema-level details.

Flow Summary​

Web / storefront integration​

  1. Initialize the SDK
    Call POST /v1/tokenize from your storefront with the tk_ client token (x-client-token header) and the browser's Origin. A scoped frontend creation SDK token is returned.

  2. Create the session
    Submit linked products (storeCode + quantity) to POST /v1/checkout/web/session with the creation token. Inline priced products are not allowed from the browser.

  3. Redirect the shopper
    Send customers to the returned redirectUrl. It includes ?sdk_token= with a session-scoped checkout token (limited to OTP permissions, bound to that session) — not your creation token.

  4. Checkout page
    The hosted checkout uses the checkout token to load session details (GET /v1/checkout/session/{token}), send/verify OTP (/v1/checkout/verification/*), and process payment (POST /v1/payments/process with the verification token).

Backend integration​

  1. Authenticate
    Call POST /v1/auth with your pk_* / sk_* API key pair. A backend creation SDK token is returned.

  2. Create the session
    Call POST /v1/checkout/backend/session with inline or linked products and an optional pre-verified customer. No Origin header is required.

  3. Redirect the shopper
    Same as the web flow: redirectUrl carries a session-scoped checkout token for the hosted checkout page.

Security notes​

  • Creation tokens (from /v1/tokenize or /v1/auth) must never be exposed in browser URLs or localStorage for checkout.
  • The checkout token in redirectUrl cannot create new sessions or set product prices.
  • A checkout token is bound to one sessionId and cannot read another session's details.

Reference​

  • Payment API – the public payment surface: auth, tokenize, checkout sessions, verification, and payments.
  • Merchant API – the merchant dashboard admin endpoints.

When you extend the integration (for example, to support additional payment methods), update the schema in openapi/payup-public.yml and re-run npm run build to regenerate the reference.