Create and use tokens with Unipaas

To tokenise card details, you need to include additional details in the /checkout request. If the payment request is processed successfully, you will receive a webhook containing the token which can be used for future payments. This token can be used for offering a faster checkout experience for for a returning customer, charge customers for subscriptions or automatic top-up payments.

Create a token

Step 1:Create a Checkout Session with set parameters

Initiate a checkout session POST /pay-ins/checkout with the following parameters to flag transactions:

storePaymentMethod: Set to true for initial transaction to store the shopper's payment details. For subsequent transactions, this parameter is not required.

reference: This is a unique transaction/order ID on your system.

This step generates a checkout session for the customer to complete a payment and the card used will be tokenized.

Note: If you want to store a card without a payment, set "amount": 0 in the /checkout request

Payload Example:

{  
  "country": "GB",
  "amount": 100, // Set 0 for saving the card without making a payment
  "currency": "GBP",  
  "email": "[email protected]",  
  "shippingSameAsBilling": true,
  "storePaymentMethod": true,
  "reference":"1000456",
  "vendorId": "66d8869bdd0d32ab4e43c4ec" // This is the vendorId of the user on your platform
}

Step 2:Handle the Authorization/Update Webhook
After successful checkout completion, UNIPaaS sends an authorization/update webhook to your server. This webhook contains crucial payment authorization details. Securely extract and store the paymentOption.id and store it against the reference. This ID is critical for initiating future MITs (Merchant Initiated Transactions).

For use case where you want to show saved cards to the customer for further CITs (Customer Initiated Transactions), securely extract and store the consumerId as well.

Webhook Example Payload:

{  
  "authorizationId": "66ebce1a19e6b90e82af68a9",  
  "transactionId": "66f50d79565de0367019477d",  
  "vendorId": "66d8869bdd0d32ab4e43c4ec",    
  "authorizationStatus": "Captured",  
  "paymentOption": { 
    "cardAccount": {  
      "brand": "VISA",  
      "bin": "400002",  
      "last4Digits": "5032",  
      "issuerCountry": "GB"  
    },
    "id": "66f50d75f737bd0abaf94423", // Store for future MITs
  },  
  "currency": "GBP",  
  "amount": 100,  
  "orderid": "123456",  
  "checkoutId": "eGxiMmLfOn",  
  "paymentMethod": "creditCard",  
  "consumerId": "66f50d75f737bd0abaf90b89", // Store for future CITs
  "consumerEmail": "[email protected]",
  "reference": "1000456"
}  

Refer to the Additional Webhooks Documentation for more information.

You can use the above information to do future MITs/CITs. Depending on your use case/cases, implement Step 3 and/or Step 4 below.

Payment with a token

Step 3: Process Unscheduled Merchant-Initiated Transactions (MIT)
To charge customers later without requiring their involvement (e.g., for additional services or usage-based fees), send a server-to-server request including the stored paymentOption.idin the /pay-ins request POST /pay-ins/

Key Parameters:
paymentOptionId: Retrieved from the webhook in Step 2.

Payload Example

{  
  "amount": 23.99,  
  "currency": "GBP",  
  "description": "Task Booking Id 19168",  
  "vendorId": "66d8869bdd0d32ab4e43c4ec",  // This is the vendorId of the user on your platform
  "paymentOptionId": "66f50d75f737bd0abaf94423",
  "consumerId": "66f50d75f737bd0abaf90b89",
  "consumer": {  
    "email": "[email protected]",  
    "firstName": "User",  
    "lastName": "Test",
    "country": "GB"
  }  
}  

Payment with a saved card

Step 4: Process Unscheduled Customer-Initiated Transactions (CIT)

To let customers use their saved cards for future payments (e.g., for additional purchases), create a /checkout session POST /pay-ins/checkout including the consumerId.

Key Parameters:
consumerId: Retrieved from the webhook in Step 2.

Payload Example

{  
  "country": "GB",
  "amount": 100,
  "currency": "GBP",  
  "email": "[email protected]",  
  "shippingSameAsBilling": true,
  "reference":"1000789",
  "consumerId": "66f50d75f737bd0abaf90b89",
  "vendorId": "66d8869bdd0d32ab4e43c4ec" // This is the vendorId of the user on your platform
}

Update stored (tokenised) card for a customer

Unipaas provides the functionality to update a customer's saved (tokenised) card. Follow the steps below if you would like to give your customers this flexibility.

Update a tokenised card

Step 5: Initiate a Checkout Session

In order to update a saved (tokenised) card for a customer, initiate a Checkout Session POST /pay-ins/checkout with the following parameters:

storePaymentMethod: Set to true to store the shopper's payment details. For subsequent transactions, this parameter is not required.

reference: This is a unique transaction/order ID on your system.

consumerId: Retrieved from the webhook in Step 2.

amount: Set to "0" in the /checkout request.

Payload Example:

{  
  "country": "GB",
  "amount": 0,
  "currency": "GBP",  
  "email": "[email protected]",  
  "shippingSameAsBilling": true,
  "storePaymentMethod": true,
  "reference":"PL-6fed969621",
  "consumerId": "66f50d75f737bd0abaf90b89", // Retreived in Step 2
  "vendorId": "66d8869bdd0d32ab4e43c4ec" // This is the vendorId of the user on your platform
}

Step 6: Handle the Authorization/Update Webhook
After a successful authorisation, UNIPaaS sends an authorization/update webhook with "authorizationStatus": "Authorized" to your server. This webhook contains payment authorization details for the customer's updated tokenised card. Securely extract and update the existing paymentOption.id for this customer with this new value. Use this new ID for initiating future MITs (Merchant Initiated Transactions).

Webhook Example Payload:

{
  "authorizationId": "6772c8b1fd73903ce84f664f",
  "transactionId": "6772c8e6fd7390bc164f6663",
  "vendorId": "66d8869bdd0d32ab4e43c4ec",
  "authorizationStatus": "Authorized",
  "paymentOption": {
    "cardAccount": {
      "brand": "MASTERCARD",
      "bin": "222100",
      "last4Digits": "7736",
      "issuerCountry": ""
    },
    "id": "6772c8b0aa6ed1e6de4bc81e" // Update existing ID on your system and use for future MITs
  },
  "currency": "GBP",
  "amount": 0,
  "orderid": "PL-6fed969621",
  "checkoutId": "DGaL5n5oUN",
  "items": [],
  "paymentMethod": "creditCard",
  "consumerId": "66f50d75f737bd0abaf90b89", // Use for future CITs
  "consumerEmail": "[email protected]"
}  

Refer to the Additional Webhooks Documentation for more information.

Follow Step 3 and Step 4 to make payments with the updated card for future MITs or CITs.