Common steps¶

This section describes steps which are common to both, the Payment Web Application and Direct integration approach.

Authentication and authorization¶

Please refer to the Security section for a generic description of how the token can be obtained.

The fine-grained privileges must be used for Payment Web Application or the Direct integration so that token cannot be misused by the customer.

The following operations must be authorized.

The {idPayin} must be replaced with an actual unique Merchant Order ID generated by merchant.

Example CURL for generating auth token¶

curl -X POST 'https://api.sandbox.echelonpay.com/auth-tokens' \
     -H 'Accept: application/json' \
     -H 'Content-Type: application/json' \
     -H 'X-API-Version: 2' \
     -d '{
           "merchantCode": "YOUR_MERCHANT_ID",
           "secret": "YOUR_MERCHANT_SECRET_KEY",
           "validitySecs": 600,
           "operations": [
             "POST /payins/!availablePaymentOptions",
             "GET /merchant-info",
             "POST /payins/TST-112233",
             "GET /payins/TST-112233",
             "POST /payins/TST-112233/!setExternalReference"
           ]
         }'

Response of this example call¶

{
  "token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJvcGVyYXRpb25zIjpbIlBPU1QgL3BheWlucy8hYXZhaWxhYmxlUGF5bWVudE1ldGhvZHMiLCJQT1NUIC9wYXlpbnMvVFNULTExMjIzMyIsIkdFVCAvcGF5aW5zL1RTVC0xMTIyMzMiXSwiZXhwIjoxNjIyNjIzNjY5LCJqdGkiOiI5ZThhNDUwNC04MmRmLTQyY2QtOTQ3Ni03NjE2YjEzOTJlM2IiLCJpYXQiOjE2MjI2MjMwNjksInN1YiI6IllPVVJfTUVSQ0hBTlRfQ09ERSJ9.LkYT9qXY3hEixjoiUBKqxXnazWgfLCNg37RtdG_oXw0"
}

Token can be decoded as it is JWT to:

Decoded token¶

{
  "operations": [
    "POST /payins/!availablePaymentOptions",
    "POST /payins/TST-112233",
    "GET /payins/TST-112233"
  ],
  "exp": 1622623669,
  "jti": "9e8a4504-82df-42cd-9476-7616b1392e3b",
  "iat": 1622623069,
  "sub": "YOUR_MERCHANT_ID"
}

Callback¶

After the payment is processed, a callback is sent to given callback URL. The callback structure is described in the callback section of POST /payins/{idPayin} endpoint. For more info about callbacks concepts, see the Callbacks section of this documentation.

Payment status check¶

To proactively check the incoming payment status use GET /payins/{idPayin} endpoint.

Example CURL for requesting payment detail:

Get status of payment with ID TST_112233¶

curl -X GET 'https://api.sandbox.echelonpay.com/payins/TST-112233' \
     -H 'Accept: application/json' \
     -H 'X-API-Version: 2' \
     -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJvcGVyYXRpb25zIjpbIlBPU1QgL3BheWlucy8hYXZhaWxhYmxlUGF5bWVudE1ldGhvZHMiLCJQT1NUIC9wYXlpbnMvVFNULTExMjIzMyIsIkdFVCAvcGF5aW5zL1RTVC0xMTIyMzMiXSwiZXhwIjoxNjIyNjIzNjY5LCJqdGkiOiI5ZThhNDUwNC04MmRmLTQyY2QtOTQ3Ni03NjE2YjEzOTJlM2IiLCJpYXQiOjE2MjI2MjMwNjksInN1YiI6IllPVVJfTUVSQ0hBTlRfQ09ERSJ9.LkYT9qXY3hEixjoiUBKqxXnazWgfLCNg37RtdG_oXw0'

Response of the example call¶

{
  "paymentRequested": {
    "money": {
      "amount": 42.05,
      "currencyCode": "USD"
    }
  },
  "process": {
    "status": "SUCCESS",
    "createdAt": "2021-05-19T10:57:28.313Z",
    "processedAt": "2021-05-19T10:58:28.313Z",
    "isTest": false
  },
  "fee": {
    "amount": 0.1,
    "currencyCode": "USD"
  },
  "paymentMethodResponse": {
    "idPayin": "TST-112233",
    "paymentMethodCode": "OFFLINE",
    "account": {
      "bankName": "Some real bank name",
      "branchName": "Some real bank branch name"
    },
    "money": {
      "amount": 42.05,
      "currencyCode": "USD"
    },
    "expireAt": "2021-05-19T12:57:28.313Z",
    "reference": "VA112233",
    "returnUrl": "https://example.com?id=123"
  }
}

Payment account check¶

To proactively check the incoming payment customer account data use GET /payins/{idPayin}/accounts endpoint.

Example CURL for requesting payment account detail:

Get account data of payment with ID TST_112233¶

curl -X GET 'https://api.sandbox.echelonpay.com/payins/TST-112233/accounts' \
-H 'Accept: application/json' \
-H 'X-API-Version: 2' \
-H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJvcGVyYXRpb25zIjpbIkdFVCAvcGF5aW5zL1RTVC0xMTIyMzMvYWNjb3VudHMiXSwiZXhwIjoxNjIyNjIzNjY5LCJqdGkiOiI5ZThhNDUwNC04MmRmLTQyY2QtOTQ3Ni03NjE2YjEzOTJlM2IiLCJpYXQiOjE2MjI2MjMwNjksInN1YiI6IllPVVJfTUVSQ0hBTlRfQ09ERSJ9.Mbk75tcMqx8Jw8HGDtARK1hhUUtk_J71sU8MVD0o1CU'