Subscriptions

Taxamo provides a very simple functionality that enables support for subscriptions with every transaction payment scenario.

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

  1. The transaction list in the merchant portal will mark the transaction with a "Placeholder" label.
  2. The invoicing mechanism in Taxamo will have the option to skip issuing invoices for placeholder transactions if that setting is enabled.

2. 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
         }]
     }
 }'

Notes

  1. With the private token status can be provided to store and confirm the transaction in a single call.
  2. The order_date should be set to null to make Taxamo use the current date or provided as an arbitrary value. If the order_date field is omitted completely, then the parent transaction's order date will be used.
  3. If some of your subscriptions are B2B then you can enable the 'Re-validate VAT numbers' setting in the dashboard so that Taxamo 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.

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 Taxamo 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 via 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).

NOTE: If using Taxamo Invoicing, it is possible to block invoice generation for noted transactions.


Did this page help you?