The AgoraPay drop-in system allows you to quickly implement AgoraPay on your payment page and start accepting payments. AgoraPay will handle the payment process via an iFrame mechanism.
If you want full control over the payment process, you can use the API only system.
How it works
The diagram describes the flows between your marketplace and AgoraPay when using the drop-in system:
This diagram shows the communication between your marketplace and AgoraPay:
- When your shopper is ready to pay, you submit your order to retrieve an authentication code and an orderId.
- With the authentication code and URL, you instantiate the drop-in system.
- The shopper can then choose a payment method and pay directly in the iFrame.
- You can then retrieve the payment results and proceed.
Before you begin
First, make sure you have followed our getting started guide to set up your test account, get your API credentials, and install AgoraPay.
Step 1 : Submit your paymentIframe request
When your shopper is ready to pay, you can submit a request and retrieve an authentication code and URL in order to instantiate the iFrame.
From your server, make a /payin/paymentIframe request:
Here is an example of JSON payload to the /payin/paymentIframe request:
"metaData": "sample data"
Retrieving the result
If your request is successful and the order gets created, you can retrieve the authentication code and iFrame URL.. You will receive the paymentIframeResponse object, containing the following information:
Reference of the order, to be use in every next request
Authentification Code to use to open user iframe
Site name or number
Url to connect iframe to.
Here is a successful response example:
Step 2: Instantiate drop-in iFrame
Once you have successfully retrieved the authenticationCode and URL, you can instantiate AgoraPay drop-in system.
If you encountered an error, please refer to our Payment error codes page for troubleshooting.
In the header of your page, add the following code.
In order to display the iFrame, you must use the pai.startPayment function with the following parameters:
Contains all the parameters required to instantiate the iFrame:
- startUrl: URL used to obtain the authentication code. This URL must match a page on your website that will call the function paymentIframe and return the authentication code and the payment URL as a JSON object (with keys authenticationCode and URL).
- By default, this value is “/token”.
- endUrl: The page to redirect the user to at the end of the payment. If not given, the marketplace must handle the redirection itself.
- requestMethod: Method used to obtain the authentication code for your Platform:
- GET: default value
- iframeContainerId: ID of the iframe’s container on your page.
- By default, this value is “paiIframeContainer” and the iFrame will be located at the centre of your page.
- If the name is not defined into the call or if the name is different de payIframeContainer then the iFrame will be in superposition
If not given, the page will be redirected to the endUrl with the following parameters:
- No authentication code returned
- Connection error to the Platform while trying to obtain the authentication code
- Error in decoding the authentication data returned by the Platform.
If given, this function will be called with the following parameters:
- abort: For cancel
- success: For success
- Resize: when request to change iFrame dimensions
- 0: in the event of success
- Height: Frame's height if messageType is resize
- Width: Frame's width if messageType is resize
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
Step 3: Make a payment
Once you have integrated the iFrame, AgoraPay will handle the payment. The shopper's payment details will be collected, and the chosen payment method will be used for completing the order.
The payment methods labels are chosen by the marketplace and can be changed.
Additional rules can be defined for the payment methods, such as forcing a specific payment method above a certain amount.
If you encounter any error, you can check the following pages for troubleshooting:
- List of API error codes