General

Subscriptions is a service that allows you to manage debtor accounts and subscriptions in the Buckaroo Payment Engine. The general flow of a subscription is as follows: When the billing day of a subscription is reached, the Buckaroo Payment Engine will create an invoice for the subscription interval period. In addition, Buckaroo Credit Management is added to this invoice to ensure the debtor will receive a reminder with multiple options to fulfill the invoice in case the initial payment fails.

Products, configurations and API calls.

In order to set up your own subscription service, perform the following steps.

  1. Create a product in the Buckaroo Payment Plaza. Make sure your user role is Technical administrator. Go to https://plaza.buckaroo.nl/Subscription/Product and click on Create Product. You will be asked to configure a rate plan for your product. This includes price amounts, payment intervals and frequency.
  2. Create a configuration set. Go to https://plaza.buckaroo.nl/Subscription/Configuration and click on Add Configuration. You will be asked to set up a few things like a SchemeKey, due date and invoice descriptions. This is needed for activating Credit Management with your Subscription service.
  3. Create the needed API calls. In general, in order to activate a subscription for a customer, you should tell us which product (price plan), configuration (for Credit Management) and customer (Debtor) need to be included for the requested subscription. The following sections will elaborate further on the various API calls that are available.

Servicecodes and actions

The Subscriptions services uses the service code: Subscriptions

The service supports the following actions:

  • CreateSubscription
  • CreateCombinedSubscription
  • UpdateSubscription
  • UpdateCombinedSubscription
  • StopSubscription
  • SubscriptionInfo

The CreateCombinedSubscription call can be a transaction request as well as a dat a requests (in the case of an emandate). The other calls are data requests only.

Data requests can be sent to https://checkout.buckaroo.nl/json/DataRequest (for live) or https://testcheckout.buckaroo.nl/json/DataRequest (for testing).

Transaction requests can be sent to https://checkout.buckaroo.nl/json/Transaction (for live) or https://testcheckout.buckaroo.nl/json/Transaction (for testing).

CreateSubscription

CreateSubscription is a data request that activates a customer subscription in the Buckaroo Payment Engine. In this call you can state which subscription needs to be activated for which customer (debtor). Additional debtor information can be provided with the request if needed. Debtor parameters are based on the AddOrUpdateDebtor action as defined in the Buckaroo Credit Management Service.

When it comes to determining the subscription payment method, there are three ways to perform this request:

  1. It is optional to provide the original transaction key of a previously succesfully performed transaction (this can be iDEAL, PayPal, Creditcard (Authorize) or Sepa Direct Debit) that has the attribute "StartRecurrent = True". This way the payment method used for that transaction will be used for the subscription payments. Use the parameter "OriginalTransactionKey", which is a basic parameter, not a (Subscription) service specific parameter.
  2. It is optional to provide the SEPA bank account details of the customer (including mandate reference), so that the subscription will use Sepa Direct Debit payments.
  3. It is possible to perform the request without reference to a transaction or bank account details. In this case the first invoice will trigger a payment invitation (PayperEmail) to the customer. If a payment via the PayPerEmail is performed, the used payment method will be also used for the following subscription payments.

Important note: when for some reason a subscription payment fails, or when the payment is being reversed (chargeback), a payment reminder for that invoice can be sent to the customer (Credit Management service). Like mentioned in point 3, the used payment method for that payment will then be used for the following subscription payments. This way it is possible that a payment method changes during a subscription.

View in playground

Request


JSON gateway request

ConfigurationCode

The unique code of the subscription configuration.

RatePlanCode
Required

GroupType = AddRatePlan. The unique code of the Product Rate Plan.

StartDate
Required

GroupType = AddRatePlan. The start date of the subscription (yyyy-mm-dd).

EndDate

GroupType = AddRatePlan. The end date of the subscription (yyyy-mm-dd). Should be equal to or later than the StartDate.

TermStartDay

The term start day determines when a subscription term starts. The value depends on the chosen invoice interval: weekly: 1 to 7, monthly/2 monthly/quarterly/half yearly/yearly: 1 to 31. Only provide this parameter if it differs from the default value in provided rate plan.

TermStartMonth

The term start month determines when a subscription term starts. The value depends on the chosen invoice interval: 2 monthly: 1 to 2. Quarterly: 1 to 3. Half yearly: 1 to 6. Yearly: 1 to 12. Only provide this parameter if it differs from the default value in provided rate plan.

BillingTiming

To bill in advance or in arrears of a period. InAdvance = 1, InArrears = 2. Only provide this parameter if it differs from the default value in provided rate plan.

RatePlanChargeCode

GroupType = AddRatePlanCharge. The unique code of the Product Rate Plan Charge. Only provide this parameter if it differs from the default value in provided rate plan.

BaseNumberOfUnits

GroupType = AddRatePlanCharge. The number of units. Only provide this parameter if it differs from the default value in provided rate plan. Secondly, using this parameter also requires the RatePlanChargeCode of the product.

PricePerUnit

GroupType = AddRatePlanCharge. The price per unit. Only provide this parameter if it differs from the default value in provided rate plan. Secondly, using this parameter also requires the RatePlanChargeCode of the product.

Code
Required

GroupType = Debtor. A unique code by which the merchant identifies the debtor. If the debtor with this code exists, any given components are overwritten.

CustomerIBAN

The IBAN of the debtor. When provided, SEPA Direct Debits will be used for the (recurring) payment(s).

CustomerAccountName

The name of the debtor for the IBAN account. Required when IBAN is provided.

CustomerBIC

The BIC code of the IBAN account. Required when providing a non Dutch IBAN.

MandateReference

The mandate reference for SEPA Direct Debits. It is possible to provide your own unique reference, or to use the mandateID from an Emandate, In any case, the MandateReference should always begin with a three digit prefix which can be found in the Sepadirectdebit subscription details in your Buckaroo account.

JSON

copy
{
   "Services": {
      "ServiceList": [
         {
            "Name": "Subscriptions",
            "Action": "CreateSubscription",
            "Parameters": [
               {
                  "Name": "StartDate",
                  "GroupType": "Addrateplan",
                  "GroupID": "",
                  "Value": "11-07-2017"
               },
               {
                  "Name": "RatePlanCode",
                  "GroupType": "Addrateplan",
                  "GroupID": "",
                  "Value": "xxxxxx"
               },
               {
                  "Name": "Code",
                  "GroupType": "Debtor",
                  "GroupID": "",
                  "Value": "xxxxxx"
               },
               {
                  "Name": "ConfigurationCode",
                  "Value": "xxxxx"
               }
            ]
         }
      ]
   }
}

Response


JSON gateway response

SubscriptionGuid

The unique key that was created to identify the subscription.

Subscription_RatePlanGuid_{rateplanCode}

The unique key that was created to identify the rate plan for the subscription.

Subscription_RatePlanChargeGuid_{rateplanCode}

The unique key that was created to identify the rate plan charges for the subscription.

JSON

copy
{
   "Key": "1783A1EB271C47818E404EB140CCxxxx",
   "Status": {
      "Code": {
         "Code": 190,
         "Description": "Success"
      },
      "SubCode": {
         "Code": "S001",
         "Description": "Transaction successfully processed"
      },
      "DateTime": "2017-07-27T11:10:31"
   },
   "RequiredAction": null,
   "Services": [
      {
         "Name": "Subscriptions",
         "Action": null,
         "Parameters": [
            {
               "Name": "SubscriptionGuid",
               "Value": "FC512FC9CC3A485D8CF3D1804FF6xxxx"
            },
            {
               "Name": "Subscription_RatePlanGuid_xxxxxx",
               "Value": "F075470B1BB24B9291943A888A2Fxxxx"
            },
            {
               "Name": "Subscription_RatePlanChargeGuid_xxxxxxx",
               "Value": "AD375E2E188747159673440898B9xxxx"
            }
         ]
      }
   ],
   "CustomParameters": null,
   "AdditionalParameters": null,
   "RequestErrors": null,
   "ServiceCode": "Subscriptions",
   "IsTest": true,
   "ConsumerMessage": null
}

CreateCombinedSubscription

CreateCombinedSubscripton is a supplementary action on a regular transaction request or data request (emandate). It functions a lot like a CreateSubscription data request, with the notable difference that it only activates a subscription when the primary transaction succeeds. If it doesn't, no follow up payments or Credit Management will be performed. This request can be combined with the following transaction types: iDEAL, Sepa Direct Debit, PayPal, Creditcards (Authorize) and eMandates (CreateMandate).

View in playground

Request


JSON gateway request

Here is an example of an iDEAL transaction combined with the Subscription service. Note that additional debtor information is added to the request, just to show how existing debtor information can be updated, or a new debtor can be created. These parameters are based on the AddOrUpdateDebtor action as defined in the Buckaroo Credit Management Service.

JSON

copy
{
   "Currency": "EUR",
   "StartRecurrent": "true",
   "AmountDebit": 10,
   "Invoice": "testsub1",
   "Services": {
      "ServiceList": [
         {
            "Name": "ideal",
            "Action": "Pay",
            "Parameters": [
               {
                  "Name": "issuer",
                  "Value": "ABNANL2A"
               }
            ]
         },
         {
            "Name": "Subscriptions",
            "Action": "CreateCombinedSubscription",
            "Parameters": [
               {
                  "Name": "StartDate",
                  "GroupType": "AddRatePlan",
                  "GroupID": "",
                  "Value": "03-08-2017"
               },
               {
                  "Name": "RatePlanCode",
                  "GroupType": "AddRatePlan",
                  "GroupID": "",
                  "Value": "gvn1f9xx"
               },
               {
                  "Name": "ConfigurationCode",
                  "Value": "9wqe32xx"
               },
               {
                  "Name": "Code",
                  "GroupType": "Debtor",
                  "GroupID": "",
                  "Value": "AapjeTest"
               },
               {
                  "Name": "FirstName",
                  "GroupType": "Person",
                  "GroupID": "",
                  "Value": "Aapje"
               },
               {
                  "Name": "LastName",
                  "GroupType": "Person",
                  "GroupID": "",
                  "Value": "de Tester"
               },
               {
                  "Name": "Gender",
                  "GroupType": "Person",
                  "GroupID": "",
                  "Value": "1"
               },
               {
                  "Name": "Culture",
                  "GroupType": "Person",
                  "GroupID": "",
                  "Value": "nl-NL"
               },
               {
                  "Name": "BirthDate",
                  "GroupType": "Person",
                  "GroupID": "",
                  "Value": "01-01-1990"
               },
               {
                  "Name": "Street",
                  "GroupType": "Address",
                  "GroupID": "",
                  "Value": "Hoofdstraat"
               },
               {
                  "Name": "HouseNumber",
                  "GroupType": "Address",
                  "GroupID": "",
                  "Value": "90"
               },
               {
                  "Name": "ZipCode",
                  "GroupType": "Address",
                  "GroupID": "",
                  "Value": "8441ER"
               },
               {
                  "Name": "City",
                  "GroupType": "Address",
                  "GroupID": "",
                  "Value": "Heerenveen"
               },
               {
                  "Name": "Country",
                  "GroupType": "Address",
                  "GroupID": "",
                  "Value": "NL"
               },
               {
                  "Name": "Email",
                  "GroupType": "Email",
                  "GroupID": "",
                  "Value": "xxx@xxx.nl"
               },
               {
                  "Name": "Mobile",
                  "GroupType": "Phone",
                  "GroupID": "",
                  "Value": "0612345678"
               }
            ]
         }
      ]
   }
}

Response


JSON gateway response

SubscriptionGuid

The unique key that was created to identify the subscription.

Subscription_RatePlanGuid_{rateplanCode}

The unique key that was created to identify the rate plan for the subscription

Subscription_RatePlanChargeGuid_{rateplanCode}

The unique key that was created to identify the rate plan charges for the subscription

JSON

copy
{
   "Key": "723AE30D9C234A0B869E1E881832xxxx",
   "Status": {
      "Code": {
         "Code": 791,
         "Description": "Pending processing"
      },
      "SubCode": {
         "Code": "S002",
         "Description": "An additional action is required: RedirectToIdeal"
      },
      "DateTime": "2017-08-03T10:27:49"
   },
   "RequiredAction": {
      "RedirectURL": "https://testcheckout.buckaroo.nl/html/redirect.ashx?r=7918A7BB505A48C684A5BF0A76B2xxxx",
      "RequestedInformation": null,
      "PayRemainderDetails": null,
      "Name": "Redirect",
      "TypeDeprecated": 0
   },
   "Services": [
      {
         "Name": "Subscriptions",
         "Action": null,
         "Parameters": [
            {
               "Name": "SubscriptionGuid",
               "Value": "7E1B40A25F194D7CA0358A05B83Dxxxx"
            },
            {
               "Name": "Subscription_RatePlanGuid_gvn1fxxx",
               "Value": "CBC6ECF6BD9843D39A347E46C8CBxxxx"
            },
            {
               "Name": "Subscription_RatePlanChargeGuid_at4hbxxx",
               "Value": "AC941EE042684F5882AA5563720Exxxx"
            },
            {
               "Name": "Subscription_RatePlanChargeGuid_trwhhxxx",
               "Value": "6E759FAB0F2A40439B03B2A43314xxxx"
            }
         ]
      },
      {
         "Name": "ideal",
         "Action": null,
         "Parameters": [
            {
               "Name": "consumerIssuer",
               "Value": "ABN Amro"
            },
            {
               "Name": "transactionId",
               "Value": "0000000000000001"
            }
         ]
      }
   ],
   "CustomParameters": null,
   "AdditionalParameters": null,
   "RequestErrors": null,
   "Invoice": "testsub1",
   "ServiceCode": "ideal",
   "IsTest": true,
   "Currency": "EUR",
   "AmountDebit": 10,
   "TransactionType": "C021",
   "MutationType": 1,
   "RelatedTransactions": null,
   "ConsumerMessage": null,
   "Order": null,
   "IssuingCountry": null,
   "StartRecurrent": true,
   "Recurring": false,
   "CustomerName": null,
   "PayerHash": null,
   "PaymentKey": "B42F96DD9E9A473495171B0E9201xxxx"
}

Push


JSON push response

SubscriptionGuid

The unique key that was created to identify the subscription.

Subscription_RatePlanGuid_{rateplanCode}

The unique key that was created to identify the rate plan for the subscription

Subscription_RatePlanChargeGuid_{rateplanCode}

The unique key that was created to identify the rate plan charges for the subscription

JSON

copy
{
   "Transaction": {
      "Key": "723AE30D9C234A0B869E1E881832xxxx",
      "Invoice": "testsub1",
      "ServiceCode": "ideal",
      "Status": {
         "Code": {
            "Code": 190,
            "Description": "Success"
         },
         "SubCode": {
            "Code": "S001",
            "Description": "Transaction successfully processed"
         },
         "DateTime": "2017-08-03T10:29:23"
      },
      "IsTest": true,
      "Order": null,
      "Currency": "EUR",
      "AmountDebit": 10,
      "TransactionType": "C021",
      "Services": [
         {
            "Name": "Subscriptions",
            "Action": null,
            "Parameters": [
               {
                  "Name": "SubscriptionGuid",
                  "Value": "7E1B40A25F194D7CA0358A05B83Dxxxx"
               },
               {
                  "Name": "Subscription_RatePlanGuid_gvn1fxxx",
                  "Value": "CBC6ECF6BD9843D39A347E46C8CBxxxx"
               },
               {
                  "Name": "Subscription_RatePlanChargeGuid_at4hbxxx",
                  "Value": "AC941EE042684F5882AA5563720Exxxx"
               },
               {
                  "Name": "Subscription_RatePlanChargeGuid_trwhhxxx",
                  "Value": "6E759FAB0F2A40439B03B2A43314xxxx"
               }
            ],
            "VersionAsProperty": 1
         },
         {
            "Name": "ideal",
            "Action": null,
            "Parameters": [
               {
                  "Name": "consumerIssuer",
                  "Value": "ABN Amro"
               },
               {
                  "Name": "transactionId",
                  "Value": "0000000000000001"
               },
               {
                  "Name": "consumerName",
                  "Value": "J. de Tèster"
               },
               {
                  "Name": "consumerIBAN",
                  "Value": "NL44RABO0123456789"
               },
               {
                  "Name": "consumerBIC",
                  "Value": "RABONL2U"
               }
            ],
            "VersionAsProperty": 2
         }
      ],
      "CustomParameters": null,
      "AdditionalParameters": null,
      "MutationType": 1,
      "RelatedTransactions": null,
      "IsCancelable": false,
      "IssuingCountry": null,
      "StartRecurrent": true,
      "Recurring": false,
      "CustomerName": "J. de Tèster",
      "PayerHash": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "PaymentKey": "B42F96DD9E9A473495171B0E9201xxxx"
   }
}

UpdateSubscription

UpdateSubscription is a data request that adds or updates subscription information in the Buckaroo Payment Engine. This allows the updating of subscription information at any time, and even in bulk, e.g. by using a batch file. There are 5 groups for updating a subscription. AddRatePlan for adding information or rate plans to a subscription. UpdateRatePlan for updating the rate plan within a subscription and DisableRatePlan to disable a rate plan within a subscription. These groups require different parameters. Therefore the request parameters are grouped by group type.

The request can also be used to update the payment method by providing a new OriginalTransactionKey (the payment method used in that transaction will then be used for the subscription) or SEPA bank credentials (BIC and IBAN). Changing the payment method can also be done by lettting the customer perform a new initial transaction with the UpdateCombinedSubscription request.

Note: it is also possible to update a default rateplan. This can be done manually in the rate plan configuration page in the Buckaroo Payment Plaza. The update will only apply to subscriptions that are created after the update. Existing subscriptions will keep the original rate plan settings; if needed these can be updated by performing an UpdateSubscription call.

View in playground

Request


JSON gateway request

ConfigurationCode

The unique code of the subscription configuration. When you have changed your settings within a configuration code that is already in use, you can send in an UpdateSubscription with that specific configuration code to update the Subscription's configuration. For example, your configuration code 1234 has a due date of 7 days. You changed it to 14 days. Doing an Update Subscription call with ConfigurationCode 1234 results in the Subscription following a due date of 14 days from now on. This will not change anything for already created invoices.

SubscriptionGuid
Required

The unique key that was created to identify the subscription.

RatePlanCode

Grouptype: AddRatePlan. The unique code of the Product Rate Plan.

StartDate

GroupType: AddRatePlan. The start date of the subscription (yyyy-mm-dd).

EndDate

Grouptype: AddRatePlan. The end date of the subscription (yyyy-mm-dd).

RatePlanChargeCode

Grouptype: AddRatePlanCharge. The unique code of the Product Rate Plan Charge.

BaseNumberOfUnits

Grouptype: AddRatePlanCharge. The number of units. Secondly, using this parameter also requires the RatePlanChargeCode of the product.

PricePerUnit

Grouptype: AddRatePlanCharge. The price per unit. Secondly, using this parameter also requires the RatePlanChargeCode of the product.

StartDate

Grouptype: UpdateRatePlan. The start date of the subscription (yyyy-mm-dd).

EndDate

Grouptype: UpdateRatePlan. The end date of the subscription (yyyy-mm-dd).

RatePlanGuid

Grouptype: UpdateRatePlan. The unique key that identifies the rate plan for the subscription.

RatePlanChargeGuid

Grouptype: UpdateRatePlanCharge. The unique key that identifies the rate plan charges for the subscription.

BaseNumberOfUnits

Grouptype: UpdateRatePlanCharge. The number of units.

PricePerUnit

Grouptype: UpdateRatePlanCharge. The price per unit.

RatePlanGuid

Grouptype: DisableRatePlan. The unique code of the Product Rate Plan.

RatePlanChargeGuid

Grouptype: DisableRatePlanCharge. The unique code of the Product Rate Plan Charge.

CustomerIBAN

The IBAN of the debtor. When provided, SEPA Direct Debits will be used for the (recurring) payment(s).

CustomerAccountName

The name of the debtor for the IBAN account. Required when IBAN is provided.

CustomerBIC

The BIC code of the IBAN account. Required when providing a non Dutch IBAN.

MandateReference

The mandate reference for SEPA Direct Debits. It is possible to provide your own unique reference, or to use the mandateID from an Emandate, In any case, the MandateReference should always begin with a three digit prefix which can be found in the Sepadirectdebit subscription details in your Buckaroo account.

JSON

copy
{
   "Services": {
      "ServiceList": [
         {
            "Name": "Subscriptions",
            "Action": "UpdateSubscription",
            "Parameters": [
               {
                  "Name": "SubscriptionGuid",
                  "Value": "FC512FC9CC3A485D8CF3D1804FF6xxxx"
               },
               {
                  "Name": "ConfigurationCode",
                  "Value": "9wqe32ew"
               },
               {
                  "Name": "RatePlanGuid",
                  "GroupType": "UpdateRatePlan",
                  "GroupID": "",
                  "Value": "F075470B1BB24B9291943A888A2Fxxxx"
               },
               {
                  "Name": "StartDate",
                  "GroupType": "UpdateRatePlan",
                  "GroupID": "",
                  "Value": "03-08-2017"
               },
               {
                  "Name": "EndDate",
                  "GroupType": "UpdateRatePlan",
                  "GroupID": "",
                  "Value": "03-09-2017"
               },
               {
                  "Name": "RatePlanChargeGuid",
                  "GroupType": "UpdateRatePlanCharge",
                  "GroupID": "",
                  "Value": "AD375E2E188747159673440898B9xxxx"
               },
               {
                  "Name": "BaseNumberOfUnits",
                  "GroupType": "UpdateRatePlanCharge",
                  "GroupID": "",
                  "Value": "1"
               },
               {
                  "Name": "PricePerUnit",
                  "GroupType": "UpdateRatePlanCharge",
                  "GroupID": "",
                  "Value": "10.00"
               }
            ]
         }
      ]
   }
}

Response


JSON gateway response

SubscriptionGuid

The unique key that identifies the subscription.

Subscription_RatePlanGuid_{rateplanCode}

The unique key that identifies the rate plan for the subscription

Subscription_RatePlanChargeGuid_{rateplanCode}

The unique key that was created to identify the rate plan charges for the subscription

JSON

copy
{
   "Key": "5EAA9CA3D50947AAA059F7621E14xxxx",
   "Status": {
      "Code": {
         "Code": 190,
         "Description": "Success"
      },
      "SubCode": {
         "Code": "S001",
         "Description": "Transaction successfully processed"
      },
      "DateTime": "2017-08-03T14:58:51"
   },
   "RequiredAction": null,
   "Services": [
      {
         "Name": "Subscriptions",
         "Action": null,
         "Parameters": [
            {
               "Name": "SubscriptionGuid",
               "Value": "FC512FC9CC3A485D8CF3D1804FF6xxxx"
            },
            {
               "Name": "Subscription_RatePlanGuid_9kh5xxxx",
               "Value": "F075470B1BB24B9291943A888A2Fxxxx"
            },
            {
               "Name": "Subscription_RatePlanChargeGuid_smtuxxxxk",
               "Value": "AD375E2E188747159673440898B9xxxx"
            }
         ]
      }
   ],
   "CustomParameters": null,
   "AdditionalParameters": null,
   "RequestErrors": null,
   "ServiceCode": "Subscriptions",
   "IsTest": true,
   "ConsumerMessage": null
}

UpdateCombinedSubscription

Use this request to change the payment method of an existing subscription by letting the customer perform a new initial transaction. The payment method used in that transaction will then be used for the subscription.

View in playground

Request


JSON gateway request

SubscriptionGuid
Required

The unique key that was created to identify the subscription.

JSON

copy
{
   "Currency": "EUR",
   "StartRecurrent": "true",
   "AmountDebit": 10,
   "Invoice": "testsub12",
   "Services": {
      "ServiceList": [
         {
            "Name": "ideal",
            "Action": "Pay",
            "Parameters": [
               {
                  "Name": "issuer",
                  "Value": "ABNANL2A"
               }
            ]
         },
         {
            "Name": "Subscriptions",
            "Action": "UpdateCombinedSubscription",
            "Parameters": [
               {
                  "Name": "SubscriptionGuid",
                  "Value": "65EB06079D854B0C9A9ECB0E2C1Cxxxx"
               }
            ]
         }
      ]
   }
}

Response


JSON gateway response

JSON

copy
{
   "Key": "292F62034744494BB09B3E39D790xxxx",
   "Status": {
      "Code": {
         "Code": 791,
         "Description": "Pending processing"
      },
      "SubCode": {
         "Code": "S002",
         "Description": "An additional action is required: RedirectToIdeal"
      },
      "DateTime": "2018-04-24T09:16:32"
   },
   "RequiredAction": {
      "RedirectURL": "https://testcheckout.buckaroo.nl/html/redirect.ashx?r=99C057951CA54EF29076BA74C2D4xxxx",
      "RequestedInformation": null,
      "PayRemainderDetails": null,
      "Name": "Redirect",
      "TypeDeprecated": 0
   },
   "Services": [
      {
         "Name": "Subscriptions",
         "Action": null,
         "Parameters": [
            {
               "Name": "SubscriptionGuid",
               "Value": "65EB06079D854B0C9A9ECB0E2C1CAxxx"
            },
            {
               "Name": "Subscription_RatePlanGuid_gvn1fxxx",
               "Value": "6253587B20B143F2A2DBCF22B2B26xxx"
            },
            {
               "Name": "Subscription_RatePlanChargeGuid_at4hbxxx",
               "Value": "D1283B6DE065462D8913B945874C2xxx"
            },
            {
               "Name": "Subscription_RatePlanChargeGuid_trwhhxxx",
               "Value": "5D0014BEE35047CEB8FE6105B8F61xxx"
            }
         ]
      },
      {
         "Name": "ideal",
         "Action": null,
         "Parameters": [
            {
               "Name": "consumerIssuer",
               "Value": "ABNAMRO Bank"
            },
            {
               "Name": "transactionId",
               "Value": "0000000000000001"
            }
         ]
      }
   ],
   "CustomParameters": null,
   "AdditionalParameters": null,
   "RequestErrors": null,
   "Invoice": "testsub12",
   "ServiceCode": "ideal",
   "IsTest": true,
   "Currency": "EUR",
   "AmountDebit": 10,
   "TransactionType": "C021",
   "MutationType": 1,
   "RelatedTransactions": null,
   "ConsumerMessage": null,
   "Order": null,
   "IssuingCountry": null,
   "StartRecurrent": true,
   "Recurring": false,
   "CustomerName": null,
   "PayerHash": null,
   "PaymentKey": "AA98139DBF314EB0BAF61E3A91E2xxxx"
}

Push


JSON push response

If the payment succeeds, a push response will be sent with a succes status and the transaction and subscription details.

JSON

copy
{
   "Transaction": {
      "Key": "292F62034744494BB09B3E39D7902xxx",
      "Invoice": "testsub12",
      "ServiceCode": "ideal",
      "Status": {
         "Code": {
            "Code": 190,
            "Description": "Success"
         },
         "SubCode": {
            "Code": "S001",
            "Description": "Transaction successfully processed"
         },
         "DateTime": "2018-04-24T09:20:26"
      },
      "IsTest": true,
      "Order": null,
      "Currency": "EUR",
      "AmountDebit": 10,
      "TransactionType": "C021",
      "Services": [
         {
            "Name": "Subscriptions",
            "Action": null,
            "Parameters": [
               {
                  "Name": "SubscriptionGuid",
                  "Value": "65EB06079D854B0C9A9ECB0E2C1CAxxx"
               },
               {
                  "Name": "Subscription_RatePlanGuid_gvn1fxxx",
                  "Value": "6253587B20B143F2A2DBCF22B2B26xxx"
               },
               {
                  "Name": "Subscription_RatePlanChargeGuid_at4hbxxx",
                  "Value": "D1283B6DE065462D8913B945874C2xxx"
               },
               {
                  "Name": "Subscription_RatePlanChargeGuid_trwhh7xx",
                  "Value": "5D0014BEE35047CEB8FE6105B8F61xxxx"
               }
            ],
            "VersionAsProperty": 1
         },
         {
            "Name": "ideal",
            "Action": null,
            "Parameters": [
               {
                  "Name": "consumerIssuer",
                  "Value": "ABNAMRO Bank"
               },
               {
                  "Name": "transactionId",
                  "Value": "0000000000000001"
               },
               {
                  "Name": "consumerName",
                  "Value": "J. de Tèster"
               },
               {
                  "Name": "consumerIBAN",
                  "Value": "NL44RABO0123456789"
               },
               {
                  "Name": "consumerBIC",
                  "Value": "RABONL2U"
               }
            ],
            "VersionAsProperty": 2
         }
      ],
      "CustomParameters": null,
      "AdditionalParameters": null,
      "MutationType": 1,
      "RelatedTransactions": null,
      "IsCancelable": false,
      "IssuingCountry": null,
      "StartRecurrent": true,
      "Recurring": false,
      "CustomerName": "J. de Tèster",
      "PayerHash": "636828004696cc6e079d2849bb4c5aedea6523a3739ddexxxx",
      "PaymentKey": "AA98139DBF314EB0BAF61E3A91E2xxxx"
   }
}

StopSubscription

Perform this call to deactivate an active or pending subscription. All rateplans within the subscription will then be deactivated. For example, if a subscription has 2 rateplans; 1 trial rateplan and 1 normal (paid) rateplan and the subscription is ended during the trial period, the normal rateplan will not start or be invoiced, since both rateplans have been deactivated. In general, it is adviced only to use this call if the subscription needs to be canceled immedately, including any planned invoices.

View in playground

Request


JSON gateway request

SubscriptionGuid
Required

The unique key that was created to identify the subscription.

JSON

copy
{
   "Services": {
      "ServiceList": [
         {
            "Name": "Subscriptions",
            "Action": "StopSubscription",
            "Parameters": [
               {
                  "Name": "SubscriptionGuid",
                  "Value": "A8A3DF828F0E4706B50191D3D1C88xxx"
               }
            ]
         }
      ]
   }
}

Response


JSON gateway response

JSON

copy
{
   "Key": "ECA987898C654F4F9D554AD1E62B4xxx",
   "Status": {
      "Code": {
         "Code": 190,
         "Description": "Success"
      },
      "SubCode": {
         "Code": "S001",
         "Description": "Transaction successfully processed"
      },
      "DateTime": "2018-04-25T17:28:53"
   },
   "RequiredAction": null,
   "Services": null,
   "CustomParameters": null,
   "AdditionalParameters": null,
   "RequestErrors": null,
   "ServiceCode": "Subscriptions",
   "IsTest": true,
   "ConsumerMessage": null
}

SubscriptionInfo

Perform this call to retrieve information of a subscription.

View in playground

Request


JSON gateway request

SubscriptionGuid
Required

The unique key that was created to identify the subscription.

JSON

copy
{
   "Services": {
      "ServiceList": [
         {
            "Name": "Subscriptions",
            "Action": "SubscriptionInfo",
            "Parameters": [
               {
                  "Name": "SubscriptionGuid",
                  "Value": "6ABDB214C4944B5C8638420CE9ECxxxx"
               }
            ]
         }
      ]
   }
}

Response


JSON gateway response

SubscriptionStatus

Status of the subscription.

IsTest

Whether the subscription is in test mode or not.

NextRunDate

The date of the next invoice.

DebtorCode

The Debtor Code

DebtorName

The name of the customer.

SubscriptionEarliestStartDate

The initial start date of the subscription

Subscription_RatePlanGuid

Unique identifier of a rate plan within the subscription.

Subscription_RatePlanName

Name of the rate plan.

Subscription_RatePlanProductName

Name of the product to which a rate plan belongs.

Subscription_RatePlanStatus

Status of a rate plan within the subscription.

Subscription_RatePlanStartDate

Start date of a rateplan within the subscription.

Subscription_RatePlanChargeGuid

Unique identifier of a rate plan charge within the subscription.

Subscription_RatePlanChargeName

Name of a rate plan charge within the subscription.

Subscription_RatePlanChargeStatus

Status of a rate plan charge within the subscription.

Subscription_RatePlanChargeType

The type of rate plan charge within the subscription.

Subscription_RatePlanChargeNumberOfUnits

Number of charged units in a rate plan charge within the subscription.

Subscription_RatePlanChargePricePerUnit

Unit price of a rate plan charge within the subscription.

Subscription_RatePlanChargeVatPercentage

VAT percentage of a rate plan charge within the subscription.

Subscription_RatePlanChargePriceIncludesVat

Whether a rate plan charge within the subscription includes VAT.

JSON

copy
{
   "Key": "96BE5CD866194885A882239D24964xxx",
   "Status": {
      "Code": {
         "Code": 190,
         "Description": "Success"
      },
      "SubCode": {
         "Code": "S001",
         "Description": "Transaction successfully processed"
      },
      "DateTime": "2018-12-27T14:17:33"
   },
   "RequiredAction": null,
   "Services": [
      {
         "Name": "Subscriptions",
         "Action": null,
         "Parameters": [
            {
               "Name": "SubscriptionGuid",
               "Value": "6ABDB214C4944B5C8638420CE9EC6xxx"
            },
            {
               "Name": "SubscriptionStatus",
               "Value": "Active"
            },
            {
               "Name": "IsTest",
               "Value": "True"
            },
            {
               "Name": "NextRunDate",
               "Value": "2019-01-01"
            },
            {
               "Name": "DebtorCode",
               "Value": "carptest2"
            },
            {
               "Name": "DebtorName",
               "Value": " Kools"
            },
            {
               "Name": "SubscriptionEarliestStartDate",
               "Value": "2018-12-05"
            },
            {
               "Name": "Subscription_RatePlanGuid_9kh5nxxx",
               "Value": "BFE7C56D867D4CE0A693DB6BC2BC9C6C"
            },
            {
               "Name": "Subscription_RatePlanName_9kh5nxxx",
               "Value": "Maand | Vooraf | 1e"
            },
            {
               "Name": "Subscription_RatePlanProductName_9kh5nxxx",
               "Value": "Vooraf Betalen Abonnement"
            },
            {
               "Name": "Subscription_RatePlanStatus_9kh5nxxx",
               "Value": "Active"
            },
            {
               "Name": "Subscription_RatePlanStartDate_9kh5nxxx",
               "Value": "2018-12-05"
            },
            {
               "Name": "Subscription_RatePlanChargeGuid_smtuuxxx",
               "Value": "FDDC5CBD59BB43DFB67A22189577DD6C"
            },
            {
               "Name": "Subscription_RatePlanChargeName_smtuuxxx",
               "Value": "Maandelijkse TV kosten"
            },
            {
               "Name": "Subscription_RatePlanChargeStatus_smtuuxxx",
               "Value": "Active"
            },
            {
               "Name": "Subscription_RatePlanChargeType_smtuuxxx",
               "Value": "Recurring"
            },
            {
               "Name": "Subscription_RatePlanChargeNumberOfUnits_smtuuxxx",
               "Value": "1.0000"
            },
            {
               "Name": "Subscription_RatePlanChargePricePerUnit_smtuuxxx",
               "Value": "14.00"
            },
            {
               "Name": "Subscription_RatePlanChargeVatPercentage_smtuuxxx",
               "Value": "21.00"
            },
            {
               "Name": "Subscription_RatePlanChargePriceIncludesVat_smtuuxxx",
               "Value": "True"
            }
         ]
      }
   ],
   "CustomParameters": null,
   "AdditionalParameters": null,
   "RequestErrors": null,
   "ServiceCode": "Subscriptions",
   "IsTest": true,
   "ConsumerMessage": null
}