English

简体中文

English

简体中文

Theme

Card Binding ​

Card binding allows merchants to securely store customer payment card information for future use. This process follows a similar flow to regular transactions but with a specific configuration.

API Request Parameters ​

POST

Important Note

The key difference between standard payment intent creation and card tokenization is the subProductType parameter:

  • For one-time payment transactions: subProductType: 'DIRECT'
  • For card tokenization: subProductType: 'TOKEN'

SDK Integration Process ​

The integration process for card binding follows the same three phases as standard Payment Intent Creation:

  1. Card Binding Intent Creation: Create a binding intent on your server with subProductType: 'TOKEN'
  2. SDK Binding Process: Initialize the SDK with the received transactionId and redirectUrl
  3. Binding Result Notification: Process the binding result and store the tokenId for future use

Important Note

When using TOKEN for card binding with payment, the system actually creates two transactions:

  1. A card binding transaction that generates a tokenId
  2. An actual payment transaction using the same transactionId that was used to initialize the SDK

As a result, you will receive two separate webhook notifications:

  • One for the card binding result
  • Another for the payment result

API Usage Examples ​

json
{
    "billingInformation": "{\"address\":\"8113 Kirlin Oval\",\"city\":\"Effertzstead\",\"country\":\"US\",\"email\":\"Deanna_Rau7@hotmail.com\",\"firstName\":\"Kadin\",\"identityNumber\":\"08598216906\",\"lastName\":\"Kris-Gerlach\",\"phone\":\"18829380147\",\"postalCode\":\"61269-8747\",\"province\":\"CO\"}",
    "merchantCustId": "CustId-JUWS-33EG",
    "merchantNo": "800209",
    "merchantTxnId": "d3e85f48-d32e-4463-a37c-674b5bf73b07",
    "merchantTxnTime": "2025-05-05 15:11:42",
    "orderAmount": "954",
    "orderCurrency": "USD",
    "productType": "CARD",
    "shippingInformation": "{\"address\":\"17833 Schneider Ways\",\"city\":\"Fort Agustinworth\",\"country\":\"US\",\"email\":\"Fernando_Harris36@yahoo.com\",\"firstName\":\"Darian\",\"identityNumber\":\"88739539890\",\"lastName\":\"Steuber\",\"phone\":\"17814340062\",\"postalCode\":\"18389-2012\",\"province\":\"CO\"}",
    "sign": "5901fb480730873d6a903ff3ac7840cb8eabd5e87594818710dc0b89831889c4",
    "subProductType": "TOKEN", // Set to TOKEN for card binding
    "txnOrderMsg": "{\"accept\":\"*/*\",\"appId\":\"1727880846378401792\",\"colorDepth\":\"24\",\"contentLength\":\"1024\",\"javaEnabled\":true,\"language\":\"en-US\",\"products\":\"[{\\\"currency\\\":\\\"USD\\\",\\\"name\\\":\\\"blackberry\\\",\\\"num\\\":\\\"42\\\",\\\"price\\\":\\\"259.99\\\",\\\"type\\\":\\\"dolor nulla amet ea commodo\\\"},{\\\"currency\\\":\\\"USD\\\",\\\"name\\\":\\\"starfruit\\\",\\\"num\\\":\\\"74\\\",\\\"price\\\":\\\"809.19\\\",\\\"type\\\":\\\"Excepteur culpa\\\"},{\\\"currency\\\":\\\"USD\\\",\\\"name\\\":\\\"mulberry\\\",\\\"num\\\":\\\"94\\\",\\\"price\\\":\\\"779.79\\\",\\\"type\\\":\\\"anim esse Ut elit Excepteur\\\"}]\",\"returnUrl\":\"https://docs.onerway.com/\",\"notifyUrl\":\"https://docs.onerway.com/apis\",\"screenHeight\":\"740\",\"screenWidth\":\"1680\",\"timeZoneOffset\":\"540\",\"transactionIp\":\"170.236.170.252\",\"userAgent\":\"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/133.0.0.0 Safari/537.36\"}",
    "txnType": "SALE"
}
json
{
    "respCode": "20000",
    "respMsg": "Success",
    "data": {
        "transactionId": "1919288893090693120", // Use for SDK initialization
        "responseTime": "2025-05-05 15:11:45",
        "txnTime": null,
        "txnTimeZone": "+08:00",
        "orderAmount": "954.00",
        "orderCurrency": "USD",
        "txnAmount": null,
        "txnCurrency": null,
        "status": "U",
        "redirectUrl": "https://sandbox-checkout-sdk.onerway.com", // Use for SDK initialization
        "contractId": null,
        "tokenId": null,
        "eci": null,
        "periodValue": null,
        "codeForm": null,
        "presentContext": null,
        "actionType": null,
        "subscriptionManageUrl": null,
        "sign": "5aba208f33d3882789bc26adb7a6fea417dd7ead9650513693336be8bd9b8ed2"
    }
}

SDK Initialization ​

Specific Configuration Options for Card Binding ​

While most configuration options are the same as for standard payment intent creation, these options are particularly relevant for card binding:

javascript
config: {
  subProductType: 'TOKEN', // Required for card binding
  buttonSeparation: true,  // When true: separate binding and payment steps
                          // When false: bind and pay in one step
  hideTokenList: false,    // When false: show previously bound cards
                          // When true: hide bound card list
}

After creating a binding intent via API, initialize the SDK with the TOKEN subProductType:

javascript
// Import the Onerway SDK script
const script = document.createElement('script');
script.src = 'https://checkout-sdk.onerway.com/v3/';
document.body.appendChild(script);

// Create SDK container
const container = document.createElement('div');
container.id = 'onerway_checkout';
document.body.appendChild(container);

// Initialize SDK once loaded
script.onload = function() {
  const pacypay = new Pacypay(transactionId, {
    container: 'onerway_checkout',
    locale: 'en',
    environment: 'sandbox',
    mode: 'CARD',
    redirectUrl: 'REDIRECT_URL_FROM_API',
    config: {
      subProductType: 'TOKEN', // Must be TOKEN for card binding
      buttonSeparation: true,  // Separate binding and payment steps
      hideTokenList: false,    // Show any previously bound cards
      // Additional standard configuration options available
    },
    onPaymentCompleted: function(result) {
      // Handle binding completion
      const bindingResult = result.data;
      
      if(result.respCode === '20000') {
        // Important: Always save the tokenId, even when 3DS verification is required
        if(bindingResult.tokenId) {
          console.log('Card binding tokenId:', bindingResult.tokenId);
          // Store tokenId securely for future tokenized payments
        }
        
        if(bindingResult.status === 'S') {
          // Binding successful - complete process
          console.log('Card binding successful');
        } else if(bindingResult.status === 'R') {
          // 3DS verification required - redirect user but keep tokenId
          console.log('3DS verification required');
          window.location.href = bindingResult.redirectUrl;
        }
      } else {
        console.error('Binding failed:', result.respMsg);
      }
    },
    onError: function(error) {
      console.error('SDK error:', error);
    }
  });
};

Understanding the Card Binding Flow

  1. When initializing the SDK with subProductType: 'TOKEN', a dual process occurs:

    • First, the card information is tokenized (generating a tokenId)
    • Then, the payment is processed using that token

  2. The buttonSeparation parameter controls this flow:

    • true: User first binds the card, then explicitly confirms payment (two-step process)
    • false: User enters card details and payment is processed immediately (one-step process)

  3. The SDK callback contains status information for both processes, but webhook notifications will come separately

SDK Callback Response Example ​

When binding a card, the SDK callback will include a tokenId even when 3DS verification is required. This tokenId should be stored for future tokenized payments.

json
{
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "transactionId": "1919274765789822976",
    "responseTime": "2025-05-05 14:16:24",
    "txnTime": "2025-05-05 14:16:22",
    "txnTimeZone": "+08:00",
    "orderAmount": "75.00",
    "orderCurrency": "USD",
    "txnAmount": null,
    "txnCurrency": null,
    "status": "R", // 'R' indicates 3DS verification required
    "redirectUrl": "https://sandbox-gw-dmz.onerway.com/3dsSecure/direct/RDT_3DS_DDC_8002091919274955627954176", // 3DS verification page URL
    "contractId": null,
    "tokenId": "287eb206feb0a832efa3d637c3dff22578f46999ec6d7788cf9de79ef3102a1e", // Store this tokenId securely
    "eci": null,
    "periodValue": null,
    "codeForm": null,
    "presentContext": null,
    "actionType": "RedirectURL",
    "subscriptionManageUrl": null,
    "sign": null
  }
}
json
{
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "transactionId": "1919275483755073536",
    "responseTime": "2025-05-05 14:19:15",
    "txnTime": "2025-05-05 14:19:05",
    "txnTimeZone": "+08:00",
    "orderAmount": "75.00",
    "orderCurrency": "USD",
    "txnAmount": null,
    "txnCurrency": null,
    "status": "S", // 'S' indicates binding success
    "redirectUrl": null,
    "contractId": null,
    "tokenId": "4b5e7c2f6a9d8b1e2c3f6a9d8b1e2c3f6a9d8b1e2c3f6a9d8b1e2c3f6a9d8b1e", // Store this tokenId securely
    "eci": "05",
    "periodValue": null,
    "codeForm": null,
    "presentContext": null,
    "actionType": null,
    "subscriptionManageUrl": null,
    "sign": null
  }
}

Webhook Notification Examples ​

For card binding with payment, you will receive two webhook notifications:

json
{
  "notifyType": "TXN",
  "transactionId": "1919279964889677824", // Card binding transaction ID
  "txnType": "BIND_CARD", // Transaction type is BIND_CARD
  "merchantNo": "800209",
  "merchantTxnId": "1746426914000",
  "responseTime": "2025-05-05 14:36:18",
  "txnTime": "2025-05-05 14:36:16",
  "txnTimeZone": "+08:00",
  "orderAmount": "0.00",
  "orderCurrency": "USD",
  "status": "S",
  "tokenId": "d057f8e7c1f887a78de8849b30224a95af11ce8c5e7b4b24d4abb471af77d845", // Generated tokenId
  "tokenExpireTime": "2099-12-31 23:59:59",
  "cardBinCountry": "US",
  "reason": "{\"respCode\":\"20000\",\"respMsg\":\"Success\"}",
  "sign": "4f31acdf58e6130da721da40066046b8779164b4acebfdc898832d1e624e9ea4",
  "paymentMethod": "VISA",
  "channelRequestId": "8002091919279971856154624"
}
json
{
  "notifyType": "TXN",
  "transactionId": "1919279706373750785", // Payment transaction ID
  "txnType": "SALE", // Transaction type is SALE
  "merchantNo": "800209",
  "merchantTxnId": "1746426914000",
  "responseTime": "2025-05-05 14:37:29",
  "txnTime": "2025-05-05 14:37:19",
  "txnTimeZone": "+08:00",
  "orderAmount": "75.00", // Actual payment amount
  "orderCurrency": "USD",
  "status": "S",
  "tokenId": "d057f8e7c1f887a78de8849b30224a95af11ce8c5e7b4b24d4abb471af77d845", // Same tokenId for future use
  "eci": "05",
  "cardBinCountry": "US",
  "reason": "{\"respCode\":\"20000\",\"respMsg\":\"Success\"}",
  "sign": "bb0b54950b6244f43cd65ee087cf892a54873f671f658f58b13b087217d247b8",
  "paymentMethod": "VISA",
  "channelRequestId": "8002091919280230334332929"
}

For a complete description of all webhook notification fields received during tokenization transactions, please refer to the Webhook Notification Documentation.

Implementation Best Practices ​

  1. Always use subProductType: 'TOKEN' for card binding operations
  2. Store the returned tokenId securely for future tokenized payments, even before 3DS verification completes
  3. Implement proper 3DS verification handling
  4. Validate all binding responses on your server side
  5. Rely on webhook notifications as the definitive source for binding status
  6. Be prepared to handle two separate webhook notifications when using card binding with payment:
    • A binding webhook with txnType: "BIND_CARD" and zero amount
    • A payment webhook with txnType: "SALE" and the actual payment amount
  7. Implement idempotent processing for webhooks to handle potential duplicate notifications
  8. Use the same tokenId from both webhooks for future tokenized payments