AgoraPay REST API Copy section link Copied!

The AgoraPay platform exposes a number of REST API endpoints to manage most aspects of your marketplace:

Pay-In endpoints - to make payment requests for your customers
Payment account endpoints - to manage your marketplace accounts
Pay-Out endpoint - to request payout to your vendors
Transfer endpoint - to transfer funds between your accounts
Operations endpoint - to retrieve information about previous payments

The API is protected by an authentication mechanism you will have to implement unless you use the AgoraPay SDK which abstracts the authentication management. Available in several languages, the AgoraPay SDK will reduce the development efforts.

While the AgoraPay documentation mostly refers to the REST API endpoints, there is a one-to-one correspondence between the REST endpoint and the SDK library classes as described below.

Test and production environments are discriminated by their root domain:

Test: api.test.agorapay.com
Production: api.live.agorapay.com

Authentication Copy section link Copied!

The REST API implements a specific security mechanism to guarantee that every API request is properly authenticated and cannot be replayed or fraudulently reused. This section describes how to request an authentication pair that must be used in each REST call.

Getting the authentication pair Copy section link Copied!

Before making HTTP requests to AgoraPay API endpoints, you must obtain a valid authentication token using your TOKEN_USER and TOKEN_PASSWORD credentials as an HTTP Basic authentication request against the TOKEN_URL endpoint.

Here is an example of token request (please replace with your own credentials for the request to work):

cURL

Copy

Copied

curl -v -u "<TOKEN_USER>:<TOKEN_PASSWORD>" -X POST "<TOKEN_URL>"

Copy

Copied

Each authentication token request returns a JSON object where you will find an authentication token pair (access_token, id_token) that must be used for every subsequent REST API request.

JSON

Copy

Copied

{
    "access_token":"74800866-1dda-35fa-b017-2351b76255b",
    "scope":"am_application_scope openid",
    "id_token":"eyJ4NXQiOiJNVFptT1daaU1HSTBZVGxpWVRaaE5UWXdOR0kxT0dGbE9UTTVPR1ZpWldZME0yWmlPV1ZtWVEiLCJraWQiOiJNVFptT1daaU1HSTBZVGxpWVRaaE5UWXdOR0kxT0dGbE9UTTVPR1ZpWldZME0yWmlPV1ZtWVEiLCJhbGciOiJSUzI1NiJ9.eyJhdF9oYXNoIjoieW40VF9aOTM3S09iWWxGOTlVTVdCUSIsImFjciI6InVybjptYWNlOmluY29tbW9uOmlhcDpzaWx2ZXIiLCJhdWQiOlsibVZKTEs4T21ab2dKRnRuWG1mZjlTQ0lKUVp3YSJdLCJhenAiOiJtVkpMSzhPbVpvZ0pGdG5YbWZmOVNDSUpRWndhIiwiaXNzIjoiaHR0cHM6XC9cL2hvbS1pcy5jYS1jZWRpY2FtLmZyOjk0NDRcL29hdXRoMlwvdG9rZW4iLCJleHAiOjE2MzQxMzcxMzEsImlhdCI6MTYzNDEzMzUzMX0.Xovs8vGs4H59f0F4NZb7DEuYiE37pb09HdowUax3ZU7PSUxde3Tis6kEIAjcHBg9Inee8mt9Lq2dbHvamNsGoYso1v6FWVrkPP2jjVTUm7kuh8xKslkfdUIuZGqtEoHsdF--qEFnlaiSR8iR8nLD0_T6unHNWWO8kXO4Y8vbbx2R0OGh5dElqxXYvsWtqBFe32Ds4XjJcmeeAlCj86oBXTlVxqwXEHsk8qSKXci2VJHhfgQBfzvU3xek7TRq9vbwIU1Dmja2XM6Q6a4l4nbF6D9Jb9I1XtEfr7I2_4ubvMAHOGRkicsNJfn0-DFehEbCC0Fqx8CyoblkNLP2bTQsa",
    "token_type":"Bearer",
    "expires_in":3600
}

Copy

Copied

As the authentication pair expires one hour after its creation, the expires_in attribute of the JSON response indicates whether the pair needs to be refreshed or not. Please avoid creating new pairs for every REST API call as it would be quite inefficient. In case you request a new pair while your current pair is still valid, the token end-point will return the same pair.

Using an invalid pair on the HTTP REST API will raise an authentication error.

Using the authentication pair Copy section link Copied!

Once you have a valid authentication pair, you must pass the access_token as an Authorization header and the id_token as a header parameter.

Here is an example of REST API request with the authentication pair:

cURL

Copy

Copied

curl -v -X POST 
-H "Authorization: Bearer 74800866-1dda-35fa-b017-2351b76255b" 
-H "id_token: eyJ4NXQiOiJNVFptT1daaU1HSTBZVGxpWVRaaE5UWXdOR0kxT0dGbE9UTTVPR1ZpWldZME0yWmlPV1ZtWVEiLCJraWQiOiJNVFptT1daaU1HSTBZVGxpWVRaaE5UWXdOR0kxT0dGbE9UTTVPR1ZpWldZME0yWmlPV1ZtWVEiLCJhbGciOiJSUzI1NiJ9.eyJhdF9oYXNoIjoieW40VF9aOTM3S09iWWxGOTlVTVdCUSIsImFjciI6InVybjptYWNlOmluY29tbW9uOmlhcDpzaWx2ZXIiLCJhdWQiOlsibVZKTEs4T21ab2dKRnRuWG1mZjlTQ0lKUVp3YSJdLCJhenAiOiJtVkpMSzhPbVpvZ0pGdG5YbWZmOVNDSUpRWndhIiwiaXNzIjoiaHR0cHM6XC9cL2hvbS1pcy5jYS1jZWRpY2FtLmZyOjk0NDRcL29hdXRoMlwvdG9rZW4iLCJleHAiOjE2MzQxMzcxMzEsImlhdCI6MTYzNDEzMzUzMX0.Xovs8vGs4H59f0F4NZb7DEuYiE37pb09HdowUax3ZU7PSUxde3Tis6kEIAjcHBg9Inee8mt9Lq2dbHvamNsGoYso1v6FWVrkPP2jjVTUm7kuh8xKslkfdUIuZGqtEoHsdF--qEFnlaiSR8iR8nLD0_T6unHNWWO8kXO4Y8vbbx2R0OGh5dElqxXYvsWtqBFe32Ds4XjJcmeeAlCj86oBXTlVxqwXEHsk8qSKXci2VJHhfgQBfzvU3xek7TRq9vbwIU1Dmja2XM6Q6a4l4nbF6D9Jb9I1XtEfr7I2_4ubvMAHOGRkicsNJfn0-DFehEbCC0Fqx8CyoblkNLP2bTQsa" 
-H "Content-Type: application/json"
"https://api.test.agorapay.fr/mkp/v1/operations/list" -d {}

Copy

Copied

Pay-In API Copy section link Copied!

Endpoint method

Endpoint path

SDK Class

Description

POST

/payin/payment

ApiPayin().payment()

Submit a payment

POST

/payin/paymentDetails

ApiPayin().payment_details()

Submit additional payment details

POST

/payin/paymentMethods

ApiPayin().payment_methods()

Submit an order/get payment methods

POST

/payin/capture

ApiPayin().capture()

Capture a transaction/order

POST

/payin/cancel

ApiPayin().cancel()

Cancel a transaction/order

GET

/payin/orderDetails

ApiPayin().order_details()

Get all the order details

POST

/payin/adjustPayment

ApiPayin().adjust_payment()

Adjust the amount of the payment/change the payment split

POST

/payin/paymentIframe

ApiPayin().payment_iframe()

Submit an order/get an authentication code

POST

/payin/refund

ApiPayin().refund()

Refund a transaction/order

Payment account API Copy section link Copied!

Endpoint method

Endpoint path

SDK class

Description

GET

/paymentAccount

ApiPaymentAccount().payment_account()

Get account details

POST

/paymentAccount/list

ApiPaymentAccount().payment_account_list()

Get account list

POST

/paymentAccount/credit

ApiPaymentAccount().credit()

Credit an account

POST

/paymentAccount/payoutAuto

ApiPaymentAccount().payout_auto()

Schedule a payout

POST

/paymentAccount/setFloorLimit

ApiPaymentAccount().set_floor_limit()

Set Account Floor Limit

POST

/paymentAccount/setIBAN

ApiPaymentAccount().set_iban()

Set Account IBAN

POST

/paymentAccount/recharge

ApiPaymentAccount().recharge()

Fund an account

POST

/paymentAccount/create

ApiPaymentAccount().create()

Create Payment Account

Pay-Out API Copy section link Copied!

Endpoint method

Endpoint path

SDK class

Description

POST

/payout/create

ApiPayout().create()

Ask for a payout

Transfer API Copy section link Copied!

Endpoint method

Endpoint path

SDK class

Description

POST

/transfer/create

ApiTransfer().create()

Ask for a transfer between two accounts

Operations API Copy section link Copied!

Endpoint method

Endpoint path

SDK class

Description

POST

/operations/list

ApiOperations().operation_list()

Get operations matching a set of criteria