API Reference Copy section link Copied!

Welcome to the API Reference page.

We are currently setting up our Github account, in the meantime, you can:

Click here to access the solution's swagger
Click here to access the Authentication swagger

/token Copy section link

Ask for a token

Request

Submit a token request.

grant_type

string

Required

to be valued by 'client_credentials'

scope

string

Required

to be valued by 'openid'

Response

Token successful

accessToken

string

The bearer access token. To consume API Agorapay Ressource, the marketplace should send the access_token directly in the Authorization request header.

scope

string

APIM scope.

id_token

string

The marketplace token. To consume API Agorapay Ressource, the marketplace should send the access_token directly in the Authorization request header.

token_type

string

Token type.

expires_in

string

The token validity periods (3600 seconds max).

Request Example

Response example

curl 'https://API_URL/token' \ -H 'Authorization: Bearer <your_access_token>' \ -H 'id_token: <your_id_token>' \

-d 'grant_type=client_credentials' \

-d 'scope=openid'

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

/payin/adjustPayment Copy section link

Adjust the amount of the payment/ change the breakdown of the payment

Before the cashing of the operation, change the payment amount and/or the breakdown
If it's only a change in the breakdown, set the adjustAmount to the same of the transactionAmount

Request

All request data are embedded in a json structure in the body

The request to change the amount or submit a new breakdown list

breakdownList

array

List of breakdown

amount

object

amount information

value

string

The value of the amount in decimal with max 2 digits after separator.
Only digits and dot are authorized.

currency

string

the currency iso code of the amount with 3 characters

sellerAccountNumber

string

Account number of the merchant or marketplace.

label

string

Label for the breakdown. Maximum 30 characters

commission

object

Commission information

amount

string

Amout of the commission in the currency of the order with two decimal maximum

account

string

Commission accountNumber

metaData

object

JSON data for the marketplace. This data is not used by payment systems.

adjustAmount

object

Amount to ajust. Must be absent for payment type card.

Mandatory if the amount is different than the initial payment.

value

string

Required

The value of the amount in decimal with max 2 digits after separator.
Only digits and dot are authorized.

currency

string

Required

the currency iso code of the amount with 3 characters

orderId

string

Order id obtained in order creation

transactionId

string

Id of the payment transaction.

Response

Before the cashing of the operation, change the payment amount and/or the breakdown If it's only a change in the breakdown, set the adjustAmount to the same of the transactionAmount

New amount and/ord breakdown successfully submitted

Adjust amount or breakdown list response

resultCode

string

Always present

API operation result. This code is 0 in case of success.
If resultCode is not 0, the operation fails.
In this case, a resultCodeMessage describe the reason of failure.
resultCodeMessage can be absent if no reason is provided for the resultCode.

resultCodeMessage

string

The failure description. The message can be used to understand
the failure reason. It must be transmitted to support for diagnostic.

Request Example

Response example

curl 'https://API_URL/mkp/v1/payin/adjustPayment' \ -H 'Authorization: Bearer <your_access_token>' \ -H 'id_token: <your_id_token>' \ -H 'Content-Type: application/json' \ --data-raw \

{
    "orderId": "1354657",
    "adjustAmount": {
        "value": "100",
        "currency": "EUR"
    },
    "breakdownList": [
        {
            "label": "bdl1",
            "transactionRef": "ref1",
            "sellerAccountNumber": "1300600000EUR01006110",
            "amount": {
                "value": "35",
                "currency": "EUR"
            }
        },
        {
            "label": "bdl2",
            "transactionRef": "ref2",
            "sellerAccountNumber": "1300600000EUR01007110",
            "amount": {
                "value": "65",
                "currency": "EUR"
            }
        }
    ]
}

Copy

Copied

{
    "resultCode": "0"
}

Copy

Copied

/payin/cancel Copy section link

Cancel a Transaction/Order

Cancel a payment transaction or all the payment transactions of an order

Request

The minimal set of properties required to perform a cancel

orderId

string

Required

Order id obtained when the payment was made and the order was created.

transactionId

string

Id of the payment transaction.

metaData

object

JSON data for the marketplace. This data is not used by payment systems.

Response

Cancel a payment transaction or all the payment transactions of an order

Cancelation Done

Cancel response

resultCode

string

Always present

resultCode of the processing

orderStatus

string

Status of an order. the following status can be provided:
- created: The order is created
- pendingpayment: Payment in progress
- complete: Payment is completed
- partialcomplete: Payment is completed but all order amount is not payed
- canceled: The order is canceled

transactionList

array

List of transaction for the order

paymentMethodId

string

id of the payment Method used for the transaction

List of transaction for the order

id

string

Always present

List of transaction for the order

status

string

Always present

List of transaction for the order

amount

object

Always present

amount of the transaction

List of transaction for the order

value

string

Always present

The value of the amount in decimal with max 2 digits after separator.
Only digits and dot are authorized.

currency

string

Always present

the currency iso code of the amount with 3 characters

type

string

List of transaction for the order

resultCodeMessage

string

The failure description. The message can be used to understand
the failure reason. It must be transmitted to support for diagnostic.

Request Example

Response example

curl 'https://API_URL/mkp/v1/payin/cancel' \ -H 'Authorization: Bearer <your_access_token>' \ -H 'id_token: <your_id_token>' \ -H 'Content-Type: application/json' \ --data-raw \

{
    "orderId": "432156",
    "transactionId": "123456789"
}

Copy

Copied

{
    "resultCode": "0",
    "orderStatus": "complete",
    "transactionList": [
        {
            "id": "123123123",
            "status": "completed",
            "amount": {
                "value": "100",
                "currency": "EUR"
            },
            "paymentMethodId": "002"
        }
    ]
}

Copy

Copied

/payin/capture Copy section link

Capture an already authorized operation

Capture a payment transaction or all the capturable payment transactions of an order

Request

The minimal set of properties required to perform a capture

orderId

string

Required

Order id obtained in order creation

transactionAmount

object

Required

Capture amount

amount information

value

string

Required

The value of the amount in decimal with max 2 digits after separator.
Only digits and dot are authorized.

currency

string

Required

the currency iso code of the amount with 3 characters

metaData

object

JSON data for the marketplace. This data is not used by payment systems.

breakdownList

array

amount

object

amount information

value

string

The value of the amount in decimal with max 2 digits after separator.
Only digits and dot are authorized.

currency

string

the currency iso code of the amount with 3 characters

sellerAccountNumber

string

Account number of the merchant or marketplace.

label

string

Label for the breakdown. Maximum 30 characters

commission

object

Commission information

amount

string

Amout of the commission in the currency of the order with two decimal maximum

account

string

Commission accountNumber

transactionId

string

Id of the payment transaction.

Response

Capture a payment transaction or all the capturable payment transactions of an order

Capture Done

capture response

resultCode

string

Always present

resultCode of the processing

orderStatus

string

Always present

transactionList

array

Always present

List of transaction for the order

paymentMethodId

string

id of the payment Method used for the transaction

List of transaction for the order

id

string

Always present

List of transaction for the order

status

string

Always present

List of transaction for the order

amount

object

Always present

amount of the transaction

List of transaction for the order

value

string

Always present

The value of the amount in decimal with max 2 digits after separator.
Only digits and dot are authorized.

currency

string

Always present

the currency iso code of the amount with 3 characters

type

string

List of transaction for the order

resultCodeMessage

string

The failure description. The message can be used to understand
the failure reason. It must be transmitted to support for diagnostic.

orderId

string

Always present

Order id obtained in order creation

Request Example

Response example

curl 'https://API_URL/mkp/v1/payin/capture' \ -H 'Authorization: Bearer <your_access_token>' \ -H 'id_token: <your_id_token>' \ -H 'Content-Type: application/json' \ --data-raw \

{
    "orderId": "3343121",
    "transactionId": "1707621",
    "transactionAmount": {
        "value": "1000.20",
        "currency": "EUR"
    },
    "breakdownList": [
        {
            "label": "bdl1",
            "sellerAccountNumber": "1300600000EUR01006110",
            "amount": {
                "value": "1000",
                "currency": "EUR"
            },
            "commission": {
                "amount": "1.01",
                "account": "1300600000EUR01004110"
            }
        },
        {
            "label": "bdl2",
            "sellerAccountNumber": "1300600000EUR01007110",
            "amount": {
                "value": "0.20",
                "currency": "EUR"
            }
        }
    ]
}

Copy

Copied

{
    "resultCode": "0",
    "orderId": "3343121",
    "orderStatus": "partial_complete",
    "transactionList": [
        {
            "id": "1707621",
            "type": "7",
            "paymentMethodId": "36",
            "status": "completed",
            "amount": {
                "value": "1103.28",
                "currency": "EUR"
            }
        },
        {
            "id": "1707721",
            "type": "1",
            "paymentMethodId": "36",
            "status": "completed",
            "amount": {
                "value": "1000.20",
                "currency": "EUR"
            }
        }
    ]
}

Copy

Copied

/payin/mandate Copy section link

This API is used to get mandate signed file

Request

Get signed mandate file

transactionId

string

Must be a transaction for SDD. Must be provided if reference is not present.

reference

string

Mandate reference (UMR). Must be provided if transationId is not present

Response

Get SDD mandate signed file

Get mandate response

resultCode

string

resultCodeMessage

string

The failure description. The message can be used to understand
the failure reason. It must be transmitted to support for diagnostic.

transactionId

string

Id of the payment transaction.

reference

string

Mandate reference

signedFileContent

string

PDF file base64 encoded

Request Example

Response example

curl --get 'https://API_URL/mkp/v1/payin/mandate' \ -H 'Authorization: Bearer <your_access_token>' \ -H 'id_token: <your_id_token>' \

-d 'transactionId=165231523612'

Copy

Copied

curl --get 'https://API_URL/mkp/v1/payin/mandate' \ -H 'Authorization: Bearer <your_access_token>' \ -H 'id_token: <your_id_token>' \

-d 'reference=2020110907201100Y0H1102'

Copy

Copied

{
    "resultCode": "0",
    "reference": "202111191439350V8211102",
    "transactionId": "165231523612",
    "signedFileContent": "DHGZHGDFUDjkk..."
}

Copy

Copied

/payin/orderDetails Copy section link

Get details for a payment

Request

Send back all the data of an order and its transactions

orderId

string

Required

id of the order.

Response

Order retrieved successfully

Details of an order

orderAmount

object

amount of the order

amount information

value

string

The value of the amount in decimal with max 2 digits after separator.
Only digits and dot are authorized.

amount information

currency

string

the currency iso code of the amount with 3 characters

amount information

orderRemainingAmount

object

remaining amount of the order if not completed

amount information

value

string

The value of the amount in decimal with max 2 digits after separator.
Only digits and dot are authorized.

amount information

currency

string

the currency iso code of the amount with 3 characters

amount information

orderId

string

Order identifier

Order id obtained in order creation

resultCode

string

Always present

resultCodeMessage

string

The failure description. The message can be used to understand
the failure reason. It must be transmitted to support for diagnostic.

orderStatus

string

transactionList

array

List of transaction for the order

paymentMethodId

string

id of the payment Method used for the transaction

List of transaction for the order

id

string

Always present

List of transaction for the order

status

string

Always present

List of transaction for the order

amount

object

Always present

amount of the transaction

List of transaction for the order

value

string

Always present

The value of the amount in decimal with max 2 digits after separator.
Only digits and dot are authorized.

currency

string

Always present

the currency iso code of the amount with 3 characters

type

string

List of transaction for the order

Request Example

Response example

curl --get 'https://API_URL/mkp/v1/payin/orderDetails' \ -H 'Authorization: Bearer <your_access_token>' \ -H 'id_token: <your_id_token>' \

-d 'orderId=25465265'

Copy

Copied

{
    "resultCode": "0",
    "orderId": "26527635",
    "orderStatus": "pending_payment",
    "orderAmount": {
        "value": "1000",
        "currency": "EUR"
    },
    "orderRemainingAmount": {
        "value": "500.87",
        "currency": "EUR"
    },
    "transactionList": [
        {
            "id": "123123123",
            "status": "completed",
            "amount": {
                "value": "500.87",
                "currency": "EUR"
            },
            "paymentMethodId": "002"
        }
    ]
}

Copy

Copied

/payin/payment Copy section link

Submit a payment with payment method

When your shopper choose a payment method, this call submit the choice and any data if already given.
The return can be final, (transaction completed) or ask to authentification details, or redirect the shopper to PSP or 3DS pages.

Request

All request data are embedded in a json structure in the body

Payment request.
if orderId is not provided, the following fields are mandatory :
- orderReference
- orderCountryCode
- payer

if orderId is present, it must be obtain from previous call to paymentMethods

transPaymentMethod

object

the payment Method choosen by the shopper

Payment method information

id

string

Required

id (string) : ID of the type of payment method.
This id must be provided to identify the payment method.
The list of payment method IDs is provided when your AgoraPay account is created.

orderId

string

Order id obtained in order creation

orderReference

string

Mandatory if orderId is not present

Marketplace reference for this order. Characters authorized are: a to z, A to Z, 0 to 9 and - / . + : and space

orderCountryCode

string

Mandatory if orderId is not present

The ISO country code in 3 characters format

breakdownList

array

List of breakdown for this payment

amount

object

amount information

value

string

The value of the amount in decimal with max 2 digits after separator.
Only digits and dot are authorized.

currency

string

the currency iso code of the amount with 3 characters

sellerAccountNumber

string

Account number of the merchant or marketplace.

label

string

Label for the breakdown. Maximum 30 characters

commission

object

Commission information

amount

string

Amout of the commission in the currency of the order with two decimal maximum

account

string

Commission accountNumber

alias

object

If the shopper use an alias

Alias identification to used

id

string

Required

Identifier for the alias

metaData

object

JSON data for the marketplace. This data is not used by payment systems.

payer

object

Mandatory if orderId is not present

Payer's details

IPAddress

string

IP address of the customer. IPv4 and IPv6 formats are accepted.

reference

string

Required

reference of the customer from the marketplace

userAgent

string

The browser information used to request the payment

language

string

The default language of the browser.
The first two characters are used to identify the language code.
Must be in upper case.
Only french is supported at this time.

details

object

Payment details information For some payment methods, additional details are needed.

firstName

string

lastName

string

address

string

Road name and number

city

string

postalCode

string

country

string

Country in 3 letters ISO format

iban

string

email

string

state

string

gender

string

phoneNumber

string

sequence

string

For payment method with mandate, the sequence is
- FRST for first use of recurrent mandate
- RCUR for use of recurrent mandate
- FNAL for last use of recurrent mandate
- OOFF for a mandate used only one time

reference

string

Mandate reference in case of a SDD payment.
transactionId of the initial payment in case of a card recurring payment.

socialReason

string

Compagny name

address2

string

Additional address

capture

string

Capture indicator. Set to "0" for authorization only (default value 1 - transaction captured))

transactionAmount

object

Required

Amount for this transaction

amount information

value

string

Required

The value of the amount in decimal with max 2 digits after separator.
Only digits and dot are authorized.

currency

string

Required

the currency iso code of the amount with 3 characters

urlRedirect

string

Required

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.

totalQuantity

string

Required

number of article in cart

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

paymentOptions

string

Payment options

Response

When your shopper choose a payment method, this call submit the choice and any data if already given. The return can be final, (transaction completed) or ask to authentification details, or redirect the shopper to PSP or 3DS pages.

Payment processing success

Payment response

orderId

string

Order id obtained in order creation

orderStatus

string

transactionId

string

Id of the payment transaction.

transactionStatus

string

Status of a transaction. The following value may be provided:
- created: The transaction is just created. No payment is already made.
- in_progress: Payment is in progress
- accepted: Payment is accepted
- completed: Payment confirmation is received
- canceled: Payment is canceled
- refused: Payment is refused
- abandonned: Payment is not performed
- refund: Transction is refunded

resultCode

string

Always present

virtualIban

string

Iban to make payment to for SCT or SWIFT method

redirectUrl

string

Url to redirect the customer to continue the payment flow with an external partner.
The marketplace must redirect its customer to this url to continue the payment process

reference

string

Mandate reference

resultCodeMessage

string

The failure description. The message can be used to understand
the failure reason. It must be transmitted to support for diagnostic.

redirectInd

string

1 if user must be redirect to the redirectUrl site

Request Example

Response example

curl 'https://API_URL/mkp/v1/payin/payment' \ -H 'Authorization: Bearer <your_access_token>' \ -H 'id_token: <your_id_token>' \ -H 'Content-Type: application/json' \ --data-raw \

{
    "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

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

Copy

Copied

/payin/paymentDetails Copy section link

Submit additionnal Payment Details

The call send the last mandatory data to finalize the payment

Request

All request data are embedded in a json structure in the body

Payment details request

metaData

object

JSON data for the marketplace. This data is not used by payment systems.

orderId

string

Required

Order id obtained in order creation

paymentData

string

Specific data for a payment method

Response

The call send the last mandatory data to finalize the payment

Payment transaction processed successfully

Payment details response

orderId

string

Present if success (resultCode=0)

Order id obtained in order creation

orderStatus

string

resultCode

string

Always present

resultCodeMessage

string

The failure description. The message can be used to understand
the failure reason. It must be transmitted to support for diagnostic.

transactionId

string

Id of the payment transaction.

transactionStatus

string

reference

string

Mandate reference

Request Example

Response example

curl 'https://API_URL/mkp/v1/payin/paymentDetails' \ -H 'Authorization: Bearer <your_access_token>' \ -H 'id_token: <your_id_token>' \ -H 'Content-Type: application/json' \ --data-raw \

{
    "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

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

Copy

Copied

/payin/paymentIframe Copy section link

Post your payment details and get an authent Code to initiate a payment Frame

When your shopper is ready to pay, submit your order/payment by this request and get an Authent Code.
Then save the orderId and open an iframe for the shopper with the authentCode.

Request

All request data are embedded in a json structure in the body

Payment with iFrame request

orderReference

string

Required

The order reference of the requester

Marketplace reference for this order. Characters authorized are: a to z, A to Z, 0 to 9 and - / . + : and space

orderCountryCode

string

Required

country iso code of the order

The ISO country code in 3 characters format

amount

object

Required

amount of the order

amount information

value

string

Required

The value of the amount in decimal with max 2 digits after separator.
Only digits and dot are authorized.

currency

string

Required

the currency iso code of the amount with 3 characters

breakdownList

array

breakdown list

amount

object

amount information

value

string

The value of the amount in decimal with max 2 digits after separator.
Only digits and dot are authorized.

currency

string

the currency iso code of the amount with 3 characters

sellerAccountNumber

string

Account number of the merchant or marketplace.

label

string

Label for the breakdown. Maximum 30 characters

commission

object

Commission information

amount

string

Amout of the commission in the currency of the order with two decimal maximum

account

string

Commission accountNumber

payer

object

Required

customer details for iframe

payer information

reference

string

Required

Reference of the customer from the marketplace, which must be equal to the initial reference

language

string

The default language of the browser.
The first two characters are used to identify the language code.
Must be in upper case.
Only french is supported at this time.

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

cart

object

Cart detail for 3DSV2. Mandatory in API v2.

totalQuantity

string

Required

number of article in cart

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.

firstName

string

lastName

string

address

string

Road name and number

city

string

postalCode

string

country

string

Country in 3 letters ISO format

iban

string

email

string

state

string

gender

string

phoneNumber

string

sequence

string

reference

string

Mandate reference in case of a SDD payment.
transactionId of the initial payment in case of a card recurring payment.

socialReason

string

Compagny name

address2

string

Additional address

page

string

Type of page to display. - iframe: integrated in marketplace site (default) - full: full page

paymentOptions

string

Payment options

reason

string

Operation label transmitted in payment system. Maximum length of 140 characters.

Response

When your shopper is ready to pay, submit your order/payment by this request and get an Authent Code. Then save the orderId and open an iframe for the shopper with the authentCode.

Start payment with iframe response

Payment with iFrame response

resultCode

string

Always present

orderId

string

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

Order id obtained in order creation

resultCodeMessage

string

The failure description. The message can be used to understand
the failure reason. It must be transmitted to support for diagnostic.

authenticationCode

string

Authentification Code to use to open user iframe

Site

string

Site name or number

url

string

Url to connect iframe to.

Request Example

Response example

curl 'https://API_URL/mkp/v1/payin/paymentIframe' \ -H 'Authorization: Bearer <your_access_token>' \ -H 'id_token: <your_id_token>' \ -H 'Content-Type: application/json' \ --data-raw \

{
    "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"
}

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

/payin/paymentMethods Copy section link

Request a payment

When your shopper is ready to pay, submit an order and get a list of the available payment methods and alias. The list is based on the shopper country and the order amount and currency.

This is the first call to use when going on a payment operation.
The next call should be /payment

Request

All request data are embedded in a json structure in the body

Payement methods request

orderReference

string

Required

Marketplace reference for this order. Characters authorized are: a to z, A to Z, 0 to 9 and - / . + : and space

orderCountryCode

string

Required

The ISO country code in 3 characters format

amount

object

Required

amount of the order

amount information

value

string

Required

The value of the amount in decimal with max 2 digits after separator.
Only digits and dot are authorized.

currency

string

Required

the currency iso code of the amount with 3 characters

payer

object

Required

Payer's details

IPAddress

string

IP address of the customer. IPv4 and IPv6 formats are accepted.

reference

string

Required

reference of the customer from the marketplace

userAgent

string

The browser information used to request the payment

language

string

The default language of the browser.
The first two characters are used to identify the language code.
Must be in upper case.
Only french is supported at this time.

metaData

object

Response

When your shopper is ready to pay, submit an order and get a list of the available payment methods and alias. The list is based on the shopper country and the order amount and currency. This is the first call to use when going on a payment operation. The next call should be /payment

Order created/retrieved, Available Payment Methods selected

Payment methods response

resultCode

string

Always present

paymentMethodList

array

list of available payment methods

aliasList

array

if alias exist for the customer and the payment Method

list of available payment methods

id

string

Always present

expirationDate

string

format MMYY

maskedPan

string

Hidden card number or IBAN

label

string

label of the alias

brand

string

Card brand (CB, VISA, MASTERCARD) or bank code for IBAN

bankCode

string

id

string

Always present

list of available payment methods

label

string

label of the payment Method

list of available payment methods

type

string

list of available payment methods

orderId

string

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

Order id obtained in order creation

resultCodeMessage

string

The failure description. The message can be used to understand
the failure reason. It must be transmitted to support for diagnostic.

Request Example

Response example

curl 'https://API_URL/mkp/v1/payin/paymentMethods' \ -H 'Authorization: Bearer <your_access_token>' \ -H 'id_token: <your_id_token>' \ -H 'Content-Type: application/json' \ --data-raw \

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

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

/payin/refund Copy section link

Refund an operation

Refund a payment transaction or all the refundable payment transactions of an order

Request

Refund request

orderId

string

Required

Id of the order

Order id obtained in order creation

transactionAmount

object

Required

Amount to refund

amount information

value

string

Required

The value of the amount in decimal with max 2 digits after separator.
Only digits and dot are authorized.

currency

string

Required

the currency iso code of the amount with 3 characters

transactionId

string

Id of the payment transaction.

metaData

object

JSON data for the marketplace. This data is not used by payment systems.

reason

string

The refund reason

Operation label transmitted in payment system. Maximum length of 140 characters.

breakdownList

array

amount

object

amount information

value

string

The value of the amount in decimal with max 2 digits after separator.
Only digits and dot are authorized.

currency

string

the currency iso code of the amount with 3 characters

sellerAccountNumber

string

Account number of the merchant or marketplace.

label

string

Label for the breakdown. Maximum 30 characters

commission

object

Commission information

amount

string

Amout of the commission in the currency of the order with two decimal maximum

account

string

Commission accountNumber

orderReference

string

Required

Marketplace reference for this order, which must be equal to the initial reference. Characters authorized are: a to z, A to Z, 0 to 9 and - / . + : and space

Marketplace reference for this order. Characters authorized are: a to z, A to Z, 0 to 9 and - / . + : and space

payer

object

Required

payer information

reference

string

Required

Reference of the customer from the marketplace, which must be equal to the initial reference

language

string

The default language of the browser.
The first two characters are used to identify the language code.
Must be in upper case.
Only french is supported at this time.

Response

Refund a payment transaction or all the refundable payment transactions of an order

Refund Done

Refund response

orderStatus

string

transactionList

array

paymentMethodId

string

id of the payment Method used for the transaction

id

string

Always present

status

string

Always present

amount

object

Always present

amount of the transaction

value

string

Always present

The value of the amount in decimal with max 2 digits after separator.
Only digits and dot are authorized.

currency

string

Always present

the currency iso code of the amount with 3 characters

type

string

resultCode

string

resultCodeMessage

string

The failure description. The message can be used to understand
the failure reason. It must be transmitted to support for diagnostic.

orderId

string

Order id obtained in order creation

Request Example

Response example

curl 'https://API_URL/mkp/v1/payin/refund' \ -H 'Authorization: Bearer <your_access_token>' \ -H 'id_token: <your_id_token>' \ -H 'Content-Type: application/json' \ --data-raw \

{
    "orderId": "14326513",
    "transactionId": "123456789",
    "transactionAmount": {
        "value": "100",
        "currency": "EUR"
    },
    "payer": {
        "reference": "customer_1363"
    },
    "breakdownList": [
        {
            "label": "bdl1",
            "sellerAccountNumber": "1300600000EUR01006110",
            "amount": {
                "value": "98.20",
                "currency": "EUR"
            },
            "commission": {
                "amount": "0.23",
                "account": "1300600000EUR01004110"
            }
        },
        {
            "label": "bdl2",
            "sellerAccountNumber": "1300600000EUR01004110",
            "amount": {
                "value": "1.80",
                "currency": "EUR"
            }
        }
    ]
}

Copy

Copied

{
    "resultCode": "0",
    "orderId": "14326513",
    "transactionId": "123456789",
    "transactionList": [
        {
            "id": "123123123",
            "status": "completed",
            "amount": {
                "value": "100",
                "currency": "EUR"
            },
            "paymentMethodId": "002"
        },
        {
            "id": "123123124",
            "status": "refund",
            "amount": {
                "value": "100",
                "currency": "EUR"
            },
            "paymentMethodId": "002"
        }
    ]
}

Copy

Copied

/payin/ticket Copy section link

This API is used to get ticket in JSON or in PDF format

Request

This API is used to get ticket in JSON or in PDF format

transactionId

string

Required

Id of the transaction. Must be a card transaction.

format

string

Required

Ticket format : J JSON, P : PDF

type

string

Required

Ticket type : C client, M : merchant

message

string

Message to set in the bottom of the ticket.

Response

Get card payment ticket

getTicket Response. If format is P, only fields resultCode, transactionId and fileContent are present

resultCode

string

resultCodeMessage

string

The failure description. The message can be used to understand
the failure reason. It must be transmitted to support for diagnostic.

transactionId

string

Id of the payment transaction.

name

string

brand

string

maskedPan

string

Hidden card number

transactionStatus

string

operationDate

string

Date of the operation.
The format must be YYYYMMDD

operationTime

string

Operation time in HH:MM:SS format

safe

string

Y if 3DS is verified

type

string

1: DEBIT, 2: CREDIT

authNumber

string

transNumber

string

Transaction number in PSP

amount

object

Purchase amount

amount information

value

string

The value of the amount in decimal with max 2 digits after separator.
Only digits and dot are authorized.

amount information

currency

string

the currency iso code of the amount with 3 characters

amount information

mode

string

PROD or TEST

fileContent

string

PDF file content base64 encoded, if format is P

contract

string

Payment partner contract number

Request Example

Response example

curl --get 'https://API_URL/mkp/v1/payin/ticket' \ -H 'Authorization: Bearer <your_access_token>' \ -H 'id_token: <your_id_token>' \

-d 'transactionId=234352' \

-d 'format=J' \

-d 'type=M' \

-d 'message=Message to display in the bottom of the PDF ticket'

Copy

Copied

{
    "resultCode": "0",
    "transactionId": "2851621",
    "name": "marketPlace A",
    "brand": "CB",
    "maskedPan": "111122*************44",
    "transactionStatus": "10",
    "operationDate": "20211118",
    "operationTime": "14:31:00",
    "safe": "N",
    "type": "DEBIT",
    "authNumber": "1762763",
    "transNumber": "35430234",
    "contract": "1111119",
    "amount": {
        "value": "1103.28",
        "currency": "EUR"
    },
    "mode": "TEST"
}

Copy

Copied

{
    "resultCode": "0",
    "transactionId": "2851621",
    "fileContent": "AHGDFHGHSGFHG..."
}

Copy

Copied

/operations/list Copy section link

get operations matching a set of criterias

Retrieve operation from criteria

Request

All request data are embedded in a json structure in the body

Criteria to list operation

pagination

string

Number of lines in reporting. Limited to 50.

startDate

string

Begin date of operation reporting in YYYYMMDD format

endDate

string

ended Date of operation Reporting in YYYYMMDD format

maxAmount

string

minAmount

string

offset

string

Start response line. Set to 0 when not indicated

orderReference

string

Order reference. Characters authorized are: a to z, A to Z, 0 to 9 and - / . + : _ and space

currency

string

Currency code in 3 characters ISO format

transactionId

string

Id of the payment transaction.

paymentMethodKey

string

Key identifier of the payment method type id - SDD: Sepa Direct Debit - SCT: Sepa Credit Transfer - CARD: Payment with card - SDD B2B: Sepa Direct Debit for B2B - PISP: PISP - INT: Internal Transfer - SCT INST: Sepa Credit Transfert Instant

sellerAccountNumber

string

Account number of the merchant or marketplace.

parentAccountNumber

string

A string representing the account number.

Response

Retrieve operation from criteria

To have the list of operation from a Marketplace

List of operation matching the request

resultCode

string

operationList

array

Always present

List of operation matching the request

amount

object

Always present

Amount of the operation

List of operation matching the request

value

string

Always present

The value of the amount in decimal with max 2 digits after separator.
Only digits and dot are authorized.

currency

string

Always present

the currency iso code of the amount with 3 characters

date

string

operation Date

List of operation matching the request

side

string

Always present

List of operation matching the request

type

string

Always present

type of the operation

List of operation matching the request

status

string

Always present

status of the operation

List of operation matching the request

breakdownList

array

List of breakdown

List of operation matching the request

amount

object

Always present

amount of the breakdown

sellerAccountNumber

string

Always present

label

string

Always present

Label for the breakdown

metaData

object

List of operation matching the request

transactionId

string

Always present

List of operation matching the request

creationDateTime

string

ISO 8601 format (ex: 20210325T082300+01:00)

List of operation matching the request

accountNumber

string

List of operation matching the request

cashedCumulAmount

string

Amount already cached

List of operation matching the request

orderReference

string

List of operation matching the request

accountCurrencyCode

string

List of operation matching the request

operationLabel

string

List of operation matching the request

relatedMsgStatusLabel

string

Status explanation

List of operation matching the request

thirdPartyName

string

List of operation matching the request

accountType

string

List of operation matching the request

accountCptNumber

string

List of operation matching the request

accountCptTypeLabel

string

List of operation matching the request

accountCptCurrencyCode

string

List of operation matching the request

thirdPartyCptName

string

List of operation matching the request

resultCodeMessage

string

The failure description. The message can be used to understand
the failure reason. It must be transmitted to support for diagnostic.

lineCount

string

Total number of lines

Request Example

Response example

curl 'https://API_URL/mkp/v1/operations/list' \ -H 'Authorization: Bearer <your_access_token>' \ -H 'id_token: <your_id_token>' \ -H 'Content-Type: application/json' \ --data-raw \

{
    "pagination": "50",
    "startDate": "20230601",
    "endDate": "20230630",
    "currency": "EUR",
    "maxAmount": "200",
    "minAmount": "1",
    "offset": "1"
}

Copy

Copied

{
    "resultCode": "0",
    "operationList": [
        {
            "transactionId": "55811",
            "reference": "20201021141554038",
            "status": "waiting",
            "type": "Payment",
            "side": "PAYIN",
            "date": "20201021",
            "amount": {
                "value": "200",
                "currency": "EUR"
            },
            "paymentMethodKey": "SCT",
            "bic": "AGRIFRPP777",
            "virtualIban": "FR7618206004320000115041197",
            "label": "Order 3478374 SCT",
            "breakdownList": [
                {
                    "label": "bdl1",
                    "sellerAccountNumber": "1300600000EUR01006110",
                    "amount": {
                        "value": "35",
                        "currency": "EUR"
                    }
                },
                {
                    "label": "bdl2",
                    "sellerAccountNumber": "1300600000EUR01007110",
                    "amount": {
                        "value": "35",
                        "currency": "EUR"
                    }
                }
            ]
        }
    ]
}

Copy

Copied

/paymentAccount Copy section link

get Account Details

Request

Get account details

accountNumber

string

Required

identifier of the account to get details.

Response

Account Details retrieved

Get account information response

account

object

Account information

number

string

Number of the account

Account information

name

string

Thirdparty name

Account information

status

string

Account information

currency

string

Account information

type

string

Account type

Account information

payoutAuto

string

1 if payout auto activated

Account information

floorLimit

string

Minimum amount for payout auto

Account information

balance

string

Account balance

Account information

availableBalance

string

Avalibale balance is the balance minus the floor limit.
Set to 0 if result is negative

Account information

resultCode

string

Always present

resultCodeMessage

string

The failure description. The message can be used to understand
the failure reason. It must be transmitted to support for diagnostic.

Request Example

Response example

curl --get 'https://API_URL/mkp/v1/paymentAccount' \ -H 'Authorization: Bearer <your_access_token>' \ -H 'id_token: <your_id_token>' \

-d 'accountNumber=1300600000EUR01006110'

Copy

Copied

{
    "resultCode": "0",
    "account": {
        "number": "1300600000EUR01006110",
        "name": "marketPlace A",
        "reference": "ref123",
        "currency": "EUR",
        "status": "activated",
        "type": "principal",
        "payoutAuto": "1",
        "floorLimit": "100.00",
        "balance": "528045.91",
        "availableBalance": "527945.91"
    }
}

Copy

Copied

/paymentAccount/credit Copy section link

Credit account

Credit payment account

Request

Data in input of paymentAccount credit request

accountNumber

string

Required

A string representing the account number.

amount

string

Required

Recharge amount

currency

string

Required

Currency code in 3 characters ISO format

paymentMethodKey

string

Required

Key identifier of the payment method type id. The following method are available: - SCT: Sepa Credit Transfer

Response

Credit payment account

Account credit response

Payment account credit response

resultCode

string

Always present

resultCodeMessage

string

The failure description. The message can be used to understand
the failure reason. It must be transmitted to support for diagnostic.

transactionId

string

Id of the payment transaction.

virtualIban

string

Iban to make payment to for SCT or SWIFT method

Request Example

Response example

curl 'https://API_URL/mkp/v1/paymentAccount/credit' \ -H 'Authorization: Bearer <your_access_token>' \ -H 'id_token: <your_id_token>' \ -H 'Content-Type: application/json' \ --data-raw \

{
    "accountNumber": "1300600000EUR01005110",
    "amount": "500.23",
    "currency": "EUR",
    "paymentMethodKey": "SCT"
}

Copy

Copied

{
    "resultCode": "0",
    "transactionId": "1289521",
    "virtualIban": "FR7618206004320000115091152"
}

Copy

Copied

/paymentAccount/disableIBAN Beta Copy section link

Disable current or pending payment method

Request

Disable IBAN request.
One of requestId or paymentMethodAlias is required

requestId

string

Current payment method, or pending payment method

paymentMethodAlias

string

Alias identifying a previously registered payment method.

Response

Disable current or pending payment method

Disable IBAN response

resultCode

string

resultCodeMessage

string

The failure description. The message can be used to understand
the failure reason. It must be transmitted to support for diagnostic.

Request Example

Response example

curl 'https://API_URL/mkp/v1/paymentAccount/disableIBAN' \ -H 'Authorization: Bearer <your_access_token>' \ -H 'id_token: <your_id_token>' \ -H 'Content-Type: application/json' \ --data-raw \

{
    "requestId": "CAPS202111260V3SH1"
}

Copy

Copied

{
    "resultCode": "0"
}

Copy

Copied

/paymentAccount/list Copy section link

Get list of account with serach criteria

Retrieve the accounts according to the search criteria

Request

Account list request. Criteria to find account

accountNumber

string

A string representing the account number.

currency

string

Currency code in 3 characters ISO format

accountStatus

string

Account status code in one char length A: Activated D: Deactivated R: Registered S: Suspended

sellerReference

string

Account reference

pagination

string

Number of line in reporting. Limited to 99. Default value 50.

offset

string

Start response line. Set to 0 when not indicated

Response

Retrieve the accounts according to the search criteria

Response contains account list

Account list response

resultCode

string

Always present

resultCodeMessage

string

The failure description. The message can be used to understand
the failure reason. It must be transmitted to support for diagnostic.

lineCount

string

Total number of lines

accountList

array

List of accounts

number

string

Number of the account

List of accounts

name

string

Thirdparty name

List of accounts

status

string

List of accounts

currency

string

List of accounts

type

string

Account type

List of accounts

payoutAuto

string

1 if payout auto activated

List of accounts

floorLimit

string

Minimum amount for payout auto

List of accounts

reference

string

Account reference

List of accounts

Request Example

Response example

curl 'https://API_URL/mkp/v1/paymentAccount/list' \ -H 'Authorization: Bearer <your_access_token>' \ -H 'id_token: <your_id_token>' \ -H 'Content-Type: application/json' \ --data-raw \

{
    "accountNumber": "1300600000EUR01005110",
    "currency": "EUR",
    "accountStatus": "A"
}

Copy

Copied

{
    "resultCode": "0",
    "lineCount": "2",
    "accountList": [
        {
            "number": "1300600000EUR01004110",
            "reference": "",
            "currency": "EUR",
            "status": "activated",
            "floorLimit": "100.00",
            "payoutAuto": "Y",
            "name": "marketPlace A",
            "type": "principal"
        },
        {
            "number": "1300600000EUR010024110",
            "reference": "",
            "currency": "EUR",
            "status": "activated",
            "floorLimit": "5.00",
            "payoutAuto": "N",
            "name": "marketPlace A",
            "type": "principal"
        }
    ]
}

Copy

Copied

/paymentAccount/payoutAuto Copy section link

Activate or deactivate automatic payout

the API allows you to configure the automatic payout

Request

Payout auto request

accountNumber

string

Required

A string representing the account number.

amount

string

Required

Recharge amount

frequency

string

Required

0: deactivate 1: once a day 2: once a week 3: once a month 10: Automatic on threshold

dayOfWeek

string

Selected day of the week. Between 0 and 6 If frequency is set to 2, dayOfWeek is a mandatory field. 0: Sunday 1: Monday 2: Tuesday 3: Wednesday 4: Thursday 5: Friday 6: Saturday

dayOfMonth

string

Selected day of the month. Between 1 and 31. If frequency is set to 3, dayOfMonth is a mandatory field

paymentMethodAlias

string

Required

Alias identifying a previously registered payment method.

Response

the API allows you to configure the automatic payout

Automatic payout response

Payout auto response

resultCode

string

resultCodeMessage

string

The failure description. The message can be used to understand
the failure reason. It must be transmitted to support for diagnostic.

Request Example

Response example

curl 'https://API_URL/mkp/v1/paymentAccount/payoutAuto' \ -H 'Authorization: Bearer <your_access_token>' \ -H 'id_token: <your_id_token>' \ -H 'Content-Type: application/json' \ --data-raw \

{
    "accountNumber": "1300600000EUR01005110",
    "amount": "200.00",
    "frequency": "2",
    "dayOfWeek": "1",
    "paymentMethodAlias": "PM2021011300GLR1100"
}

Copy

Copied

{
    "resultCode": "0"
}

Copy

Copied

/paymentAccount/setFloorLimit Beta Copy section link

Modifiy account floor limit

This function start the process to change IBAN.
In response a requestID is provided to identify the change process.
After validation in tyhe BO, the proprietary of the account will received an email with a link to validate this request.

Request

Set account floor limit request

accountNumber

string

Required

A string representing the account number.

amount

object

Required

Floor limit amount

amount information

value

string

Required

The value of the amount in decimal with max 2 digits after separator.
Only digits and dot are authorized.

currency

string

Required

the currency iso code of the amount with 3 characters

Response

This function start the process to change IBAN. In response a requestID is provided to identify the change process. After validation in tyhe BO, the proprietary of the account will received an email with a link to validate this request.

Start change IBAN process

Change account floor limit

Set account floor limit response

resultCode

string

resultCodeMessage

string

The failure description. The message can be used to understand
the failure reason. It must be transmitted to support for diagnostic.

Request Example

Response example

curl 'https://API_URL/mkp/v1/paymentAccount/setFloorLimit' \ -H 'Authorization: Bearer <your_access_token>' \ -H 'id_token: <your_id_token>' \ -H 'Content-Type: application/json' \ --data-raw \

{
    "accountNumber": "1300600000EUR01006110",
    "amount": {
        "value": "100.00",
        "currency": "EUR"
    }
}

Copy

Copied

{
    "resultCode": "0"
}

Copy

Copied

/paymentAccount/setIBAN Beta Copy section link

Create a new payment method

Request

Start the change IBAN process request
Upload must be done in multipart/form-data mime type.
One part must be a valid JSON with required fields in content-disposition named 'json'.
Second part must be the file base64 encoded in content-disposition named 'file'.
fileExt is defined in content-type of file part.

accountNumber

string

A string representing the account number.

firstName

string

The first name of the IBAN account's owner

lastName

string

The last name of the IBAN account's owner