SDK Authorization

SDK Authorization allows merchants to reserve customer funds first and decide whether to complete the actual debit later. This process follows a similar flow to regular transactions but requires specific configuration.

API Request Parameters

POST

Important Note

The key difference between standard payment transactions and authorization transactions is the txnType parameter:

For one-time payment transactions: txnType: 'SALE'
For authorization transactions: txnType: 'AUTH'

SDK Integration Process

The integration process for authorization transactions follows the same general pattern as standard Payment Intent Creation:

Authorization Intent Creation: Create an authorization intent on your server with txnType: 'AUTH'
SDK Payment Process: Initialize the SDK with the received transactionId and redirectUrl
Authorization Result Notification: Process the authorization result via webhook and store the transactionId
Capture Processing: Send a separate capture request via the Capture API to complete the payment

Important Note

Authorization transactions only reserve funds without transferring them. To complete the payment, merchants must explicitly send a capture request using the original transactionId as reference.

Authorized funds are typically held for 7 days (varies by card issuer) before being automatically released if not captured.

API Usage Examples

RequestResponse

json

{
    "billingInformation": "{\"address\":\"969 Cedar Street\",\"city\":\"Bernierville\",\"country\":\"US\",\"email\":\"Kiarra.King@yahoo.com\",\"firstName\":\"Keeley\",\"identityNumber\":\"91266607415\",\"lastName\":\"Mayer\",\"phone\":\"17463110652\",\"postalCode\":\"14990\",\"province\":\"CO\"}",
    "merchantCustId": "CustId-7O58-5XVK",
    "merchantNo": "800209",
    "merchantTxnId": "a878e562-b2e5-48f2-95a3-e0ebd626af2b",
    "merchantTxnTime": "2025-05-05 16:56:49",
    "orderAmount": "3",
    "orderCurrency": "USD",
    "productType": "CARD",
    "shippingInformation": "{\"address\":\"4429 Jameson Gateway\",\"city\":\"Brandon\",\"country\":\"US\",\"email\":\"Jerod.Rippin@hotmail.com\",\"firstName\":\"Rasheed\",\"identityNumber\":\"80749336470\",\"lastName\":\"Schmitt\",\"phone\":\"17028187067\",\"postalCode\":\"02643\",\"province\":\"CO\"}",
    "sign": "a1682caaae4eaffe8f94c6fd9c3ee3a7734a81bc51263702801220d651e7e871",
    "subProductType": "DIRECT",
    "txnOrderMsg": "{\"accept\":\"*/*\",\"appId\":\"1727880846378401792\",\"colorDepth\":\"32\",\"contentLength\":\"4096\",\"javaEnabled\":true,\"language\":\"en-US\",\"products\":\"[{\\\"currency\\\":\\\"USD\\\",\\\"name\\\":\\\"fig\\\",\\\"num\\\":\\\"37\\\",\\\"price\\\":\\\"382.49\\\",\\\"type\\\":\\\"et eiusmod\\\"},{\\\"currency\\\":\\\"USD\\\",\\\"name\\\":\\\"snowpea\\\",\\\"num\\\":\\\"18\\\",\\\"price\\\":\\\"219.70\\\",\\\"type\\\":\\\"sunt aliqua Ut dolore\\\"}]\",\"returnUrl\":\"https://docs.onerway.com/\",\"notifyUrl\":\"https://docs.onerway.com/apis\",\"screenHeight\":\"1366\",\"screenWidth\":\"2048\",\"timeZoneOffset\":\"720\",\"transactionIp\":\"155.187.249.120\",\"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": "AUTH" // Set to AUTH for authorization transaction
}

json

{
    "respCode": "20000",
    "respMsg": "Success",
    "data": {
        "transactionId": "1919315397308710912", // Use for SDK initialization
        "responseTime": "2025-05-05 16:57:04",
        "txnTime": null,
        "txnTimeZone": "+08:00",
        "orderAmount": "3.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": "046f492c0a939c06c0ff33e197eecb04ef258974d554e9beb86fd36c44fc6ffc"
    }
}

SDK Initialization

After creating an authorization transaction, initialize the SDK with the received transactionId and redirectUrl:

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: {
      // Standard configuration options
    },
    onPaymentCompleted: function(result) {
      // Handle authorization completion
      const authResult = result.data;
      
      if(result.respCode === '20000') {
        // Process successful response
        if(authResult.status === 'S') {
          // Authorization successful
          console.log('Authorization successful');
          // Store transactionId for subsequent capture
          console.log('Auth transaction ID:', authResult.transactionId);
        } else if(authResult.status === 'R') {
          // 3DS verification required
          console.log('3DS verification required');
          window.location.href = authResult.redirectUrl;
        }
      } else {
        console.error('Authorization failed:', result.respMsg);
      }
    },
    onError: function(error) {
      console.error('SDK error:', error);
    }
  });
};

Understanding the Authorization Flow

Authorization transactions (txnType: 'AUTH') only reserve funds, they do not immediately debit
To complete the transaction, merchant must send a capture request (using the Capture API)
Authorized funds are typically held for 7 days (varies by card issuer) before being automatically released
Merchants should store the authorization transaction's transactionId for subsequent capture requests

SDK Callback Response Examples

When the user completes the SDK payment process, the callback will return authorization results, which may require 3DS verification.

SDK Callback - 3DS RequiredSDK Callback - Authorization Success

json

{
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "transactionId": "1919315843586850816",
    "responseTime": "2025-05-05 16:59:18",
    "txnTime": "2025-05-05 16:58:50",
    "txnTimeZone": "+08:00",
    "orderAmount": "45.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_8002091919315955817775105", // 3DS verification page URL
    "contractId": null,
    "tokenId": null,
    "eci": null,
    "periodValue": null,
    "codeForm": null,
    "presentContext": null,
    "actionType": "RedirectURL",
    "subscriptionManageUrl": null,
    "sign": null
  }
}

json

{
  "respCode": "20000",
  "respMsg": "Success",
  "data": {
    "transactionId": "1919315843586850816",
    "responseTime": "2025-05-05 17:03:11",
    "txnTime": "2025-05-05 16:59:16",
    "txnTimeZone": "+08:00",
    "orderAmount": "45.00",
    "orderCurrency": "USD",
    "txnAmount": null,
    "txnCurrency": null,
    "status": "S", // 'S' indicates authorization success
    "redirectUrl": null,
    "contractId": null,
    "tokenId": null,
    "eci": "05",
    "periodValue": null,
    "codeForm": null,
    "presentContext": null,
    "actionType": null,
    "subscriptionManageUrl": null,
    "sign": null
  }
}

Webhook Notification Example

After a successful authorization, you will receive a webhook notification similar to the following:

json

{
  "notifyType": "TXN",
  "transactionId": "1919315843586850816", // Auth transaction ID for subsequent capture
  "txnType": "AUTH", // Transaction type is AUTH
  "merchantNo": "800209",
  "merchantTxnId": "1746435530000",
  "responseTime": "2025-05-05 17:03:11",
  "txnTime": "2025-05-05 16:59:16",
  "txnTimeZone": "+08:00",
  "orderAmount": "45.00",
  "orderCurrency": "USD",
  "status": "S", // 'S' indicates success
  "eci": "05",
  "cardBinCountry": "US",
  "reason": "{\"respCode\":\"20000\",\"respMsg\":\"Success\"}",
  "sign": "887426ee2d07a993a429d73b64fbfc5b7f7c81505e87f9c9da6043c193a79107",
  "paymentMethod": "VISA",
  "channelRequestId": "8002091919315955817775105"
}

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

Implementation Best Practices