CreateSubscription

CreateSubscription is a data request to create a subscription in the Buckaroo Payment Engine. In this request, three things need to be specified:

Debtor
Rateplan(s)
Configuration

Debtor

A unique debtor code needs to be provided.

Rateplan

There are three ways to specify a subscription rateplan:

Provide the rateplan code of a product rateplan. A product rateplan can be created manually in your Buckaroo Plaza account. The subscription rateplan will be created based on the properties of the product rateplan at that point in time.
Provide the rateplan code of a product rateplan but specify one or more properties that differ from the default properties of the product rateplan, for example, a different unit price.
Don't provide a rateplan code of a product rateplan, but instead, specify a custom subscription rateplan by specifying all of its rateplan and rateplancharge properties.

Configuration

There are two ways to specify the subscription configuration:

Provide the configuration code of a product configuration. A product configuration can be created manually in your Buckaroo Plaza account.
Don't provide the configuration code of a product configuration, but instead, specify a custom subscription configuration by specifying all its properties.

Payment Data

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

It is optional to provide the original transaction key of a previously successfully performed transaction (this can be iDEAL, PayPal, Bancontact, KBC, Creditcard, SEPA Direct Debit, Sofort, Giropay, EPS, Belfius, and Payconiq) 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.
It is optional to provide the SEPA bank account details of the customer (account name, IBAN, BIC), so that the subscription will use SEPA Direct Debit as the payment method.
It is also possible to provide a mandate reference of an existing emandate, so that the subscription will use SEPA Direct Debit as the payment method.

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 also be used for the following subscription payments.

CreateSubscription Request

Service-Specific Parameters

Recommended Parameters

Parameter	Type	GroupType	Description	Required
Code	String	Debtor	Unique identifier of the debtor. Additional debtor information may be needed; please see the Credit Management service documentation	Yes
StartDate	String	AddRatePlan	Start date of the subscription rateplan (yyyy-mm-dd). Should be the current date or later.	Yes
RatePlanCode	String	AddRatePlan	Unique code of a product rateplan.
ConfigurationCode	String		Unique code of a product configuration.

Rateplan

Provide one or more of these parameters if they differ from the default product rateplan values, or provide all of these values when specifying a custom subscription rateplan.

Parameter	Type	GroupType	Description
EndDate	String	AddRatePlan	End date of the subscription's rateplan (yyyy-mm-dd). If provided, it should be equal to or later than the StartDate.
RatePlanName	String	AddRatePlan	Name of the subscription's rateplan
RatePlanDescription	String	AddRatePlan	Description of the subscription's rateplan
Currency	String	AddRatePlan	Currency of the subscription's rateplan
BillingTiming	Integer	AddRatePlan	To bill in advance or in arrears of a period. InAdvance = 1, InArrears = 2.
AutomaticTerm	Boolean	AddRatePlan	If true, the TermStartDay will be the same day as the day on the StartDate of the rateplan
BillingInterval	String	AddRatePlan	Billing interval of the subscription. Possible values: Weekly, FourWeekly, Monthly, TwoMonthly, Quarterly, HalfYearly, Yearly, Custom
CustomNumberOfDays	Integer	AddRatePlan	Length of BillingInterval in the number of days. Required if BillingInterval = Custom
TermStartDay	Integer	AddRatePlan	First day of a subscription term. Value depends on the chosen interval: weekly/four weekly: 1 to 7, monthly/2 monthly/quarterly/half yearly/yearly: 1 to 31
TermStartWeek	String	AddRatePlan	First week of a subscription term. Only applies to FourWeekly intervals. Possible values: 1 to 4.
TermStartMonth	Integer	AddRatePlan	First month of a subscription term. 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
TrialPeriodDays	Integer	AddRatePlan	Duration of the trial period in a number of days
TrialPeriodMonths	Integer	AddRatePlan	Duration of the trial period in a number of months
InheritPaymentMethod	Boolean	AddRatePlan	If true, the payment data of the last transaction will be used for the next payment

Rateplan Charge

Provide one or more of these parameters if they differ from the default product rateplan charge values, or provide all of these values when specifying a custom subscription rateplan (charge).

Parameter	Type	GroupType	Description
RatePlanChargeCode	String	AddRatePlanCharge	The unique code of the Product Rate Plan Charge. If not provided, then specify a custom subscription rateplan charge by providing all AddRateplanCharge parameters.
RatePlanChargeName	String	AddRatePlanCharge	Name of the rateplan charge
RateplanChargeProductId	String	AddRatePlanCharge	Product ID of the rateplan charge
RateplanChargeDescription	String	AddRatePlanCharge	Description of the rateplan charge
UnitOfMeasure	String	AddRatePlanCharge	Unit of measurement
RatePlanChargeType	String	AddRatePlanCharge	Type of charge. Possible values: Recurring, One-time
BaseNumberOfUnits	Decimal	AddRatePlanCharge	The number of units. Using this parameter also requires the RatePlanChargeCode of the product.
PartialBilling	String	AddRatePlanCharge	Type of billing. Possible values: BillFull, BillPartial, NoBilling
PricePerUnit	Decimal	AddRatePlanCharge	The price per unit. Secondly, using this parameter also requires the RatePlanChargeCode of the product.
PriceIncludesVat	Boolean	AddRatePlanCharge	Whether a rate plan charge within the subscription includes VAT.
VatPercentage	Decimal	AddRatePlanCharge	The VAT percentage. Secondly, using this parameter also requires the RatePlanChargeCode of the product.
B2B	String	AddRatePlanCharge	Is the subscription to be paid via SEPA Direct Debit B2B? Possible values: True, False. If True, then it is required to provide the MandateReference.

Configuration

Provide one or more of these parameters if they differ from the default product configuration. Provide all of these values when specifying a custom subscription configuration.

Parameter	Type	GroupType	Description
Name	String	AddConfiguration	Name of the configuration.
SchemeKey	String	AddConfiguration	Credit Management scheme key
InvoiceNumberPrefix	String	AddConfiguration	Prefix of the invoice.
InvoiceDescriptionFormat	String	AddConfiguration	Description of the invoice.
DueDateDays	Integer	AddConfiguration	The number of days after the invoice date where the debtor has to pay the invoice.
AllowedServices	String	AddConfiguration	A list of comma-separated payment method service codes.
GenerateInvoiceSpecification	Boolean	AddConfiguration	If true, an invoice specification will be generated with each invoice.
SkipPayPerEmail	Boolean	AddConfiguration	If true, a PayPerEmail will be sent if no payment configuration is known

Miscellaneous

Parameter	Type	Description
CustomerIBAN	String	The IBAN of the debtor. When provided, SEPA Direct Debits will be used for the (recurring) payment(s).
CustomerAccountName	String	The name of the debtor for the IBAN account. Required when IBAN is provided.
CustomerBIC	String	The BIC code of the IBAN account. Required when providing a non-Dutch IBAN.
MandateReference	String	Mandate reference for SEPA Direct Debits. It's 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. If B2B = True is provided in the request, then the MandateReference should be registered with the customer bank for B2B SEPA Direct Debits.

Example Request

{
   "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"
               }
            ]
         }
      ]
   }
}

CreateSubscription Response

Service-Specific Parameters

Parameter	Type	Description
SubscriptionGuid	String	The unique key that was created to identify the subscription.
SubscriptionRatePlanGuid{rateplanCode}	String	The unique key that was created to identify the rate plan for the subscription.
SubscriptionRatePlanChargeGuid{rateplanCode}	String	The unique key that was created to identify the rate plan charges for the subscription.

Example Response

{
   "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

CreateCombinedSubscription 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, Bancontact, Creditcards (Authorize), and eMandates (CreateMandate).

Furthermore, the same request parameters are available as with the CreateSubscription request, with the addition of the parameter IncludeTransaction.

CreateCombinedSubscription 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.

Service-Specific Parameters

Parameter	Type	Required	Recommended	Description
IncludeTransaction	String			Provide this parameter with value 'true' if the initial transaction should be used to fulfill the first invoice(s). For example, if the default recurring subscription invoice amount is 10 euro, and the initial transaction is 15 euro, then the first subscription invoice will be fulfilled completely (therefore no recurring payment or request will be initiated), the second subscription invoice will be reduced to 5 euro (therefore a recurring payment or request of 5 euro will be initiated).
TransactionVatPercentage	Decimal	Only if IncludeTransaction is True	Vat percentage of the initial transaction. Required if IncludeTransaction is provided with value 'True'.

Example Request

{
   "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": "IncludeTransaction",
                  "GroupType": "",
                  "GroupID": "",
                  "Value": "false"
               },
               {
                  "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": "[email protected]"
               },
               {
                  "Name": "Mobile",
                  "GroupType": "Phone",
                  "GroupID": "",
                  "Value": "0612345678"
               }
            ]
         }
      ]
   }
}

CreateCombinedSubscription Response

Service-Specific Parameters

Parameter	Type	Description
SubscriptionGuid	String	The unique key that was created to identify the subscription.
SubscriptionRatePlanGuid{rateplanCode}	String	The unique key that was created to identify the rate plan for the subscription.
SubscriptionRatePlanChargeGuid{rateplanCode}	String	The unique key that was created to identify the rate plan charges for the subscription.

Example Response

{
   "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"
}

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 five groups for updating a subscription:

AddRatePlan: For adding an extra rateplan to the subscription. This can be done by providing a RatePlanCode, RatePlanCode with deviating rateplan values, or specifying a custom subscription rateplan.
AddRatePlanCharge: For adding an extra rateplan charge to a subscription. This can be done by providing a RatePlanChargeCode, RatePlanChargeCode with deviating rateplancharge values, or specifying a custom subscription rateplan charge.
UpdateRatePlan: For updating a subscription rateplan.
UpdateRatePlanCharge: For updating a subscription rateplan charge.
DisableRatePlan: To disable a subscription rateplan.
DisableRatePlanCharge: To disable a subscription rateplan charge.

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
Providing SEPA bank credentials (BIC and IBAN).

Changing the payment method can also be done by letting the customer perform a new initial transaction with the UpdateCombinedSubscription request.

Note: It is also possible to update a product rateplan. This can be done manually on 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 their original rate plan settings; if needed these can be updated by performing an UpdateSubscription call.

UpdateSubscription Request

Service-Specific Parameters

Parameter	Type	Description	Required
SubscriptionGuid	String	The unique key that was created to identify the subscription.	Yes

Add Rateplan

Provide one or more of these parameters if they differ from a provided RatePlanCode, or provide all of them when specifying a custom subscription rateplan.

Parameter	Type	GroupType	Description	Required
RatePlanCode	String	AddRatePlan	The unique code of the to be added Product Rate Plan. Should match the BillingTiming, BillingInterval, and TermStartDay of the subscription. If not provided, then specify a custom subscription rateplan by providing AddRateplan and AddRateplanCharge parameters.
StartDate	Date	AddRatePlan	The start date of the rateplan (yyyy-mm-dd). Should be current date or later.	Only if AddRatePlan info is provided
EndDate	Date	AddRatePlan	The end date of the rateplan (yyyy-mm-dd). If provided, it should be equal to or later than the StartDate.
RatePlanName	String	AddRatePlan	Name of the subscription's rateplan
RatePlanDescription	String	AddRatePlan	Description of the subscription's rateplan
Currency	String	AddRatePlan	Currency of the subscription's rateplan.*
BillingTiming	Integer	AddRatePlan	To bill in advance or in arrears of a period. InAdvance = 1, InArrears = 2.*
AutomaticTerm	Boolean	AddRatePlan	If true, the TermStartDay will be the same day as the day on the StartDate of the rateplan.*
BillingInterval	String	AddRatePlan	Billing interval of the subscription. Possible values: Weekly, FourWeekly, Monthly, TwoMonthly, Quarterly, HalfYearly, Yearly, Custom.*
CustomNumberOfDays	Integer	AddRatePlan	Length of BillingInterval in the number of days. Required if BillingInterval = Custom.*
TermStartDay	Integer	AddRatePlan	First day of a subscription term. Value depends on the chosen interval: weekly/four weekly: 1 to 7, monthly/2 monthly/quarterly/half yearly/yearly: 1 to 31*
TermStartWeek	String	AddRatePlan	First week of a subscription term. Only applies to FourWeekly intervals. Possible values: 1 to 4.*
TermStartMonth	Integer	AddRatePlan	First month of a subscription term. 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.*
TrialPeriodDays	Integer	AddRatePlan	Duration of the trial period in a number of days
TrialPeriodMonths	Integer	AddRatePlan	Duration of the trial period in a number of months
InheritPaymentMethod	Boolean	AddRatePlan	If true, the payment data of the last transaction will be used for the next payment

Add Rateplan Charge

There are two ways to add an additional rateplan charge:

If a RatePlanChargeCode is provided, then the other AddRatePlanCharge parameters are optional. They can be provided if different values (from the default rateplan charge) need to be set for the subscription.
If no RatePlanCode is provided, then it is required to either provide a RatePlanChargeCode or provide all of the AddRatePlanCharge parameters.

Provide one or more of these parameters if they differ from a provided RatePlanChargeCode, or provide all of these values when specifying a custom subscription rateplan.

Parameter	Type	GroupType	Description
RatePlanChargeCode	String	AddRatePlanCharge	The unique code of the to be added Product Rate Plan Charge.
RatePlanChargeName	String	AddRatePlanCharge	Name of the rateplan charge
RateplanChargeProductId	String	AddRatePlanCharge	Product ID of the rateplan charge
RateplanChargeDescription	String	AddRatePlanCharge	Description of the rateplan charge
UnitOfMeasure	String	AddRatePlanCharge	Unit of measurement
RatePlanChargeType	String	AddRatePlanCharge	Type of charge. Possible values: Recurring, One-time
BaseNumberOfUnits	Decimal	AddRatePlanCharge	The number of units. Using this parameter also requires the RatePlanChargeCode of the product.
PartialBilling	String	AddRatePlanCharge	Type of billing. Possible values: Bill full, Bill partial, No billing.*
PricePerUnit	Decimal	AddRatePlanCharge	The price per unit. Secondly, using this parameter also requires the RatePlanChargeCode of the product.
PriceIncludesVat	Boolean	AddRatePlanCharge	Whether the rateplan charge includes VAT.
VatPercentage	Decimal	AddRatePlanCharge	The VAT percentage. Secondly, using this parameter also requires the RatePlanChargeCode of the product.
B2B	String	AddRatePlanCharge	Is the subscription to be paid via SEPA Direct Debit B2B? Possible values: True, False. If True, then it is required to provide the MandateReference.*

Update Rateplan

Parameter	Type	GroupType	Description	Required
RatePlanGuid	String	UpdateRatePlan	The unique identifier of a to be updated subscription rateplan.	Only if at least 1 UpdateRateplan parameter is provided
StartDate	Date	UpdateRatePlan	The start date of the subscription (yyyy-mm-dd). Should be current date or later AND current StartDate is not in the past.
EndDate	Date	UpdateRatePlan	The end date of the subscription. Should be past the StartDate (yyyy-mm-dd).

Update Rateplan Charge

Parameter	Type	GroupType	Description	Required
RatePlanChargeGuid	String	UpdateRatePlanCharge	The unique identifier of a to be updated subscription rateplan charge.	Only if at least 1 UpdateRatePlanCharge parameter is provided
BaseNumberOfUnits	Decimal	UpdateRatePlanCharge	The number of units.
PricePerUnit	Decimal	UpdateRatePlanCharge	The price per unit.
PriceIncludesVat	Boolean	UpdateRatePlanCharge	Name of the rateplan charge
VatPercentage	Decimal	UpdateRatePlanCharge	The VAT percentage.

Disable Rateplan (Charge)

Parameter	Type	GroupType	Description	Required
RatePlanGuid	String	DisableRatePlan	The unique identifier of a to be disabled subscription rateplan.
RatePlanChargeGuid	String	DisableRatePlanCharge	The unique identifier of a to be disabled subscription rateplan charge.

Miscellaneous

Parameter	Type	Description
CustomerIBAN	String	The IBAN of the debtor. When provided, SEPA Direct Debits will be used for the (recurring) payment(s).
CustomerAccountName	String	The name of the debtor for the IBAN account. Required when IBAN is provided.
CustomerBIC	String	The BIC code of the IBAN account. Required when providing a non-Dutch IBAN.
MandateReference	String	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.
RemoveCustomParameters	String	Delete one or more custom parameters that exist on the subscription. Provide a comma-separated list of the parameter names.
ConfigurationCode	String	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 `UpdateSubscription` 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.
AllowedServices	String	Selection of payment methods that can be offered to the customer to pay via an invoice paylink. Possible values: ideal, sepadirectdebit, visa, mastercard, amex, visaelectron, maestro, paypal, dankort, vpay, cartasi, cartebancaire, cartebleuevisa, nexi.

Example Request

{
   "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"
               }
            ]
         }
      ]
   }
}

UpdateSubscription Response

Service-Specific Parameters

Parameter	Type	Description
SubscriptionGuid	String	The unique key that was created to identify the subscription.
SubscriptionRatePlanGuid{rateplanCode}	String	The unique key that identifies the rate plan for the subscription.
SubscriptionRatePlanChargeGuid{rateplanCode}	String	The unique key that was created to identify the rate plan charges for the subscription.

Example Response

{
   "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.

UpdateCombinedSubscription Request

Service-Specific Parameters

Parameter	Type	Required	Recommended	Description
SubscriptionGuid	String	Yes		The unique key that was created to identify the subscription.

Example Request

{
   "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"
               }
            ]
         }
      ]
   }
}

UpdateCombinedSubscription Response

Example Response

Example response
{
   "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"
}

UpdateCombinedSubscription push

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

Example response

{
   "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 advised only to use this call if the subscription needs to be canceled immediately, including any planned invoices.

StopSubscription request

Parameters

Parameter	Type	Required	Recommended	Description
SubscriptionGuid	String	Yes		The unique key that was created to identify the subscription.

Basic parameters

Here you can find all basic parameters.

Example request

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

StopSubscription response

Parameters

Example response

{
   "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.

SubscriptionInfo request

Parameters

Parameter	Type	Required	Recommended	Description
SubscriptionGuid	String	Yes		The unique key that was created to identify the subscription.

Example request

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

SubscriptionInfo response

Parameters

Parameter	Type	Description
SubscriptionStatus	String	Status of the subscription.
IsTest	String	Whether the subscription is in test mode or not.
NextRunDate	String	The date of the next invoice.
DebtorCode	String	The Debtor Code
DebtorName	String	The name of the customer.
SubscriptionEarliestStartDate	String	The initial start date of the subscription
Subscription_RatePlanGuid	String	Unique identifier of a rate plan within the subscription.
Subscription_RatePlanName	String	Name of the rate plan.
Subscription_RatePlanProductName	String	Name of the product to which a rate plan belongs.
Subscription_RatePlanStatus	String	Status of a rate plan within the subscription.
Subscription_RatePlanStartDate	String	Start date of a rateplan within the subscription.
Subscription_RatePlanChargeGuid	String	Unique identifier of a rate plan charge within the subscription.
Subscription_RatePlanChargeName	String	Name of a rate plan charge within the subscription.
Subscription_RatePlanChargeStatus	String	Status of a rate plan charge within the subscription.
Subscription_RatePlanChargeType	String	The type of rate plan charge within the subscription.
Subscription_RatePlanChargeNumberOfUnits	String	Number of charged units in a rate plan charge within the subscription.
Subscription_RatePlanChargePricePerUnit	String	Unit price of a rate plan charge within the subscription.
Subscription_RatePlanChargeVatPercentage	String	VAT percentage of a rate plan charge within the subscription.
Subscription_RatePlanChargePriceIncludesVat	String	Whether a rate plan charge within the subscription includes VAT.
PaymentConfigurationType	String	Type of payment, e.g. iDEAL, PayPal, Mastercard.
PaymentConfigurationStatus	String	Status of the payment configuration
PaymentConfigurationPayerIdentifier	String	Payment identifier of the payment configuration type, e.g. NL44RABO0123456789

Example response

{
   "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
}

DeletePaymentConfiguration

This action can be used to delete stored payment details of an existing subscription. After deletion, the next invoice will be created with a PayPerEmail, instead of a recurring transaction.

DeletePaymentConfiguration request

Parameters

Parameter	Type	Required	Recommended	Description
SubscriptionGuid	String	Yes		The unique key that was created to identify the subscription.

Example request

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

DeletePaymentConfiguration response

Parameters

Parameter	Type	Required	Recommended	Description
SubscriptionGuid	String	Yes		The unique key that was created to identify the subscription.

Example response

{
    "Key": "94DB79E198194F0291DC6C16A31",
    "Status": {
        "Code": {
            "Code": 190,
            "Description": "Success"
        },
        "SubCode": {
            "Code": "S001",
            "Description": "Transaction successfully processed"
        },
        "DateTime": "2020-10-23T11:25:43"
    },
    "RequiredAction": null,
    "Services": null,
    "CustomParameters": null,
    "AdditionalParameters": null,
    "RequestErrors": null,
    "ServiceCode": "Subscriptions",
    "IsTest": true,
    "ConsumerMessage": null
}

PauseSubscription

This action will pause the subscription immediately. All active rateplan(s) within the subscription will be paused. It’s optional to provide a ResumeDate, to automatically resume the subscription somewhere in the future. If not provided, the subscription will stay paused until a ResumeSubscription action is performed.

PauseSubscription request

Parameters

Parameter	Type	Required	Recommended	Description
SubscriptionGuid	String	Yes		The unique key that was created to identify the subscription.
ResumeDate	String			Day on which the subscription needs to be resumed.

Example request

{
  "Services": {
    "ServiceList": [
      {
        "Name": "Subscriptions",
        "Action": "PauseSubscription",
        "Parameters": [
          {
            "Name": "ResumeDate",
            "Value": ""
          },
          {
            "Name": "SubscriptionGuid",
            "Value": ""
          }
        ]
      }
    ]
  }
}

PauseSubscription response

Example response

{
  "Key": "478C1FC77584423484E7FDEC9DE",
  "Status": {
    "Code": {
      "Code": 190,
      "Description": "Success"
    },
    "SubCode": {
      "Code": "S001",
      "Description": "Transaction successfully processed"
    },
    "DateTime": "2020-11-24T13:55:39"
  },
  "RequiredAction": null,
  "Services":

 null,
  "CustomParameters": null,
  "AdditionalParameters": null,
  "RequestErrors": null,
  "ServiceCode": "Subscriptions",
  "IsTest": true,
  "ConsumerMessage": null
}

ResumeSubscription

This action can be performed to resume the subscription. If no ResumeDate is provided, the subscription is resumed immediately. All paused rateplan(s) within the subscription will be resumed.

Optionally a ResumeDate can be provided to automatically resume the subscription somewhere in the future.

Service specific parameters

Parameter	Type	Required	Recommended	Description
SubscriptionGuid	String	Yes		The unique key that was created to identify the subscription.
ResumeDate	String			Day on which the subscription needs to be resumed.

Example request

{
  "Services": {
    "ServiceList": [
      {
        "Name": "Subscriptions",
        "Action": "ResumeSubscription",
        "Parameters": [
          {
            "Name": "ResumeDate",
            "Value": ""
          },
          {
            "Name": "SubscriptionGuid",
            "Value": ""
          }
        ]
      }
    ]
  }
}

ResumeSubscription response

Example request

{
  "Key": "A6FEBD16BD5849B38CF1AF3DBDB1",
  "Status": {
    "Code": {
      "Code": 190,
      "Description": "Success"
    },
    "SubCode": {
      "Code": "S001",
      "Description": "Transaction successfully processed"
    },
    "DateTime": "2020-11-19T15:29:40"
  },
  "RequiredAction": null,
  "Services": null,
  "CustomParameters": null,
  "AdditionalParameters": null,
  "RequestErrors": null,
  "ServiceCode": "Subscriptions",
  "IsTest": false,
  "ConsumerMessage": null
}