¿Cómo funciona Chytapay?

Chytapay te permite crear grupos de clientes, enviarles solicitudes de cobro y hacer seguimiento de los pagos desde un panel centralizado. Los clientes reciben notificaciones automáticas por WhatsApp y email, y el dinero acredita directamente en tu cuenta.

¿Cuánto cuesta Chytapay?

Chytapay ofrece 15 días gratis sin tarjeta de crédito. Después, el costo es del 1% + IVA (1,21% final) por cobro acreditado. Sin costos fijos ni de activación.

¿En qué países está disponible Chytapay?

Chytapay está disponible en Argentina. Los cobros se realizan por transferencia bancaria (CBU/CVU/alias) y los fondos acreditan en cuentas argentinas.

📖 Documentación

Primeros pasos

Guía paso a paso para configurar e implementar la integración con Chytapay.

Variables de URLs

Variable	Test TEST	Producción PROD
Auth API	`https://auth-api.test.chytapay.com.ar`	`https://auth-api.chytapay.com.ar`
Integration API	`https://integration-api.test.chytapay.com.ar`	`https://integration-api.chytapay.com.ar`

💡 Prerrequisito: Si ya recibiste tu email con credenciales y cambiaste tu contraseña, saltea al Paso 2.

Cambiar Contraseña Temporal

POST /integration/admin/change-password

Al recibir el email de bienvenida, tendrás una contraseña temporal que debés cambiar antes de continuar.

POST{{auth-api-url}}/integration/admin/change-password

bash

curl -X POST {{auth-api-url}}/integration/admin/change-password \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "currentPassword": "TempPass123!",
    "newPassword": "TuNuevaPassword123!"
  }'

Response

json

{ "message": "Password changed successfully" }

POST /integration/admin/login

Iniciá sesión con tus credenciales para obtener el token de administrador.

POST{{auth-api-url}}/integration/admin/login

bash

curl -X POST {{auth-api-url}}/integration/admin/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "TuNuevaPassword123!"
  }'

Response

json

{
  "success": true,
  "idToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

💡Guardá el idToken — lo vas a necesitar en los siguientes pasos.

Configurar URLs

POST /my-integration/url

Configurá tu webhook URL (donde recibirás notificaciones de pago) y tu redirect URI (para el flujo OAuth).

POST{{integration-admin-url}}/my-integration/url

bash — webhook

curl -X POST {{integration-admin-url}}/my-integration/url \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {admin_id_token}" \
  -d '{
    "url": "https://tuapp.com/webhook",
    "urlType": "webhook",
    "validationToken": "tu_token_secreto_16chars"
  }'

💡Validation Token: si lo incluís, lo recibirás en el header validation-token de cada webhook para verificar que proviene de Chytapay. Mínimo 16 caracteres.

bash — redirect URI

curl -X POST {{integration-admin-url}}/my-integration/url \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {admin_id_token}" \
  -d '{
    "url": "https://tuapp.com/oauth/callback",
    "urlType": "redirect_uri"
  }'

Flujo OAuth

Autorización de usuarios Chytapay

Para crear payment requests en nombre de un usuario Chytapay, necesitás su autorización vía OAuth2.

4.1 Autorización

⚠️Importante: el usuario que autoriza es la cuenta de comercio del merchant (la que va a recibir los pagos), NO tu cuenta de admin del portal. Esta confusión es el error más frecuente — consultá Actores para más contexto.

Redirigí al usuario a la URL de autorización:

url

GET {{auth-api-url}}/integration/oauth2/authorize?
  response_type=code
  &clientId={tu_client_id}
  &redirectUri=https://tuapp.com/oauth/callback
  &scope=openid profile
  &state=random_state_string

El usuario autorizará y será redirigido con un código:

url

https://tuapp.com/oauth/callback?code=AUTH_CODE&state=random_state_string

4.2 Obtener Tokens

POST{{auth-api-url}}/integration/oauth2/token

bash

curl -X POST {{auth-api-url}}/integration/oauth2/token \
  -H "Content-Type: application/json" \
  -d '{
    "code": "AUTH_CODE",
    "clientId": "{tu_client_id}",
    "clientSecret": "{tu_client_secret}",
    "redirectUri": "https://tuapp.com/oauth/callback"
  }'

Response

json

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

💡Guardá el refreshToken de forma segura para obtener nuevos tokens cuando el idToken expire.

4.3 Refrescar Token

POST{{auth-api-url}}/integration/oauth2/refresh

bash

curl -X POST {{auth-api-url}}/integration/oauth2/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "{refresh_token}",
    "clientId": "{tu_client_id}",
    "clientSecret": "{tu_client_secret}"
  }'

Crear Payment Request

POST /payment-request

Con el idToken del usuario, podés crear solicitudes de cobro.

POST{{integration-url}}/payment-request

bash

curl -X POST {{integration-url}}/payment-request \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {user_id_token}" \
  -d '{
    "referenceId": "factura-001",
    "amount": 1000,
    "description": "Cuota mensual - Enero 2025",
    "dueDates": ["2025-01-15", "2025-01-30"],
    "surcharge": { "type": "%", "value": 10 },
    "sendWhatsappNotification": true,
    "sendEmailNotification": true,
    "customer": {
      "name": "Juan Pérez",
      "phoneNumber": { "countryCode": "+54", "number": "1112345678" },
      "email": "[email protected]"
    }
  }'

Response

json

{
  "referenceId": "factura-001",
  "amount": 1000,
  "calculatedAmounts": [
    { "dueDate": "2025-01-15", "amount": 1000, "isOriginalAmount": true },
    { "dueDate": "2025-01-30", "amount": 1100, "surchargeApplied": 100 }
  ],
  "CVU": "0000003100012345678901",
  "bankAccountInfo": {
    "accountHolderName": "Usuario Chytapay",
    "bankName": "AGILPAGOS"
  }
}

Conciliación por CUIL (opcional)

Por defecto, cada pago se concilia por CVU. Si necesitás conciliar por CUIL del pagador, agregá conciliationType: "cuil" y el campo customer.taxDocument con el CUIL o DNI del cliente.

bash

# Ejemplo con CUIL explícito
curl -X POST {{integration-url}}/payment-request \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {user_id_token}" \
  -d '{
    "referenceId": "factura-cuil-001",
    "amount": 5000,
    "description": "Cuota con conciliación por CUIL",
    "dueDates": ["2025-02-15"],
    "conciliationType": "cuil",
    "customer": {
      "name": "María García",
      "email": "[email protected]",
      "taxDocument": "27304050604"
    }
  }'

# Ejemplo con DNI (se generan automáticamente los candidatos CUIL 20 y 27)
curl -X POST {{integration-url}}/payment-request \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {user_id_token}" \
  -d '{
    "referenceId": "factura-dni-001",
    "amount": 5000,
    "description": "Cuota con conciliación por DNI",
    "dueDates": ["2025-02-15"],
    "conciliationType": "cuil",
    "customer": {
      "name": "Carlos López",
      "email": "[email protected]",
      "taxDocument": "30405060"
    }
  }'

Campo	Descripción
`conciliationType`	"cvu" (default) o "cuil". Determina cómo se vincula el pago recibido con el payment request.
`customer.taxDocument`	CUIL (11 dígitos) o DNI (7-8 dígitos) del pagador. Requerido cuando conciliationType es "cuil". Ignorado en modo CVU.

💡Cuando enviás un DNI, el sistema genera automáticamente los candidatos CUIL posibles y registra los válidos. La respuesta devuelve el customer.taxDocument exactamente como lo enviaste.

Consultar Payment Requests

GET /payment-request

Consultá todos los payment requests de tu integración. Podés filtrar por fecha de creación.

GET{{integration-url}}/payment-request?startDate=2025-01-01&endDate=2025-01-31

bash

curl -X GET "{{integration-url}}/payment-request?startDate=2025-01-01&endDate=2025-01-31" \
  -H "Authorization: Bearer {user_id_token}"

Response

json

[
  {
    "paymentRequestId": "uuid",
    "referenceId": "factura-001",
    "amount": 1000,
    "paidAmount": 1100,
    "dueDate": "2025-01-15T00:00:00.000Z",
    "status": "PAID",
    "customer": { "name": "Juan Pérez", "email": "[email protected]" },
    "createdAt": "2025-01-05T10:30:00.000Z"
  }
]

💡Estados posibles: pending · partial_payment · total_payment · overdue · partial_overdue · canceled

💡Para volúmenes altos: este endpoint no implementa paginación. Usá los parámetros startDate y endDate para filtrar por rango temporal y mantener responses manejables.

Recibir Webhooks

POST en tu webhook URL

Cuando el estado de un payment request cambia, Chytapay envía un POST a tu webhook URL. Para información completa sobre el payload, seguridad (validation-token), reintentos e idempotencia, consultá la sección Webhooks.

💡Ver la sección Webhooks completa →

✓

Validaciones del Payment Request

referenceId

·8–100 caracteres
·Caracteres permitidos: letras, números, guiones, underscores
·Debe ser único (recomendamos UUIDs)

amount

·Número positivo mayor a 0 · máximo 10.000.000
·Hasta 2 decimales de precisión

dueDates

·Mínimo 1, máximo 2 fechas · formato YYYY-MM-DD
·Cada fecha debe ser posterior a hoy y no mayor a 35 días desde hoy

surcharge

·Obligatorio si hay 2 fechas · NO enviar si hay solo 1 fecha
·type: % | fixed | none
·value: 0–100 para % · 0–10.000.000 para fixed · 0 para none

customer

·name: requerido, 2–150 caracteres
·phoneNumber: requerido si sendWhatsappNotification = true
·email: requerido si sendEmailNotification = true

→

Resumen del Flujo

Cambiar password temporal✓

Configurar webhook URL y redirect URI✓

Implementar flujo OAuth con usuario Chytapay✓

Crear payment request con token del usuario✓

Consultar payment requests creados✓

Recibir webhook cuando se pague✓

🟠 Colección Postman

Importá la colección y probá todos los endpoints en minutos. Incluye environments de Test y Producción listos para usar.

⬇ Colección API ⬇ Environment Test ⬇ Environment Producción

Próximos pasos

Ya tenés el flujo de integración completo. Estas secciones te van a ayudar a profundizar:

Actores →Entendé la diferencia entre Integration admin y Cuenta de comercio.Vinculación vs uso recurrente →El flujo de una sola vez vs el flujo server-side recurrente.Webhooks →Payload completo, seguridad (validation-token), reintentos e idempotencia.Errores típicos →Los problemas más frecuentes al integrar y cómo resolverlos.API Reference interactiva →Todos los endpoints con parámetros, respuestas y ejemplos en vivo.