Recurring API

Enables Easy merchants to create subscriptions and handle recurring payments.

Method URL Description Response class
POST /v1/payments/ Create Payment (with  Subscription option) Status 201
GET /v1/subscriptions/{subscriptionId} Get Subscription details Status 200
POST /v1/subscriptions/charges Charge Subscription(s) Status 202
GET /v1/subscriptions/charges/{BulkId} Get charge  details Status 200

 

Subscription payments in Easy

Using recurring API allows you to charge your customer on a regular basis, for example a monthly subscription on a product the customer must pay for every month.
This solution makes it easy to take care of keeping your customers paying for your product.


 

Create a Subscription - API

Title

Create Subscription

URL

api.dibspayment.eu/v1/payments/

URL Parameters

 

Data Parameters

"endDate" string that represents a timestamp

“frequency" integer representing number of days

"charge" bool determines whether or no an immediate charge is made

Success Response

Returns a payment ID

{

"paymentId": "e1d5385e0be74353b25e1b0ae1ce3d57"

}

Error Responses

Code 400 "Subscription end date must be in the future"

Sample Call

{  
"order":{  
	"items":[  
		{  
		"reference":"Reference3",
		"name":"Test Subscription",
		"quantity":1.0,
		"unit":"unit",
		"unitPrice":10000,
		"taxRate":10,
		"taxAmount":200,
		"grossTotalAmount":10000,
		"netTotalAmount":300
		}
	],
	"amount":10000,
	"currency":"NOK",
	"reference":"Mike CT true F 0"
},
"checkout":{  
	"url":"https://dev.epayment.nets.eu",
	"consumer":null,
	"termsUrl":"http://foo.bar",
	"shippingCountries":null,
	"shipping":{  
		"countries":[  

		],
		"merchantHandlesShippingCost":false
	},
	"consumerType":null,
	"charge":false
},
"merchantNumber":null,
"notifications":null,
"subscription":{  
	"endDate":"2019-07-18T00:00:00+00:00",
	"frequency":0
}
}

 

Description of special fields for recurring payments

Charge

When creating a subscription, the 'charge' field is only needed if you want to do a charge at the actual time of subscription creation.

Example 1 ‘charge = true, frequency =3’ will create a charge when the subscription is created but the subscription needs to wait 3 days before the first recurring charge can be made.

Example 2 ‘charge = false, frequency =3’ means no charge will be made at the time the subscription is created and the subscription needs to wait 3 days before the first recurring charge can be made. Beyond the moment of subscription creation, the charge field is not used.

Note: After the initial call to setup up the subscription, you will need to send in a charge call for each following charge.

Frequency

Defines the minimum number of days between each recurring charge. This interval commences from either the day the subscription was made or the most recent subscription charge. Whichever is the later.

Example. On day 1 a merchant creates a subscription with a 5 day interval. This allows his first subscription charge to be made on day 6. If the merchant doesn’t make the first charge until day 8 then the merchants second charge can’t be made until day 13 (5 days after the most recent charge). The charge can be made at any time of the day.

Note: ‘frequency=0’ removes all payment interval restrictions. The merchant can charge as often as he likes (payment interval = 0 days).

endDate

The endDate field has three components. Date, time and timezone. Date refers to the date the subscription will expire. Time refers to the time in the day the subscription will expire, timezone is the offset to GMT to denote which timezone the subscription expires.

Example 1. endDate is "2018-07-02T12:00:00.0000+02:00".

Note: The timezone (+02:00) in the example, means that the endDate will be offset +2:00 hours from GMT.

Use Case

This use case describes the behaviour of the Subscriptions APIs

Name

Purchase subscription

Triggers

As an end user I want to purchase a subscription item

Pre Conditions

End User has added the subscription item to the basket and has been provided with all the information related to charges for that item.

Post Conditions

A subscription item is purchased.

Normal flow

- The user clicks on the checkout button to purchase a subscription item (note no development has been done in the checkout to date).

- The user receives confirmation the subscription has been purchased.

- The merchant receives an initial charge if applicable.

- The merchant receives a subscription ID which allows the merchant to charge the subscription as required.

Alternative flows

None

 

Common pitfalls:

  1. Avoid specifying a subscription interval which has a duration longer than the subscription end date. In this case a recurring payment is created but can never be charged as it will expire before the first charge can be made.
  2. A merchant cannot tell from the API call 'Get subscription details' when the next subscription charge date is due. The merchant needs to manage when they charge their subscriptions.
  3. Where the time of day the subscription expires is 00:00:00 the subscription expires at midnight so cannot be charged on its last day. To avoid this the merchant needs to specify a subscription expiry time that meets their own requirements
  4. Merchants often like to charge on the first or last day of a month. Creating a subscription with an interval of 0 or 1 will allow them to do that
  5. Subscriptions may be charged even after the credit cards expires. This is normal behaviour for recurring payment and not a defect in Easy Recurring.
  6. Subscription management is not included in the portal, but the payments will most often show up in the portal as charged payments. Subscription charges will be viewable in the portal and have the corresponding SubscriptionID attached to it. You can search for a specific subscriptionID, see the charges made and find address and consumer info on the payment. If merchant want to reserve the initial subscription by using ‘charge’ with the ‘create subscription’ call, it is possible to charge the payment from portal or admin. However following charges must be made through the API.

FAQ

Q1: Can a subscription be refunded?

A: Any of the payments charged may be refunded is the usual way but only on a per payment basis, not the whole subscription.

Q2: Can a subscription be invoiced?

A: No. Only cards can be charged in subscription payments.

Q3: The consumer name or credit card number never appears in the portal for a recurring payment. Is that a defect or a feature?

A: It’s a feature. The business process of charging a subscription is completely different to the usual process for a one of card payment.

Get Subscription details - API

Title

Get Subscription details

URL

api.dibspayment.eu/v1/subscriptions/{{subscriptionId}}

URL Parameters

{{ subscriptionId }}

Data Parameters

N/A

Success Response

Returns the subscription details

{  
  "subscriptionId":"9cb30d7afc554363944dac71a21a39b5",
  "frequency":0,
  "endDate":"2018-07-14T00:00:00.0000+02:00",
  "paymentDetails":{  
    "paymentType":"CARD",
    "paymentMethod":"Visa",
    "cardDetails":{  
      "expiryDate":"1221",
      "maskedPan":"492500******0004"
    }
  }
}

Error Responses

 

Sample Call

 

 

Charge Subscriptions

Single Charge

Title

Charge Subscription

URL

api.dibspayment.eu/v1/subscriptions/{{subscriptionId}}/charges

URL Parameters

{{ subscriptionId }}

Data Parameters

 

Success Response

Returns a Charge ID and Payment ID

{

"paymentId": "b281c5eed8e54d67b4ca7bae5fd47069",

"chargeId": "9489fa55cb1d4d79946e4125b829fc34"

}

Error Responses

 

Sample Call

{  
  "order":{  
    "items":[  
      {  
        "reference":"abcd",
        "name":"Camera",
        "quantity":1.0,
        "unit":"ct",
        "unitPrice":0,
        "taxRate":0,
        "taxAmount":0,
        "grossTotalAmount":2500,
        "netTotalAmount":0
      }
    ],
    "amount":2500,
    "currency":"NOK",
    "reference":"hello"
  },
  "merchantNumber":null
}

Bulk Charge

This use case describes the behavior of the Bulk charge APIs

Name

Bulk charge subscriptions

Usage

As a merchant I want to be able to charge my subscriptions in batch so that I can charge all my subscriptions at the same time. This will help me manage for instance monthly subscriptions

Pre Conditions

The merchant has a batch of valid subscriptions which he wants to charge

Post Conditions

All subscriptions will be charged as expected.
The merchant will receive a list of the status of each subscription.

Normal flow

The merchant makes a single API call to charge all subscriptions.
The merchant receives a unique bulk charge ID to easily identify the bulk charge.
The merchant uses the bulk charge ID to query the status of all subscriptions after a charge is made.

Alternative flow 1

The merchant has errors in his API call, so A 400 error is returned. No charges are made.

Alternative flow 2

A bulk charge is made where the bulk charge contains expired subscriptions or subscriptions not yet due for a charge. Only the valid subscriptions are charged. The Merchant receives a response showing which subscriptions were not charged any why.

API call examples can be found below. The bulk charge API uses the standard recurring API with just a few added parameters.
 

Make Bulk Charge

Title

Make Bulk Charge

URL

Post {{url}}//v1/subscriptions/charges

URL Parameters

{{url}}

Data Parameters

"externalBulkChargeId" A unique string provided by the merchant to identify the bulk charge

" subscriptionId " multiple subscription IDs are provided all which are to be bulk charged

Success Response

Returns a bulkID to identify the results of the bulk charge

{

"bulkId": "ded0d5a60c014a9794706872e3443b9b"

}

Error Responses

(1) If the value for externalBulkChargeId" has been used in a previous charge the API call will return a status 400 with response response "Bulk charge has already been registered".

(2) Where the bulk charge contains an invalid subscription ID the API call is returned status 400 with nothing in the response.

(3) Where the bulk charge contains a subscription ID which isn’t 32 characters in length statue 400 is returned and the response contains an error message EG "Error converting value \"eee3e3fe291246ae883880db080ee5ex\" to type 'System.Guid'. Path 'subscriptions[0].subscriptionId', line 8, position 58."

(4) Where there are duplicate subscription IDs in the bulk charge the API call is returned status 400 with the following response "Bulk charge contains multiple entries with the same subscription id"

(5) Where a bulk charge contains subscriptions from two different merchants the API call returns a status 400 with the following response message..

"message": "All subscriptions must refer to the same merchant when bulk charging"

Sample Call

{  
  "externalBulkChargeId":"Mybulkcharge1",
  "notifications":null,
  // The subscriptions you would like to charge 

"subscriptions":[  
    // Example of subscription with a single product 

// Multiple subscription payments can be used within the same file    {  
      "subscriptionId":" b9b691c8cc8a4e429e6e5c86e58f34fc ",
      "order":{  
        "items":[  
          {  
            "reference":"Product1",
            "name":"Bulk Test Subscription 1",
            "quantity":1.0,
            "unit":"unit",
            "unitPrice":800,
            "taxRate":2500,
            "taxAmount":200,
            "grossTotalAmount":1000,
            "netTotalAmount":800
          }
        ],
        "amount":1000,
        "currency":"NOK",
        "reference":"My Bulk Charge 1"
      }
    },
    // Example of subscription with multiple products    {  
      "subscriptionId":"523198375a4b4804901f7a003d2c40bf",
      "order":{  
        "items":[  
          {  
            "reference":"Product6a",
            "name":"Bulk Test Subscription 6a",
            "quantity":1.0,
            "unit":"unit",
            "unitPrice":800,
            "taxRate":2500,
            "taxAmount":200,
            "grossTotalAmount":1000,
            "netTotalAmount":800
          },
          {  
            "reference":"Productb6",
            "name":"Bulk Test Subscription 6b",
            "quantity":1.0,
            "unit":"unit",
            "unitPrice":800,
            "taxRate":2500,
            "taxAmount":200,
            "grossTotalAmount":1000,
            "netTotalAmount":800
          }
        ],
        "amount":2000,
        "currency":"NOK",
        "reference":"Mike Bulk Charge 6"
      }
    }
  ]
}

Get Bulk Charge Details

Title

Get Bulk Charge Details

URL

GET {{url}}/v1/subscriptions/charges/{{bulkId}}

URL Parameters

{{url}}

/{{bulkId}}

Data Parameters

 

Success Response

Returns the details of all the subscription charges in the bulk charge

{  
  "page":[  
    {  
      "subscriptionId":"b9b691c8cc8a4e429e6e5c86e58f34fc",
      "paymentId":"0d0f075522b84237b1ddb2c36321e236",
      "status":"Succeeded"
    },
    {  
      "subscriptionId":"523198375a4b4804901f7a003d2c40bf",
      "paymentId":"e64c4e024db543b6b97f03038ac82098",
      "status":"Succeeded"
    },

  ],
  "more":false
}

Error Responses

Code 400 "Subscription end date must be in the future"

(1) Where an expired subscription ID appears in the bulk charge the API call is returns status 200 and the following response for the expired subscription…

"status": "Failed",

"message": "Direct charge failed. Subscription has expired",

(2) Where a subscription ID appears in the bulk charge whose next charging period is in a future date the API call is returned status 200 and the following response for the expired subscription…

"status": "Failed",

"message": "Direct charge failed. ErrorMessage: Recurr too soon (freq)",

 

Subscription Importing

What is a Subscription Import? Where a merchant needs to move pre-existing subscriptions from another Nets platform to Easy or from another PSP then subscription importing is used. This involves the merchant providing a flat file containing details of the subscriptions to be imported. After NETS have completed the import. The receiving merchant can then charge the subscriptions.

Name

Import Subscriptions

Triggers

A merchant wants to move subscriptions from another Nets platform to Easy or from another PSP

Pre Conditions

The merchant has exported his subscriptions into a flat file containing the subscriptions details EG card number, subscription expiry, interval etc..

Post Conditions

Once NETS back office has imported the subscriptions, the importing merchant will be able to charge the subscriptions in the same manner as the exporting merchant used to be able to.

Normal flow

The subscriptions are imported without error

Alternative flow 1

The flat file contains errors. The subscription import process detects those errors and aborts the import until the errors are corrected.

 

Technical Implementation
Following is the structure of the CSV flat file.

Title

Import format

Format sample

4925000000000004;20200101;01;20;1;1000

Above is an example of subscription import for card number 4925000000000004 with an expiry date of January 2020 and a subscription expiring on 1st January 2020. The interval for charging is 0 (so the card be charged at any time). The reference is 1000.

Format fields

Cardnumber, subscriptionexpiry(YYYYMMDD), card expiry month(MM), card expiry year(YY); interval; externalreference (alphanumeric).

 

Common pitfalls

1. The subscription IDs of the merchant exporting the subscriptions are ignored and not relevant to the subscription import process. New subscription IDs are created for the merchant importing the subscriptions by the subscription import process.

2. If there are multiple lines of the same reference, only the first will be imported

3. Where an expired subscription exists, the subscription will be created but cannot be charged.

4. The reference can be any alphanumeric string. Generally best to avoid special characters (though the – character is supported) as they may cause problems when charging subscriptions.

5. The subscription import process will not execute if there is a date format error in the input file

6. The subscription import process will run where an invalid credit card number exists in the input file. A subscription is still created which cannot be charged (charging the subscription results in an error "An error has occurred" being returned in the API response). This is correct behaviour for the subscription import. It is up to the merchant to make sure that the card numbers are valid.

7. Where a credit card has an invalid expiry date, a subscription still gets created and can be charged. This is the correct behaviour as the merchant needs to make sure that the information is correct.

 

Check subscription details by Reference ID

A merchant can send a call to Easy to check the details of a specific subscription.
It is however highly recommended that the merchant saves the subscription details in their own environment, as it is the merchants responsibility.

Title

Get Subscription Details by Reference ID

URL

GET {{url}}/v1/subscriptions?externalreference=/{{ReferenceID}}

URL Parameters

{{url}}

Data Parameters

/{{ ReferenceID }}

Success Response

{  
  "subscriptionId":"3abed40c7bb44c4eb51679e68c6b46b9",
  "frequency":0,
  "interval":0,
  "endDate":"2020-01-01T00:00:00.0000+01:00",
  "paymentDetails":{  
    "paymentType":"CARD",
    "paymentMethod":"Visa",
    "cardDetails":{  
      "expiryDate":"0120",
      "maskedPan":"492500******0004"
    }
  }
}

Error Responses

Code 404 returned if the subscription reference cannot be found

Sample Call

 

 

Do you have a question or need help?
Follow us
DIBS Payment Services
Stockholm +46 (0)8-527 525 00
Göteborg +46 031-600 800
København +45 7020 3077
Oslo +47 21 55 44 00
Close menu