Connect merchant accounts

How a merchant account authorizes your integration with OAuth, and how to use, refresh, and revoke its tokens.

By the end, your integration holds the idToken of each linked merchant account, to create charges on its behalf, and knows how to refresh it, revoke it and unlink.

Before you begin

All from the same environment, Sandbox or Production:

• The clientId and clientSecret, in the Portal under Credenciales (Credentials). The clientSecret goes only from your backend to the Auth API (/token, /refresh and /revoke).
• An https redirect_uri registered in the Portal under Configuración (Settings).
• A merchant account: the one that receives the payments, not your integration admin user.

The flow runs against the Auth API, under /integration/oauth2/: https://auth-api.test.chytapay.com.ar in Sandbox and https://auth-api.chytapay.com.ar in Production.

1Send the merchant to authorize

In your backend, generate a random state, store it in the session and redirect the browser to GET /integration/oauth2/authorize:

The camelCase names (clientId, redirectUri, responseType) are also accepted, but use snake_case in new code.

import crypto from 'node:crypto';

const AUTH_API = 'https://auth-api.test.chytapay.com.ar';
const REDIRECT_URI = 'https://yourapp.com/oauth/callback';

// Express handler: the merchant clicks "Connect with Chytapay".
app.get('/connect-chytapay', (req, res) => {
  const state = crypto.randomBytes(32).toString('base64url');
  req.session.chytapayState = state;

  const url = new URL(`${AUTH_API}/integration/oauth2/authorize`);
  url.search = new URLSearchParams({
    response_type: 'code',
    client_id: process.env.CHYTAPAY_CLIENT_ID,
    redirect_uri: REDIRECT_URI,
    state,
  }).toString();

  res.redirect(url.toString());
});

The authorization screen shows your integration's name and logo, and the fee if you have an active offer. The merchant account signs in there, never the integration admin. The screen uses POST /integration/oauth2/complete-login, which your integration doesn't call.

2Receive the code and validate the state

When the merchant authorizes, Chytapay redirects their browser to your redirect_uri:

https://yourapp.com/oauth/callback?code=<code>&state=<the state you sent>

Validating the state stops an attacker from linking your user to someone else's merchant account.

3Exchange the code for tokens

In your backend, send POST /integration/oauth2/token a JSON body with grantType: "authorization_code", the code, your clientId and clientSecret, and the same redirectUri from /authorize, identical:

curl -X POST https://auth-api.test.chytapay.com.ar/integration/oauth2/token \
  -H "Content-Type: application/json" \
  -d '{
    "grantType": "authorization_code",
    "code": "'"$CODE"'",
    "clientId": "'"$CHYTAPAY_CLIENT_ID"'",
    "clientSecret": "'"$CHYTAPAY_CLIENT_SECRET"'",
    "redirectUri": "https://yourapp.com/oauth/callback"
  }'

{
  "idToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJjdHkiOiJKV1QiLCJlbmMiOiJBMjU2R0NNIn0...",
  "tokenType": "Bearer",
  "expiresIn": 3600
}

With this response the merchant is linked. Store its refreshToken: it lets you keep operating without a new authorization. If the merchant authorizes again, you get new tokens.

4Confirm which merchant authorized

With the idToken you just obtained, call GET /me on the Integration API to find out which merchant account it belongs to, and store its merchantUserId next to the link in your system:

curl https://integration-api.test.chytapay.com.ar/me \
  -H "Authorization: Bearer $ID_TOKEN"

{
  "merchantUserId": "3f8a1c52-7d4e-4b19-9a60-2c5e8d1f0b47",
  "email": "[email protected]",
  "fantasyName": "Papelería del Sur",
  "accountHolderName": "Del Sur Papelería S.R.L.",
  "accountHolderTaxId": "30123456781",
  "integration": { "name": "My integration" },
  "tenantKey": "sede-centro",
  "linkedAt": "2026-05-20T14:30:00.000Z"
}

The identity comes from the idToken: GET /me takes no parameters and ignores any you send. A merchant account that isn't linked or was unlinked gets 403.

Authenticate your API calls

Every Integration API request carries the idToken in Authorization:

curl https://integration-api.test.chytapay.com.ar/payment-request/invoice-1001 \
  -H "Authorization: Bearer $ID_TOKEN"

Its aud claim is your clientId and its sub is the merchant account: that's how Chytapay knows on whose behalf you operate. /token returns no access token: you use the idToken. The integration admin token gets 401, and an unlinked merchant account gets 403.

Before the idToken expires, or on a 401, request a new one from POST /integration/oauth2/refresh with grantType: "refresh_token", the merchant's stored refreshToken, your clientId and your clientSecret. The merchant isn't involved. The response carries a new idToken and no refreshToken: the refresh token doesn't rotate, keep using the same one until you revoke it or it expires.

Revoke a refresh token

When you stop operating for a merchant, revoke its refresh token with POST /integration/oauth2/revoke:

curl -X POST https://auth-api.test.chytapay.com.ar/integration/oauth2/revoke \
  -H "Content-Type: application/json" \
  -d '{
    "token": "'"$REFRESH_TOKEN"'",
    "tokenTypeHint": "refresh_token",
    "clientId": "'"$CHYTAPAY_CLIENT_ID"'",
    "clientSecret": "'"$CHYTAPAY_CLIENT_SECRET"'"
  }'

It returns 200 with no body. tokenTypeHint is optional and its value is refresh_token. Revoking doesn't unlink: the merchant can authorize again. To end the link, unlink the merchant.

Unlink a merchant

In the Portal, under Cuentas de comercio (Merchant accounts), use Desvincular (Unlink) on the merchant's row. From then on, its tokens get 403 from the Integration API until the merchant authorizes again. If the account was already unlinked, the Portal tells you it isn't linked.

Show your logo on the authorization screen

Without a logo, the merchant sees only your integration's name. Upload it in the Portal under Configuración (Settings), Logo section: the Portal scales it to 512 px on its longest side.

It accepts PNG, JPEG or WEBP up to 5 MB, and rejects SVG. Each upload replaces the previous one.

The redirect_uri isn't the webhook URL

Configure the webhook URL in Webhooks.

Errors

Errors carry code, message and id, which you use to trace the case. Other API errors are in Operations and errors.