Guides
GuidesAPI ReferenceCreate Your Account

Create Plans and Subscriptions

Suggest Edits

Implementation

Step 1: Create a plan:

During plan creation, determine who the plan owner will be.

Use cases:

  • Create a plan for your platform e.g. to collect subscription fees from your users.
  • Create a plan on behalf of your users e.g. where the user/vendor collects payments/subscription fees from the end customer/buyer.

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

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

Main plan fields:

NameTypeDescription
nameStringPlan name
descriptionStringPlan description
priceDecimalPlan price amount
currencyStringCurrency standard ISO 4217
periodUOMEnum stringDefines the billing cycle type (days, weeks, months, years)
periodIntegerThe length of the plan in 'PeriodUOM' units
trialUOM
(Optional)		Enum stringDefines trial period cycle type (days, weeks, months, years)
trial Period
(Optional)		IntegerThe length of the trial period in 'PeriodUOM' units
statusEnum stringDefines the status of the plan
autoRenewalBooleanDefines auto-renewal
vendorIdStringvendor ID of the user OR platform ID of the platform
pricingModelStringDefines the model (ramp or fixed

Key Parameters:

  • vendorId - Use vendorId of your user (from /vendor API) when creating a plan on behalf of your user
    OR Platform ID (Found in User profile > "Account Details" in the top right corner of the Portal)

Example of a request payload

{
  "name": "Premium Plan for all",
  "description": "Access to all premium features",
  "group": "Group Name",
  "country": "GB",
  "currency": "GBP",
  "period": 12,
  "periodUOM": "months",
  "autoRenewal": false,
  "vendorId": "66d8869bdd0d32ab4e43c4ec",// This is the Platform ID or vendorId
  "pricingModel": "ramp",
  "rampIntervals": [
    {
      "unitAmount": 10,
      "cycles": 3
    },
{
      "unitAmount": 20,
      "cycles": 3
    },
{
      "unitAmount": 30,
      "cycles": 6
    }
  ],
    "setupFee": 40
}

Response

{
    "consent": "By subscribing, you authorize PlatformName to charge your selected payment method as outlined in their terms and conditions. You can cancel your subscription at any time.",
    "setupFee": 40,
    "rampIntervals": [
        {
            "unitAmount": 10,
            "cycles": 3
        },
        {
            "unitAmount": 20,
            "cycles": 3
        },
        {
            "unitAmount": 30,
            "cycles": 6
        }
    ],
    "pricingModel": "ramp",
    "autoRenewal": false,
    "trialPeriod": 0,
    "periodUom": "months",
    "period": 12,
    "currency": "GBP",
    "group": "Group Name",
    "description": "Access to all premium features",
    "name": "Premium Plan for all",
    "status": "active",
    "vendorId": "66d8869bdd0d32ab4e43c4ec",// This is the Platform ID or vendorId
    "merchantName": "PlatformName",
    "merchantId": "PlatformId",
    "id": "67891400cb2350877f51ca15",
    "createdAt": "2025-01-16T14:13:20.311Z",
    "updatedAt": "2025-01-16T14:13:20.311Z"
}

Note: Once the plan is created, the subsequent steps remain the same for both scenarios.

Step 2: Create a Checkout for the Subscription

Once a plan is created, subscriptions can be attached to it. To proceed, initiate a Checkout Create request. This request generates a checkout UI (hosted or embedded), enabling the payer to either create a new payment method or select an existing one while providing their consent for the subscription. This ensures the subscription is successfully linked to the payer with an active payment method.

Make a POST/pay-ins/checkout request to create a checkout for the subscription.

Key Parameters:

NameTypeRequiredDescription
plansArrayYes
paymentMethodsArrayNo
consumer.referenceStringYes
consumer.nameStringNo
consumer.emailStringNo
successfulPaymentRedirectStringNo
countryStringYesISO31661 Alpha2 code

Example of a request payload

{
 "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
    "name": "John Doe",
    "email": "[email protected]"
 },
 "plans": [
   "6751e3c1f7180997ad5c0f9c" // This is the planId from Step 1
 ],
  "successfulPaymentRedirect": "https://platform.com/redirect"
}

Response

{
    "vendor": {
        "name": "John Doe",
        "email": "[email protected]",
        "country": "GB"
    },
    "status": "open",
    "mode": "online",
    "plans": [
        {
            "id": "6752d6ecf7180997ad5c107d"
        }
    ],
    "isMoto": false,
    "id": "6752d71bca2ec7447f9c6d85",
    "country": "GB",
    "paymentMethods": [
        "card"
    ],
    "reference": "1000456",
    "amount": 41,
    "currency": "GBP",
    "totalAmount": 90,
    "totalPaid": 0,
    "expiresAt": "2025-06-04T10:51:07.000Z",
    "shortLink": "https://sandbox-checkout.unipaas.com/DRe0gsR9A-/",
    "merchantId": "66d58bd06098898a5de10bdc",
    "signedLinkId": "DRe0gsR9A-",
    "items": [],
    "createdAt": "2024-12-06T10:51:07.974Z",
    "updatedAt": "2025-01-16T14:55:24.889Z",
    "successfulPaymentRedirect": "https://platform.com/redirect",
    "sessionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJtZXJjaGFudElkIjoiNjZkNThiZDA2MDk4ODk4YTVkZTEwYmRjIiwibWVyY2hhbnROYW1lIjoiTmlja3kgRGhhbGl3YWwiLCJhbW91bnQiOjQxLCJjdXJyZW5jeSI6IkdCUCIsImVtYWlsIjoidXNlckBleGFtcGxlLmNvbSIsImNvdW50cnkiOiJHQiIsInNlbGxlcklkIjoiNjZkODg2OWJkZDBkMzJhYjRlNDNjNGVjIiwidmVuZG9ySWQiOiI2NmQ4ODY5YmRkMGQzMmFiNGU0M2M0ZWMiLCJ0b2tlbk9ubHkiOnRydWUsInNjb3BlcyI6WyJ3ZWJzZGtfYWNjZXNzIiwiZGlyZWN0X2RlYml0X3JlYWQiLCJkaXJlY3RfZGViaXRfd3JpdGUiXSwicGF5bWVudE1ldGhvZHMiOlsiY3JlZGl0Q2FyZCJdLCJpc1JlY3VycmluZyI6dHJ1ZSwicGxhbnMiOlsiNjc1MWUzYzFmNzE4MDk5N2FkNWMwZjljIl0sImNvbnN1bWVyIjp7InJlZmVyZW5jZSI6IjQ1Njg0cjM0NTM0NTY1MTM1NDM1NDY1NDYifSwiZW52Ijoic2FuZGJveCIsInBheW1lbnRMaW5rSWQiOiJEUmUwZ3NSOUEtIiwiaWF0IjoxNzM3MDM5MzI0LCJleHAiOjE3MzcxMjU3MjR9.Lx9x4zEETZ9ABq7-AimSnE6SBTVUKkodJ5EvKKKIC2M",
    "qrPaymentLink": "https://sandbox.unipaas.com/platform/qr-code/generate?url=https://sandbox-checkout.unipaas.com/DRe0gsR9A-/",
    "vendorId": "66d8869bdd0d32ab4e43c4ec",
    "consumer": {
        "email": "[email protected]",
        "firstName": "",
        "lastName": "",
        "name": "",
        "billingAddress": {
            "country": "GB"
        },
        "shippingSameAsBilling": true,
        "reference": "45684r3453456513543546546"
    }
}

Store the following from the response:

  • shortLink - This URL should be used if you want to using the Unipaas redirect the customer to the Hosted Checkout page.
  • sessionToken - This session token should be used for authorization if you are implementing our Subscription Checkout UI web embeds.

Step 3: Display the Checkout to the Customer

Unipaas offers 2 options to show the checkout to the customer:

Hosted checkout page

To use our hosted checkout, save theshortLink from Step 2 and share it directly with payers. The hosted checkout will handle the UI logic, including displaying available payment methods, plan details, trial period and determining the flow based on whether the user is new or returning.
For more information: Checkout Page

Subscription Checkout UI Web Embed

To use our checkout UI web embed, refer to the following documentation. The checkout UI web embed will manage the UI logic, including displaying available payment methods, handling plan details, and determining the flow based on whether the user is new or returning.


Step 4: 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:

  1. Verify Capture status: Check ifauthorizationStatus: "Captured" then mark the payment as successful in your database . This status confirms the payment has been successfully captured.
  2. 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.
  3. Extract and use orderid to associate the the checkout with the Unique order ID / payment ID on your system.

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

Next steps:

📘

Update Plan

📘

Update Subscription

See also:

📘

To use Tokens from Subscription for Unscheduled MITs

Updated 3 days ago