Subscriptions

Paylands offers the possibility to make recurring payments through subscriptions.

In the following guide we will show step by step how to configure and integrate the recurring payments of a streaming service in which we will have a monthly plan that will be charged month to month and also an annual plan that will be charged every year.

Configuration

1. Create company

The first step is to create our company in Paylands. This only needs to be done the first time we set up the subscription system. We can do it easily from the Paylands Backend → Payment Tools → Subscriptions where a button to create the company will appear.

info

This step can also be done from the API using the Create company method.

2. Create products

Next we must register the products we want to offer by clicking on the New Product button.

In the example we are doing of streaming service platform would be enough to create a single product called Streaming Service.

We introduce an External ID to uniquely identify a product and optionally a Notification URL that will receive an HTTP notification when the payment changes status. The Environment is auto-selected according to the Backend environment we are working on.

info

This step can also be done from the API using the Create Product method.

3. Create plans

Once we have the product created, pressing the New Plan button we can create the plans we want for the product in question. For our example we will create 2 plans: Monthly and Annual.

We will start by creating the Monthly plan by filling in the form with the following fields:

• Name. We introduce as plan name Monthly.
• External ID. We choose as plan identifier MONTHLY.
• Interval. As we want to charge month to month, we will choose as interval 1.
• Type of interval. The drop-down menu gives us the options of Daily, Weekly, Monthly and Yearly. In our case we will choose Monthly.
• Amount. The price of this plan will be 10€. As we must enter the value in cents we will write 1000.
• Test available. We will check this option to give the user a trial period.
• Trial interval. We will give 1 month trial for this plan so we will enter as value 1.
• Trial interval type. We will select as trial interval type Monthly.

Next we will create the Yearly plan by filling in the form with the following fields:

• Name. We introduce as plan name Annual.
• External ID. We choose as plan identifier ANUAL.
• Interval. As we want to charge year to year, we will choose as interval 1.
• Interval type. The drop-down menu gives us the options of Daily, Weekly, Monthly and Yearly. In our case we will choose Annual.
• Amount. The price of this plan will be 100€. As we must enter the value in cents we will write 10000.
• Test available. For the annual plan of this example we will not mark trial period.

With both plans created, our subscription would look like this.

info

It is possible to create the plans from the API using the Create plan method.

Integration

Once we have the company, the products and the plans configured we are ready to start registering the subscriptions of our customers. If we wish we can register subscriptions manually from the Backend with the option Subscribe a customer manually.

Although the usual way will be to enable in our commerce web all the logic of registration of new customers and their subscriptions through calls to our API. Next we will see for our example of Streaming Service how to do it.

1. List plans for a product

The first step will be to list in our commerce web the different plans that we have for our Streaming Service product. For it we can make a call to the method List plans that will list all the plans that we have created.

We only have to pass as parameter in the URL of the call the product that corresponds to the external_id of the product that we have created. In our example it is SERSTR.

curl --request GET 'https://api.paylands.com/v1/sandbox/subscriptions/list-plans/?product=SERSTR' \
--header 'Authorization: pk_test_3c140607778e1217f56ccb8b50540e00' \
--header 'Content-Type: application/json' \
--data-raw '{
  "signature": "121149a0ba5361191d740fa898784a8b",
}'

In the response we will have the details of the plans to then present them on our trading website.

{
  "message": "OK",
  "code": 200,
  "current_time": "2022-02-03T16:37:02+0100",
  "plans": [{
    "amount": 1000,
    "created_at": "2022-02-03 16:05:24",
    "external_id": "MENSUAL",
    "interval": 1,
    "interval_type": "MONTHLY",
    "interval_offset": 1,
    "interval_offset_type": "MONTHLY",
    "name": "Mensual",
    "trial_available": true,
    "updated_at": "2022-02-03 16:05:24",
    "product": {
      "created_at": "2022-02-03 16:05:18",
      "external_id": "SERSTR",
      "name": "Servicio de Streaming",
      "notification_url": "https://yourdomain.com/subscriptions/notify",
      "sandbox": true,
      "updated_at": "2022-02-03 16:05:18"
    }
  },
  {
    "amount": 10000,
    "created_at": "2022-02-03 16:05:24",
    "external_id": "ANUAL",
    "interval": 1,
    "interval_type": "ANNUAL",
    "interval_offset": null,
    "interval_offset_type": null,
    "name": "Anual",
    "trial_available": false,
    "updated_at": "2022-02-03 16:05:24",
    "product": {
      "created_at": "2022-02-03 16:05:18",
      "external_id": "SERSTR",
      "name": "Servicio de Streaming",
      "notification_url": "https://yourdomain.com/subscriptions/notify",
      "sandbox": true,
      "updated_at": "2022-02-03 16:05:18"
    }
  }]
}

It is also possible to obtain the information of the plans individually using the Get plan method. If we choose this option, we will launch 2 requests to this method indicating as plan_external_id once MONTHLY and the other ANUAL request.

curl --request GET 'https://api.paylands.com/v1/sandbox/subscriptions/plan/{plan_external_id}' \
--header 'Authorization: pk_test_3c140607778e1217f56ccb8b50540e00' \
--header 'Content-Type: application/json' \
--data-raw '{
  "signature": "121149a0ba5361191d740fa898784a8b",
  "plan_external_id": "MENSUAL"
}'

With this information we can present the plans on the retailer's website as follows:

2. Subscribe a customer

When a customer clicks on the purchase button of any of the plans, we must show him a form asking for his data. These data we will have to save them in our database and then we will register the subscription for this client with the method Subscribe a client.

To subscribe a customer to a plan, it will be necessary to inform the external ID of the customer in customer and the external ID of the plan in plan, among other parameters. A common external identifier for the customer is to use the NIF or also the ID from our database.

In the call we can report the following parameters:

• customer. External ID of the customer we want to subscribe.
• plan. External ID of the plan we want to subscribe to.
• additional_data. Data block with additional information of the subscription.
• additional. Free field that the merchant can use to store information that he considers appropriate.
• customer_ext_id. External ID of the customer we want to subscribe. We must also enter it in this field.
• operative. Type of operation AUTHORIZATION.
• service. UUID of service.
• source_uuid. UUID of the card that we must have previously saved. See our guide to card saving and usage.
• url_post. URL of our merchant server to which Paylands will notify with the result of this call.
• initial_date. Date from which the subscription will start posting.
• payment_attempts_limit. Limit of payment attempts allowed.
• total_payment_number. Maximum number of payments that will be successfully completed before the subscription is cancelled. If we want the subscription to expire in 12 months, we would enter the value 12. In our example we do not want it to expire and leave it empty.

curl --request POST 'https://api.paylands.com/v1/sandbox/subscriptions/subscription' \``jsx {6-7}
--header 'Authorization: pk_test_3c140607778e1217f56ccb8b50540e00' \
--header 'Content-Type: application/json' \
--data-raw '{
  "signature": "121149a0ba5361191d740fa898784a8b",
  "customer": "ES41749999P",
  "plan": "MENSUAL",
  "additional_data": {
    "additional": "Datos extra",
    "customer_ext_id": "ES41749999P",
    "operative": "AUTHORIZATION",
    "service": "60A1F4C0-CC58-47A9-A0B9-868F9EF29045",
    "source_uuid": "C10721E7-1404-45DC-8762-351DD9945D1D",
    "url_post": "https://yourdomain.com/subscriptions/notify"
  },
  "initial_date": "2022-02-05T10:34:12.640Z",
  "payment_attempts_limit": 3,
  "total_payment_number": null,
}'

info

If the plan we want to subscribe to has the trial_available parameter set to false, a charge will be made immediately after subscribing the customer. In our example the ANNUAL plan would not have the trial period, so the charge would be executed immediately.

In the response we will have the result of the operation. The identifier of the subscription will come to us in the parameter subscription and the state of the same one in status.

{
  "amount": 1,
  "attempt": 1,
  "company": "FF255421-F4B7-47E9-9816-949F5F03DE6F",
  "currency": "978",
  "customer": "customer_external_id",
  "payment_date": "2022-02-05T10:34:12.640Z",
  "payment_id": "5dfa00a4229c1a127749ae9e",
  "payment_number": 1,
  "plan": "plan_external_id",
  "product": "product_external_id",
  "status": "PAID",
  "subscription": "5dfa00a4229c1a127749ae9d"
}

info

If any of the parameters (UUID of service or card, for example) is incorrect the subscription will be registered but the payment cannot be made. In this case the status will be FAILED_NOTIFICATION.

3. Obtaining a subscription

Once we have a customer subscribed, we may be interested in showing him the status of his subscription within the My account → My subscription section of the merchant's website. To do this, we can retrieve the subscription information by making a call to the method Get a subscription indicating the subscription ID subscription_id.

curl --request GET 'https://api.paylands.com/v1/sandbox/subscriptions/subscription/{subscription_id}' \
--header 'Authorization: pk_test_3c140607778e1217f56ccb8b50540e00' \
--header 'Content-Type: application/json' \

With this call, we will get all the subscription information, including the payments made.

{
  "message": "OK",
  "code": 200,
  "current_time": "2022-02-05T16:51:27+0100",
  "subscription": {
    "active": true,
    "additional_data": "{\"operative\":\"AUTHORIZATION\",\"source_uuid\":\"92766871-ABDD-405C-B436-A6F179FD81B3\",\"customer_ext_id\":\"test\",\"service\":\"C8C482B2-6846-4FA9-A813-1800610996A2\",\"url_post\":\"https:\/en26526quut1w.x.pipedream.net"}",
    "created_at": "2022-02-05 16:11:16",
    "first_charge_date": "2022-02-05",
    "id": "5e6116949d3a0c6b2e56826b",
    "next_charge_date": "2020-04-05",
    "payment_attempts_limit": 3,
    "status": "CREATED",
    "total_payment_charged": 1,
    "total_payment_number": 3,
    "updated_at": "2022-02-05 16:11:18",
    "payments": [
      {
        "amount": 1000,
        "attempt": 1,
        "created_at": "2022-02-05 16:11:16",
        "id": "5e6116949d3a0c6b2e56826c",
        "payment_date": "2022-02-05",
        "payment_details": "{\"order_uuid\":\"8B5BEB82-0CCA-47B7-A82C-FCEC6D8116B9\",\"source_uuid\":\"92766871-ABDD-405C-B436-A6F179FD81B3\",\"transaction_uuid\":\"7E531738-5A56-4319-925A-F97CD96E14D3\"}",
        "payment_number": 1,
        "status": "PAID",
        "updated_at": "2022-02-05 16:11:18"
      },
      {
        "amount": 1000,
        "attempt": 1,
        "created_at": "2022-01-05 16:11:18",
        "id": "5e6116969d3a0c6b2e56826d",
        "payment_date": "2022-02-05",
        "payment_details": null,
        "payment_number": 2,
        "status": "CREATED",
        "updated_at": "2022-02-05 16:11:18"
      }
    ],
    "plan": {
      "amount": 1000,
      "created_at": "2022-01-05 16:05:24",
      "external_id": "plan",
      "interval": 1,
      "interval_offset": 1,
      "interval_offset_type": "MONTHLY",
      "interval_type": "MONTHLY",
      "name": "Mensual",
      "trial_available": false,
      "updated_at": "2022-01-05 16:05:24",
      "product": {
        "created_at": "2022-01-05 16:05:18",
        "external_id": "SERSTR",
        "name": "Servicio de Streaming",
        "notification_url": "https://en26526quut1w.x.pipedream.net",
        "sandbox": true,
        "updated_at": "2022-01-05 16:05:18"
      }
    }
  }
}

With this information we can present a screen to the user as shown below.

4. Cancel a subscription

If we want to offer the customer the possibility to cancel his subscription from the merchant's website, we can put an option to do so next to his subscription information.

This link should make a call to the method Cancel a subscription indicating the subscription ID subscription_id.

curl --request DELETE DELETE 'https://api.paylands.com/v1/sandbox/subscriptions/subscription/{subscription_id}' \
--header 'Authorization: pk_test_3c140607778e1217f56ccb8b50540e00' \
--header 'Content-Type: application/json' \
--data-raw '{
  "signature": "121149a0ba5361191d740fa898784a8b"
}'

The response will return the deleted value to 1 if the subscription has been successfully removed.

{
  "message": "OK",
  "code": 200,
  "current_time": "2022-02-08T17:40:46+0100",
  "deleted": 1
}