Subscriptions: set up recurring billing: Difference between revisions

From Barion Documentation
Jump to navigation Jump to search
(create page)
 
(fixed links)
Line 5: Line 5:
<blockquote>Once the funding source has been tokenized in the initial transaction, this is a customer-not-present scenario, so 3DS doesn’t apply.
<blockquote>Once the funding source has been tokenized in the initial transaction, this is a customer-not-present scenario, so 3DS doesn’t apply.
</blockquote>
</blockquote>
<span id="prerequisites"></span>
== 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
* an active Barion shop
* an active Barion shop
* 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
<span id="enable-token-payment-scenarios-for-your-barion-shop"></span>
=== Enable token payment scenarios for your Barion shop ===
=== Enable token payment scenarios for your Barion shop ===
<blockquote>Recurring payments are enabled by default in 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>
<blockquote>Recurring payments are enabled by default in 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>
<li>your customers are informed about how they can change their mind about the scenario
<li>your customers are informed about how they can change their mind about the scenario
<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].</blockquote>
<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 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.
</li>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.
 
<span id="create-a-token-to-represent-the-customers-payment-instrument"></span>
== 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.
Create a token to represent the customer’s payment instrument</blockquote>
</li><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 [[05-api-reference/01-payment-resource/01-payment-start|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>
<blockquote><p>The <code>PurchaseInformation</code> property, unique to recurring payments, is a structured property with nested properties of its own.</p></blockquote>
<ul>
<ul>
Line 43: Line 37:
</blockquote>
</blockquote>
<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>
<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>
<li><p>[[01-payments/02-basic-payment-concepts/03-callback-mechanism|Process the payment callback]] as usual.</p>
<li><p>[[Callback mechanism|Process the payment callback]] as usual.</p>
<syntaxhighlight lang="json">
<syntaxhighlight lang="json">
{
{
Line 69: Line 63:
}
}
</syntaxhighlight></li>
</syntaxhighlight></li>
<li><p>Query [[05-api-reference/01-payment-resource/01-payment-state|the payment state endpoint]], and store the <code>TraceId</code> in its response.</p>
<li><p>Query [[Payment-PaymentState-v4|the payment state endpoint]], and store the <code>TraceId</code> in its response.</p>
<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>
<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>
<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>
<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>
<span id="use-the-registered-token-for-recurring-payments"></span>
== Use the registered token for recurring payments ==
== Use the registered token for recurring payments ==


Line 91: Line 83:
<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.
<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.
</blockquote>
</blockquote>
<span id="steps"></span>
=== Steps ===
=== Steps ===


<ol style="list-style-type: decimal;">
<ol style="list-style-type: decimal;">
<li><p>Call [[05-api-reference/01-payment-resource/01-payment-start|the Payment start Barion API endpoint]], and pass it:</p>
<li><p>Call [[Payment-Start-v2|the Payment start Barion API endpoint]], and pass it:</p>
<ul>
<ul>
<li>the <code>TraceId</code> (if the call to the payment state endpoint after the initial payment returned one)</li>
<li>the <code>TraceId</code> (if the call to the payment state endpoint after the initial payment returned one)</li>
Line 181: Line 172:
|NotFound
|NotFound
|The RecurrenceId sent with the query wasn’t recognized.  
|The RecurrenceId sent with the query wasn’t recognized.  
|}</li></ul></ol>
|}</li></ul>
 
<span id="troubleshoot-subsequent-payments"></span>
== Troubleshoot subsequent payments ==
== Troubleshoot subsequent payments ==


Line 234: Line 223:


<ol style="list-style-type: decimal;">
<ol style="list-style-type: decimal;">
<li><p>Make a call to the [[05-api-reference/01-payment-resource/01-payment-start|the Payment start API endpoint]] with the following properties:</p>
<li><p>Make a call to the [[Payment-Start-v2|the Payment start API endpoint]] with the following properties:</p>
<ul>
<ul>
<li><p><code>InitiateRecurrence: true</code></p></li>
<li><p><code>InitiateRecurrence: true</code></p></li>
Line 241: Line 230:


<blockquote><p>Make sure not to include a <code>TraceId</code> property.</p></blockquote></li>
<blockquote><p>Make sure not to include a <code>TraceId</code> property.</p></blockquote></li>
<li><p>[[01-payments/02-basic-payment-concepts/03-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 [[05-api-reference/01-payment-resource/01-payment-state|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 07:39, 12 August 2024

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.

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

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

  • 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:

      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.

      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, and then used
      Overview of how the token (RecurrenceId) is registered, and then used

      If the endpoint responds with the RecurringPaymentNotAllowed error code, get in touch with Barion customer support to enable token payments for your shop.

    2. Process the payment callback as usual.

      {
        "PaymentId": "ee849878c554ef118c0c001dd8b71cc5",
        "PaymentRequestId": "DEV-TEST-615",
        "Status": "Prepared",
        "QRUrl": "https://api.test.barion.com/qr/generate?paymentId=ee849878-c554-ef11-8c0c-001dd8b71cc5&size=Large",
        "Transactions": [
          {
            "POSTransactionId": "DEV-TEST-01-01",
            "TransactionId": "ef849878c554ef118c0c001dd8b71cc5",
            "Status": "Prepared",
            "Currency": "EUR",
            "TransactionTime": "0001-01-01T00:00:00",
            "RelatedId": null
          }
        ],
        "RecurrenceResult": "None",
        "ThreeDSAuthClientData": null,
        "GatewayUrl": "https://secure.test.barion.com/Pay?Id=ee849878c554ef118c0c001dd8b71cc5",
        "RedirectUrl": "https://example.com/?paymentId=ee849878c554ef118c0c001dd8b71cc5",
        "CallbackUrl": "",
        "TraceId": null,
        "Errors": []
      }
    3. Query the payment state endpoint, and store the TraceId in its response.

      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.

    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.

      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": "ee849878c554ef118c0c001dd8b71cc5",
        "PaymentRequestId": "DEV-TEST-615",
        "Status": "Prepared",
        "QRUrl": "https://api.test.barion.com/qr/generate?paymentId=ee849878-c554-ef11-8c0c-001dd8b71cc5&size=Large",
        "Transactions": [
          {
            "POSTransactionId": "DEV-TEST-01-01",
            "TransactionId": "ef849878c554ef118c0c001dd8b71cc5",
            "Status": "Prepared",
            "Currency": "EUR",
            "TransactionTime": "0001-01-01T00:00:00",
            "RelatedId": null
          }
        ],
        "RecurrenceResult": "None",
        "ThreeDSAuthClientData": null,
        "GatewayUrl": "https://secure.test.barion.com/Pay?Id=ee849878c554ef118c0c001dd8b71cc5",
        "RedirectUrl": "https://example.com/?paymentId=ee849878c554ef118c0c001dd8b71cc5",
        "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.
      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.
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>

    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.