Skip to content

    Manage unscheduled subscriptions

    This guide is for developers who want to charge unscheduled subscription payments programmatically using the Payment API.

    Complexity: Medium
    Coding: Yes (Backend)
    Platform:

    Before you start

    This guide assumes that you have followed and implemented the guides:

    Overview

    Once you have a checkout page that can handle unscheduled subscriptions, it is time to implement functionality on your backend to manage these unscheduled subscriptions:

    • Charge sunscheduled ubscriptions: You can charge one or multiple unscheduled subscriptions at once. Charging an unscheduled subscription is an asynchronous operation. You create a new bulk charge operation and then retrieve the status of the operation at a later stage.

    Important

    It is not permitted to create subscriptions with low amount (like 1.00 EUR) just to register a card with Easy. 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.

    Retrieve unscheduled subscription details

    Before you can charge an unscheduled subscription, you need to obtain the identifier of the unscheduled subscription. You can get the unscheduled subscription identifier from Easy Portal or the Payment API. The guide Unscheduled Subscriptions (uCoF) describes how to retrieve unscheduled subscription details, including the unscheduledSubscriptionId. Please see Retrieve unscheduled subscription ID using the Payment API for more details.

    Charge an unscheduled subscription

    When a new unscheduled subscription payment has been created and you have retrieved the unscheduledSubscriptionId, you can initiate new payments associated with the unscheduled subscription. You are free to create arbitrary payments with completely different order items and amounts.

    When charging an unscheduled subscription, you need to provide a full order that specifies what you are charging your customer for. Use the Charge unscheduled subscription method to charge an unscheduled subscription.

    If you want to get notified for successful unscheduled subscription charges, you should listen to payment.charge.created.v2. If you want to get informed about failed unscheduled subscription charge attempts, you should listen to payment.reservation.failed.

    Here is an example:

    Charge unscheduled subscription

    charge-unscheduledsubscriptions.php
    <?php
    
    $curl = curl_init();

    Remember to replace <YOUR_SECRET_API_KEY> with your secret key.

    The payload is typically created dynamically by your backend. But if you just want to try it out, you can use the following hard-coded request body that charges for a single item. Remember to replace <UNSCHEDULEDSUBSCRIPTION_ID> with a valid unscheduled subscription identifier.

    Charge an unscheduled subscription (request)

    {
        "unscheduledSubscriptions": [
            {
                "unscheduledSubscriptionId": "<UNSCHEDULEDSUBSCRIPTION_ID>",

    Charge multiple unscheduled subscriptions

    It is possible to charge multiple unscheduled subscriptions in bulk. In a single API call, you can charge an arbitrary amount of unscheduled subscriptions. The unscheduled subscription identifiers are typically saved on your side so that you can compose charge requests of all your unscheduled subscriptions.

    Here is an example of a payload which charges two active unscheduled subscriptions. Remember to replace <UNSCHEDULEDSUBSCRIPTION_ID_1> and <UNSCHEDULEDSUBSCIRIPTION_ID_2> with actual unscheduled subscription identifiers before posting the request.

    Bulk charge unscheduled subscriptions (request)

    payload.json
    {
        "externalBulkChargeId": "1002",
         "notifications": {
            "webhooks": [ ]

    The example also demonstrates that it is possible to add an array of webhooks to the request so that you can track the events triggered by the bulk charge operation. You can find more information about the notifications property in the API reference.

    Each unscheduled subscription you try to charge will generate a new payment object and therefore also trigger a new sequence of webhook events. For example, if you charge 10 unscheduled subscriptions in a bulk request, there will also be 10 payment.charge.created.v2 events triggered.

    If the charge request was sucessful, a 202 HTTP status code is returned with a new bulk identifier:

    Bulk charge unscheduled subscriptions (response)

    {
        "bulkId": "d6c11ab596184414bef9adf20936e583"
    }

    A successful response does not imply that all of the unscheduled subscriptions have been charged successfully. However, you can use the bulkId returned in the response body to retrieve details about a bulk charge operation, as shown in the following step.

    Retrieve bulk charge details

    When you perform a bulk charge operation, unscheduled subscriptions might fail for various reasons, for example:

    • Not enough funds on the card, which makes the bank reject the reservation. In this case you can inform your customer about the situation and try to do a new charge.

    • The card has become invalid because it has expired, has been reported stolen, etc. In this case you need to update the unscheduled subscription.

    To retrieve the status of a bulk charge operation, you can use the method Retrieve bulk unscheduled charges.

    The response is paginated since a lot of unscheduled subscriptions are potentially being processed. You have two options when specifying the range of charges you want to retrieve:

    1. Use skip and take.
    2. Use pageNumber and pageSize.

    In the sample code below, skip and take is used to specify that the first 10 unscheduled subscriptions should be retrieved:

    Retrieve bulk charges (uCoF)

    get-bulk-charges.php
    <?php
    
    $secretKey = "<YOUR_SECRET_API_KEY>";
    $bulkId = "<BULK_ID>";

    The following response from the server indicates that all unscheduled subscriptions were returned ("more": false) and that all charges have completed successfully:

    Retrieve bulk charges (response)

    {
        "page": [
            {
                "unscheduledSubscriptionId": "6946cde8d7a049dc89145224088b0df9",
    🎉

    Congratulations!

    You now know how to:

    • Charge a single unscheduled subscription or multiple unscheduled subscriptions in bulk