Conectar comercios

Cómo una cuenta de comercio autoriza a tu integración con OAuth, y cómo usar, renovar y revocar sus tokens.

Al terminar tenés el idToken de cada comercio vinculado, para crear cobros a su nombre, y sabés renovarlo, revocarlo y desvincular.

Antes de empezar

Todo del mismo ambiente, Sandbox o Producción:

• El clientId y el clientSecret, en el Portal, en Credenciales. El clientSecret va solo de tu backend a la Auth API (/token, /refresh y /revoke).
• Una redirect_uri https registrada en el Portal, en Configuración.
• Una cuenta de comercio: la que recibe los pagos, no tu usuario de admin de la integración.

El flujo corre contra la Auth API, en /integration/oauth2/: https://auth-api.test.chytapay.com.ar en Sandbox y https://auth-api.chytapay.com.ar en Producción.

1Mandá al comercio a autorizar

En tu backend, generá un state aleatorio, guardalo en la sesión y redirigí el navegador a GET /integration/oauth2/authorize:

También se aceptan los nombres en camelCase (clientId, redirectUri, responseType), pero en código nuevo usá snake_case.

import crypto from 'node:crypto';

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

// Handler de Express: el comercio hace clic en "Conectar con Chytapay".
app.get('/conectar-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());
});

La pantalla de autorización muestra el nombre y el logo de tu integración, y la comisión si tenés una oferta activa. Ahí inicia sesión la cuenta de comercio, nunca el admin de la integración. Usa POST /integration/oauth2/complete-login, que tu integración no llama.

2Recibí el code y validá el state

Cuando el comercio autoriza, Chytapay redirige su navegador a tu redirect_uri:

https://tuapp.com/oauth/callback?code=<code>&state=<el state que mandaste>

El state evita que un atacante vincule a tu usuario con una cuenta ajena.

3Cambiá el code por tokens

Desde tu backend, POST /integration/oauth2/token con grantType: "authorization_code", code, clientId, clientSecret y la misma redirectUri de /authorize:

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://tuapp.com/oauth/callback"
  }'

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

El comercio queda vinculado. Guardá su refreshToken: te deja operar sin que autorice de nuevo. Si vuelve a autorizar, recibís tokens nuevos.

4Confirmá qué comercio autorizó

Con el idToken recién obtenido, llamá a GET /me en la Integration API para saber a qué cuenta de comercio pertenece, y guardá su merchantUserId junto al vínculo en tu sistema:

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": "Mi integración" },
  "tenantKey": "sede-centro",
  "linkedAt": "2026-05-20T14:30:00.000Z"
}

La identidad sale del idToken: GET /me no recibe parámetros y ignora los que le mandes. Una cuenta de comercio no vinculada o desvinculada recibe 403.

Autenticá las llamadas a la API

Cada request a la Integration API lleva el idToken en Authorization:

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

Su claim aud es tu clientId y su sub, la cuenta de comercio: así sabe Chytapay a nombre de quién operás. /token no devuelve access token: usás el idToken. El token del admin de la integración da 401, y una cuenta de comercio no vinculada, 403.

Antes de que venza el idToken, o ante un 401, pedí uno nuevo con POST /integration/oauth2/refresh: grantType: "refresh_token", el refreshToken del comercio, clientId y clientSecret. El comercio no interviene. La respuesta trae solo un idToken nuevo: el refresh token no rota, seguí usando el mismo hasta que lo revoques o venza.

Revocá un refresh token

Cuando dejás de operar para un comercio, revocá su refresh token con 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"'"
  }'

Responde 200 sin cuerpo. tokenTypeHint es opcional y vale refresh_token. Revocar no desvincula: el comercio puede volver a autorizar. Para cortar el vínculo, desvinculalo.

Desvinculá un comercio

En el Portal, en Cuentas de comercio, usá Desvincular en la fila del comercio. Desde ahí, sus tokens reciben 403 en la Integration API hasta que el comercio autorice de nuevo. Si la cuenta ya estaba desvinculada, el Portal avisa que no está vinculada.

Mostrá tu logo en la pantalla de autorización

Sin logo, el comercio ve solo el nombre de tu integración. Subilo en el Portal, en Configuración, sección Logo. Acepta PNG, JPEG o WEBP de hasta 5 MB (no SVG), lo reduce a 512 px del lado más largo y cada subida reemplaza la anterior.

La redirect_uri no es la URL de webhook

Configurá la URL de webhook en Webhooks.

Errores

Los errores traen code, message e id, que sirve para rastrear el caso. Los demás errores de la API están en Operación y errores.