# 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`](https://docs.unipaas.com/reference/payinplancontroller_createpayinplan) 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:  

```json
{
  "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": "month",
  "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`](https://docs.unipaas.com/reference/websdkpayincontroller_createcheckout) 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:  

```json
{
 "country": "GB",
 "email": "user@example.com",  
 "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
}
```

<br />

**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:

1. *Verify Capture status:* Check if`authorizationStatus: "Captured"` then mark the payment as successful in your database . This status confirms the payment has been successfully captured.
2. *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). 
3. *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.
4. *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: 

1. *Extract and store the`consumerId`* against the  `consumer.reference` supplied in Step 2. 
2. For subsequent transactions, pass the `consumerId` in checkout session [`POST /pay-ins/checkout`](https://docs.unipaas.com/reference/websdkpayincontroller_createcheckout)

Webhook Example Payload:  

```json
{
  "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": "user@example.com"
}
```

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/`](https://docs.unipaas.com/reference/websdkpayincontroller_createpayin) 

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

Payload Example:  

```json
{  
  "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": "user@googlemail.com",  
    "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:

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

Webhook Example Payload:  

```json
{
  "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": "user@googlemail.com"
}
```