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

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