Build a subscription integration

Overview

Use the SDK subscription model when you need to complete the initial subscription payment and recurring renewals within your own checkout page. Compared with a standard one-time payment, SDK subscriptions have these key differences:

• The request must set subProductType to "SUBSCRIBE"
• You must provide the subscription parameter (a JSON string) to define subscription rules
• The initial payment may still require a 3DS flow (redirect when status = "R")
• When card-binding capabilities are enabled, you may receive both BIND_CARD and SALE notifications

Always treat webhooks as the transaction source of truth ( source of truth ).

Choose a subscription mode

subscription.selfExecute determines who executes renewals:

{
  "requestType": "0",
  "merchantCustId": "CUST-10001",
  "selfExecute": "1",
  "mode": "2",
  "frequencyType": "M",
  "frequencyPoint": "1",
  "cycleCount": 12
}

Integration steps

Implement in this order:

1. Create a SUBSCRIBE transaction on the server
2. Initialize the SDK on the client (SUBSCRIBE mode)
3. Handle SDK callbacks and 3DS redirects
4. Receive and process webhooks idempotently (including scenarios)
5. Store subscription credentials and drive business state

Create a SUBSCRIBE transaction on the server Server-side

The server request is similar to a standard SDK transaction. Key differences:

• Set subProductType to "SUBSCRIBE"
• subscription is required and must be a JSON string
• Pass merchantCustId explicitly to bind customer and subscription relationship

{
  "merchantNo": "800209",
  "merchantTxnId": "SUB-ORDER-20260313-0001",
  "merchantTxnTime": "2026-03-13 10:00:00",
  "merchantCustId": "CUST-10001",
  "orderAmount": "5.00",
  "orderCurrency": "USD",
  "productType": "CARD",
  "subProductType": "SUBSCRIBE",
  "txnType": "SALE",
  "txnOrderMsg": "{\"appId\":\"YOUR_APP_ID\",\"returnUrl\":\"https://merchant.example.com/return\",\"notifyUrl\":\"https://merchant.example.com/webhook\"}",
  "billingInformation": "{\"email\":\"customer@example.com\",\"country\":\"US\"}",
  "shippingInformation": "{\"email\":\"customer@example.com\",\"country\":\"US\"}",
  "subscription": "{\"requestType\":\"0\",\"merchantCustId\":\"CUST-10001\",\"productName\":\"Pro Plan Monthly\",\"frequencyType\":\"M\",\"frequencyPoint\":\"1\",\"cycleCount\":12,\"selfExecute\":\"1\",\"mode\":\"2\",\"notificationEmail\":\"customer@example.com\"}",
  "sign": "YOUR_SIGNATURE"
}

After order creation succeeds, return these fields to the frontend for SDK initialization:

• transactionId
• redirectUrl

Subscription parameter guidance (subscription) Server-side

To avoid confusion, interpret parameters as shared fields + mode-specific fields.

Shared fields (recommended to confirm first in both modes)

Managed subscription fields (selfExecute = "1")

Self-managed subscription fields (selfExecute = "2")

Initialize the SDK on the frontend (SUBSCRIBE mode) Client-side

const pacypay = new Pacypay(transactionId, {
  container: 'onerway_checkout',
  locale: 'zh-cn',
  environment: 'sandbox',
  mode: 'CARD',
  redirectUrl: redirectUrlFromServer,
  config: {
    subProductType: 'SUBSCRIBE'
  },
  onPaymentCompleted: function (result) {
    const { respCode, respMsg, data } = result || {};
    if (respCode !== '20000') {
      console.error('Subscription request failed:', respMsg);
      return;
    }

    if (data?.status === 'R' && data?.redirectUrl) {
      window.location.replace(data.redirectUrl);
      return;
    }

    if (data?.status === 'S') {
      // For frontend UX feedback only. Use webhook as the final state source of truth.
      console.log('Subscription submitted successfully. Waiting for webhook confirmation.');
    }
  },
  onError: function (error) {
    console.error('SDK error:', error);
  }
});

Handle SDK callbacks and 3DS redirects Client-side Server-side

When the SDK callback returns status = "R":

1. Read redirectUrl
2. Redirect immediately to the 3DS verification page
3. The customer completes verification and returns to returnUrl
4. The server waits for webhook confirmation of final status

Responsibility boundary (Must / Must not):

Receive and process webhooks (idempotency required) Server-side

In SDK subscription scenarios, webhooks may include:

• txnType = "BIND_CARD": card-binding result (typically for credential setup)
• txnType = "SALE": initial payment or renewal charge result

If subscription-related binding is enabled, the initial stage may return two notifications (BIND_CARD + SALE) and arrival order is not guaranteed.

@PostMapping(value = "/webhook", produces = "text/plain")
public String handleWebhook(@RequestBody Map<String, Object> body) {
    String transactionId = (String) body.get("transactionId");
    String txnType = (String) body.get("txnType");
    String status = (String) body.get("status");

    if (!verifySignature(body)) return "";
    if (alreadyProcessed(transactionId, txnType)) return transactionId;

    if ("BIND_CARD".equals(txnType) && "S".equals(status)) {
        saveTokenId((String) body.get("merchantCustId"), (String) body.get("tokenId"));
    }

    if ("SALE".equals(txnType)) {
        handleSubscriptionSale(body); // Parse scenarios / subscriptionStatus / contractId
    }

    markProcessed(transactionId, txnType);
    return transactionId;
}

Subscription event-to-action mapping

Use webhook field scenarios to identify subscription lifecycle events:

Key field and config quick reference

Wallet subscriptions (Google Pay / Apple Pay)

SDK subscriptions also support wallet payments. Core rules stay the same:

• Subscription requests still use subProductType = "SUBSCRIBE" (DIRECT for non-subscription transactions)
• Webhooks remain the transaction source of truth (do not rely on SDK sync callbacks only)
• Wallet payments usually do not go through traditional 3DS challenges, but you still need failure handling and async notification processing

const pacypay = new Pacypay(transactionId, {
  container: 'onerway_checkout',
  locale: 'zh',
  environment: 'sandbox',
  mode: 'GooglePay',
  redirectUrl: redirectUrlFromServer,
  config: {
    subProductType: 'SUBSCRIBE',
    googlePayButtonType: 'subscribe',
    googlePayButtonColor: 'black',
    googlePayEnvironment: 'TEST'
  }
});

Test checklist

• Confirm the server request sets subProductType to SUBSCRIBE
• Confirm the subscription field is serialized correctly and passes signature verification
• Confirm the frontend receives transactionId and redirectUrl and initializes the SDK successfully
• Confirm status = "R" can complete 3DS redirect and return flow correctly
• Confirm initial transactions receive and process SALE notifications
• Confirm BIND_CARD and SALE notifications are both handled when binding-related capabilities are enabled
• Confirm repeated webhook deliveries do not create duplicate side effects (idempotency)
• Confirm out-of-order BIND_CARD and SALE notifications are handled correctly
• Confirm scenarios can drive activation, renewal, cancellation, and expiration logic correctly
• Confirm mode and button configuration are effective in Google Pay / Apple Pay mode
• Confirm WebView scenarios (if applicable) can redirect to the system browser and return correctly
• Confirm webhook reconciliation can distinguish wallet source through walletTypeName

Best practices

1. Treat SDK callbacks as frontend UX events, and webhook verification results as business final-state events.
2. Build a traceable data model for contractId, tokenId, and subscriptionManageUrl, and bind it to merchantCustId.
3. In managed mode, prioritize notification handling and status synchronization. In self-managed mode, prioritize renewal scheduling and retry strategies.
4. Enable trials only when product policy is explicit, to avoid conflicts between trial logic and billing logic.
5. Before launch, at minimum cover success, failure, 3DS, duplicate notifications, out-of-order notifications, and network jitter scenarios.