OAuth Ecart Pay

Table of Contents

• 🚀 Getting Started
• 🔑 How the Flow Works
• 1️⃣ Create Your Application
• 2️⃣ Redirect the Merchant to Ecart Pay
• 3️⃣ Receive the Authorization Code
• 4️⃣ Exchange the Code for the Merchant Credentials
• 🔐 Scopes
• 🔄 Updating Scopes & Re-Authorization
• 🏢 Multi-Company Applications
• 🧪 Complete Example
• 🧪 Testing
• 🚀 Going to Production
• 🧰 Error Reference
• 🔎 Resources

🚀 Getting Started

Prerequisites

Before integrating OAuth with Ecart Pay, ensure:

📘

Base URLs

• Production: https://ecartpay.com
• Sandbox: https://sandbox.ecartpay.com

Use the sandbox while developing. Switch to production only when you are ready to go live.

🔑 How the Flow Works

👍

One-Time Verification

A merchant only completes verification once. On later connections, an already verified
merchant sees a short confirmation screen and is returned to your app immediately.

1️⃣ Create Your Application

Create your OAuth application once. The response includes your client_id and
client_secret.

cURL

curl -X POST "https://ecartpay.com/api/oauth/applications" \
  -H "Authorization: Bearer <DASHBOARD_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Your App",
    "description": "Short description shown on the consent screen",
    "logo_url": "https://cdn.yourapp.com/logo.png",
    "redirect_url": "https://yourapp.com/oauth/callback",
    "scopes": ["read_orders", "write_orders"],
    "onboarding": {
      "headline": "Connect Your App with Ecart Pay",
      "permissions_summary": ["View and create orders"]
    }
  }'

Response 201

{
  "id": "665f2a...",
  "name": "Your App",
  "client_id": "oauth_live_0cba2d6ad48c3e2f451eaa5e3f93cd12",
  "client_secret": "secret_4f1c...e9",
  "redirect_url": "https://yourapp.com/oauth/callback",
  "scopes": ["read_orders", "write_orders", "read_credentials"],
  "status": "active"
}

⚠️

Store Your Secret

The client_secret is returned only once. Store it securely on your backend.
You can rotate it later with POST /api/oauth/applications/:id/secret.

Body Parameters

2️⃣ Redirect the Merchant to Ecart Pay

Send the merchant's browser to the OAuth entry point:

https://ecartpay.com/oauth?client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URI>&state=<STATE>

Query Parameters

📘

What the Merchant Sees

Ecart Pay handles sign-in, runs verification (KYC levels 0 and 1) when required, and
shows a consent screen with your app's name, logo, and the permissions you requested.

3️⃣ Receive the Authorization Code

After the merchant grants consent, Ecart Pay redirects to your redirect_uri:

https://yourapp.com/oauth/callback?code=<CODE>&state=<STATE>

⚠️

Validate and Be Quick

• Verify the returned state matches the value you sent.
• The code is single-use and expires in 5 minutes — exchange it promptly.

4️⃣ Exchange the Code for the Merchant Credentials

From your backend, exchange the code for the merchant's API keys. The code goes in the
Authorization header and your secret in the x-secret header.

cURL

curl -X POST "https://ecartpay.com/api/oauth/token?client_id=<CLIENT_ID>" \
  -H "Authorization: <CODE>" \
  -H "x-secret: <CLIENT_SECRET>" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "redirect_url": "https://yourapp.com/oauth/callback"
  }'

Response 200

{
  "account_id": "665f2a...",
  "public_id": "pub_live_...",
  "private_id": "prv_live_...",
  "scope": "read_orders,write_orders,read_credentials"
}

👍

One-Step Exchange

The token exchange returns the merchant account_id, public_id, and private_id
directly. Use these keys to operate on the merchant's behalf with the standard
Ecart Pay API (for example, the Orders API).

⚠️

Store the Keys Securely

The private_id is a secret. Store it encrypted on your backend, just like your
client_secret, and never expose it in the browser.

Request Reference

📘

Scope Required

Returning the credentials requires the read_credentials scope, which is granted to
every application by default.

🔐 Scopes

Request the scopes your integration needs at registration time. The merchant sees these
permissions on the consent screen and must approve them.

🔄 Updating Scopes & Re-Authorization

You can change the scopes your application requests at any time by updating the application.
How it takes effect depends on whether you add or remove scopes.

cURL

curl -X PUT "https://ecartpay.com/api/oauth/applications/<APPLICATION_ID>" \
  -H "Authorization: Bearer <DASHBOARD_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "scopes": ["read_orders", "write_orders", "read_customers"]
  }'

📘

Why Already-Connected Merchants Still See the Old Scopes

A merchant's consent (and the resulting credentials) are snapshotted at authorization
time. Adding scopes to the app does not retroactively grant them to merchants who
connected earlier — they must approve the new permissions once.

Automatic Notification

When you add scopes, Ecart Pay automatically emails every affected merchant (those with
an active credential) a message titled "requests new permissions", including a
re-authorization link that points to your application's OAuth entry point.

How to Apply the New Scopes

👍

Your Keys Do Not Change

Re-authorization does not rotate the merchant's public_id / private_id. You do not
need to request new credentials — only the granted scopes are updated on the same keys.

⚠️

Tokens Are Scoped at Issue Time

Scopes travel inside the token. Tokens issued before the merchant re-authorized keep
the old scopes until they expire. Always generate a new token after the merchant
re-authorizes so it reflects the added permissions.

🏢 Multi-Company Applications

If your partner account manages multiple companies, you can own an OAuth application under
a specific company instead of your personal account. Pass the optional company_id when
creating the application.

cURL

curl -X POST "https://ecartpay.com/api/oauth/applications" \
  -H "Authorization: Bearer <DASHBOARD_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Your App",
    "redirect_url": "https://yourapp.com/oauth/callback",
    "company_id": "665f3b0a9c1d2e4f8a7b6c50",
    "scopes": ["read_orders", "write_orders"]
  }'

📘

How Ownership Works

• The company_id must belong to your account. Otherwise the request fails with
  400 The selected company does not exist for this account.
• Applications are listed within their owning context: personal applications and each
  company's applications are scoped separately.
• The OAuth flow, consent, and token exchange work exactly the same regardless of whether
  the application is personal or company-owned.

👍

Same Integration, Any Owner

client_id, client_secret, redirect handling, scopes, and the token exchange are
identical for personal and company-owned applications — only the ownership/visibility differs.

🧪 Complete Example

A minimal Node.js backend handling the callback and token exchange:

JavaScript

const express = require('express');
const axios = require('axios');

const app = express();

const BASE_URL = 'https://sandbox.ecartpay.com';
const CLIENT_ID = process.env.ECARTPAY_CLIENT_ID;
const CLIENT_SECRET = process.env.ECARTPAY_CLIENT_SECRET;
const REDIRECT_URI = 'https://yourapp.com/oauth/callback';

// 1. Start the flow: redirect the merchant to Ecart Pay
app.get('/connect', (req, res) => {
  const state = crypto.randomUUID();
  // persist `state` in the user session for verification
  const url = `${BASE_URL}/oauth?client_id=${CLIENT_ID}` +
    `&redirect_uri=${encodeURIComponent(REDIRECT_URI)}&state=${state}`;
  res.redirect(url);
});

// 2. Handle the callback and exchange the code for the merchant credentials
app.get('/oauth/callback', async (req, res) => {
  const { code, state } = req.query;
  // verify `state` matches the value stored for this user

  const { data } = await axios.post(
    `${BASE_URL}/api/oauth/token?client_id=${CLIENT_ID}`,
    { grant_type: 'authorization_code', redirect_url: REDIRECT_URI },
    { headers: { Authorization: code, 'x-secret': CLIENT_SECRET } }
  );

  // The response already contains the merchant API keys.
  // Store data.public_id / data.private_id (encrypted) against this merchant.
  res.json({
    account_id: data.account_id,
    public_id: data.public_id,
    private_id: data.private_id,
  });
});

app.listen(3000);

🧪 Testing

Use the Sandbox environment during development:

https://sandbox.ecartpay.com/oauth?client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URI>

🚀 Going to Production

🧰 Error Reference

🔎 Resources