Use Tokens from Subscription for Unscheduled MITs

Using Unipaas, you can do unscheduled card-on-file transactions using a subscriptions saved card details. This guide provides a step-by-step approach to integrating subscription management and using the saved card details to make future MITs. Both capabilities enable efficient management of recurring and further on-demand payments.By following these steps, you can seamlessly integrate subscriptions and card-on-file functionalities into your application.

Step 1: Create a Plan

This API call serves as the foundation for setting up a subscription.

Define a plan POST /pay-ins/plans to establish pricing, billing cycles, and other details by passing in the following in the payload:

name: Name of the subscription plan.
periodUOM and period: Define the billing frequency.
autoRenewal: Whether the subscription renews automatically.
pricingModel: Set as fixed for subscriptions which do not change over time or set as ramp for subscriptions which change after certain no. of cycles.

Payload Example:

{
  "vendorId": "66d8869bdd0d32ab4e43c4ec", // This is the vendorId of the user on your platform
  "name": "Premium Plan",
  "description": "Access to all premium features",
  "currency": "GBP",
  "period": 12,
  "periodUOM": "months",
  "pricingModel": "ramp",
  "rampIntervals": [
    {
      "unitAmount": 10,
      "cycles": 3
    },
{
      "unitAmount": 20,
      "cycles": 3
    },
{
      "unitAmount": 30,
      "cycles": 6
    }
  ],
  "autoRenewal": false,
  "setupFee": 40
}

For further details, refer to the Subscriptions Guide.

Step 2: Create a Checkout Session
Initiate a checkout session POST /pay-ins/checkout with the created plan. This step captures customer payment details and subscribes them to the selected plan.

Key Parameters:
plans: Array of plan IDs (e.g., the ID created in Step 1).
consumer.reference: Unique identifier for the consumer/buyer on your system.
reference: Unique order ID / payment ID on your system.
This step generates a checkout session for the customer to complete.

Payload Example:

{
 "country": "GB",
 "email": "[email protected]",  
 "paymentMethods": ["card"],
 "shippingSameAsBilling": true, 
 "reference": "1000456", // Platform order ID OR platform payment ID
 "consumer": {
   "reference": "45684r3453456513543546546" // Unique ID of the buyer on your system
 },
 "plans": [
   "6751e3c1f7180997ad5c0f9c" // This is the planId from Step 1
 ],
  "vendorId": "66d8869bdd0d32ab4e43c4ec" // This is the vendorId of the user on your platform
}

Step 3: Handle the Authorization/Update Webhook

After successful checkout completion, UNIPaaS sends an authorization/update webhook to your server with crucial payment authorization details.

To ensure your platform reflects the updated status of the transaction:

Verify Capture status: Check ifauthorizationStatus: "Captured" then mark the payment as successful in your database . This status confirms the payment has been successfully captured.
Extract and store the paymentOption.id against the consumer.reference supplied in Step 2. This ID is token of the payment method and used for initiating future MITs (Merchant Initiated Transactions).
Save Subscription ID: Save subscriptionId field from the initial transaction. Use this to track subsequent transactions on your system and to update/cancel the subscription for the end customer.
Extract and use orderid to associate the the checkout with the Unique order ID / payment ID on your system.

Note: If you would like to support Card-on-File transactions (show/give an option to use the saved card to the customer for future payments) as well:

Extract and store theconsumerId against the consumer.reference supplied in Step 2.
For subsequent transactions, pass the consumerId in checkout session POST /pay-ins/checkout

Webhook Example Payload:

{
  "authorizationId": "6752d768383576f170cb898f",
  "transactionId": "6752d768383576f170cb89a4",
  "vendorId": "66d8869bdd0d32ab4e43c4ec",
  "authorizationStatus": "Captured",
  "paymentOption": {
    "cardAccount": {
      "brand": "VISA",
      "bin": "400002",
      "last4Digits": "5032",
      "issuerCountry": "GB"
    },
    "id": "6752d762c31925ed37c11738" // This is the token of the saved card
  },
  "currency": "GBP",
  "amount": 50,
  "orderid":"1000456", // This is the Platform order ID OR platform payment ID(reference) in Step 2
  "checkoutId": "DRe0gsR9A-",
  "items": [],
  "planId": "6752d6ecf7180997ad5c107d",
  "subscriptionId": "6752d768f7180997ad5c108c",
  "metadata": {},
  "paymentMethod": "creditCard",
  "consumerId": "6752d761145ad6c0f8f5a317",
  "consumerEmail": "[email protected]"
}

Refer to the Additional Webhooks Documentation for more information.

Payment with a token

Step 4: 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.id to POST /pay-ins/

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

Payload Example:

{  
  "amount": 23.99,  
  "currency": "GBP",  
  "country": "GB",  
  "description": "Task Booking Id 19168",  
  "vendorId": "66d8869bdd0d32ab4e43c4ec",  
  "paymentOptionId": "6752d762c31925ed37c11738",  
  "reference": "19168",   // This is the Platform order ID OR platform payment ID
  "consumer": {  
    "email": "[email protected]",  
    "firstName": "User",  
    "lastName": "Test",
    "country": "GB"  
  }  
}

Step 5: Handle the Authorization/Update Webhook

Similar to Step 3, after successful payment, UNIPaaS sends an authorization/update webhook to your server with payment authorization details.

To ensure your platform reflects the updated status of the transaction:

Verify Capture status: Check ifauthorizationStatus: "Captured" then mark the MIT payment as successful in your database . This status confirms the payment has been successfully captured.
Extract and use orderid to associate the the MIT payment with the Unique order ID / payment ID on your system.

Webhook Example Payload:

{
  "authorizationId": "675c23257a7107ef64a29062",
  "transactionId": "675c23257a7107e22ba29067",
  "vendorId": "66d8869bdd0d32ab4e43c4ec",
  "authorizationStatus": "Captured",
  "paymentOption": {
    "cardAccount": {
      "brand": "VISA",
      "bin": "400002",
      "last4Digits": "5032",
      "issuerCountry": "GB"
    },
    "id": "6752d762c31925ed37c11738" // This is the token of the saved card
  },
  "currency": "GBP",
  "amount": 23.99,
  "orderid":"19168", // This is the Platform order ID OR platform payment ID(reference) in Step 4
  "items": [],
  "description": "Task Booking Id 19168",  
  "paymentMethod": "creditCard",
  "consumerId": "6752d761145ad6c0f8f5a317",
  "consumerEmail": "[email protected]"
}