Introduction

Whether you redirect customers to a Pockyt-hosted checkout page, embed the payment experience directly into your own UI, or process card payments with 3D Secure, Pockyt provides dedicated endpoints for each integration path — primarily the SecurePay API and the Capture API.

The online payments workflow supports three key functions:

1. Customer Registration: The merchant backend registers the customer with Pockyt to obtain a unique customerNo, which is referenced across all subsequent payment requests.
2. Payment Initiation: The merchant calls the appropriate Pockyt payment endpoint (e.g., SecurePay API, Capture API) to create a payment session. Depending on the integration type, the response returns either a hosted checkout URL, SDK initialization data, or a payment form reference for rendering the payment experience.
3. Transaction Confirmation: Payment status is confirmed asynchronously via webhook notification, with an optional transaction query endpoint available for manual verification.

How Online Payments Work

All online payment integrations follow the same high-level pattern. The merchant backend authenticates, registers the customer, calls a Pockyt payment endpoint to initiate the transaction, and then handles the result via webhook. The difference between integration types is in which endpoint is called and how the customer completes the payment — the overall flow remains consistent.

sequenceDiagram
    participant C as Customer
    participant MB as Merchant Backend
    participant PA as Pockyt API

    Note over MB: Step 1: Register Customer
    MB->>PA: POST /v1/customers/create
    PA-->>MB: customerNo

    Note over MB: Step 2: Initiate Payment
    MB->>PA: Call payment endpoint (SecurePay, Capture, etc.)
    PA-->>MB: Payment session data

    Note over C: Step 3: Customer Completes Payment
    C->>PA: Payment authorized via hosted page, SDK, or form

    Note over PA: Step 4: Webhook Notification
    PA-->>MB: Transaction result (status, transactionNo)

    Note over MB: Step 5: Query (Optional)
    MB->>PA: POST /app-data-search/v3/tran-query
    PA-->>MB: Transaction status

Integration Types

Pockyt supports several online payment integration types, each tailored to different merchant needs. Most flows are initiated through the SecurePay API, while others — such as direct credit card processing — use the Capture API. Each integration guide specifies the exact endpoint and parameters required.

Hosted Checkout Page

The merchant calls SecurePay and receives a cashierUrl. The customer is redirected to Pockyt's hosted payment page, where they select a payment method and complete the transaction. This is the fastest integration path — no frontend SDK work required.

📘

Best for: Merchants who want a quick integration with minimal frontend development. Pockyt manages the entire payment UI.

Whitelabel Checkout (YIP)

The merchant calls SecurePay with terminal: "YIP" and receives vendor-specific SDK initialization data instead of a hosted URL. The merchant renders the payment experience directly on their own checkout page using the vendor SDK (e.g., Cash App Pay, PayPal JS, Venmo).

📘

Best for: Merchants who want full control over the checkout UI and branding while still using Pockyt for payment processing.

Credit Card Payments (Capture 3DS)

For direct credit card acceptance, Pockyt supports a Capture API flow with 3D Secure authentication. The merchant calls the POST /order/v4/capture endpoint to initiate the transaction, which includes an additional step for 3DS verification before the card is charged.

📘

Best for: Merchants who need to accept credit and debit cards with strong customer authentication (SCA) compliance.

Recurring Payments (Vaulting)

Merchants can store a customer's payment method using Pockyt's vaulting capability. The initial payment creates a vaultId, which is used for all subsequent charges without requiring the customer to re-enter payment details. Vaulting is supported through both the SecurePay API and the Capture API.

📘

Best for: Subscription services, membership platforms, or any business model that requires repeat billing.

Key Considerations

1. Direct Merchant Behavior: Online payment flows behave the same whether the merchant operates as a direct merchant or as a partner with sub-merchants. The checkout integration always operates at the individual merchant level — each merchant uses their own merchantNo and storeNo credentials regardless of the account hierarchy above them.

2. Consistent Patterns Across Endpoints: While different integration types may use different Pockyt endpoints (SecurePay for hosted and whitelabel flows, Capture for credit card 3DS), the overall workflow pattern remains the same: register customer → initiate payment → customer authorizes → confirm via webhook. Parameters like terminal, creditType, and vendor control the behavior within each endpoint. Refer to the specific integration guide for the exact endpoint and parameter configuration.

3. Vendor Support: Different payment vendors are available depending on the integration type and the merchant's configuration. Reference the Available Payment Methods for the full list of supported vendor parameter values.

4. Error Handling: A ret_code of 000100 indicates success on all Pockyt API responses. Handle errors consistently and implement retry logic for transient failures. See Status & Error Codes for the complete reference.

Integration Guides

For step-by-step implementation instructions, refer to the integration guide that matches your checkout type:

📘

Checkout Integration Guides:

• Pockyt Hosted Checkout Page w/ SecurePay
• Pockyt Whitelabel Checkout w/ SecurePay (YIP)
• Pockyt Credit Card Payments w/ Capture 3DS
• Recurring Payments via SecurePay API (Vaulting)
• Recurring Payments via the Capture API