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
How to read the flow charts
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.
Please note that the flow charts are meant to illustrate the sequencing principles of the API and the handling of key attributes (notably orderReference, orderId, transactionId described in the payin operations life cycle). For an exhaustive description of the input and output parameters of the API, please refer to the API reference.
Credit-card payment 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
New credit-card payment
The flow is mainly driven by whether there is an initial capture in the /payin/payment call or not.
New Drop-in credit-card payment
Credit Card - Re-use payment alias
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.
Re-use payment authorization
The SCT payment flows are only affected by whether you provide an initial split (to split the cart transaction revenue across multiple vendors).
New SCT payment
Re-used SCT payment
SDD payment flows
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.
New SDD payment
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.
Recurring SDD payment
Setting the sequence to RCUR or FNAL allows to use to execute recurring payments as described in the SDD payments section.