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.

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.

First, make sure you have followed our getting started guide to set up your test account, get your API credentials, and install AgoraPay.

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:

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

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

Here is an example of a paymentMethodResponse JSON payload:

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.

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.

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

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

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.

Here is a successful response JSON payload example:

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

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 1 hour) 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.

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

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

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.

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

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.

If you encounter any error, you can check the following pages for troubleshooting:

• List of API error codes

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.