Subscriptions: set up recurring billing: Difference between revisions

From Barion Documentation
Jump to navigation Jump to search
(new diagrams, notificationboxes)
Line 2: Line 2:
{{TableOfContents}}
{{TableOfContents}}
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.
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.
<blockquote>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.
{{NotificationBox|title=Note|text=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.|color=#1993c7}}
</blockquote>
 
<blockquote>Once the payment instrument has been tokenized in the initial transaction, this is a customer-not-present scenario, so 3DS doesn’t apply.
</blockquote>
== Prerequisites ==
== Prerequisites ==
* a Barion Wallet with a balance in the currency of the payment
* a Barion Wallet with a balance in the currency of the payment
Line 11: Line 9:
* an approved request to Barion to allow recurring payment scenarios in the Barion shop
* an approved request to Barion to allow recurring payment scenarios in the Barion shop
=== Enable token payment scenarios for your Barion shop ===
=== Enable token payment scenarios for your Barion shop ===
<blockquote>Recurring payments are enabled by default in [[Sandbox|the Barion Sandbox environment]].</blockquote>Make sure that your webshop meets the following criteria for recurring payment scenarios:<ul><li>your customers are prompted to explicitly consent before you trigger the payment scenario</li>
{{NotificationBox|title=Note|text=Recurring payments are enabled by default in [[Sandbox|the Barion Sandbox environment]].|color=#1993c7}}
<ol><li>
Make sure that your webshop meets the following criteria for recurring payment scenarios:<ul><li>your customers are prompted to explicitly consent before you trigger the payment scenario</li>
<li>your customers are informed about how they can change their mind about the scenario</li></ul>
<li>your customers are informed about how they can change their mind about the scenario</li></ul>
<blockquote>Read the full list of Barion's criteria for enabling recurring payments for a Barion shop [https://www.barion.com/en/help/business/open-and-manage-a-shop/can-i-collect-fees-from-my-customers-on-a-monthly-basis/ here]. 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.
 
</blockquote>
{{NotificationBox|title=Note|text=[https://www.barion.com/en/help/business/open-and-manage-a-shop/can-i-collect-fees-from-my-customers-on-a-monthly-basis/ Read the full list of Barion's criteria for enabling recurring payments for a Barion shop].|color=#1993c7}}
</li>
<li>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.</li></ol>
== Create a token to represent the customer’s payment instrument ==
== Create a token to represent the customer’s payment instrument ==
<blockquote>Note that you need to request and receive consent from the customer [https://www.barion.com/en/help/business/open-and-manage-a-shop/can-i-collect-fees-from-my-customers-on-a-monthly-basis/ in a way that meets Barion’s relevant requirements], before you can register their payment instrument with Barion.
<blockquote>Note that you need to request and receive consent from the customer [https://www.barion.com/en/help/business/open-and-manage-a-shop/can-i-collect-fees-from-my-customers-on-a-monthly-basis/ in a way that meets Barion’s relevant requirements], before you can register their payment instrument with Barion.</blockquote>
</blockquote>
When you’d like to set up a recurring payment using a customer’s specific payment instrument, do the following.
When you’d like to set up a recurring payment using a customer’s specific payment instrument, do the following.
<ol style="list-style-type: decimal;">
<ol style="list-style-type: decimal;">
<li><p>Make a call to [[Payment-Start-v2|the Payment start API endpoint]] with the following four extra properties:</p>
<li><p>Make a call to [[Payment-Start-v2|the Payment start API endpoint]] with the following four extra properties:</p>
<blockquote><p>The <code>PurchaseInformation</code> property, unique to recurring payments, is a structured property with nested properties of its own.</p></blockquote>
{{NotificationBox|title=Note|text=The <code>PurchaseInformation</code> property, unique to recurring payments, is a structured property with nested properties of its own.|color=#1993c7}}
<ul>
<ul>
<li><p><code>InitiateRecurrence</code>: <code>true</code></p></li>
<li><p><code>InitiateRecurrence</code>: <code>true</code></p></li>
<li><p><code>RecurrenceId</code>: &lt;the unique token that you generate and save for the customer’s payment instrument&gt;</p>
<li><p><code>RecurrenceId</code>: &lt;the unique token that you generate and save for the customer’s payment instrument&gt;</p>
<blockquote><p>Multiple shops can share the same token – [mailto:[email protected] get in touch with Merchant Helpdesk] for details.</p></blockquote></li>
<blockquote>Multiple shops can share the same token – [mailto:[email protected] get in touch with Merchant Helpdesk] for details.</blockquote>
</li>
<li><p><code>RecurrenceType</code>: <code>RecurringPayment</code></p></li>
<li><p><code>RecurrenceType</code>: <code>RecurringPayment</code></p></li>
<li><p><code>PurchaseInformation</code></p>
<li><p><code>PurchaseInformation</code></p>
Line 32: Line 34:
<li><p><code>RecurringFrequency</code>: The minimum number of days between two payments with the specified <code>RecurrenceId</code>.</p></li></ul>
<li><p><code>RecurringFrequency</code>: The minimum number of days between two payments with the specified <code>RecurrenceId</code>.</p></li></ul>
</li></ul>
</li></ul>
<blockquote><p>The <code>RecurrenceResult</code> property, which indicates the status of the token registration is <code>None</code> 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.</p>
{{NotificationBox|title=Note|text=The <code>RecurrenceResult</code> property, which indicates the status of the token registration is <code>None</code> 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.|color=#1993c7}}
[[File:Recurring.png|alt=Overview of how the token (RecurrenceId) is registered, and then used|Overview of how the token (RecurrenceId) is registered, and then used]]
 
</blockquote>
[[File:Recurring registering.png|alt=Overview of how the token (RecurrenceId) is registered|Overview of how the token (RecurrenceId) is registered]]
<blockquote><p>If the endpoint responds with the <code>RecurringPaymentNotAllowed</code> error code, get in touch with Barion customer support to enable token payments for your shop.</p></blockquote></li>
<br/>
[[File:Recurring subsequent.png|alt=Overview of how the RecurrenceId is used in a subsequent subscription payment|Overview of how the RecurrenceId is used in a subsequent subscription payment]]
 
{{NotificationBox|title=Note|text=If the endpoint responds with the <code>RecurringPaymentNotAllowed</code> error code, get in touch with Barion customer support.|color=#1993c7}}
</li>
<li><p>[[Callback mechanism|Process the payment callback]] as usual.</p>
<li><p>[[Callback mechanism|Process the payment callback]] as usual.</p>
</li>
</li>
Line 82: Line 88:
}
}
</syntaxhighlight>
</syntaxhighlight>
<blockquote><p>If the tokenized payment instrument is a Barion Wallet balance, a <code>TraceId</code> is unnecessary, and won’t be returned in the payment state endpoint response.</p></blockquote>
{{NotificationBox|title=Note|text=If the tokenized payment instrument is a Barion Wallet balance, a <code>TraceId</code> is unnecessary, and won’t be returned in the payment state endpoint response.|color=#1993c7}}
<p>This value is crucial to recurring payments, as it represents the payment instrument for the given recurring payment scenario in subsequent transactions.</p>
<p>This value is crucial to recurring payments, as it represents the payment instrument for the given recurring payment scenario in subsequent transactions.</p>
<p>You’ll need to provide it for every subsequent payment in the recurring payment that you’ve just set up.</p>
<p>You’ll need to provide it for every subsequent payment in the recurring payment that you’ve just set up.</p>
<blockquote><p>Best practice is to also store the <code>FundingSource</code> and <code>FundingInformation</code> 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 <code>RecurrenceId</code> token will represent in future payments.</p></blockquote></li></ol>
{{NotificationBox|title=Note|text=Best practice is to also store the <code>FundingSource</code> and <code>FundingInformation</code> 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 <code>RecurrenceId</code> token will represent in future payments.|color=#1993c7}}
 
</li></ol>
== Use the registered token for recurring payments ==
== Use the registered token for recurring payments ==
<span id="prerequisites-1"></span>
<span id="prerequisites-1"></span>
Line 95: Line 101:
* at least a number of days specified in the <code>RecurringFrequency</code> property must elapse between two payments in a recurring scenario
* at least a number of days specified in the <code>RecurringFrequency</code> 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 <code>RecurringExpiry</code> property
* the date of a payment in a recurring payment scenario can’t be later than the specified <code>RecurringExpiry</code> property
<blockquote>Note that you can switch to a different payment scenario if the above conditions are no longer met, by requesting a new <code>TraceId</code> for the customer’s payment instrument.
{{NotificationBox|title=Note|text=You can switch to a different payment scenario if the above conditions are no longer met, by requesting a new <code>TraceId</code> for the customer’s payment instrument.|color=#1993c7}}
</blockquote>
=== Steps ===
=== Steps ===
<ol style="list-style-type: decimal;">
<ol style="list-style-type: decimal;">
Line 105: Line 110:
<li><code>RecurrenceType: RecurringPayment</code>, and</li>
<li><code>RecurrenceType: RecurringPayment</code>, and</li>
<li><code>InitiateRecurrence: false</code>.</li></ul>
<li><code>InitiateRecurrence: false</code>.</li></ul>
<blockquote><p>Don’t pass a <code>PurchaseInformation</code> property – you’ve already fixed the values of its sub-properties during the initial token-registering payment.</p></blockquote>
{{NotificationBox|title=Note|text=Don’t pass a <code>PurchaseInformation</code> property – you’ve already fixed the values of its sub-properties during the initial token-registering payment.|color=#1993c7}}{{NotificationBox|title=Note|text=Recurring payments are enabled by default in [[Sandbox|the Barion Sandbox environment]].|color=#1993c7}}
<syntaxhighlight lang="json">
<syntaxhighlight lang="json">
     {
     {
Line 186: Line 191:
|None
|None
|No token payment was requested (<code>InitiateRecurrence</code> was omitted, or set to <code>true</code>).<br/>Repeat steps 1–2, making sure to pass <code>InitiateRecurrence: true</code>.
|No token payment was requested (<code>InitiateRecurrence</code> was omitted, or set to <code>true</code>).<br/>Repeat steps 1–2, making sure to pass <code>InitiateRecurrence: true</code>.
|-
|ThreeDSAuthenticationRequired
|This return value doesn’t apply when the registered payment instrument is a Barion Wallet.<br/>The holder of the card whose token you registered is challenged to perform 3DSecure authentication.<br/>In a recurring payment scenario this can only happen if the <code>TraceId</code> is missing or incorrect, that is, it refers to a payment instrument different from the initial token-registering payment.<br/>To fix this, call the payment state endpoint, and repeat steps 1–2, making sure to use the <code>TraceId</code> parameter that the payment state endpoint returned.
|-
|-
|NotFound
|NotFound
Line 247: Line 249:
<li><p><code>RecurrenceId</code>: <code>&lt;the original token&gt;</code></p></li>
<li><p><code>RecurrenceId</code>: <code>&lt;the original token&gt;</code></p></li>
<li><p><code>RecurrenceType</code>: <code>&lt;the value first used&gt;</code></p></li></ul>
<li><p><code>RecurrenceType</code>: <code>&lt;the value first used&gt;</code></p></li></ul>
 
{{NotificationBox|title=Note|text=Make sure not to include a <code>TraceId</code> property.|color=#1993c7}}
<blockquote><p>Make sure not to include a <code>TraceId</code> property.</p></blockquote></li>
<li><p>[[Callback mechanism|Wait for the callback]] and verify that the customer paid the order.</p></li>
<li><p>[[Callback mechanism|Wait for the callback]] and verify that the customer paid the order.</p></li>
<li><p>Query [[Payment-PaymentState-v4|the payment state endpoint]], and store the newly-generated <code>TraceId</code> that the endpoint returns.</p></li>
<li><p>Query [[Payment-PaymentState-v4|the payment state endpoint]], and store the newly-generated <code>TraceId</code> that the endpoint returns.</p></li>
<li><p>Use the new <code>TraceId</code> for subsequent payments as before.</p></li></ol>
<li><p>Use the new <code>TraceId</code> for subsequent payments as before.</p></li></ol>

Revision as of 12:16, 12 August 2024

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
  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.

    Overview of how the token (RecurrenceId) is registered
    Overview of how the RecurrenceId is used in a subsequent subscription payment

    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.

    {
        "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": "trid-e94f6993bdec463da5079cb7b5b56616",
        "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.
    Note
    Recurring payments are enabled by default in the Barion Sandbox environment.
        {
        "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=093a87ea9158ef118c0c001dd8b71cc5&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.