Overview

The Payment API may be used to utilize NMI's recurring module. With the Payment API you may create, update and delete recurring plans or you may create customizable subscriptions for your customers.

This article will go over how to create plans and assign them to a customer for recurring payments and go over the creation of custom subscriptions.

Creating a Plan

With the Payment API you may create set recurring plans which you may then later use these plans to set up recurring payments with customers.

In order to create a plan you will need to utilize the plan variables listed within the recurring section of the Payment API documentation, which may be found here.

Here is an example of what the integration should post to the Payment API:

POST /api/transact.php
  
PARAMS: [
    security_key* : your_security_key
    recurring* : add_plan
    plan_payments* : "The number of payments before the recurring plan is complete."
    
    plan_amount* : "The plan amount to be charged each billing cycle."
    
    plan_name : "The display name of the plan"
    
    plan_id : "The unique plan ID that references only this recurring plan."
    
    day_frequency** : "How often in days will the customer be charged."
    month_frequency*** : "How often, in months, to charge the customer."
    
    day_of_month*** : "The day that the customer will be charged."

]

Parameters marked * are always required, for certain requests
Parameters marked ** required unless 'month_frequency' and 'day_of_month' is set.                                                Parameters marked *** required unless 'day_frequency' is set.

Creating a Subscription Using a Plan

Once you have created plans following the recommendations above, you may now attach customers to your created plans in order to set up recurring payments for your customers. 

To set up a customer with recurring your integration will need to submit a Payment API request including both the recurring and plan_id variables.

Additionally, there are various optional parameters which you may send within the request. For the full list of parameters please review our recurring documentation found here.

Here is an example of what the integration should post to the Payment API:

POST /api/transact.php

  PARAMS: [
    security_key : your_security_key
    recurring : "add_subscription" 
    
    plan_id : "Your Plan Id Here"
    ccnumber : "Credit card number"
    ccexp : "Credit Card Expiration"
]

The example request utilizes ccnumber and ccexp, however, if utilizing Collect.js you may simply pass the payment token.

Custom Subscriptions

Along with the recurring plans, the Payment API allows you to set up custom subscriptions. Custom subscriptions work similar to the recurring plans, however, it allows for a lot more customizability at the time of the subscription creation for each individual customer.

Custom subscriptions are very similar to both processes of the recurring plan. Within your Payment API request you will pass specified parameters in order to configure the subscription plan, while also providing customer information in order to add the customer to the subscription.

Custom subscription are set up per individual unlike a plan, meaning anytime you would like to set a customer up with a subscription you will need to configure the subscription within the request along with providing the customer's payment data. Here is an example of what the integration should post to the Payment API in order to create a custom subscription:

POST /api/transact.php

  PARAMS: [ 
    
  security_key* : your_security_key 
    
  recurring* : add_subscription 
    
  plan_payments* : "The number of payments before the recurring plan is complete."
    
  plan_amount* : "The plan amount to be charged each billing cycle."
    
  day_frequency** : "How often in days will the customer be charged." 
    
  month_frequency*** : "How often, in months, to charge the customer."
    
  day_of_month*** : "The day that the customer will be charged."
    
  ccnumber : "Credit Card Number" 
    
  ccexp : "Credit Card Expiration"

]

Parameters marked * are always required, for certain requests
Parameters marked ** required unless 'month_frequency' and 'day_of_month' is set.                                                Parameters marked *** required unless 'day_frequency' is set.

Cancel/Delete Subscriptions

The Payment API allows for integrators to delete/cancel subscriptions via API requests. Deleting a subscription will stop recurring payments and remove the subscription from the active list. However, you may still find any deleted subscriptions through the merchant gateway account under the recurring section.

Here is an example of what the integration should post to the Payment API in order to delete a subscription:

POST /api/transact.php

  PARAMS: [
    security_key : your_security_key
    
    recurring* : delete_subscription
    subscription_id* : "The subscription ID that will be deleted."
]