The Ezypay API uses OAuth 2.0 to authenticate and authorise API calls. Authentication requires both partner and merchant credentials to generate a bearer token, which authorises API calls on behalf of a specific merchant.

• Partner credentials: Each partner has unique credentials allowing access to all merchants associated with them.
• Merchant credentials: Each merchant has unique credentials granting access only to their own data. API calls are made by the partner platform on the merchant’s behalf using both sets of credentials.

The credentials are shared after successfully onboarding with Ezypay. Store them in your database and reuse it for authentication.

Get started

1. To obtain an access token, use the following cURL command. Replace placeholders with actual credentials:

curl -X POST \
  https://identity-sandbox.ezypay.com/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=password&username={{username}}&password={{password}}&client_id={{client_id}}&client_secret={{client_secret}}&scope=integrator%20billing_profile%20create_payment_method%20offline_access'

2. After a successful request, capture the access_token from the response. This token authorises API requests. Add Authorization: Bearer {{accessToken}} in the header of each API call.

{
    "token_type": "Bearer",
    "expires_in": 3600,
    "access_token": "{{accessToken}}",
    "scope": "integrator offline_access billing_profile create_payment_method",
    "refresh_token": "{{refreshToken}}"
}

🚧

Attention

Tokens expire after 60 minutes, so you’ll need to regenerate them periodically.

3. Refresh access token. When the access token expires, use the refresh_token from the previous response to obtain a new one. The refresh token is valid for 7 days.

curl -X POST \
  https://identity-sandbox.ezypay.com/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=refresh_token&client_id={clientId}&client_secret={clientSecret}&refresh_token={refreshToken}'

🚧

Attention

Instead of refreshing an expired refresh token, you may start again from Step 1 to generate a new access token when it expired.

Best practice

Reusing authentication token

Integrators should always reuse the access token until it expires, rather than requesting a new token before every API call. To protect against potential DDoS attacks, Ezypay enforces a rate limit of 5,000 token requests per 5 minutes. Exceeding this limit will result in a 429 too Many Requests error and request may be temporarily blocked.

Merchant credentials form

Typically, merchant credentials are manually entered into a database or configuration file by developers, which poses a confidentiality risk during the process. To address this, the partner platform should provide a secure interface within the merchant portal, enabling merchants to independently input their username, password, and merchant ID.

This approach allows merchants to activate the Ezypay integration directly through the platform, ensuring the confidentiality and security of their credentials while eliminating the need for manual handling by developers.

📘

Additional Readings

A good primer for OAuth 2 can be found here:

https://developer.okta.com/blog/2017/06/21/what-the-heck-is-oauth