General concepts¶

Learn our general concepts and principles all our APIs has common.

Security¶

Every API request is secured with auth token, which is transported in HTTP authorization header (Authorization: Bearer <token>).

To generate auth token use POST /auth-tokens-by-action API.

Prerequisites for generating auth token are:

merchantCode - This code is obtained during the merchant Merchant enrollment process as your Merchant ID.
secret - This is Merchant Secret key obtained upon merchant Merchant enrollment process. This must be kept secure and cannot be shared in publicly accessible areas such as GitHub, client-side code, and so forth.

Auth token can carry various privileges and when limited to a specific payment id, it can be shared with client side code such as web applications.

Auth token uses JWT so it can be easily decoded to verify its content by pasting the token on the mentioned page.

Basic usage¶

The POST /auth-tokens-by-action endpoint accepts action and idPayment attributes to restrict the privileges of the token holder. Optionally money attribute can be used to create a token for payment limited only to specified amount and currency.

Here is an example of generating an auth token for creating payment with platform web application:

Create auth token¶

curl -X POST 'https://api.sandbox.echelonpay.com/auth-tokens-by-action' \
-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,
"action": "PAYIN_CREATE",
"idPayment": "TST-112233",
"money": {
"currencyCode": "INR",
"amount": 5000
}
}'

The generated token can be used to create payin with the specified id TST-112233 by allowing these endpoints:

POST /payins/!availablePaymentOptions for ability to the choose payment method / operator by user
POST /payins/TST-112233 for the ability to create specific payment with Merchant Order ID TST-112233
GET /payins/TST-112233 for the ability to get payment (but only with Merchant Order ID TST-112233) details/status

Each auth token can be generated only for desired operation. The previous example can be reduced only to:

Create auth token allowing access to details of one incoming payment only¶

curl -X POST 'https://api.sandbox.|TenantDomain|/auth-tokens-by-action' \
-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,
"action": "PAYIN_INFO",
"idPayment": "TST-112233",
}'

With this auth token only detail of incoming payment with Merchant Order ID TST-112233 can be obtained, it is safe to share this token in client side code, emails, etc.

Fine-grained privileges¶

If the above endpoint does not provide enough granularity, you can limit the access to specific URLs using POST /auth-tokens endpoint. It accepts operations attribute with URL list. Optionally money attribute can be used to create a token for payment limited only to specified amount and currency.

Values passed in operations are simply HTTP methods followed by an endpoint to which permission should be granted.

Here is an example of generating an auth token for creating payment with platform web application:

Create auth token for more operations¶

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",
             "POST /payins/TST-112233",
             "GET /payins/TST-112233"
           ],
           "money": {
             "currencyCode": "INR",
             "amount": 5000
            }
         }'

There are 3 operations allowed within this token:

POST /payins/!availablePaymentOptions for ability to the choose payment method / operator by user
POST /payins/TST-112233 for the ability to create specific payment with Merchant Order ID TST-112233
GET /payins/TST-112233 for the ability to get payment (but only with Merchant Order ID TST-112233) details/status

Each auth token can be generated only for desired operation. The previous example can be reduced only to:

Create auth token allowing access to details of one incoming payment only substitutions¶

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": [
             "GET /payins/TST-112233"
           ]
         }'

With this auth token only detail of incoming payment with Merchant Order ID TST-112233 can be obtained, it is safe to share this token in client side code, emails, etc.

General privileges¶

As the operations format supports regular expressions, a more general token can be created to e.g. access/create multiple payments with a single token. For example, use POST /payins/.* operation to be able to create incoming payment with any Merchant Order ID or GET /payins/.* to access any incoming payment details/status. Tokens with general privileges are not intended to be used by client side code, emails, etc, as they are considered serious security risks.

Here is an example of generating token for checking status of all available incoming payments:

Create auth token allowing access to all payments details substitutions:¶

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": [
             "GET /payins/.*"
           ]
         }'

Versioning¶

Latest API version: 2.52

The API version provided in HTTP request controls the API and callbacks behavior you see (e.g., what properties you see in responses, what parameters you’re permitted to send in requests, etc.).

Every request must include HTTP header X-API-Version with only MAJOR version of used API. If no version or unsupported version of API is sent, HTTP 404 Not Found error will be returned. E.g. request for API in version 2.52 must include HTTP header:

X-API-Version: 2

All minor version changes are considered backward compatible (non breaking) changes to the API. With every backward incompatible (breaking) change new major version of API is released. The old version is supported for an announced period of time to enable the seamless upgrading of your system.

Non breaking changes¶

The following changes are considered as backwards compatible (non breaking) changes and thus do not change the major version of API:

Adding new API resources.
Adding new optional request parameters to existing API methods.
Adding new properties to existing API responses. You should ignore unexpected properties.
Changing the order of properties in existing API responses.
Adding new event types. Your callback listener should gracefully handle unfamiliar event types.
Adding new items to code-list endpoints, such as GET /currencies, GET /payment-operators etc.

Request IDs¶

All calls creating new payments (POST /payins/{idPayin}, POST /payouts/{idPayout}) must include an your Merchant Order ID (idPayin, idPayout) provided by your side. Consider using UUID or another random string with enough entropy to avoid collisions.

APIs for creating new entities supports idempotency to safely retry requests without accidentally performing the operation twice. If no response is received due to disrupted network connection or other reason it is safe to make the same request (with the same ID) again. If the request was already accepted by our platform, then 409 Conflict HTTP error is returned.

Callbacks¶

When a payment request is accepted by platform, a change of status of this transaction is alerted by a callback. Callbacks are anemic events that only notify about change within a given entity, but do not carry the change itself (mainly for security reasons) so as an after effect of callback the call of GET /payins/{idPayin}, GET /payouts/{idPayout} should follow to check the status.

Examples of how to check payment details are described in the section Payment status check, Payment status check.

Query for multiple values¶

If you need to use multiple values for attributes in query operations use comma (,) as the separator of these the values. If one of values is unsupported/invalid, this value is ignored.

E.g. for GET /balances for currency IDR and INR make the query as: /balances/?currencies=INR,IDR.

Throttling¶

There is a limitation of how many request can be processed with our platform. You can make up to 10 requests per second. If this limitation is exceeded 429 Too many requests HTTP error is returned and request is not processed.

Navigation

Related Topics