Edenred Direct Payment Services

1. Generalities

In Greece, with the Ticket Restaurant Card, a user can spend the amount requested without any limitation (in the limit of the balance available on his account), i.e. balance can’t be negative.

The regulation(s) are handled on the Edenred side. Please note that all amounts in our API are given in cents (example: 9€ = 900).

{{Authentication URL}} = https://sso.sbx.edenred.io

{{payment URL}} = https://directpayment.stg.eu.edenred.io/v2

2. User Security Tokens

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

The following flow is the only authentication flow supported for security reasons (no authentication flow is available per API for example)

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=7deea1a069ed44f98dd97634e286f443&scope=openid%20edg-xp-mealdelivery-api%20offline_access&redirect_uri=http://nowhere.edenred.net/oauth/callback&state=d710ce14-ace6-4300-8e58-5877e7b92500&nonce=11df89b0-4bde-4696-a00ed04cf06b9ab2&acr_values=tenant:gr-ben&ui_locales=el

Example of account that can be used to test the API:

  Username: edps.ergruat2@gmail.com
  Password: Edenred2020*
  CVV: 9856

####

2) After login and consent granted by the user, we will redirect the user to a url you have provided us like :

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

This URL must be whilested on our side to be used. We can whitelist several on demand.

3) During the redirection process, we send you back the authorization code. Copy the authorization_code and use the request "Get access_token from authorization_code" in the following collection of API calls :

Please note that an authorization_code is burned every time you try to use it. If your API call fails, you must get a new authorization_code.

2.2. Logout Process

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

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

Where

'authentication-URL' = sso.sbx.edenred.io

And idToken is retrieved from the refreshing token response

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

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

3. Direct Payment API

3.1. Postman Collection

If you use the postman collection, the access_token will automatically be placed in your HTTP Authorization header after Get Token from authorization code request is sent.

3.2. User Balance

Get Balance

Gets the available amount that can be spent on the user's account.

The authorization header is mandatory for this request.

Note: The {Username} is retrieved by introspection of the token-id

Request:

 GET {{payment URL}}/users/{username}/balances HTTP/1.1
 Host: {{payment URL}}
 Authorization: Bearer {token}
 X-Client-Id: {payment-clientId}
 X-Client-Secret: {payment-clientSecret}

Response:

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

Estimate Charge

Check if an amount can be spent and answer the exact amount that could be spent (if the balance is below the requested amount).

The authorization header is mandatory for this request.

Note: The {Username} is retrieved by introspection of the token-id

Request:

 POST {{payment URL}}/users/{username}/actions/estimate-charge HTTP/1.1
 Host: {{payment URL}}
 Authorization: Bearer {token}
 X-Client-Id: {payment-clientId}
 X-Client-Secret: {payment-clientSecret}
 Content-Type: application/json
 {
   "amount": 1
 }

Response:

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

3.3. User Transactions

EDPS manages two kinds of transaction mode, auto and manual. The postman collection provided is set up in capture mode auto. If you want to test an environment in capture mode manual, please request a dedicated environment.

In the next sections, we will explain the difference between those two modes.

Capture Mode: Manual

Step 1: Authorize a payment

An authorization is requested with an amount.

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 {{payment URL}}/transactions HTTP/1.1
 Host: {{payment URL}}
 Authorization: Bearer {token}
 X-Client-Id: {payment-clientId}
 X-Client-Secret: {payment-clientSecret}
 Content-Type: application/json

 {
    "mid": "5423945122",
    "amount": 1,
    "security_level": "standard",
    "capture_mode": "manual",
    "order_ref": "785420",
    "tstamp": "2020-05-26T19:45:51Z",
    "currency": "EUR"
}

Response:

{
    "meta": {
        "status": "succeeded"
    },
    "data": {
        "order_ref": "679089",
        "mid": "5423945122",
        "status": "authorized",
        "authorization_id": "MTU5MjMxMzkzNzU0MjM5NDUxMjI0M-031407",
        "authorized_amount": 1
    }
}

Step 2: Cancel OR Capture a payment

An "authorized" payment can be cancelled or captured.

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

The authorized_amount must be provided in the body of the request.

The canceled amount must be equal to the authorized amount

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.

Cancel Request:

 POST {{payment URL}}/transactions/{authorization_id}/actions/cancel HTTP/1.1
 Host: {{payment URL}}
 X-Client-Id: {payment-clientId}
 X-Client-Secret: {payment-clientSecret}
 Content-Type: application/json
 {
   "amount": 1,
   "currency": "EUR",
   "tstamp": "2020-05-26T19:45:51Z"
 }

Cancel Response:

{
    "meta": {
        "status": "succeeded"
    },
    "data": {
        "mid": "5423945122",
        "status": "cancelled",
        "cancel_id": "MTU5MTgwMDMxMzU0MjM5NDUxMjI0M",
        "cancelled_amount": 1,
        "order_ref": "679089",
        "authorization_id": "MTU5MjMxMzkzNzU0MjM5NDUxMjI0M-031407",
        "authorized_amount": 1
    }
}

OR

Capture Request:

 POST {{payment URL}}/transactions/{authorization_id}/actions/capture HTTP/1.1
 Host: {{payment URL}}
 X-Client-Id: {payment-clientId}
 X-Client-Secret: {payment-clientSecret}
 Content-Type: application/json
 {
   "amount": 1,
   "currency": "EUR",
   "tstamp": "2020-05-26T19:45:51Z"
 }

Capture Response:

{
  "meta": {
     "status": "succeeded",
     "messages": []
  },
  "data": {
      "order_ref": "889180",
      "mid": "5423945122",
      "capture_id": "MTU5MjMxNDAyMTU0MjM5NDUxMjI0M-110983",
      "capture_amount": 1,
      "status": "captured",
      "authorization_id": "MTU5MjMxNDAyMTU0MjM5NDUxMjI0M-110983",
      "authorized_amount": 1
    }
}

Step 3: Refund a captured payment

Once captured, a transaction can't be cancelled, it can be only refunded.

We support both the partial refund OR the refund of the full amount of the captured transaction. The query param "partial" must be provided in the refund request to manage a partial refund.

The authorization_id provided during the authorization/capture process must be provided in this request with the amount to refund

• "captured_amount" in case of full refund request
• "amount" (below the "captured_amount") in case of partial refund request

The authorization header should not be set for this operation.

The field tstamp MUST be set in order to manage idempotency

Full Refund

Request:

POST {{payment-url}}/transactions/{{authorization_id}}/actions/refund
Host: {{payment-url}}
X-Client-Id: {payment-clientId}
X-Client-Secret: {payment-clientSecret}
Content-Type: application/json

{
  "amount": 1,
  "capture_mode": "manual",
  "currency": "EUR",
  "tstamp": "2020-05-27T08:54:20Z"
}

Response:

{
  "meta": {
"status": "succeeded"

},
  "data": {
      "mid": "5423945122",
      "status": "refunded",
      "refund_id": "MTU5MDU1ODg2MDU0MjM5NDUxMjI0M",
      "refunded_amount": 1,
    }
}

Partial Refund

Request:

POST {{payment-url}}/transactions/{{authorization_id}}/actions/**refund?type=partial**
Host: {{payment-url}}
X-Client-Id: {payment-clientId}
X-Client-Secret: {payment-clientSecret}
Content-Type: application/json

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

Response:

{
  "meta": {
"status": "succeeded"

},
  "data": {
      "mid": "5423945122",
      "status": "refunded",
      "refund_id": "MTU5MDU1ODg2MDU0MjM5NDUxMjI0M",
      "refunded_amount": 1,
    }
}

Capture Mode: Auto

Step 1: Auto Capture a payment

An transaction processed is "authorization + auto capture" is requested with an amount.

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 {{payment URL}}/transactions HTTP/1.1
 Host: {{payment URL}}
 Authorization: Bearer {token}
 X-Client-Id: {payment-clientId}
 X-Client-Secret: {payment-clientSecret}
 Content-Type: application/json
 {

       "mid": "5423945122",
       "amount": 1,
       "security_level": "standard",
       "capture_mode": "auto",
       "order_ref": "419134",
       "tstamp": "2020-05-27T08:53:20Z"
       "currency": "EUR"

 }

Response:

{
  "meta": {
     "status": "succeeded",
     "messages": []
  },
  "data": {
      "order_ref": "5423945122",
      "mid": "419134",
      "capture_id": "MTU5MDU1ODg2MDU0MjM5NDUxMjI0M-127298",
      "capture_amount": 1,
      "status": "captured",
      "authorization_id": "MTU5MDU1ODg2MDU0MjM5NDUxMjI0M-127298",
      "authorized_amount": 1
    }
}

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.

We support both the partial refund OR the refund of the full amount of the captured transaction. The query param "partial" must be provided in the refund request to manage a partial refund.

The authorization_id provided during the authorization/capture process must be provided in this request with the amount to refund

• "captured_amount" in case of full refund request
• "amount" (below the "captured_amount") in case of partial refund request

The authorization header should not be set for this operation.

The field tstamp MUST be set in order to manage idempotency

Full Refund

Request:

POST {{payment-url}}/transactions/{{authorization_id}}/actions/refund
Host: {{payment-url}}
X-Client-Id: {payment-clientId}
X-Client-Secret: {payment-clientSecret}
Content-Type: application/json

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

Response:

{
  "meta": {
"status": "succeeded"

},
  "data": {
      "mid": "5423945122",
      "status": "refunded",
      "refund_id": "MTU5MDU1ODg2MDU0MjM5NDUxMjI0M",
      "refunded_amount": 1,
    }
}

Partial Refund

Request:

POST {{payment-url}}/transactions/{{authorization_id}}/actions/**refund?type=partial**
Host: {{payment-url}}
X-Client-Id: {payment-clientId}
X-Client-Secret: {payment-clientSecret}
Content-Type: application/json

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

Response:

{
  "meta": {
"status": "succeeded"

},
  "data": {
      "mid": "5423945122",
      "status": "refunded",
      "refund_id": "MTU5MDU1ODg2MDU0MjM5NDUxMjI0M",
      "refunded_amount": 1,
    }
}

4. Error Codes