Edenred Direct Payment Services

1. Generalities

In Finland, our payment API is configured on one product: Lounari Card which enable users to pay for a meal or food. With the Lounari Card, a user can spend the amount requested without any limitation of number of transactions per day (in the limit of the balance available on his account, i.e. balance can’t be negative).

Some spending rules are applied on the transaction processing with a minimum and maximum amount checked on each transaction requested:

   • The minimum amount for a transaction is 8€
   • The maximum amount for a transaction is 12,70€

If a user has a complementary payment method linked to his Lounari Card, the exceeded amount will be done using that method.

The regulation(s) checks and rules on the transaction processing are handled on the Edenred side.

Please note that all amounts in our API are given in cents (example: 9€ = 900).

2. User Security Tokens

Please refer to this section for more details about security tokens.

2.1. Authentication URL

Here is the URL configuration to be used to call the authentication process per environment

   • ‘authentication-url’ in UAT : https://sso.sbx.edenred.io
   • ‘authentication-url’ in Prod : https://sso.eu.edenred.io

2.1. Login Process

1) To test the API in sandbox, you can get an authorization_code by clicking on the link bellow:

https://sso.sbx.edenred.io/connect/authorize?response_type=code&client_id=441ebeb360914be9b8725e827a976b6c&scope=openid%20edg-xp-mealdelivery-api%20offline_access&redirect_uri=http://nowhere.edenred.net/oauth-callback&acr_values=tenant:fi-ben&ui_locales=en

The authentication URL is built as follow:

{{authentication-url}}/connect/authorize?response_type=code&client_id={{authentication-client_id}}={{scope}}&redirect_uri={{authentication-redirect_url}}&acr_values=tenant:{{tenant}}

Where

{{authentication-url}} = see chapter 2.1

{{authentication-client_id}} = configuration provided by Edenred (Dedicated client id in UAT and in production)

{{scope}} = openid edg-xp-mealdelivery-api offline_access (to be provided on each authentication request to provide the good level of rights to the user in the payment experience)

{{authentication-redirect_url}} = callback URL(s) whitelisted on our side (to be provided in the configuration request for the whitelisting on Edenred side). Several redirect URLs can be whitelisted/managed on Edenred side (different values can be set in UAT and in production)

{{tenant}} = fi-ben

Example of account and credit card information that can be used to test the API in UAT:

Edenred user:

  Username: edpstest03
  Password: edpstest03
  CVV: 861

Credit / Debit Card:

 •Name: Test Card
 •PAN: 4242 4242 4242 4242
 •Exp date: 01/25
 •CVV: 100

Note: 3DSV2 validation code is static in UAT: Checkout1!

Login Process

All the following steps are mandatory on the user side to connect his MyEdenred account on the partner platform:

1- User provides his username / Password of his MyEdenred account

2- User provides the CVV of his Edenred Card

3- User provides a credit card

Case 1: User has no credit card yet attached to his MyEdenred account, in this case: =>
•User fills-in his credit card information,
•User validates his identity via a 3DS check
•if 3DS check validated by the user, (credit card is tokenized in real-time and saved in a secured place on Edenred backend)
Note: the user validates a 3DS check each time he requests to add a new card
Case 2: User has already a credit card attached to his MyEdenred account => User selects the existing credit card (no 3DS check in this specific case)

4- User provides his opt-in to the service

2) After user has successfully logged-in, he'll be redirected to a url - you have provided us, and we have configured on our end - like below in which we will provide you an "authorization code":

http://nowhere.edenred.net/oauth-callback?code={authorization_code}&...

3) Copy the authorization_code and use the API request "Get access_token from authorization_code**" in the following collection of API calls :

Please note that the authorization_code is burned once you have use it to retrieve the tokens. If the API call fails, you must get a new authorization_code to make a retry (i.e.: user has to go through the authentication steps again).

Note: in case of failure in any step of the authentication process (or if the user leaves the authentication process before the last step), there is no error message sent back to the partner platform

2.2. Logout Process

Logout the Edenred account from your platform. All tokens are then invalid

GET {host}/connect/endsession?id_token_hint=<idToken>=<postLogoutRedirectUri> HTTP/1.1
Host: {{authentication-url}}

Where

'authentication-url' = see chapter 2.1

And id_Token is retrieved from the refreshing token response

And postLogoutRedirectUri is a callback URL whitelisted on our side (to be provided in the configuration request for the whitelisting on Edenred side)

eg: postLogoutRedirectUri = http://nowhere.edenred.net/oauth-callback

3. Direct Payment API

3.1. Postman Collection

3.2. Payment URL

Here is the URL configuration to be used to call the APIs per environnement

   • ‘payment-url’ in UAT : https://directpayment.stg.eu.edenred.io/v2
   • ‘payment-url’ in Prod : https://directpayment.eu.edenred.io/v2

3.3. User Balance

Get Balances

Gets all the available amount of the balances on the user account. In Finland, in the current configuration, we provide the full sum of the balance of the Lounari product available for the user.

The authorization header is mandatory for this request.

Request:

 GET {host}/v2/users/{username}/balances?product_class={{product_class}} HTTP/1.1
 Host: {payment-url}
 Authorization: Bearer {token}
 X-Client-Id: {payment-clientId}
 X-Client-Secret: {payment-clientSecret}
 Content-Type: application/json
 Product_Class: MAIN (for Lounari product)

Response:

{
    "meta": {
        "status": "succeeded",
        "messages": []
    },
    "data": [
        {
            "product_class": "MAIN",
            "available_amount": 48295,
            "currency": "EUR"
        }
    ]
}

Estimate Charge

Check if an amount can be spent and answer the possible amount that can be spent. If the requested amount is above the available balance, the service will provide the available amount that can be spent with Edenred in the response.

The authorization header is mandatory for this request.

Example 1: Requested amount < max amount that can be used with Edenred

Request:

 POST {host}/v2/users/{username}/actions/estimate-charge?product_class={{product_class}} HTTP/1.1
 Host: {payment-url}
 Authorization: Bearer {token}
 X-Client-Id: {payment-clientId}
 X-Client-Secret: {payment-clientSecret}
 Content-Type: application/json
 Product_Class: MAIN (for Lounari product)

 {
   "amount": 1000
 }

Response:

{
    "meta": {
        "status": "succeeded",
        "messages": []
    },
    "data": {
        "available_amount": 1000,
        "currency": "EUR"
    }
}

Example 2: Requested amount > max amount that can be used with Edenred

Request:

 POST {host}/v2/users/{username}/actions/estimate-charge?product_class={{product_class}} HTTP/1.1
 Host: {payment-url}
 Authorization: Bearer {token}
 X-Client-Id: {payment-clientId}
 X-Client-Secret: {payment-clientSecret}
 Content-Type: application/json
 Product_Class: MAIN (for Lounari product)

 {
   "amount": 1900
 }

Response:

{
    "meta": {
        "status": "succeeded",
        "messages": []
    },
    "data": {
        "available_amount": 1130,
        "currency": "EUR"
    }
}

3.4. User Transactions

EDPS supports 2 authorization implementation methods:

1. Dual messaging 1. (also named “manual capture”): this processing allows the partner to manage the payment in 2 dedicated steps : 1/ on the “authorize” request, the funds are saved on the user wallet(s), 2/ on the “capture” request, the funds are collected on the user wallet(s),
2. Single messaging (also named “automatic capture”) : this processing allows the partner to manage the payment in 1 step : authorization and capture are done in one call (the “authorize” request) on the different wallet(s) involved for the payment.

In both configurations, EDPS supports the possibility to manage a payment with 2 payment methods (one via the Edenred Card and one via a personal credit card). We can then handle different payment use cases 1/ manage the remaining amount with the credit card on top of the amount processed with the Edenred payment mean or 2/ charge to the credit card the amount that can’t be spent via the Edenred Card.Please refer to the dedicated section below to get more details on the implementation.

Definition

The partner can use 2 fields in the payment APIs to provide the amount to be processed by Edenred :

• The ‘amount’ - mandatory field - corresponds to the amount that can be paid by an Edenred payment mean (i.e.: food, beverage)

• The 'ineligible_amount' - optional field - corresponds to the amount that will not be paid by an Edenred payment mean (i.e.: delivery fee, non-food items like alcohol…)

The principle is that if the input ‘amount’ is higher than the available amount on the user balance, the difference between these 2 amounts will be paid by the credit card and/or if the partner provides a value in the ‘ineligible_amount’ field, this “ineligible” amount will be charged directly to the credit card of the user.

Please refer to the dedicated section below to get more details on the implementation.

Examples

In the following examples, we take as an assumption that the following items can’t be spent via the Edenred payment mean: Alcohol, service fees, delivery fees.

Case 1 : Order is within the Edenred limit but includes non-eligible items

• User has an available amount to spend on his Edenred Payment mean of 11.30€
• User orders on the partner platform the following basket
     o Healthy salad: 9,00€
     o White Wine Bottle (25cl): 4,00€
• Partner applies a  fee of 2,00€ on this basket
     o Delivery fee: 2,00€

• Partner will allocate the amount as follow in the transaction request(s)
     o ‘amount’ = 900
     o ‘ineligible_amount’ = 600, to handle
              Non food item = 400
              Delivery fee = 200

• Edenred will charge the Edenred payment mean for the 9€ (900) and the credit card for the 6€ (600)
• An authorization of 15€ (1500) will be sent back to the partner once the payment is accepted.

Case 2: Order is above the Edenred limit and includes non-eligible items

• User has an available amount to spend on his Edenred Payment mean of 11.30€
• User orders on the partner platform the following basket
     o Family box : 35,00€
• Partner applies a fee of 3,00€ on this basket
     o Delivery fee: 2,00€
     o Service fee: 1,00€

• Partner will allocate the amount as follow in the transaction request
     o ‘amount’ = 3500
     o ‘ineligible_amount’ = 300, to handle
              Delivery fee = 200
              Service fee = 100

• Edenred will charge the Edenred payment mean for the 11.30€ and the credit card for the remaining amount = 27.10€ => ((35€-11.3€)+3€)
• An authorization of 38€ (3800) will be sent back to the partner once the payment is accepted.

Case 3: Order is below the Edenred limit and includes non-eligible items

• User has an available amount to spend on his Edenred Payment mean of 11.30€
• User orders on the partner platform the following basket
     o Frozen Yogourt : 4,00€
• Partner applies a fee of 2,00€ on this basket
     o Delivery fee: 2,00€

• Partner will allocate the amount as follow in the transaction request
     o ‘amount’ = 400
     o ‘ineligible_amount’ = 200, to handle
              Delivery fee = 200

• Edenred will charge the credit card for the full amount = 600€ => (4€+2€)
• An authorization of 6€ (600) will be sent back to the partner once the payment is accepted.

Case 4: Order is within the Edenred limit, includes non-eligible items but user balance is null

• User has an available amount to spend on his Edenred Payment mean of 0€
• User orders on the partner platform the following basket
     o Pizza : 10,00€
• Partner applies a fee of 2,00€ on this basket
     o Delivery fee: 2,00€

• Partner will allocate the amount as follow in the transaction request
     o ‘amount’ = 1000
     o ‘ineligible_amount’ = 200, to handle
              Delivery fee = 200

• Edenred will charge the credit card for the full amount = 1200€ => (10€+2€)
• An authorization of 12€ (1200) will be sent back to the partner once the payment is accepted.

Capture Mode: Manual

Note: In this capture mode, the partner must capture/cancel all the authorization request accepted by Edenred

Step 1: Authorize a payment

An authorization can be requested with an amount, which is the amount that is eligible to Edenred product.

In capture mode = manual, you must set the capture mode in the body of the request to "manual".

The authorization header should be set for this operation.

The field `tstamp` MUST be set in order to manage idempotency

Request:

 POST {host}/v2/transactions?product_class={product_class} HTTP/1.1
 Host: {payment-url}
 Authorization: Bearer {access_token}
 X-Client-Id: {payment-clientId}
 X-Client-Secret: {payment-clientSecret}
 product_class: MAIN (for Lounari product)
 Content-Type: application/json

{
  "mid": "{{mid}}",
  "order_ref": "Test020522-3",
  "amount": 1000,
  "ineligible_amount": 200,
  "capture_mode": "manual",
  "tstamp": "2022-05-02T02:33:09Z"
}

Response:

{
    "meta": {
        "status": "succeeded",
        "messages": []
    },
    "data": {
        "order_ref": "Test020522-3",
        "mid": "41T929990200",
        "authorization_id": "MTY1MTQ1ODc4OTQxVDkyOTk5MDIwMD-737239",
        "authorized_amount": 1200,
        "status": "authorized"
    }
}

Step 2: Capture OR Cancel a payment

An "authorized" payment can be cancelled or captured.

The authorization_id provided by Edenred in the authorization response during the authorization process must be provided in this request.

The authorized_amount must be provided in the body of the request. The captured amount can be lower or equal to the authorized amount.

The authorization header must be set for the two operations cancel and capture.

Capture Request:

 POST [host}/v2/transactions/{authorization_id}/actions/cancel?product_class={product_class} HTTP/1.1
 Host: {payment-url}
 X-Client-Id: {payment-clientId}
 X-Client-Secret: {payment-clientSecret}
 product_class: MAIN (for Lounari product)

Content-Type: application/json
 {
   "amount": 1000,
   "ineligible_amount": 200,
   "currency": "EUR",
   "tstamp": "2022-05-02T02:34:09Z"
 }

Capture Response:

{
    "meta": {
        "status": "succeeded",
        "messages": []
    },
    "data": {
        "capture_id": "MTY1MTQ4Mzc2NTQxVDkyOTk5MDIwMD-256671",
        "captured_amount": 1200,
        "status": "captured"
    }
}

Our APIs handles the partial Capture of an authorization with the following use case in the capture request sent by the partner

1. Captured amount = Authorized “amount” AND Captured “ineligible amount” = Authorized “ineligible amount”
2. Captured amount = Authorized “amount” AND Captured “ineligible amount” < Authorized “ineligible amount”
3. Captured amount < Authorized “amount” AND Captured “ineligible amount” = Authorized “ineligible amount”
4. Captured amount < Authorized “amount” AND Captured “ineligible amount” < Authorized “ineligible amount”
5. Captured amount < Authorized “amount” AND Captured “ineligible amount” > Authorized “ineligible amount”

Our APIs DOES NOT handle the following use cases in the capture request sent by the partner

1. Captured amount > Authorized “amount” AND Captured “ineligible amount” = Authorized “ineligible amount”
2. Captured amount = Authorized “amount” AND Captured “ineligible amount” > Authorized “ineligible amount”
3. Captured amount > Authorized “amount” AND Captured “ineligible amount” > Authorized “ineligible amount”
4. Captured amount = 0€ AND Captured “ineligible amount” = Authorized “ineligible amount”
5. Captured amount = 0€ AND Captured “ineligible amount” < Authorized “ineligible amount”
6. Captured amount = 0€ AND Captured “ineligible amount” > Authorized “ineligible amount”

Note: if the “capture_amount” is below the “authorized amount”, the original transaction (pending in “authorized” status) is automatically canceled and a new transaction is created (for the requested captured_amount) and automatically captured for that amount

In this case a new authorization ID is provided in the response and must be stored by the partner (to request a refund later on for example)

Alternative 2: Cancel the pending authorization

The full amount authorized should be provided in the “amount” of the Cancel request. Edenred handles the full cancellation of the authorization pending on the Edenred authorization platform and on the credit card of the user

Cancel Request:

     POST [host}/v2/transactions/{authorization_id}/actions/cancel?product_class={product_class} HTTP/1.1
 Host: {payment-url}
 X-Client-Id: {payment-clientId}
 X-Client-Secret: {payment-clientSecret}
 product_class: MAIN (for Lounari product)
 Content-Type: application/json

{
   "amount": 1200,
   "currency": "EUR",
   "tstamp": "2020-05-26T19:45:51Z"
 }

Cancel Response:

    {
    "meta": {
        "status": "succeeded"
    },
    "data": {
        "status": "cancelled",
        "cancel_id": "MTU5MTgwMDMxMzU0MjM5NDUxMjI0M",
        "cancelled_amount": 1200
    }
}

Note : after 7 days, a pending authorization – not authorized or canceled by the partner, will be automatically EXPIRED by the authorization platform (reserved funds will be put back on the user account)

Step 3: Refund a captured payment

Once captured, a transaction can't be cancelled but have to be refunded.

The authorization_id provided during the authorization process must be provided in this request.

The exact captured_amount must be provided in the body of the request. The refund can't be partial.

The authorization header should not be set for this operation.

The capture_mode is mandatory in case of dual messaging (Authorize + Capture).

The capture_mode must be set to ‘manual’ in this case ("capture_mode": "manual",)

The field tstamp MUST be set in order to manage idempotency

Refund Request:

 POST {host}/v2/transactions/{authorization_id}/actions/refund?product_class={product_class} HTTP/1.1
 Host: {payment-url}
 X-Client-Id: {payment-clientId}
 X-Client-Secret: {payment-clientSecret}
 Content-Type: application/json
 product_class: MAIN (for Lounari product)
 {
    "amount": 1200,
    "currency": "EUR",
    "capture_mode": "manual",
    "tstamp": "2022-05-06T12:17:53Z"
 }

Refund Response:

{
    "meta": {
        "status": "succeeded",
        "messages": []
    },
    "data": {
        "mid": "41T929990200",
        "refund_id": "MTY1MTQ4NDM2MDQxVDkyOTk5MDIwMD-256671",
        "refunded_amount": 1200,
        "status": "refunded"
    }
}

Capture Mode: Auto

In the capture mode = 'auto', the default configuration allows to process complementary payment transactions.

Step 1: Auto Capture a payment

A transaction processed in "auto capture" manages both the authorization and the capture in a single call. The Partner has to provide in the field “amount”, the amount that is eligible to Edenred product and in the “ineligible amount”, the amount of the order that can’t be spent with Edenred product (delivery fee, alcohol… items that can’t be spent with the Edenred product).

A transaction processed is "authorization + auto capture" is requested with an amount, which is the amount that is eligible to Edenred product. And an ineligible amount for the amount of an order that can’t be spent with Edenred product.

In capture mode = auto, the capture mode is not mandatory in the body of the request. This is default capture mode of the API.

The authorization header should be set for this operation.

The field `tstamp` MUST be set in order to manage idempotency

Request:

 POST {host}/v2/transactions?product_class={product_class} HTTP/1.1
 Host: {payment-url}
 Authorization: Bearer {token}
 X-Client-Id: {payment-clientId}
 X-Client-Secret: {payment-clientSecret}
 product_class: MAIN (for Lounari product)
 Content-Type: application/json

 {
  "mid": "5423945122",
  "amount": 3000,
  “ineligible_amount”: 200,
  "security_level": "standard",
  "capture_mode": "auto",
  "order_ref": "419134",
  "tstamp": "2021-05-27T08:53:20Z"
  "currency": "EUR"
 }

Response:

    "meta": {
        "status": "succeeded"
    },
    "data": {
        "order_ref": "419134",
        "mid": "5423945122",
        "status": "captured",
        "authorization_id": "MTU5MDU1ODg2MDU0MjM5NDUxMjI0M-127298",
        "authorized_amount": 3200,
        "capture_id": "MTU5MDU1ODg2MDU0MjM5NDUxMjI0M-127298",
        "captured_amount": 3200
    }
}

Step 2: Refund a captured payment

In this capture mode scenario the "Cancel" and "Capture" are not used.

Once captured, a transaction can be only refunded.

The authorization_id provided during the authorization/capture process must be provided in this request with the exact amount provided in "captured_amount"*.

The authorization header should not be set for this operation.

The field `tstamp` MUST be set in order to manage idempotency

*Note: a request with an amount different from the captured amount will be declined with the reason “ORIGIN_TRANSACTION_ID_NOT_FOUND”. We can’t process to a partial refund of the captured transaction

Refund Request:

 POST {host}/v2/transactions/{authorization_id}/actions/refund?product_class={product_class} HTTP/1.1
 Host: {product_class}
 X-Client-Id: {payment-clientId}
 X-Client-Secret: {payment-clientSecret}
 product_class=MAIN
 Content-Type: application/json

 {
   "amount": 3200,
   "currency": "EUR",
   "tstamp": "2021-05-27T08:54:20Z"
 }

Refund Response:

 {
    "meta": {
        "status": "succeeded"
    },
    "data": {
        "mid": "5423945122",
        "status": "refunded",
        "refund_id": "MTU5MDU1ODg2MDU0MjM5NDUxMjI0M-127298",
        "refunded_amount": 3200,
    }
}

4. Error Codes