API only Copy section link Copied!

If you want full control over your checkout process, AgoraPay exposes an API for you to build your own payment form.


If you prefer to let AgoraPay handle most of the process, you can check our drop-in system.

How it works Copy section link Copied!

There are 2 ways to initiate payments:

  1. The user has not chosen a payment method yet. See Step 1.
  2. For some payment methods, such as SDD recurring payments or card payments, you might want to handle the payment methods on your side. If the user has already chosen their payment method, and you want to proceed straight to the payment, you can skip step 1, and you won’t have an orderId. Skip to Step 2.

For some payment methods, you will need to send additional payment information. You can read more about these in Step 3.

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 : Retrieve the available payment methods Copy section link Copied!

When your shopper enters the checkout page, you can transfer their details to retrieve the available payment methods.

From your server, make a /payin/paymentMethods 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
payer
check
object
Payer's details
metaData
object

Example: Copy section link Copied!

Here is an example of the JSON payload of a /payin/paymentMethods request

JSON
Copy
Copied
{
"paymentAccount": "1300600000EUR01004110",
"orderReference": "ORDREF_20210203180537394",
"orderCountryCode": "FRA",
"amount": {
"value": "70",
"currency": "EUR"
},
"payer": {
"language": "FR",
"reference": "CREF_20210203180537464",
"IPAddress": "192.168.0.1"
}
}
Copy
Copied

Retrieving the result Copy section link Copied!

If your request was successful, you will receive a paymentMethodResponse object, containing the list of available payment methods:

Parameter Name
Type
Description
resultCode
string
paymentMethodList
array

list of available payment methods

orderId
string

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

resultCodeMessage
string

Example of response Copy section link Copied!

Here is an example of a paymentMethodResponse JSON payload:

JSON
Copy
Copied
{
"resultCode": "0",
"paymentMethodList": [
{
"id": "1",
"label": "SCT transfer",
"type": "2"
},
{
"id": "2",
"label": "card payment",
"type": "4",
"aliasList": [
{
"id": "001",
"label": "carte xxx",
"expirationDate": "202505",
"maskedPan": "123456xxxxxx1234"
}
]
}
]
}
Copy
Copied

Once you have retrieved the available payment methods, you need to build your payment form and collect the end-user's details. When the user has chosen their payment method, you can initiate the payment.

Step 2 : Create a payment form and collect the shopper's details Copy section link Copied!

When your user has chosen a payment method, you can retrieve an orderId that you can use in the /payin/payment request to initiate the payment:


You can initiate a payment directly with the /payin/payment/ request, but you will need to provide the following information:

  • orderReference
  • transPaymentMethod and aliasId*
  • payer


The transPaymentMethod is the unique identifier for a payment method. These identifiers are given to you when you register your account with AgoraPay.


*
You can record the shopper's payment details for a future transaction using registerAlias field. You will retrieve an aliasId in the result, which you can use in order to skip Step 1 - Retrieve available payment methods. You will still need to provide transPaymentMethod.

Parameter Name
Required
Type
Description
transPaymentMethod
object
Payment method information
orderId
string
Order id obtained in order creation
orderReference
string
Marketplace reference for this order. Characters authorized are: a to z, A to Z, 0 to 9 and - / . + _ : and space
orderCountryCode
string
The ISO country code in 3 characters format
breakdownList
array
List of breakdown for this payment
alias
object
Alias identification to used
metaData
object
JSON data for the marketplace. This data is not used by payment systems.
payer
object
Payer's details
details
object
Payment details information For some payment methods, additional details are needed.
capture
string
Capture indicator. Set to "0" for authorization only (default value 1 - transaction captured))
transactionAmount
check
object
amount information
urlRedirect
check
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)
registerAlias
string
When set to "1" or "Y", an alias will be registered when the payment will be completed, if possible. If not present or equal to "0" or "N", no alias is registered.
reason
string
Operation label transmitted in payment system. Maximum length of 140 characters.
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.
cart
object
Cart detail for 3DSV2. Mandatory in API v2.
operationDate
string
Date of the operation. The format must be YYYYMMDD
cbChallenge
string
Challenge negotiation for card payment. 01: No preference 02: No challenge required 03: Desired challenge 04: Required challenge

Here is a JSON sample for a payment of €70.10:

JSON
Copy
Copied
{
"orderId": "2987721",
"transactionAmount": {
"value": "70.10",
"currency": "EUR"
},
"transPaymentMethod": {
"id": "4"
},
"endToEndId": "Test",
"breakdownList": [
{
"label": "bdl1",
"transactionRef": "ref1",
"sellerAccountNumber": "1300600000EUR01006110",
"amount": {
"value": "70",
"currency": "EUR"
}
},
{
"label": "bdl2",
"transactionRef": "ref2",
"sellerAccountNumber": "1300600000EUR01007110",
"amount": {
"value": "0.10",
"currency": "EUR"
}
}
]
}
Copy
Copied

Retrieving the result Copy section link Copied!

You can retrieve the paymentResponse object, containing the following payload information:

Parameter Name
Type
Description
orderId
string
orderStatus
string
transactionId
string
transactionStatus
string
resultCode
string
virtualIban
string
redirectUrl
string
reference
string
resultCodeMessage
string
redirectInd
string

1 if user must be redirect to the redirectUrl site


You can use the orderStatus and transactionStatus to inform the end-user of the payment status and process.

In the case of a card payment, the redirectUrl will be used to redirect the customer at the end of the payment.

In the case of a SDD payment, the resultCode will depend on the customer's signature :of the mandate:

  • resultCode = 0 : The customer signed the electronic mandate
  • resultCode <> 0 : The customer didn't sign the electronic mandate or couldn't finish the signature.

The content of the returned XML must be passed in the paymentData field of the paymentDetails method.

In the case of a Payment Initiation, the buyer's bank is dealing directly with AgoraPay.

Please refer to the payment flows section to get a complete view of the API sequence.

If you encounter an error, please refer to our Payment error codes for troubleshooting.

Example Copy section link Copied!

Here is a successful response JSON payload example:

JSON
Copy
Copied
{
"resultCode": "0",
"orderId": "3343021",
"orderStatus": "pending_payment",
"transactionId": "1707521",
"transactionStatus": "in_progress",
"virtualIban": "FR7618206004320000127591154"
}
Copy
Copied

Step 3 : Additional payment details Copy section link Copied!

As shown in the process flow charts, some payment methods will require you to request additional payment details. You can do so using the /payin/paymentDetails request:

Parameter Name
Required
Type
Description
metaData
object
JSON data for the marketplace. This data is not used by payment systems.
orderId
check
string
Order id obtained in order creation
paymentData
string
Specific data for a payment method

The paymentDetails API allows the marketplace to pass the callback response of the web interactions as an optional parameter to the request (‘paymentData’). It has no impact on the workflow of the transaction itself. This optional data is stored only for logging purposes, in the event of an incident.


If, for some reason, the browser callback cannot be retrieved, it is possible to make the API request without the paymentData field.


A generic timeout (around 10 min) is set up for all payment methods:

  • If the transaction is not finalised by the shopper within this period, it is automatically considered to have been abandoned.
  • If the marketplace sends a paymentDetails on a cancelled transaction, then a resultCode of 4002 is returned.


Although the API return will provide you with the transaction status, the webhook remains the only reference. The information sent back from this API is therefore purely informational.

Example Copy section link Copied!

Here is an example JSON payload for a /payin/paymentDetails request:

JSON
Copy
Copied
1
2
3
4
{
"orderId": "123456789",
"paymentData": "AMT=110328&CMD=1705821&AUTH=XXXXXX&USER=0&BRAND=CB&EXPIRY=2301&RESULT=00000&SAFE3DS=N&BIN=401200&CARD=12&U3DS=U&TIME=08%3A38%3A04&DATE=26032021&NUM=60078063&TRANS=33938398&ACCOUNT=CMDLpSqLLDS++2301++---&COUNTRY=FRA&SIGN=3Fu2QJJ%2F6iz%2F%2F5tjDkWf6AHEz8SASvfsOPn32lPYdgJ%2BF8oOeobUHz65tr%2B%2BBjsvxGrmzh7UQHjEyLura9eU8%2FvTGKRgKda%2Bz6xTZ9YpmA7MlxPNc0AofnHXoReumb%2B7%2BwvYpKZ46AjZQ8nICaZbgRrSD3Sq3yVpCZa1T9Pw3TM%3D"
}
Copy
Copied

Retrieving the result Copy section link Copied!

If your request was successful, yo will retrieve the paymentResponseComplete object, containing the following information:

Parameter Name
Type
Description
orderId
string

Present if success (resultCode=0)

orderStatus
string
resultCode
string
resultCodeMessage
string
transactionId
string
transactionStatus
string
reference
string

You can use the orderStatus and transactionStatus to inform the end-user on the payment status and proceed.


If you encounter an error, please refer to our Payment error codes page for troubleshooting.

Example Copy section link Copied!

Here is a successful response to a /payin/paymentDetails request:

JSON
Copy
Copied
{
"resultCode": "0",
"orderId": "123456789",
"orderStatus": "complete",
"transactionId": "123123",
"transactionStatus": "completed"
}
Copy
Copied

A generic timeout is set up for all means of payment. If the transaction is not finalised within this time, it is automatically cancelled. If the marketplace sends a paymentDetails for a cancelled transaction, then a resultCode of 4002 is returned.

For an SDD payment, if there is a mandate to sign, the electronic signature screen for the mandate has a dedicated timeout so that the customer can proceed with the signature. The marketplace can then retrieve the XML returned. If the signature is not finalised, the general timeout is set. However, only the return of the paymentDetails API and the operation webhook (sent when validating the payment) guarantee that the payment is processed correctly.

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 sent by your implementation manager to test your integration and make sure everything is working properly. You can also track and manage your test payments within your transactions dashboard from the AgoraPay Portal.