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:

  1. When your shopper is ready to pay, you submit your order to retrieve an authentication code and an orderId.
  2. With the authentication code and URL, you instantiate the drop-in system.
  3. The shopper can then choose a payment method and pay directly in the iFrame.
  4. 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:

Parameter Name
Required
Type
Description
orderReference
check
string
Marketplace reference for this order. Characters authorized are: a to z, A to Z, 0 to 9 and - / . + _ : and space
orderCountryCode
check
string
The ISO country code in 3 characters format
amount
check
object
amount information
breakdownList
array
breakdown list
payer
check
object
payer information
capture
string
Capture indicator. Set to "0" for authorization only (default value 1 - transaction captured))
metaData
object
JSON data for the marketplace. This data is not used by payment systems.
recurrent
string
recurrent indicator "1" for recurrent payment "0" or absent if not a recurrent payment
endToEndId
string
Use to identify transaction in SEPA transfer. Autorized characters are alpha numeric, - and /. Characters / and space are authorized but not in first and last position. Also, two // are not allowed.
paymentMethodId
string
Identifier of the payment method. If given, the end-user will be redirected to the corresponding payment method iFrame. If not given, the end-user will be redirected to the payment method selection iFrame.
urlRedirect
string
Url where the customer must be redirected at the end of the payment with the partner. This URL is completed by /success, /error or /cancel according to the partner response status. When the customer will be redirected to the marketPlace at the end of the partner payment process, the paymentDetails function must be called to terminate payment with the data transmitted by the partner. For development purpose, you can use http://127.0.0.1 (localhost is not supported)
cart
object
Cart detail for 3DSV2. Mandatory in API v2.
paymentAccount
string
cbChallenge
string
Challenge negotiation for card payment. 01: No preference 02: No challenge required 03: Desired challenge 04: Required challenge
details
object
Payment details information For some payment methods, additional details are needed.
page
string
Type of page to display. - iframe: integrated in marketplace site (default) - full: full page

Example Copy section link Copied!

Here is an example of JSON payload to the /payin/paymentIframe request:

JSON
Copy
Copied
{
"orderReference": "ref_0102636",
"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"
}
Copy
Copied

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:

Parameter Name
Type
Description
resultCode
string
orderId
string

Reference of the order, to be use in every next request

resultCodeMessage
string
authenticationCode
string

Authentification Code to use to open user iframe

Site
string

Site name or number

url
string

Url to connect iframe to.

Example Copy section link Copied!

Here is a successful response example:

JSON
Copy
Copied
{
"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"
}
Copy
Copied

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!

HTML
Copy
Copied
1
<script type="text/javascript" src="https://checkout.test.agorapay.com/js/payment.js"></script>
Copy
Copied

Production mode Copy section link Copied!

HTML
Copy
Copied
1
<script type="text/javascript" src="https://checkout.agorapay.com/js/payment.js"></script>
Copy
Copied

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:

HTML
Copy
Copied
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
<html>
<head>
<meta charset=utf-8>
<meta http-equiv=X-UA-Compatible content="IE=edge">
<meta name=viewport content="width=device-width,initial-scale=1">
<script type="text/javascript" src="https://checkout.test.agorapay.com
</head>
<body>
<script>
function start() {
pai.startPayment({
startUrl:"https://mamarketplace.com/cgi-bin/token.cgi",
},(result) => {
console.log("result", result);
// Continue after payment end
});
}
</script>
<h1>Marketplace</h1>
<input type='button' value='Pay' onclick="start()"></input>
<div id="paiIFrameContainer"></div>
</body>
</html>
Copy
Copied

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:

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.