Drop-in system Copy section link Copied!
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 Copy section link Copied!
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 Copy section link Copied!
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 Copy section link Copied!
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:
Example Copy section link Copied!
Here is an example of JSON payload to the /payin/paymentIframe request:
{
"orderReference": "ref0102636",
"orderCountryCode": "FRA",
"amount": {
"value": "12.45",
"currency": "EUR"
},
"payer": {
"reference": "customer1"
},
"breakdownList": [
{
"label": "ref1",
"sellerAccountNumber": "1300600000EUR60002411",
"amount": {
"value": "12.00",
"currency": "EUR"
}
},
{
"label": "ref2",
"sellerAccountNumber": "1300600000EUR60002411",
"amount": {
"value": "0.45",
"currency": "EUR"
}
}
],
"capture": "1",
"metaData": {
"metaData": "sample data"
},
"urlRedirect": "https://monsite.com/paymentEnd"
}
Retrieving the result Copy section link Copied!
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.
Example Copy section link Copied!
Here is a successful response example:
{
"resultCode": "0",
"orderId": "249021",
"authentificationCode": "db1a03ec-c6f5-565e-06ba-0df30507738c",
"url": "https://frontal.paymentsite.com?code=db1a03ec-c6f5-565e-06ba-0df30507738&site=1",
"site": "1"
}
Step 2: Instantiate drop-in iFrame Copy section link Copied!
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.
Test mode Copy section link Copied!
1 | |
Production mode Copy section link Copied!
1 | |
When the Javascript is loaded, an object called “pai” will be created, containing all client API functions.
In order to display the iFrame, you must use the pai.startPayment function with the following parameters:
Parameter name
Required
Type
Description
params
Yes
object
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
- POST
- 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
callback
No
object
If not given, the page will be redirected to the endUrl with the following parameters:
- resultCode:
- 9991
- 9992
- 9993
- error:
- 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:
- messageType:
- abort: For cancel
- success: For success
- Resize: when request to change iFrame dimensions
- resultCode:
- 0: in the event of success
- Height: Frame's height if messageType is resize
- Width: Frame's width if messageType is resize
- transactionId
- transactionStatusCode
Example Copy section link Copied!
Here is an example of an HTML page invoking the AgoraPay Javascript library:
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 Copy section link Copied!
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.
Error handling Copy section link Copied!
If you encounter any error, you can check the following pages for troubleshooting:
- List of API error codes
Test and go live Copy section link Copied!
You can use your test payment methods delivered by your implementation manager to test your integration and make sure everything is working. You can also track and manage your test payments within your transactions dashboard from AgoraPay Portal.