Edenred Checkout API Contract
home
Introduction to Checkout
Checkout is the new version of Edenred's online payment solution.
Checkout was built in order to provide external partners with an easily integrated payment solution whose scope was enlarged from ticket restaurant to gift Edenred products.
Get started with Edenred Checkout
Checkout uses REST, authentication with Client ID, Client secret and return HTTP Response codes and responses encoded in JSON.
How to integrate to Checkout
A partner is granted access to Checkout via a set of credentials.
These credentials include a Checkout Client Id and a Checkout Client secret.
These will enable the usage of checkout API.
The process of retrieving the client ID and client secret is as follows:
- Partner asks Business Unit for Checkout access.
- Partner needs to provide Business Unit with: choice between automatic ( single messaging) capture mode and manual capture mode ( dual messaging), return URL after checkout payment flow, partner logo URL and environment (UAT and PROD). Cancel URL is optional in case partner wants to display a link for a user who wants to quit the checkout flow.
- Partner will receive checkout ID and checkout secret for both in UAT and PROD via email.
Example of a request which includes credentials information:
curl --location --request POST 'https://checkout.sbx.eu.edenred.io/' \
--header 'x-client-id: YOUR_CLIENTID' \
--header 'x-client-secret: YOUR_CLIENTSECRET' \API Reference for testing and production environments
The URL to the API service is either:
- Sandbox: https://checkout.sbx.eu.edenred.io
- Staging EU: https://checkout.stg.eu.edenred.io
- Production EU: https://checkout.eu.edenred.io
How to onboard a user on Checkout
To onboard a user on Checkout, we use the agreement concept, which includes its creation and execution.
How to create an Agreement?
The first step to create an agreement is for checkout to allow the partner to call Checkout API providing redirect URL. He can also provide Checkout with UI locale (user interface language), custom user identifier and a cancel URL. Only redirect URL is mandatory.
Agreement Creation endpoint documentation: https://anypoint.mulesoft.com/exchange/f02a5569-24ac-491a-964a-0950ab318728/edenred-checkout/minor/0.1/console/method/%23528/
How to execute an Agreement?
The agreement created will be created in pending state and will need to be executed by the user to associate their credentials. To be executed by the user the partner must prompt a dedicated page with the agreement ID in a WebView or regular browser.
Example of Agreement URL execution: https://checkout.sbx.eu.edenred.io/web/confirm-agreement?agreement_id=rob1fd047f7c02d149vc8426674fb0e6f519
Agreement is an optional step to allow the partner application to serve as a contract between the partner application and ER Checkout, enabling the user to associate their credentials for future payments. If an agreement is generated, the user will not be forced to re-login during token duration period ( 60 days) and payment without user interaction ( API payment) is available. This API payment flow was generated for one-card holders, users with default card and user whose order can only be paid with one card. If an agreement is not generated or if there was no activity for more than 60 days, the user must login and complete checkout's payment flow.
Callback URL to notify the partner once agreement is completed
After an agreement is executed, ER Checkout will redirect the user to the partner’s website using a return url provided by the partner, giving the user immediate feedback. Concurrently, ER Checkout developed a mechanism which will send a callback to the partner’s backend with the agreement status. Additionally, the partner’s backend can query ER Checkout with the agreement ID to obtain the current agreement status.
The Agreement callback payload
{
"id": "rob10598f47e1a7748028fg2x1d3ed843797"
"status": "confirmed"
}
Retrieve the details of the agreement
Partners have the capability to retrieve the details of the agreement via an API call that returns information such as the status or the balance. A valid agreement is required to perform this operation.
Retrieve agreement details endpoint documentation: https://anypoint.mulesoft.com/exchange/f02a5569-24ac-491a-964a-0950ab318728/edenred-checkout/minor/0.1/console/method/%23536/
Revoking an Agreement
Partners have the capability to revoke an agreement via an API call. When an agreement is revoked, the user will need to go through the onboarding process again to re-establish the agreement or re-authenticate each time they execute a payment request without a valid agreement.
Revoke agreement endpoint documentation: https://anypoint.mulesoft.com/exchange/f02a5569-24ac-491a-964a-0950ab318728/edenred-checkout/minor/0.1/console/method/%23544/
Payments
After executing the agreement, the user's account is linked to the partner application. The partner can now create a payment request using this agreement providing 2 mandatory parameters, the merchant ID and the transaction amount. The agreement, if provided and valid, allows bypassing authentication for the payment. If the agreement is not provided or invalid, the user will need to reauthenticate during the payment execution. In detail, the partner will call Checkout backend to create the payment request, while checkout will create, store it and provide the partner with the payment request ID back. At this moment, the payment request, despite well created, is still in pending state.
Create Payment Request endpoint documentation: https://anypoint.mulesoft.com/exchange/f02a5569-24ac-491a-964a-0950ab318728/edenred-checkout/minor/0.1/console/method/%23551/
How to execute a Payment Request?
Once the payment request is created, it shall be processed. To execute the payment request, checkout proposes 2 solutions: the payment via User Interface (UI) and the payment via API.
The payment request process is comprised of 2 phases, the first phase is to call the estimate charge endpoint while the second phase is to proceed with the payment via UI or API.
The estimate charge endpoint shall be called after the user has finalized his order and prior to the payment being authorized.
To call this endpoint, the partner must provide agreement ID and order amount per category.
The objective of the estimate charge endpoint is to provide the status and balance of a user's card if:
The user has one default card => endpoint will return its status and min ( balance, order amount) => payment can be processed via API with this card
The user has only one card associated with his account => endpoint will return its status and min ( balance, order amount) => payment can be processed via API with this card
The user can pay with only one card => endpoint will return its status and min ( balance, order amount) => payment can be processed via API with this card
If the user has multiple cards that can be used to pay for the order in question, the partner will receive the status: USER_INTERACTION_REQUIRED => partner to open checkout web-view to complete the payment with user interaction ( payment via UI).
The endpoint's response will determine which payment option a partner should choose, UI or API.
If the backend response is " INVALID AGREEMENT" the partner should prompt the onboarding UI so that a new agreement ID can be generated.
If the backend response is available: the balance is ready to use without any restrictions or further actions required by the user.
If the backend response is unavailable: the balance is currently not accessible, which may due to reasons such as insufficient funds, no associated payment method, or other restrictions preventing usage.
If the backend response is user_interaction_required: the user needs to complete an action to access the balance. This could be due to multiple reasons such as multiple fund sources requiring selection or the user having to confirm his identity.
When it comes to processing the Payment Request, there are 2 options:
- Authorizing the payment request using the UI ( user interface), requiring user interaction
The partner can load a dedicated web page with the payment request ID to proceed with the payment. If an agreement was provided and is valid, it will bypass the authentication and during the process ER Checkout will save the card used and associate it with the agreement, in case the user decides to set it as default.
Example of Payment URL that shall be prompted by the partner if payment is authorized via UI : https://checkout.sbx.eu.edenred.io/web/authorize-payment?payment_id=rob13a9d116c5e754cadbd95d95d5e7fa2be
- Authorizing the payment request using the API, without user interaction
If there is a valid agreement for the user, the partner can authorize the payment request via API, without any user interaction, under 3 circumstances: (1) The default card associated with the agreement will be used. (2) There is no default card associated with the agreement but the user has only one eligible card linked to his account.(3) There is only one card with which the order in question can be paid for.
During the payment authorization via API, the Checkout API call to authorize the payment request will fail with a specific error code "USER_INTERACTION_REQUIRED" if (1) agreement is invalid or revoked or (2) there is no default card in the agreement and/or there is no card eligible for the payment. The partner application must then prompt the user to complete the payment through the UI, using the same payment request ID.
Authorize Payment via API endpoint documentation: https://anypoint.mulesoft.com/exchange/f02a5569-24ac-491a-964a-0950ab318728/edenred-checkout/minor/0.1/console/method/%23567/
Callback URL to notify the partner once payment is completed
Using the same mechanism as for the agreement yet a different callback URL, after a payment is completed, ER Checkout will redirect the user to the partner’s website using a return url provided by the partner, giving the user immediate feedback. Concurrently, ER Checkout will send a callback to the partner’s backend with the payment status. Additionally, the partner’s backend can also query ER Checkout with the payment ID to obtain the current payment status.
Retrieve Payment Request details endpoint documentation: endpoint documentation: https://anypoint.mulesoft.com/exchange/f02a5569-24ac-491a-964a-0950ab318728/edenred-checkout/minor/0.1/console/method/%23559/
The Payment callback payload example
{
"id": "rob10598f47e1a7748028fg2x1d3ed843797",
"status": "authorized",
"sub_status": ""
}
Finalize the payment (Capturing the transaction)
In case the payment was not captured during the authorization (e.g. if the partner does or prefers manual capture), the partner can call an API to capture or cancel all or a part of the previously authorized amount.
If the partner chooses the automatic capture mode ( single messaging), the payment will be completed ( authorized + captured) once the user is redirected back to the partner via the redirect URL. In this case, only a refund can be performed on the transaction in question.
Capture Payment Request endpoint documentation: https://anypoint.mulesoft.com/exchange/f02a5569-24ac-491a-964a-0950ab318728/edenred-checkout/minor/0.1/console/method/%23575/
Cancel Payment Request endpoint documentation: https://anypoint.mulesoft.com/exchange/f02a5569-24ac-491a-964a-0950ab318728/edenred-checkout/minor/0.1/console/method/%23583/
Please note that, once an Edenred card was selected for a payment, the maximum amount possible will be charged on it based on the transaction amount. This transaction amount is specified by the partner as the total amount payable using the Edenred card selected. The rules are as follows:
- If the user balance does not cover the full transaction amount, Checkout throw an error.
- If the balance covers the full transaction amount, Checkout will charge the maximum amount.
Refunding a Payment
Partners have the capability to refund a payment that has already been executed via an API call. The refund can be for the full or partial amount of the original transaction.
If the Payment is Authorized, a Cancel request is needed to unblock the funds. If the Payment is Captured, then a refund request is needed to refund the amount charged.
Refund Payment endpoint documentation: https://anypoint.mulesoft.com/exchange/f02a5569-24ac-491a-964a-0950ab318728/edenred-checkout/minor/0.1/console/method/%23591/
Errors with Payment
Checkout's payment page ( shown when partner authorizes payment via UI) will only expose cards which (1) the user has in his wallet, (2) the partner can accept (3) can be used to pay the order in question. This filter is done at the moment where the user confirms that he wants to proceed with the payment, so the backend will then have access to the the user's cards, their balance and status. If there is any payment error, checkout's backend will send an error message to the partner "CANNOT_PROCESS_PAYMENT_REQUEST", and checkout will prompt an error page informing the user about the payment having failed and redirecting him back to the partner.
If the payment is authorized via API, and there is a payment error, the backend will send an error message to the partner " CANNOT_PROCESS_PAYMENT_REQUEST", and partner should expose the error message he pleases on his own UI.
That said, the meaning of the possible errors can be found below:
- USER_INTERACTION_REQUIRED => partner to open checkout web-view to complete the payment with user interaction
- CANNOT_PROCESS_PAYMENT_REQUEST => means that it is impossible to pay with Edenred, if payment is authorized via UI, then the user will be presented checkout's error page and be redirected to the partner; if payment is authorized via API, error sent via backend from checkout to the partner, UI to be managed by the partner.