¿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.

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 vas a tener una contraseña temporal. Entrá al Portal y definí una nueva antes de continuar. Si preferís hacerlo server-to-server, el mismo cambio está disponible en este endpoint.

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" }

Entrá al Portal de integración con tus credenciales de admin de la integración. Casi todo lo de esta guía —cambiar la contraseña, configurar URLs, dar de alta sedes— lo podés hacer desde ahí, sin llamar a la API.

POST /integration/admin/login

Iniciá sesión en el Portal con tus credenciales de administrador de la integración. Para el flujo server-to-server, el mismo login está disponible en este endpoint y te devuelve 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

Desde el Portal, en Mi integración → Configuración, agregás tu webhook URL (donde recibís las notificaciones de pago), tu redirect URI (para el flujo OAuth) y el token de validación. Todo esto también está disponible en este endpoint.

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.

Ver ejemplos (CUIL y DNI)

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.

Cancelar: POST /payment-request/{referenceId}/cancel solo aplica a cobros en draft o pending. Cualquier otro estado (paid, overdue, canceled, partial…) devuelve HTTP 409. Si sale bien, responde { referenceId, state: "canceled" }.

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)
·Podés codificarlo para que sea significativo — por ejemplo CLIENTE01-SEDE03-FACT123.

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
·Por día (YYYY-MM-DD): vence al fin del día en hora Argentina, debe ser posterior a hoy y no mayor a 35 días. Admite hasta 2 vencimientos (con recargo).
·Con hora (YYYY-MM-DDTHH:MM[:SS], zona opcional — sin zona = hora Argentina, Z = UTC, o ±HH:MM): debe ser al menos dentro de 3 minutos y no mayor a 35 días. Un solo vencimiento.

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.