Unscheduled Subscriptions (uCoF)
This guide is for developers who want to add unscheduled subscriptions to their checkout page.
Before you start
This guide assumes that you have followed and implemented the guide Integrate Checkout on your website. So, before you read this guide you should already have a checkout page up and running that handles single payments.
Overview
Unscheduled Subscriptions (Unscheduled Card on File, UCoF) allow merchant-initiated transactions on a non-fixed schedule with flexible amounts (opposed to regular subscriptions, where the same amount is charged on a defined schedule as a recurring payment). Common scenarios for the use of unscheduled subscriptions are pay-per-use services such as car sharing, electric scooters, top up for internally used payment cards (canteen), payments for meal delivery and so on.
The payment details (cards) for unscheduled subscriptions are stored with Checkout, so that PCI (data security standard) compliance is ensured. However, your Terms and Conditions must cover the user's consent to store their payment details for unscheduled subscriptions.
Similar to regular subscriptions, an unscheduled subscription is always associated with at least one payment object. A new unscheduled subscription is created by the create payment method with some specific parameters.
After an unscheduled subscription is created, you can charge new payments without additional interaction with the customer. At every charge, a new payment object is created and then automatically charged.
Since each charging of an unscheduled subscription will create a new payment object with an individual chargeID and paymentID, you can refund individual charges from an unscheduled subscription, as you would do with regular payments.
Create a new unscheduled subscription
To configure the checkout for unscheduled subscriptions, the unscheduledSubscription object has to be added to the create payment’s request body. Here is an example of an updated version of payload.json that includes the required unscheduledSubscription properties:
Create unscheduled subscription
{ "order": { "items": [ {
It is possible to specify an amount greater than zero and make an initial charge when creating the unscheduled subscription.
Troubleshooting
If you are sending zero amount in the create payment request and cards are getting declined when verifying, that is likely because the issuing bank doesn't allow for zero amount verifications. To overcome this problem, please send a value of 1 instead of 0 (regardless of currency).
Important
It is not permitted to create subscriptions with low amount (like 1.00 EUR) just to register a card with Checkout. Instead, create a payment with unscheduled subscription object amount=0 to verify the card.
If the card is valid, you will be able to query for the token (unscheduled subscription ID) and use it for future charges.
This is the compliant way to register a card without charging the customer and get a token back. Low-value amount transactions (1.00 EUR / SEK / DKK /etc.) that are not captured or cancelled may be declined or generate fines from Visa or MasterCard.
The unscheduledSubscription key of the payload.json request body contains create. When set to true, a new unscheduled card on file agreement is going to be created. This can be omitted, if an existent unscheduled card on file agreement is going to be updated.
With create:true, a new unscheduledSubscriptionId will be created. However, the call will return only a paymentID. To get the newly created unscheduledSubscriptionId you must use the Retrieve payment call and find the unscheduledSubscriptionId in this call's response.
New unscheduled subscription with initial charge
By setting the boolean property checkout.charge to true, the customer is charged when the unscheduled subscription is created. The following JSON payload will create a new unscheduled subscription and also automatically charge the customer for the specified order.
payload.json
{ "order": { "items": [ {
Retrieve unscheduled subscription ID using the Payment API
The unscheduled subscription ID can be retrieved programatically. For this, you must retrieve the unscheduled subscription payment object sending the retrieve-payment call:
Retrieve payment
- PHP
- Node
<?php $paymentId = "<YOUR_PAYMENT_ID>"; $ch = curl_init('https://test.api.dibspayment.eu/v1/payments/' . $paymentId);
Remember to replace <PAYMENT_ID> with the payment identifier you received from the API when creating the subscription payment. The placeholder <YOUR_SECRET_KEY> should be replaced with your secret key.
A successful API call will return something similar to this:
Retrieve payment response (uCoF)
{ "payment": { "paymentId": "0260000060003b7b47f0833960dc60d6", "summary": {
The payment.unscheduledSubscription.id key's value is the unscheduledSubscriptionId you are looking for. Use that identifier to get more information about the unscheduled subscription with the Retrieve unscheduled subscription call:
Retrieve uCoF details
<?php $unscheduledSubscriptionId = "<UNSCHEDULEDSUBSCIRPTION_ID>";
Again, make sure you replace all the placeholder strings marked with <...>.
The JSON response from the retrieve subscriptions request can look something like this:
uCoF subscription details response
{ "unscheduledSubscriptionId": "205e808f6fba40828b0389c8b943aefe", "paymentDetails": { "paymentType": "CARD",
Now you know how to retrieve the unscheduledSubscription identifier and other details related to a uCoF set up. The unscheduledSubscription identifier is required when you want to charge an unscheduled subscription at a later stage.
You can charge multiple subscriptions in bulk using the API method Bulk charge unscheduled subscriptions.
Now you know how to set up your checkout page to support unscheduled transactions. You also know how to get the unscheduledSubscriptionId which is necessary for future charges.