Payment flow Copy section link Copied!

Completing the entire payment flow requires making specific sequences of AgoraPay API calls depending on the payment scenarios you implement on your marketplace.

This section describes the API flow sequences for the various payment methods and payment types (one-time versus recurring payment). It will introduce you to the key API calls you will be using for managing payments:

• /payin/paymentMethods/ to retrieve the available payment methods for a customer order
• /payin/payment/ to initiate a payment
• /payin/paymentIframe/ to initiate a payment via the AgoraPay Drop-in mechanism
• /payin/cancel/ to cancel a payment transaction
• /payin/refund/ to request a refund
• /payin/adjustPayment/ to split the transaction across the cart vendors

The flow charts below reference the main API calls of the AgoraPay platform that you will have to instantiate in your marketplace before making and modifying payments. Each call takes input parameters and results in output parameters. While most API calls can be followed by any other API calls, you must follow the sequences for the specific scenarios.

The charts will help you to:

• Understand how certain parameters can influence the user experience
• Learn which optional parameters might impact subsequent flows
• When new transactions get created (typically /payin/capture and /payin/refund calls generate a new transactionId for the same orderReference and orderId)
• How you can re-use previous payment information (such as a credit-card alias or previous payment transactionIds) to perform recurring payments

Please refer to the financial flow section to understand how AgoraPay handles the payment flow, from the creation to the clearing process and how the notions of order, transaction and operation relate to each other, as these are key to the understanding of the process flows.

The flow for the credit-card payment method is influenced by 2 factors:

• Whether you want to perform an authorisation and payment together or an authorisation only followed by a later capture
• Whether you want the end-user to enter a new credit-card or you want to reuse a known card you have previously recorded

The flow is mainly driven by whether there is an initial capture in the /payin/payment call or not.

If you use the drop-in system instead of the API-only implementation, the flow is similar except that the use of the /payin/paymentIframe API covers the paymentMethod and payment calls.

To make a credit-card recurring payment, a known payment alias you retrieved from a previous payment through the /payin/paymentMethods API must be used.

The SCT payment flows are only affected by whether you provide an initial split (to split the cart transaction revenue across multiple vendors).

SDD payments are largely dependent on how AgoraPay platform evaluates and scores a payment request. 2 outcomes are possible:

• The scoring of the transaction requires a digital signature. In this case, the customer is presented, via a web interaction, with a digital mandate to be signed with a One-Time-Password sent to their mobile phone.
• The transaction only requires a certification without a signature and the transaction passes immediately to the completed status

In both cases, the customer receives a pre-notification email informing about them of the upcoming SEPA payment. You can set the number of days to wait between the email notification and the funds transfer.

AgoraPay recommends a 14 days’ notice period (higher values will increase the risk of overdue payments). Note that the funds will be available on your marketplace account one day after the client transfer is executed.

The response to the /payin/payment API will control whether you need to provide a web interaction with the customer or not (presence of redirectUrl parameter).

As for the SCT payment, using an initial split affects the ability to use /payin/refund.

Setting the sequence to RCUR or FNAL allows to use to execute recurring payments as described in the SDD payments section.