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.
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
-
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
- 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.
Make a call to the Payment start API endpoint with the following four extra properties:
NoteThePurchaseInformation
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 specifiedRecurrenceId
.RecurringFrequency
: The minimum number of days between two payments with the specifiedRecurrenceId
.
NoteTheRecurrenceResult
property, which indicates the status of the token registration isNone
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.NoteIf the endpoint responds with theRecurringPaymentNotAllowed
error code, get in touch with Barion customer support.Process the payment callback as usual.
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": [] }
NoteIf the tokenized payment instrument is a Barion Wallet balance, aTraceId
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.
NoteBest practice is to also store theFundingSource
andFundingInformation
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 theRecurrenceId
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
TraceId
for the customer’s payment instrument.Steps
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
, andInitiateRecurrence: false
.
NoteDon’t pass aPurchaseInformation
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" } ] } ] }
- the
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 totrue
).
Repeat steps 1–2, making sure to passInitiateRecurrence: 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.
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>
NoteMake sure not to include aTraceId
property.Wait for the callback and verify that the customer paid the order.
Query the payment state endpoint, and store the newly-generated
TraceId
that the endpoint returns.Use the new
TraceId
for subsequent payments as before.