Pockyt Whitelabel Checkout w/ SecurePay (YIP)

Introduction

This solution enables merchants to accept payments through a fully whitelabel checkout experience. Unlike the Hosted Checkout Page where customers are redirected to Pockyt's branded cashier page, the Whitelabel Checkout (YIP) integration allows the merchant to build and control the entire checkout UI.

The merchant system supports three key functions in this workflow:

1. Customer Registration: The merchant backend registers the customer with Pockyt to obtain a unique customerNo used for SecurePay transactions.
2. Whitelabel Checkout Initiation: The merchant calls SecurePay with terminal: "YIP" to receive vendor-specific SDK initialization data instead of a hosted checkout URL. The merchant renders the vendor SDK on their own checkout page and the customer authorizes the payment directly within the SDK.
3. Transaction Confirmation: The payment status is confirmed via webhook notification or optional transaction query, allowing the merchant to finalize the order and update internal records.

API Diagram

API workflow

📘

API References for Endpoints in this Workflow:

• Step 1 Register Customer
• Step 2 Secure-pay
• Step 4 Handling Webhooks via IPN Url
• Step 5 Query Transaction Status

Step-by-Step Whitelabel Checkout (YIP) Workflow

Step 1: Register Customer

Action: The merchant backend registers the customer using the
POST /v1/customers/create endpoint.
This returns a customerNo that will be referenced in the SecurePay request.

Step 2: Initiate Whitelabel Checkout (YIP)

Action: The customer initiates a checkout session on the merchant's own checkout page.

1. The merchant backend calls the
   POST /online/v3/secure-pay endpoint with terminal: "YIP".
2. The creditType should be set to "normal" for standard one-time payments.
3. For the vendor parameter value, you can reference the following list vendor parameter. Common YIP-supported vendors include cashapppay, paypal, and venmo.
4. Unlike the Hosted Checkout flow, the Pockyt API does not return a cashierUrl. Instead, it returns vendor-specific initialization data that the merchant uses to render the payment UI on their own page.

Example Request (Cash App Pay):

{
  "amount": "100.00",
  "storeNo": "305209",
  "currency": "USD",
  "settleCurrency": "USD",
  "merchantNo": "204674",
  "callbackUrl": "https://merchant.com/payment-complete",
  "terminal": "YIP",
  "ipnUrl": "https://merchant.com/webhooks/pockyt",
  "reference": "order_20260330_001",
  "vendor": "cashapppay",
  "verifySign": "{{verifySign}}"
}

Example Response (Cash App Pay):

{
  "result": {
    "amount": "100.00",
    "clientId": "CAS-CI_POCKYT",
    "brandId": "BRAND_xxxxxxxxxxxxxxxxxxxxxxxx",
    "transactionNo": "301XXXXXXXXXXXXXXX",
    "currency": "USD",
    "creditType": "normal"
  },
  "ret_code": "000100",
  "ret_msg": "success"
}

Step 3: Render Vendor SDK and Authorize Payment

Action: The merchant frontend uses the initialization data from Step 2 to render the vendor's payment SDK on their checkout page.

1. Initialize the vendor SDK using the returned parameters. For example, Cash App Pay requires the clientId and brandId to render its payment button.
2. The customer interacts with the vendor SDK to authorize the payment (e.g., scanning a QR code, approving in the Cash App mobile application, or clicking a payment button).
3. Once the customer authorizes, the vendor SDK communicates the authorization directly to Pockyt on the backend. The merchant does not need to make any additional API calls to finalize the payment.
4. The merchant should wait for the webhook notification (Step 4) to confirm the transaction result before updating the order status.

📘

Vendor SDK Documentation: Pockyt provides vendor-specific HTML demo files and SDK references for each supported payment method. Contact your Pockyt Solutions representative.

Step 4: Handle Webhook Notifications

Action: Pockyt sends a webhook to the merchant backend with the final transaction result.

• The webhook includes fields such as transaction number, status, and amount.
• The merchant should listen for this webhook on the URL defined in the ipnUrl parameter of the original request.

✅

Payments should only be considered complete after a "success" status is received via webhook or confirmed manually.

Step 5: (Optional) Query Transaction Status

Action: If webhook confirmation is delayed or not received, the merchant may query the transaction status using
POST app-data-search/v3/tran-query.

Use Case: This endpoint retrieves the transaction status using the original transaction number.

Supported Vendors for YIP

The following payment vendors support the YIP whitelabel integration. Contact your Pockyt Solutions representative to confirm vendor availability for your account:

📘

For the full list of supported payment methods and vendor parameters, see Available Payment Methods.

Key Considerations

1. Vendor SDK Demo Files: When integrating a specific vendor, request the HTML demo file from your Pockyt Solutions representative. These files contain working examples of SDK initialization and payment authorization flows for each vendor.

2. Error Handling: A ret_code of 000100 indicates success on all Pockyt API responses. Handle errors consistently and implement retry logic for transient failures.

3. Idempotency: Use unique reference values for each transaction to prevent duplicate charges. See Idempotency Key for details.