Payment Flow

Payment steps in a nutshell

1. You need to create a payment order.
2. Thunes Collections requests an authorization for the amount ordered with the payment method chosen by the user.
3. Once the authorization is granted, the authorized amount can be charged and/or cancelled within a defined validity period (7 days).
4. All amounts charged may subsequently be refunded.

NOTE: Charging operations, cancellations and refunds may be partial. You can cancel part of a payment and charge the remainder, or charge/refund in several installments, etc.

Payment flow description

Step 1: Creating the payment order:

• The user reaches the stage of paying the order; the shopping cart contains two products each from a different vendor.

• On your payment method selection page, the user selects a credit card payment method managed by Thunes Collections.

• You call the PaymentOrder/Create web service to generate a payment order. This call must include the following:

  1. The identifier of the payment method selected: CreditCard, Alipay, Sofort, Giropay, iDeal, Mistercash, etc...

  2. The merchant identifier:

     • for a single-vendor order: the vendor’s Thunes ID.
     • for a multi-vendor order: a technical merchant ID provided by Thunes Collections at the start of the project.

  3. Order information (amount, customer information, etc.)

  4. Return URLs for the various possible payment results:

     • Successful authorization request (ReturnUrl)
     • Cancellation by the user, or authorization refused (AbortedUrl)
     • Error during the payment operation (ErrorUrl)

  5. An optional, but highly recommended, notification URL (ServerNotificationUrl) that we will call in server-to-server mode to notify you of important events in the payment order life cycle (e.g. payment result in case of interruption in the clickstream, when redirecting the user to your site)

• Thunes Collections then creates the payment order and returns the URL for, in this example, the credit card payment page.

• You can then flag the order as "pending payment validation".

Step 2: Payment:

• You redirect the user to the payment page using the URL provided by Thunes Collections.

• The user enters his or her credit card numbers required for a payment.

• If the user cancels the payment, Thunes Collections redirects the user to the cancellation URL (AbortedUrl) provided in Step 1, where you can display an appropriate message and cancel the order. If the user closes the web browser without clicking on the cancel button, the payment order will be cancelled automatically (no later than 120 minutes after the payment), and you will be notified of this operation.

Step 3: Payment Result:

Mono-vendor payment diagram

Multi-vendor payment diagram

• Upon acceptance of the payment, Thunes Collections redirects the user to the return URL (ReturnUrl) that you have provided. You must then check the payment order status by calling the PaymentOrder/Detail web service (for security reasons). When the user is redirected to the ReturnUrl, Thunes Collections notifies you that the payment result is known. Therefore, in case of interruption in the user clickstream, you will still be able to follow through on the order. Thunes Collections advise you to initiate your order confirmation processing operations on the first feedback you receive (ReturnUrl via the user, or ServerNotificationUrl):

  • If the status is Authorized or Charged:

    • For a single-vendor transaction, you can confirm the order, display a successful payment message, and send out a confirmation email. If the transaction is Authorized, you can then charge or cancel or refund the payment, as described in Step 4 below, using the Thunes ID for the transaction. If the transaction is Charged, you can then only refund the payment.

    • For a multi vendor transaction, you can generate payment orders to the vendors involved. For each vendor, you must call the web service PaymentOrder/Pay, providing:

      • The Thunes identifier for the technical transaction (created initially)
      • The vendor’s identifier
      • the amount and sub-order reference, etc.

• If Thunes Collections refuses payment (inadequate balance, risk of fraud, etc.), Thunes Collections redirect the user to the cancellation URL (AbortedUrl), which is also used when the user voluntarily cancels the order (the status of the payment order is updated to Refused).

• If an error occurs, Thunes Collections redirects the user to the error URL provided when the payment order was created (ErrorUrl). Here you can display an appropriate message and cancel the order (payment order status is updated to Error).

• Once this process has been followed for each vendor, you can confirm the order to the buyer, display a successful payment message, and send out a confirmation email. You can then charge, cancel or refund the payment for each of the vendor’s transactions, as described in Step 4 below.

👍

What happens if the authorization for a multi-vendor transaction is KO?

If a multi-vendor transaction is KO, you can either partially validate the order or cancel it. To cancel the order, you have to cancel all previous Authorized transactions by requesting the Cancel web service to release authorized amounts on credit card and allow your customer to try and pay again.

Step 4: Post-Payment Operations:

Mono-vendor payment diagram

Multi-vendor payment diagram

• Once the payment orders have been authorized, several actions are possible for managing payment in the order it was chronologically processed for each vendor:

  • Total or partial cancellation (PaymentOrder/Cancel): Calling this web service is essential to service quality since it enables us to release the reserved funds to the user. If you omit this call, the amount will only be released at the end of the reservation period, which may be prolonged.

  • Total or partial charging operation (PaymentOrder/Charge): This web service can request for a vendor’s payment order to be charged and also inform us of the fee amount (commission). We make every effort to ensure that all payment methods involved in a transaction always issue a positive response to a charging request within six days, as for credit or debit card operations. However, we advise you to check the response to your charge request before following through on the order, whether or not the response is given within six days.

📘

For multi vendor orders, all post-payment operations (cancel, charge, refund) must be performed on transactions per vendor and not on the initial technical transaction, unlike with single vendor orders.

Please refer to the Status descriptions table for a list of the possible actions associated with each payment order status.