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:

/token Copy section link

Ask for a token

Request

Submit a token request.

open-expander open-expander

grant_type

string
Required

To be valued by 'client_credentials'

open-expander open-expander

scope

string
Required

To be valued by 'openid'

Response

Token successful

open-expander open-expander

accessToken

string

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

open-expander open-expander

scope

string

APIM scope.

open-expander open-expander

id_token

string

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

open-expander open-expander

token_type

string

Token type.

open-expander open-expander

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

open-expander open-expander

breakdownList

array

List of breakdown

open-expander open-expander
amount
object

amount information

open-expander open-expander
value
string

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

open-expander open-expander
currency
string

the currency iso code of the amount with 3 characters

open-expander open-expander
sellerAccountNumber
string

Account number of the merchant or marketplace.

open-expander open-expander
label
string

Label for the breakdown. Maximum 30 characters

open-expander open-expander
commission
object

Commission information

open-expander open-expander
amount
string

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

open-expander open-expander
account
string

Commission accountNumber

open-expander open-expander

metaData

object

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

open-expander open-expander

adjustAmount

object

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

Mandatory if the amount is different than the initial payment.

open-expander open-expander
value
string
Required

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

open-expander open-expander
currency
string
Required

the currency iso code of the amount with 3 characters

open-expander open-expander

orderId

string
Required

Order id obtained in order creation

open-expander open-expander

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

open-expander open-expander

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.

open-expander open-expander

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

open-expander open-expander

orderId

string
Required

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

open-expander open-expander

transactionId

string

Id of the payment transaction.

open-expander open-expander

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

open-expander open-expander

resultCode

string
Always present

resultCode of the processing

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.

open-expander open-expander

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
- partial
complete: Payment is completed but all order amount is not payed
- canceled: The order is canceled

open-expander open-expander

transactionList

array

List of transaction for the order

open-expander open-expander
paymentMethodId
string

id of the payment Method used for the transaction

List of transaction for the order

open-expander open-expander
id
string
Always present

List of transaction for the order

open-expander open-expander
status
string
Always present

List of transaction for the order

open-expander open-expander
amount
object
Always present

amount of the transaction

List of transaction for the order

open-expander open-expander
value
string
Always present

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

open-expander open-expander
currency
string
Always present

the currency iso code of the amount with 3 characters

open-expander open-expander
type
string

List of transaction for the order

open-expander open-expander

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

open-expander open-expander

orderId

string
Required

Order id obtained in order creation

open-expander open-expander

transactionAmount

object
Required

Capture amount

amount information

open-expander open-expander
value
string
Required

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

open-expander open-expander
currency
string
Required

the currency iso code of the amount with 3 characters

open-expander open-expander

metaData

object

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

open-expander open-expander

breakdownList

array

open-expander open-expander
amount
object

amount information

open-expander open-expander
value
string

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

open-expander open-expander
currency
string

the currency iso code of the amount with 3 characters

open-expander open-expander
sellerAccountNumber
string

Account number of the merchant or marketplace.

open-expander open-expander
label
string

Label for the breakdown. Maximum 30 characters

open-expander open-expander
commission
object

Commission information

open-expander open-expander
amount
string

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

open-expander open-expander
account
string

Commission accountNumber

open-expander open-expander

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

open-expander open-expander

resultCode

string
Always present

resultCode of the processing

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.

open-expander open-expander

orderStatus

string
Always present

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

open-expander open-expander

transactionList

array
Always present

List of transaction for the order

open-expander open-expander
paymentMethodId
string

id of the payment Method used for the transaction

List of transaction for the order

open-expander open-expander
id
string
Always present

List of transaction for the order

open-expander open-expander
status
string
Always present

List of transaction for the order

open-expander open-expander
amount
object
Always present

amount of the transaction

List of transaction for the order

open-expander open-expander
value
string
Always present

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

open-expander open-expander
currency
string
Always present

the currency iso code of the amount with 3 characters

open-expander open-expander
type
string

List of transaction for the order

open-expander open-expander

resultCodeMessage

string

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

open-expander open-expander

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

open-expander open-expander

transactionId

string

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

open-expander open-expander

reference

string

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

Response

Get SDD mandate signed file

Get mandate response

open-expander open-expander

resultCode

string

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.

open-expander open-expander

resultCodeMessage

string

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

open-expander open-expander

transactionId

string

Id of the payment transaction.

open-expander open-expander

reference

string

Mandate reference

open-expander open-expander

signedFileContent

string

PDF file base64 encoded

Request Example
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

open-expander open-expander

orderId

string
Required

id of the order.

Response

Order retrieved successfully

Details of an order

open-expander open-expander

orderAmount

object

amount of the order

amount information

open-expander open-expander
value
string

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

amount information

open-expander open-expander
currency
string

the currency iso code of the amount with 3 characters

amount information

open-expander open-expander

orderRemainingAmount

object

remaining amount of the order if not completed

amount information

open-expander open-expander
value
string

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

amount information

open-expander open-expander
currency
string

the currency iso code of the amount with 3 characters

amount information

open-expander open-expander

orderId

string

Order identifier

Order id obtained in order creation

open-expander open-expander

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.

open-expander open-expander

resultCodeMessage

string

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

open-expander open-expander

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
- partial
complete: Payment is completed but all order amount is not payed
- canceled: The order is canceled

open-expander open-expander

transactionList

array

List of transaction for the order

open-expander open-expander
paymentMethodId
string

id of the payment Method used for the transaction

List of transaction for the order

open-expander open-expander
id
string
Always present

List of transaction for the order

open-expander open-expander
status
string
Always present

List of transaction for the order

open-expander open-expander
amount
object
Always present

amount of the transaction

List of transaction for the order

open-expander open-expander
value
string
Always present

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

open-expander open-expander
currency
string
Always present

the currency iso code of the amount with 3 characters

open-expander open-expander
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

open-expander open-expander

transPaymentMethod

object

the payment Method choosen by the shopper

Payment method information

open-expander open-expander
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.

open-expander open-expander

orderId

string

Order id obtained in order creation

open-expander open-expander

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

open-expander open-expander

orderCountryCode

string

Mandatory if orderId is not present

The ISO country code in 3 characters format

open-expander open-expander

breakdownList

array

List of breakdown for this payment

open-expander open-expander
amount
object

amount information

open-expander open-expander
value
string

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

open-expander open-expander
currency
string

the currency iso code of the amount with 3 characters

open-expander open-expander
sellerAccountNumber
string

Account number of the merchant or marketplace.

open-expander open-expander
label
string

Label for the breakdown. Maximum 30 characters

open-expander open-expander
commission
object

Commission information

open-expander open-expander
amount
string

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

open-expander open-expander
account
string

Commission accountNumber

open-expander open-expander

alias

object

If the shopper use an alias

Alias identification to used

open-expander open-expander
id
string
Required

Identifier for the alias

open-expander open-expander

metaData

object

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

open-expander open-expander

payer

object

Mandatory if orderId is not present

Payer's details

open-expander open-expander
IPAddress
string

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

open-expander open-expander
reference
string
Required

reference of the customer from the marketplace

open-expander open-expander
userAgent
string

The browser information used to request the payment

open-expander open-expander
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.

open-expander open-expander

details

object

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

open-expander open-expander
firstName
string
open-expander open-expander
lastName
string
open-expander open-expander
address
string

Road name and number

open-expander open-expander
city
string
open-expander open-expander
postalCode
string
open-expander open-expander
country
string

Country in 3 letters ISO format

open-expander open-expander
iban
string
open-expander open-expander
email
string
open-expander open-expander
state
string
open-expander open-expander
gender
string
open-expander open-expander
phoneNumber
string
open-expander open-expander
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

open-expander open-expander
reference
string

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

open-expander open-expander
socialReason
string

Compagny name

open-expander open-expander
address2
string

Additional address

open-expander open-expander

capture

string

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

open-expander open-expander

transactionAmount

object
Required

Amount for this transaction

amount information

open-expander open-expander
value
string
Required

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

open-expander open-expander
currency
string
Required

the currency iso code of the amount with 3 characters

open-expander open-expander

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)

open-expander open-expander

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.

open-expander open-expander

reason

string

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

open-expander open-expander

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.

open-expander open-expander

cart

object

Cart detail for 3DSV2. Mandatory in API v2.

open-expander open-expander
totalQuantity
string
Required

number of article in cart

open-expander open-expander

operationDate

string

Date of the operation. The format must be YYYYMMDD

open-expander open-expander

cbChallenge

string

Challenge negotiation for card payment. 01: No preference 02: No challenge required 03: Desired challenge 04: Required challenge

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

open-expander open-expander

orderId

string

Order id obtained in order creation

open-expander open-expander

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
- partial
complete: Payment is completed but all order amount is not payed
- canceled: The order is canceled

open-expander open-expander

transactionId

string

Id of the payment transaction.

open-expander open-expander

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

open-expander open-expander

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.

open-expander open-expander

virtualIban

string

Iban to make payment to for SCT or SWIFT method

open-expander open-expander

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

open-expander open-expander

reference

string

Mandate reference

open-expander open-expander

resultCodeMessage

string

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

open-expander open-expander

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

open-expander open-expander

metaData

object

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

open-expander open-expander

orderId

string
Required

Order id obtained in order creation

open-expander open-expander

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

open-expander open-expander

orderId

string

Present if success (resultCode=0)

Order id obtained in order creation

open-expander open-expander

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
- partial
complete: Payment is completed but all order amount is not payed
- canceled: The order is canceled

open-expander open-expander

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.

open-expander open-expander

resultCodeMessage

string

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

open-expander open-expander

transactionId

string

Id of the payment transaction.

open-expander open-expander

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

open-expander open-expander

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

open-expander open-expander

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

open-expander open-expander

orderCountryCode

string
Required

country iso code of the order

The ISO country code in 3 characters format

open-expander open-expander

amount

object
Required

amount of the order

amount information

open-expander open-expander
value
string
Required

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

open-expander open-expander
currency
string
Required

the currency iso code of the amount with 3 characters

open-expander open-expander

breakdownList

array

breakdown list

open-expander open-expander
amount
object

amount information

open-expander open-expander
value
string

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

open-expander open-expander
currency
string

the currency iso code of the amount with 3 characters

open-expander open-expander
sellerAccountNumber
string

Account number of the merchant or marketplace.

open-expander open-expander
label
string

Label for the breakdown. Maximum 30 characters

open-expander open-expander
commission
object

Commission information

open-expander open-expander
amount
string

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

open-expander open-expander
account
string

Commission accountNumber

open-expander open-expander

payer

object
Required

customer details for iframe

payer information

open-expander open-expander
reference
string
Required

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

open-expander open-expander
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.

open-expander open-expander

capture

string

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

open-expander open-expander

metaData

object

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

open-expander open-expander

recurrent

string

recurrent indicator "1" for recurrent payment "0" or absent if not a recurrent payment

open-expander open-expander

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.

open-expander open-expander

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.

open-expander open-expander

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)

open-expander open-expander

cart

object

Cart detail for 3DSV2. Mandatory in API v2.

open-expander open-expander
totalQuantity
string
Required

number of article in cart

open-expander open-expander

paymentAccount

string

open-expander open-expander

cbChallenge

string

Challenge negotiation for card payment. 01: No preference 02: No challenge required 03: Desired challenge 04: Required challenge

open-expander open-expander

details

object

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

open-expander open-expander
firstName
string
open-expander open-expander
lastName
string
open-expander open-expander
address
string

Road name and number

open-expander open-expander
city
string
open-expander open-expander
postalCode
string
open-expander open-expander
country
string

Country in 3 letters ISO format

open-expander open-expander
iban
string
open-expander open-expander
email
string
open-expander open-expander
state
string
open-expander open-expander
gender
string
open-expander open-expander
phoneNumber
string
open-expander open-expander
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

open-expander open-expander
reference
string

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

open-expander open-expander
socialReason
string

Compagny name

open-expander open-expander
address2
string

Additional address

open-expander open-expander

page

string

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

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

open-expander open-expander

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.

open-expander open-expander

orderId

string

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

Order id obtained in order creation

open-expander open-expander

resultCodeMessage

string

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

open-expander open-expander

authenticationCode

string

Authentification Code to use to open user iframe

open-expander open-expander

Site

string

Site name or number

open-expander open-expander

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

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

open-expander open-expander

orderReference

string
Required

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

open-expander open-expander

orderCountryCode

string
Required

The ISO country code in 3 characters format

open-expander open-expander

amount

object
Required

amount of the order

amount information

open-expander open-expander
value
string
Required

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

open-expander open-expander
currency
string
Required

the currency iso code of the amount with 3 characters

open-expander open-expander

payer

object
Required

Payer's details

open-expander open-expander
IPAddress
string

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

open-expander open-expander
reference
string
Required

reference of the customer from the marketplace

open-expander open-expander
userAgent
string

The browser information used to request the payment

open-expander open-expander
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.

open-expander open-expander

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

open-expander open-expander

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.

open-expander open-expander

paymentMethodList

array

list of available payment methods

open-expander open-expander
aliasList
array

if alias exist for the customer and the payment Method

list of available payment methods

open-expander open-expander
id
string
Always present
open-expander open-expander
expirationDate
string

format MMYY

open-expander open-expander
maskedPan
string

Hidden card number or IBAN

open-expander open-expander
label
string

label of the alias

open-expander open-expander
brand
string

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

open-expander open-expander
bankCode
string
open-expander open-expander
id
string
Always present

list of available payment methods

open-expander open-expander
label
string

label of the payment Method

list of available payment methods

open-expander open-expander
type
string

list of available payment methods

open-expander open-expander

orderId

string

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

Order id obtained in order creation

open-expander open-expander

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": "ORDREF_20210203180537394",
"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

open-expander open-expander

orderId

string
Required

Id of the order

Order id obtained in order creation

open-expander open-expander

transactionAmount

object
Required

Amount to refund

amount information

open-expander open-expander
value
string
Required

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

open-expander open-expander
currency
string
Required

the currency iso code of the amount with 3 characters

open-expander open-expander

transactionId

string

Id of the payment transaction.

open-expander open-expander

metaData

object

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

open-expander open-expander

reason

string

The refund reason

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

open-expander open-expander

breakdownList

array

open-expander open-expander
amount
object

amount information

open-expander open-expander
value
string

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

open-expander open-expander
currency
string

the currency iso code of the amount with 3 characters

open-expander open-expander
sellerAccountNumber
string

Account number of the merchant or marketplace.

open-expander open-expander
label
string

Label for the breakdown. Maximum 30 characters

open-expander open-expander
commission
object

Commission information

open-expander open-expander
amount
string

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

open-expander open-expander
account
string

Commission accountNumber

open-expander open-expander

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

open-expander open-expander

payer

object
Required

payer information

open-expander open-expander
reference
string
Required

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

open-expander open-expander
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

open-expander open-expander

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
- partial
complete: Payment is completed but all order amount is not payed
- canceled: The order is canceled

open-expander open-expander

transactionList

array
open-expander open-expander
paymentMethodId
string

id of the payment Method used for the transaction

open-expander open-expander
id
string
Always present

open-expander open-expander
status
string
Always present

open-expander open-expander
amount
object
Always present

amount of the transaction

open-expander open-expander
value
string
Always present

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

open-expander open-expander
currency
string
Always present

the currency iso code of the amount with 3 characters

open-expander open-expander
type
string

open-expander open-expander

resultCode

string

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.

open-expander open-expander

resultCodeMessage

string

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

open-expander open-expander

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

open-expander open-expander

transactionId

string
Required

Id of the transaction. Must be a card transaction.

open-expander open-expander

format

string
Required

Ticket format : J JSON, P : PDF

open-expander open-expander

type

string
Required

Ticket type : C client, M : merchant

open-expander open-expander

message

string

Message to set in the bottom of the ticket.

Response

Get card payment ticket

Get card payment ticket

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

open-expander open-expander

resultCode

string

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.

open-expander open-expander

resultCodeMessage

string

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

open-expander open-expander

transactionId

string

Id of the payment transaction.

open-expander open-expander

name

string
open-expander open-expander

brand

string
open-expander open-expander

maskedPan

string

Hidden card number

open-expander open-expander

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

open-expander open-expander

operationDate

string

Date of the operation.
The format must be YYYYMMDD

open-expander open-expander

operationTime

string

Operation time in HH:MM:SS format

open-expander open-expander

safe

string

Y if 3DS is verified

open-expander open-expander

type

string

1: DEBIT, 2: CREDIT

open-expander open-expander

authNumber

string
open-expander open-expander

transNumber

string

Transaction number in PSP

open-expander open-expander

amount

object

Purchase amount

amount information

open-expander open-expander
value
string

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

amount information

open-expander open-expander
currency
string

the currency iso code of the amount with 3 characters

amount information

open-expander open-expander

mode

string

PROD or TEST

open-expander open-expander

fileContent

string

PDF file content base64 encoded, if format is P

open-expander open-expander

contract

string

Payment partner contract number

Request Example
Response 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

open-expander open-expander

pagination

string

Number of lines in reporting. Limited to 50.

open-expander open-expander

startDate

string

Begin date of operation reporting in YYYYMMDD format

open-expander open-expander

endDate

string

ended Date of operation Reporting in YYYYMMDD format

open-expander open-expander

maxAmount

string

open-expander open-expander

minAmount

string

open-expander open-expander

offset

string

Start response line. Set to 0 when not indicated

open-expander open-expander

orderReference

string

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

open-expander open-expander

currency

string

Currency code in 3 characters ISO format

open-expander open-expander

transactionId

string

Id of the payment transaction.

open-expander open-expander

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

open-expander open-expander

sellerAccountNumber

string

Account number of the merchant or marketplace.

open-expander open-expander

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

open-expander open-expander

resultCode

string

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.

open-expander open-expander

operationList

array
Always present

List of operation matching the request

open-expander open-expander
amount
object
Always present

Amount of the operation

List of operation matching the request

open-expander open-expander
value
string
Always present

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

open-expander open-expander
currency
string
Always present

the currency iso code of the amount with 3 characters

open-expander open-expander
date
string

operation Date

List of operation matching the request

open-expander open-expander
side
string
Always present

List of operation matching the request

open-expander open-expander
type
string
Always present

type of the operation

List of operation matching the request

open-expander open-expander
status
string
Always present

status of the operation

List of operation matching the request

open-expander open-expander
breakdownList
array

List of breakdown

List of operation matching the request

open-expander open-expander
amount
object
Always present

amount of the breakdown

open-expander open-expander
sellerAccountNumber
string
Always present
open-expander open-expander
label
string
Always present

Label for the breakdown

open-expander open-expander
metaData
object

List of operation matching the request

open-expander open-expander
transactionId
string
Always present

List of operation matching the request

open-expander open-expander
creationDateTime
string

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

List of operation matching the request

open-expander open-expander
accountNumber
string

List of operation matching the request

open-expander open-expander
cachedCumulAmount
string

Amount already cached

List of operation matching the request

open-expander open-expander
orderReference
string

List of operation matching the request

open-expander open-expander
accountCurrencyCode
string

List of operation matching the request

open-expander open-expander
operationLabel
string

List of operation matching the request

open-expander open-expander
relatedMsgStatusLabel
string

Status explanation

List of operation matching the request

open-expander open-expander
thirdPartyName
string

List of operation matching the request

open-expander open-expander
accountType
string

List of operation matching the request

open-expander open-expander
accountCptNumber
string

List of operation matching the request

open-expander open-expander
accountCptTypeLabel
string

List of operation matching the request

open-expander open-expander
accountCptCurrencyCode
string

List of operation matching the request

open-expander open-expander
thirdPartyCptName
string

List of operation matching the request

open-expander open-expander

resultCodeMessage

string

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

open-expander open-expander

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": "010820101000",
"endDate": "281020101900",
"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

open-expander open-expander

accountNumber

string
Required

identifier of the account to get details.

Response

Account Details retrieved

Get account information response

open-expander open-expander

account

object

Account information

open-expander open-expander
number
string

Number of the account

Account information

open-expander open-expander
name
string

Thirdparty name

Account information

open-expander open-expander
status
string

Account information

open-expander open-expander
currency
string

Account information

open-expander open-expander
type
string

Account type

Account information

open-expander open-expander
payoutAuto
string

1 if payout auto activated

Account information

open-expander open-expander
floorLimit
string

Minimum amount for payout auto

Account information

open-expander open-expander
balance
string

Account balance

Account information

open-expander open-expander
availableBalance
string

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

Account information

open-expander open-expander

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.

open-expander open-expander

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

open-expander open-expander

accountNumber

string
Required

A string representing the account number.

open-expander open-expander

amount

string
Required

Recharge amount

open-expander open-expander

currency

string

Currency code in 3 characters ISO format

open-expander open-expander

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

open-expander open-expander

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.

open-expander open-expander

resultCodeMessage

string

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

open-expander open-expander

transactionId

string

Id of the payment transaction.

open-expander open-expander

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/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

open-expander open-expander

accountNumber

string

A string representing the account number.

open-expander open-expander

currency

string

Currency code in 3 characters ISO format

open-expander open-expander

accountStatus

string

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

open-expander open-expander

sellerReference

string

Account reference

open-expander open-expander

pagination

string

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

open-expander open-expander

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

open-expander open-expander

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.

open-expander open-expander

resultCodeMessage

string

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

open-expander open-expander

lineCount

string

Total number of lines

open-expander open-expander

accountList

array

List of accounts

open-expander open-expander
number
string

Number of the account

List of accounts

open-expander open-expander
name
string

Thirdparty name

List of accounts

open-expander open-expander
status
string

List of accounts

open-expander open-expander
currency
string

List of accounts

open-expander open-expander
type
string

Account type

List of accounts

open-expander open-expander
payoutAuto
string

1 if payout auto activated

List of accounts

open-expander open-expander
floorLimit
string

Minimum amount for payout auto

List of accounts

open-expander open-expander
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

open-expander open-expander

accountNumber

string

A string representing the account number.

open-expander open-expander

amount

string
Required

Recharge amount

open-expander open-expander

frequency

string
Required

0: deactivate 1: once a day 2: once a week 3: once a month

open-expander open-expander

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

open-expander open-expander

dayOfMonth

string

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

open-expander open-expander

paymentMethodAlias

string

Alias identifying a previously registered payment method.

Response

the API allows you to configure the automatic payout

Automatic payout response

Payout auto response

open-expander open-expander

resultCode

string

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.

open-expander open-expander

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

/payout/create Copy section link

Submit a payout from accountNumber to the bank account associated to this account number.

From accountNumber to the bank account associated to this account number.

Request

Payout request

open-expander open-expander

endToEndId

string

end to end identifier

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.

open-expander open-expander

payoutAmount

object
Required

amount and currency of the payout

amount information

open-expander open-expander
value
string
Required

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

open-expander open-expander
currency
string
Required

the currency iso code of the amount with 3 characters

open-expander open-expander

paymentMethodAlias

string
Required

Alias identifying a previously registered payment method.

open-expander open-expander

accountNumber

string
Required

Account Number invloved in payout

A string representing the account number.

open-expander open-expander

commission

object

Commission information

open-expander open-expander
amount
string
Required

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

open-expander open-expander
account
string

Commission accountNumber

open-expander open-expander

metaData

object

User metaData in Json or string format

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

open-expander open-expander

reason

string

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

Response

From accountNumber to the bank account associated to this account number.

Payout successful

Payout response

open-expander open-expander

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.

open-expander open-expander

resultCodeMessage

string

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

open-expander open-expander

transactionId

string

Id of the payment transaction.

open-expander open-expander

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

Request Example
Response example

curl 'https://API_URL/mkp/v1/payout/create' \ -H 'Authorization: Bearer <your_access_token>' \ -H 'id_token: <your_id_token>' \ -H 'Content-Type: application/json' \ --data-raw \ 
{
"accountNumber": "1300600000EUR01006110",
"reason": "test",
"endToEndId": "ETEID-20210203142803584",
"paymentMethodAlias": "PM2021011300GLR1100",
"metaData": {
"Metadata3": "donn\u00e9e3",
"Metadata4": "donnee4"
},
"payoutAmount": {
"value": "200",
"currency": "EUR"
},
"commission": {
"amount": "1.00",
"account": "1300600000EUR60002411"
}
}

Copy
Copied

{
"resultCode": "0",
"transactionId": "1289921"
}

Copy
Copied

/transfer/create Copy section link

Ask for a transfer between two accounts

Submit a transfer from one account (accountNumber) to another (accountCtpNumber)

Request

Transfer Resquest

open-expander open-expander

accountCptNumber

string
Required

Account number to credit

A string representing the account number.

open-expander open-expander

transferAmount

object
Required

the Amount to transfer

amount information

open-expander open-expander
value
string
Required

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

open-expander open-expander
currency
string
Required

the currency iso code of the amount with 3 characters

open-expander open-expander

accountNumber

string
Required

Account Number to debit

A string representing the account number.

open-expander open-expander

orderRef

string

operation reference of the transfer

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

open-expander open-expander

metaData

object

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

open-expander open-expander

reason

string
Required

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

Response

Submit a transfer from one account (accountNumber) to another (accountCtpNumber)

transfer done successfully

open-expander open-expander

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.

open-expander open-expander

resultCodeMessage

string

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

open-expander open-expander

transactionId

string

Id of the payment transaction.

Request Example
Response example

curl 'https://API_URL/mkp/v1/transfer/create' \ -H 'Authorization: Bearer <your_access_token>' \ -H 'id_token: <your_id_token>' \ -H 'Content-Type: application/json' \ --data-raw \ 
{
"accountNumber": "1300600000EUR01004110",
"accountCptNumber": "1300600000EUR01006110",
"orderRef": "20210203142044",
"reason": "test",
"transferAmount": {
"value": "10.01",
"currency": "EUR"
}
}

Copy
Copied

{
"resultCode": "0",
"transactionId": "1287521"
}

Copy
Copied