Subscriptions

Subscriptions are transactions with recurring payments.

To model these types of transactions in the service, complete the following steps:

1. Create a placeholder transaction

A placeholder transaction is one that is used in subscriptions to hold the location evidence at the time the subscription is initiated and is referenced by future renewal transactions.

There are no special requirements for a placeholder transaction. Any valid transaction can be referenced by another, making the referenced transaction the placeholder, but a common pattern is to create an initial zero-amount transaction as the placeholder and then reference in the initial payment transaction and all subsequent renewals.

Here is an example of what a placeholder transaction might look like:

{
    "transaction": {
      	"Status":"C",
        "transaction_lines": [{
            "custom_id": "plan_id",
            "amount": 0
        }],
        "custom_fields": [{
            "key": "placeholder-transaction",
            "value": "my psp"
        }],
        "currency_code": "EUR",
        "billing_country_code": "BE",
        "buyer_credit_card_prefix": "424242424"
    }
}

The custom field with a key placeholder-transaction is optional, but it is generally advised to set it during the creation of the placeholder transaction. This will allow:

  • The transaction list in the merchant portal will mark the transaction with a "Placeholder" label.
  • The invoicing feature allows you to skip issuing invoices for placeholder transactions if that setting is enabled. For more information, see Invoice Settings.

2. Create a sub-transaction for every payment

Next, you need to create a sub-transaction for every payment.

This placeholder transaction key can be referenced as an original_transaction_key when creating transactions with a private token and the manual_mode field is set to true.

Here is an example call using cURL:

curl -X POST https://services.taxamo.com/api/v2/transactions \
 --header "Content-type: application/json" -d \
'{
   "private_token": "SamplePrivateTestKey1",
     "manual_mode": true,
     "transaction": {
         "original_transaction_key": "TfKYAAAABwG-sHwPx7I5Wiq_XgSU",
         "status": "C",
         "order_date": null,
         "currency_code": "EUR",
         "transaction_lines": [{
             "custom_id": "1",
             "amount": 9.99
         }]
     }
 }

Note the following:

  • With the private token status can be provided to store and confirm the transaction in a single call.
  • The order_date should be set to null to ensure that the service uses the current date or it is provided as an arbitrary value. If the order_date field is omitted completely, then the parent transaction's order date will be used.
  • If some of your subscriptions are Business-t-Business (B2B), you can enable the Re-validate VAT numbers setting in the dashboard so that the service will re-verify the VAT number with every renewal. In the future, if the number fails to validate, the transaction will still succeed but you will be alerted to investigate and take corrective action.

3. Re-validate VAT numbers

When this option is enabled, each qualifying subscription renewal transaction will have its VAT number re-checked upon renewal.

If the VAT number turns out to be invalid, or if the validation service is not available, a notification will be sent to the account’s primary email. The transaction will be marked in the Dashboard, but the payment will not be stopped and the amount will not be changed.

To qualify for a re-check, the renewal transaction must be created using Stripe, Braintree and PayPal webhooks/IPN or using manual_mode and original_transaction_key, which uses a VAT number (this is currently available in the EU or Norway).

📘

Information

If you use the invoicing features, you can block invoice generation for noted transactions.

Invoices for Subscriptions

For more information, see Invoices for Subscriptions.