Find out how to use the Barion Gateway API to set up a subscription (recurring payment in Barion terminology). In a recurring payment, 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.
The transactions in recurring payments aren’t automated – the feature lets merchants set up recurrence, but they’ll have to explicitly charge the customer themselves in the scenario.
Once the funding source has been tokenized in the initial transaction, this is a customer-not-present scenario, so 3DS doesn’t apply.
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
Recurring payments are enabled by default in the Barion Sandbox environment.
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
Read the full list of Barion's criteria for enabling recurring payments for a Barion shop here.Ask Barion customer support to enable recurring payments for your Barion shop, 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
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.
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.
If the endpoint responds with the RecurringPaymentNotAllowed error code, get in touch with Barion customer support to enable token payments for your shop.
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.
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 that 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.
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.
ThreeDSAuthenticationRequired
This return value doesn’t apply when the registered payment instrument is a Barion Wallet. The holder of the card whose token you registered is challenged to perform 3DSecure authentication. In a recurring payment scenario this can only happen if the TraceId is missing or incorrect, that is, it refers to a payment instrument different from the initial token-registering payment. To fix this, call the payment state endpoint, and repeat steps 1–2, making sure to use the TraceId parameter that the payment state endpoint returned.
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.
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.