Scenarios

You can use the Subscriptions API to create subscriptions to schedule regular, recurring payments for your consumers. With subscriptions, you can take advantage of tokenized credit card and bank account payment information, which is stored in the Paysafe Customer Vault.

The scenarios below describe some ways that merchants can set up recurring payments with Paysafe.

Scenario 1: Charge a Monthly Gym Membership to a Consumer's ACH Bank Account

This scenario illustrates the case where a merchant wants to charge a monthly gym membership of $30.00 to a consumer's ACH bank account.

  1. Create a plan that you want to use for the gym membership subscription.
  2. POST https://api.test.paysafe.com/subscriptionsplans/v1/plans

    In this example:

    • The amount is set to 3000.
    • In the billingCycle object, the frequency is set to MONTHLY and the interval is set to 1. This means that the plan will generate a payment request of $30.00 once a month. The exact payment date is specified in the subscription, when you create it.

    If, e.g., you wanted to charge $60 every two months, you would set the amount to 6000 and the interval to 2.

    {
    	"name": "Golden Plan",
    	"description": "Golden Plan for Gym Members",
    	"amount": "3000",
    	"currencyCode": "USD",
    	"billingCycle": {
    		"frequency": "MONTHLY",
    		"interval": "1"
    	},
    	"startDate": "2018-03-01",
    	"endDate": "2019-03-31"
    }
  3. Before you can use the plan in a subscription, you have to update the plan to have a status of ACTIVE. By default, when you create a plan, its status is set to INITIAL.
  4. Create a subscription for your consumer.
  5. POST https://api.test.paysafe.com/subscriptionsplans/v1/plans/plan_id/subscriptions

  6. The new subscription request includes the plan ID in the endpoint (the plan ID is the unique id returned in the response when you created the plan). The payload will look something like this:
{
	"accountId": "88919000",
	"paymentToken": "CNjEzMTM4NDg1",
	"paymentDescriptor": "Gym Golden Plan",
	"merchantRefNum": "sub-1",
	"dupCheck": true,
	"itemQuantity": 1,
	"status": "ACTIVE",
	"startDate": "2019-01-15",
	"endDate": "2019-12-31"
}
  1. The example payload above contains several important elements:
    • The account number (accountId) of your merchant account that is configured to process payments through the Paysafe Direct Debit API
    • A payment token that represents the consumer's ACH bank account (paymentToken), created in the Paysafe Customer Vault API
    • The start and end dates for the subscription – if no startDate is included, the subscription begins immediately; if no endDate is included, the subscription continues indefinitely
  2. Once you have received a successful response from Paysafe, in which the status is ACTIVE, the subscription is set up. In the example above, the first payment of $30.00 will be made against the consumer's bank account on January 15, 2019, using the Paysafe Direct Debit API. This will be followed by subsequent payments of $30.00 on the 15th of each month for the rest of the year, at which point the subscription will end.

You must ensure that the paymentToken you use in your subscription is valid and active. Otherwise, the Direct Debit payment request will fail.

Scenario 2: Copy a Plan to Create a Newer Version

It can be convenient for a merchant to copy a plan because, for example, they might want to reproduce a monthly plan, including start and end dates, and change only the amount. There are several variations for copying a plan.

  • You can copy a plan with an empty payload, since none of the elements are required. In this case, you would have an exact replica of the original plan, but with version incremented to 2.
  • You can copy a plan and include values for any elements except name. In this case, you will have a plan with the same name, with version incremented to 2, and with the values from the original plan you are copying overwritten by any new values included in this request. E.g., you could include a new description to reflect an increased amount value.
  • You can copy a plan and provide a different name value in the request. In this case, you would create a new plan with the version set to 1.

In all these cases, you can then update the new plan to modify any of its values, as required.

This scenario illustrates the case where a merchant wants to copy an existing plan, but with higher monthly fees.

  1. Select the id of the plan that you want to copy. This ID is returned in the response to the original plan creation request.
  2. Send a POST request to the newversion endpoint.
  3. POST https://api.test.paysafe.com/subscriptionsplans/v1/plans/plan_id/newversion

  4. Include the following as your payload. Only the amount value is provided.
{
	"amount": "8000"
}
  1. A response like the following would be returned.
{
  "id": "rtr7d83f-add7-4b6b-8884-dfa8693ddrtr",
  "version": 2,
  "name": "Gold",
  "description": "Gold plan for Elite members",
  "amount": "8000",
  "currencyCode": "USD",
  "billingCycle": {
    "frequency": "MONTHLY",
    "interval": "1"
  },
  "startDate": "2018-03-01",
  "endDate": "2019-03-31",
  "status": "INITIAL",
  "creationTime": "2018-02-14T15:12:18Z",
  "lastUpdatedTime": "2018-02-14T15:12:18Z",
  "links": [
    {
      "rel": "self",
      "href": "https://api.test.paysafe.com/subscriptionsplans/v1/plans/rtr7d83f-add7-4b6b-8884-dfa8693ddrtr"
    },
    {
      "rel": "subscriptions",
      "href": "https://api.test.paysafe.com/subscriptionsplans/v1/plans/rtr7d83f-add7-4b6b-8884-dfa8693ddrtr/subscriptions"
    },
    {
      "rel": "previousVersion",
      "href": "https://api.test.paysafe.com/subscriptionsplans/v1/plans/e067d83f-add7-4b6b-8884-dfa8693dde1f"
    }
  ]
}
  1. In this response, only the unique id (rtr7d83f-add7-4b6b-8884-dfa8693ddrtr), the version (2) and the amount (8000) will be different from the plan being copied.
  2. As in Scenario 1, you have to update the plan to have a status of ACTIVE before you can use it in a subscription.
  3. Create your subscription for your consumer, using the unique id returned in the plan creation response.
  4. POST https://api.test.paysafe.com/subscriptionsplans/v1/plans/plan_id/subscriptions

Did you find this page useful?