Edenred Direct Payment Services

1. Generalities

In Belgium, a user can spend the exact amount requested without any limitation (apart from the balance available on his account), i.e. balance can’t be negative.

These regulations are handled on the Edenred side.

Please note that all amounts in our API are given in cents 9€ = 900

2. User Security Tokens

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

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=6999151c1ff6462192a092f05fb2eed3&scope=openid%20edg-xp-mealdelivery-api%20offline_access&redirect_uri=http://nowhere.edenred.net/oauth-callback&state=abc123&nonce=456azerty&acr_values=tenant:be-ben-sa&ui_locales=en

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

Account: uat1c@vva.net
Password: Secret123
Masked PAN: 7628

2) After login, you'll be redirected to a url like :

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

3) 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 /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.

The postman configuration available here is set in auto-clearing mode => cancel and capture routes are not available but put as examples.

Notes: You can request an access to our UAT environment in manual-clearing mode if you choose to implement the payment with Edenred this way.

3.2. User Balance

Get Balance per product

Gets the available user balance for the wallet enabled.

To request the balance of one the various wallets enabled on the account (and upon your configuration), you have to pass a query parameter in the request

• Ticket Restaurant: ETR (default value used if no query parameter provided in the request)
• Ticket Compliment : ETC
• Ticket Ecochèque : EEC
• Ticket Sport: ESC
• Consumption Voucher: CVE

The Authorization header is mandatory for this request.

Request:

GET /v2/users/{username}/balances HTTP/1.1
Query parameter: ETR
Host: directpayment.stg.eu.edenred.io
 Authorization: Bearer {token}
 X-Client-Id: {payment-clientId}
 X-Client-Secret: {payment-clientSecret}

Response:

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

###

Get Balances of all products

Gets the available user balances for the wallet enabled.

To request the balances of all the products enabled on the account (and upon your configuration).

Request:

 GET /v2/users/{username}/balances HTTP/1.1
 Host: directpayment.stg.eu.edenred.io
 Authorization: Bearer {token}
 X-Client-Id: {payment-clientId}
 X-Client-Secret: {payment-clientSecret}

Response:

{
  "meta": {
    "status": "succeeded",
    "messages": []
  },
    "data": [
        {
            "product_class": "CVE",
            "available_amount": 0,
            "currency": "EUR"
        },
        {
            "product_class": "EEC",
            "available_amount": 99991,
            "currency": "EUR"
        },
        {
            "product_class": "ETC",
            "available_amount": 159798,
            "currency": "EUR"
        },
        {
            "product_class": "ETR",
            "available_amount": 12033,
            "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 in the response.

To request the balance of one the various wallets enabled on the account (and upon your configuration), you have to pass a query parameter in the request.

The Authorization header is mandatory for this request.

Request:

 POST /v2/users/{username}/actions/estimate-charge HTTP/1.1
 Host: directpayment.stg.eu.edenred.io
 Query parameter: ETR
 Authorization: Bearer {token}
 X-Client-Id: {payment-clientId}
 X-Client-Secret: {payment-clientSecret}
 Content-Type: application/json
 {
   "amount": 1900
 }

Response:

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

3.3. User Transactions

Capture Mode: Manual

Step 1: Authorize a payment

An authorization is requested with an amount in cents of Euros (10€ = 1000).

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

To request a transaction of a specific wallet enabled on the card (and upon your configuration), you have to pass a query parameter in the request

• Ticket Restaurant: ETR (default value used if no query parameter provided in the request)
• Ticket Compliment : ETC
• Ticket Ecochèque : EEC
• Ticket Sport: ESC
• Consumption Voucher: CVE

The authorization header should be set for this operation.

The field tstamp MUST be set in order to manage idempotency

Request:

 POST /v2/transactions HTTP/1.1
 Host: directpayment.stg.eu.edenred.io
 Authorization: Bearer {token}
 X-Client-Id: {payment-clientId}
 X-Client-Secret: {payment-clientSecret}
 Content-Type: application/json

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

Response:

{
    "meta": {
        "status": "succeeded"
    },
    "data": {
        "order_ref": "30192",
        "mid": "203696",
        "status": "authorized",
        "authorization_id": "MTU5MjIxOTg1ODIwMzY5NjYzMDEwM-780920",
        "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 or 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 /v2/transactions/{authorization_id}/actions/cancel HTTP/1.1
 Host: directpayment.stg.eu.edenred.io
 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": "203696",
        "status": "cancelled",
        "cancel_id": "MTU5MjIxOTg1ODIwMzY5NjYzMDEwM",
        "cancelled_amount": 1,
        "order_ref": "30192",
        "authorization_id": "MTU5MjIxOTg1ODIwMzY5NjYzMDEwM-780920",
        "authorized_amount": 1
    }
}

OR

Capture Request:

 POST /v2/transactions/{authorization_id}/actions/capture HTTP/1.1
 Host: directpayment.stg.eu.edenred.io
 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"
    },
    "data": {
        "order_ref": "30192",
        "mid": "203696",
        "status": "captured",
        "capture_id": "MTU5MjIyODQyMzIwMzY5NjYzMDEwM-756374",
        "capture_amount": 1,
        "authorization_id": "MTU5MjIyODQyMzIwMzY5NjYzMDEwM-756374",
        "authorized_amount": 1
    }
}

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 (and its value is manual) in case of dual messaging (Authorize + Capture).

The field tstamp MUST be set in order to manage idempotency

Refund Request:

 POST /v2/transactions/{authorization_id}/actions/refund HTTP/1.1
 Host: directpayment.stg.eu.edenred.io
 X-Client-Id: {payment-clientId}
 X-Client-Secret: {payment-clientSecret}
 Content-Type: application/json
 {
    "amount": 1,
    "currency": "EUR",
    "tstamp": "2019-05-26T12:17:53Z",
    "capture_mode": "manual"
 }

Refund Response:

{
    "meta": {
        "status": "succeeded"
    },
    "data": {
        "mid": "203696",
        "status": "refunded",
        "refund_id": "MTU5MjIyMDE4MjIwMzY5NjYzMDEwM-014300",
        "refunded_amount": 1,
        "order_ref": "30192",
        "capture_id": "MTU5MjIzMjU2NTIwMzY5NjYzMDEwM-014300",
        "capture_amount": 1,
        "authorization_id": "MTU5MjIzMjU2NTIwMzY5NjYzMDEwM-014300",
        "authorized_amount": 1
    }
}

Capture Mode: Auto

Step 1: Auto Capture a payment

An authorization with auto capture can be requested with an amount in cents of Euros (10€ = 1000).

To request a transaction of a specific wallet enabled on the card (and upon your configuration), you have to pass a query parameter in the request

• Ticket Restaurant: ETR (default value used if no query parameter provided in the request)
• Ticket Compliment : ETC
• Ticket Ecochèque : EEC
• Ticket Sport: ESC
• Consumption Voucher: CVE

The authorization header should be set for this operation.

The field tstamp MUST be set in order to manage idempotency

Request:

 POST /v2/transactions HTTP/1.1
 Host: directpayment.stg.eu.edenred.io
 Authorization: Bearer {token}
 X-Client-Id: {payment-clientId}
 X-Client-Secret: {payment-clientSecret}
 Content-Type: application/json
 {
  "order_ref": "51195",
  "mid": "203696",
  "amount": 1,
  "currency": "EUR",
  "capture_mode": "auto",
  "extra_field": "51195",
  "tstamp": "2019-05-23T14:02:50Z",
  "security_level": "standard"
 }

Response:

{
    "meta": {
        "status": "succeeded"
    },
    "data": {
        "order_ref": "51195",
        "mid": "203696",
        "status": "captured",
        "authorization_id": "MTU5MjIzNDk0MTIwMzY5NjYzMDEwM-519587",
        "authorized_amount": 1,
        "capture_id": "MTU5MjIzNDk0MTIwMzY5NjYzMDEwM-519587",
        "captured_amount": 1
    }
}

Step 2: Refund a captured payment

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

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

The authorization header should not be set for this operation.

The field tstamp MUST be set in order to manage idempotency

Refund Request:

 POST /v2/transactions/{authorization_id}/actions/refund HTTP/1.1
 Host: directpayment.stg.eu.edenred.io
 X-Client-Id: {payment-clientId}
 X-Client-Secret: {payment-clientSecret}
 Content-Type: application/json
 {
   "amount": 1,
   "currency": "EUR",
   "tstamp": "2019-05-23T14:02:50Z"
 }

Refund Response:

 {
    "meta": {
        "status": "succeeded"
    },
    "data": {
        "mid": "203696",
        "status": "refunded",
        "refund_id": "MTU5MjIzNDk0MTIwMzY5NjYzMDEwM",
        "refunded_amount": 1,
        "order_ref": "51195",
        "authorization_id": "MTU5MjIzNDg5MTIwMzY5NjYzMDEwM-297895",
        "authorized_amount": 1,
        "capture_id": "MTU5MjIzNDg5MTIwMzY5NjYzMDEwM-297895",
        "captured_amount": 1
    }
}

4. Error Codes