Subscriptions: set up recurring billing

Subscriptions: set up recurring billing

Find out how to use the Barion Gateway API to set up a subscription – billing your customer at regular intervals for an ongoing service. In a subscription, a Barion shop is authorized by the customer to charge the customer’s specific payment instrument the same amount at predefined intervals, until a predefined future date.

Note

The transactions in subscription payments aren’t automated – the feature lets you as a merchant set up the intervals and amounts, but you’ll still have to explicitly charge your customer.

Prerequisites

• a Barion Wallet with a balance in the currency of the payment
• an active Barion shop
• an approved request to Barion to allow recurring payment scenarios in the Barion shop

Enable token payment scenarios for your Barion shop

Note

Recurring payments are enabled by default in the Barion Sandbox environment.

1. Make sure that your webshop meets the following criteria for recurring payment scenarios:
   • your customers are prompted to explicitly consent before you trigger the payment scenario
   • your customers are informed about how they can change their mind about the scenario
   Note

   Read the full list of Barion's criteria for enabling recurring payments for a Barion shop.
2. Ask Barion customer support for details about enabling the feature, and to request recurring payments using the Customer service tab in your Barion Wallet, or the "Other>Help" screen in the Barion app.

Create a token to represent the customer’s payment instrument

Note that you need to request and receive consent from the customer in a way that meets Barion’s relevant requirements, before you can register their payment instrument with Barion.

When you’d like to set up a recurring payment using a customer’s specific payment instrument, do the following.

1. Make a call to the Payment start API endpoint with the following four extra properties:

   Note

   The PurchaseInformation property, unique to recurring payments, is a structured property with nested properties of its own.

   • InitiateRecurrence: true

   • RecurrenceId: <the unique token that you generate and save for the customer’s payment instrument>

     Multiple shops can share the same token – get in touch with Merchant Helpdesk for details.

   • RecurrenceType: RecurringPayment

   • PurchaseInformation

     • RecurringExpiry: The locale-specific date past which no subsequent charges are accepted for the payment instrument using the specified RecurrenceId.

     • RecurringFrequency: The minimum number of days between two payments with the specified RecurrenceId.

   Note

   The RecurrenceResult property, which indicates the status of the token registration is None at this stage, because the registration of a payment instrument effectively happens when the customer selects the given payment instrument on the Barion Smart Gateway UI.

   
   

   Note

   If the endpoint responds with the RecurringPaymentNotAllowed error code, get in touch with Barion customer support.

2. Process the payment callback as usual.

3. Query the payment state endpoint, and store the TraceId in its response.

   Make sure you store the TraceId as-is, including whitespace characters – often the identifier includes multiple spaces or symbols; this is normal.

   {
       "PaymentId": "093a87ea9158ef118c0c001dd8b71cc5",
       "PaymentRequestId": "TEST-01",
       "OrderNumber": null,
       "POSId": "your-POSKey",
       "POSName": "Modify Name",
       "POSOwnerEmail": "[email protected]",
       "POSOwnerCountry": "HU",
       "Status": "Succeeded",
       "PaymentType": "Immediate",
       "FundingSource": "BankCard",
       "RecurrenceType": "RecurringPayment",
       "TraceId": "[this is the important line]",
       "FundingInformation": {
           "BankCard": {
               ...
           },
           "AuthorizationCode": "iw5q3o",
           "ProcessResult": "Successful"
       },
       "AllowedFundingSources": [
           "All"
       ],
       "GuestCheckout": true,
       ...
       "Transactions": [
           {
               "TransactionId": "0a3a87ea9158ef118c0c001dd8b71cc5",
               ...
           },
           {
               "TransactionId": "fd9cbd5c9258ef118c0c001dd8b71cc5",
               ...
           }
       ],
       "Total": 100.00,
       ...
       "Currency": "HUF",
       "PaymentMethod": "BankCard",
       "Errors": []
   }

   Note

   If the tokenized payment instrument is a Barion Wallet balance, a TraceId is unnecessary, and won’t be returned in the payment state endpoint response.

   This value is crucial to recurring payments, as it represents the payment instrument for the given recurring payment scenario in subsequent transactions.

   You’ll need to provide it for every subsequent payment in the recurring payment that you’ve just set up.

   Note

   Best practice is to also store the FundingSource and FundingInformation values in the payment state response – these indicate the type of payment method and the description of the payment instrument that the customer has selected for the payment, and so the payment instrument that the RecurrenceId token will represent in future payments.

Use the registered token for recurring payments

Prerequisites

Unless the tokenized payment instrument is a Barion Wallet balance, you’ll need a TraceId from a successful recurrence-initializing payment for all subsequent payments in a recurring payment scenario. There are three conditions that need to be met for a recurring payment transaction to be successful:

• the amount in the subsequent payment can’t exceed the original payment where the token was set up
• at least a number of days specified in the RecurringFrequency property must elapse between two payments in a recurring scenario
• the date of a payment in a recurring payment scenario can’t be later than the specified RecurringExpiry property

Note

You can switch to a different payment scenario if the above conditions are no longer met, by requesting a new TraceId for the customer’s payment instrument.

Steps

1. Call the Payment start Barion API endpoint, and pass it:

   • the TraceId (if the call to the payment state endpoint after the initial payment returned one)
   • the registered RecurrenceId,
   • RecurrenceType: RecurringPayment, and
   • InitiateRecurrence: false.
   Note

   Don’t pass a PurchaseInformation property – you’ve already fixed the values of its sub-properties during the initial token-registering payment.

       {
       "POSKey": "[[SECRET_POS_KEY]]",
       "PaymentType": "Immediate",
       "PaymentRequestId": "EXMPLSHOP-PM-002",
       "InitiateRecurrence": false,
       "RecurrenceId": "SHOP-XMLP-TOKEN-ABC-123",
       "RecurrenceType": "RecurringPayment",
       "TraceId": "FGTRR55322843442124780",
       "FundingSources": ["All"],
       "GuestCheckOut" : true,
       "Currency": "EUR",
       "Transactions": [
           {
               "POSTransactionId": "EXMPLSHOP-PM-002/TR001",
               "Payee": "[[MERCHANTS_BARION_EMAIL]]",
               "Total": 25.2,
               "Comment": "Subscription fee for the second month",
               "Items": [
                   {
                       "Name": "Website subscription",
                       "Description": "Website subscription for one month",
                       "Quantity": 1,
                       "Unit": "month",
                       "UnitPrice": 25.2,
                       "ItemTotal": 25.2,
                       "SKU": "EXMPLSHOP/SKU/PHC-02"
                   }
               ]
           }
       ]
       }

2. Check the RecurrenceResult property in the payment start endpoint response, which indicates whether the token registration had been successful:

   A generic Payment/Start API endpoint response:

   {
       "PaymentId": "fa2bf7469358ef118c0c001dd8b71cc5",
       "PaymentRequestId": "TEST-15",
       "Status": "Succeeded",
       "QRUrl": "https://api.test.barion.com/qr/generate?paymentId=fa2bf746-9358-ef11-8c0c-001dd8b71cc5&size=Large",
       "Transactions": [
           {
               "POSTransactionId": "TEST-15-02",
               "TransactionId": "fb2bf7469358ef118c0c001dd8b71cc5",
               "Status": "Succeeded",
               "Currency": "HUF",
               "TransactionTime": "2024-08-12T10:11:46.253",
               "RelatedId": null
           },
           {
               "POSTransactionId": null,
               "TransactionId": "fd2bf7469358ef118c0c001dd8b71cc5",
               "Status": "Reserved",
               "Currency": "HUF",
               "TransactionTime": "2024-08-12T10:11:46.253",
               "RelatedId": null
           }
       ],
       "RecurrenceResult": "Successful",
       "ThreeDSAuthClientData": null,
       "GatewayUrl": "https://secure.test.barion.com/Pay?Id=fa2bf7469358ef118c0c001dd8b71cc5",
       "RedirectUrl": "https://example.com/?paymentId=fa2bf7469358ef118c0c001dd8b71cc5",
       "CallbackUrl": "",
       "TraceId": null,
       "Errors": []
   }

   RecurrenceResult value	Description
   Successful	The token had been registered successfully to the payment instrument that the customer used to complete the initial payment. The token had been registered successfully to the payment instrument that the customer used to complete the initial payment. The subsequent payment is paid for using the token that now represents the customer’s payment instrument.
   Failed	The token won’t work. Check the call details, and try again.
   None	No token payment was requested (InitiateRecurrence was omitted, or set to true). Repeat steps 1–2, making sure to pass InitiateRecurrence: true.
   NotFound	The RecurrenceId sent with the query wasn’t recognized.

Troubleshoot subsequent payments

Here’s the list of possible error codes that subsequent recurring payments can trigger, and how best to deal with them.

Error code	Description
InvalidRecurrenceId	The registered token was found to be invalid. This is usually because the token’s registration had failed. Try again from the top.
RecurringPaymentDenied	The user associated with the token had been deleted, suspended, or blocked since the token was registered.
InsufficientFunds	The Barion Wallet that the token represents doesn’t have enough funds to fulfill the charge.
OriginalPaymentWasntSuccessful	The payment where the bank card that the token represents was registered didn’t itself succeed, which had invalidated the token.
InvalidCurrency	The Barion Wallet that the token represents doesn’t have a balance in the currency that the current payment requires.
CardExpired	The bank card that whose token was registered had since expired. Re-initialize the original RecurrenceId to fix this.
TopUpFailed	This is an error code that isn’t relevant to the scenario, but which might still pop up. It’s usually accompanied by another more specific error code.
ThreeDSNotEnabled	The issuer rejected the tokenized bank card because of a lack of Strong Customer Authentication.
InvalidUser	The source Barion Wallet doesn’t exist or isn’t fully activated.
UserCantMakeOutgoingTransaction	The source Barion Wallet is suspended or doesn’t exist.
CardError	An error occurred in either the 3DS authentication system or the bank system when processing the tokenized bank card. There can be several causes for this, from security settings to active limits on the card. You’ll need to reach out to the customer to troubleshoot the issue.
PingFailed	The bank or other third party didn’t respond to the request, so the Barion Payment API cancelled it. Try again later.

Troubleshoot an invalidated payment instrument

If the payment instrument you’ve registered has become invalid since the initial payment (expires, gets reported as lost, etc.), you’ll need to re-register the payment instrument’s RecurrenceId to go on using it in the scenario.

1. Make a call to the the Payment start API endpoint with the following properties:

   • InitiateRecurrence: true

   • RecurrenceId: <the original token>

   • RecurrenceType: <the value first used>

   Note

   Make sure not to include a TraceId property.

2. Wait for the callback and verify that the customer paid the order.

3. Query the payment state endpoint, and store the newly-generated TraceId that the endpoint returns.

4. Use the new TraceId for subsequent payments as before.