Autenticación, integración y configuración

Estado documental: Contrato propuesto. Las rutas, campos, límites y tiempos pasan a estado confirmado solo después de su implementación y verificación.

Objetivo: Inventariar autenticación, capacidades, referencias, credenciales y perfil de cobro administrable por la empresa.

Autenticación e identidad de integración

Audiencia	Método	Ruta propuesta	Uso	Idempotencia	Eventos o callbacks relacionados
Integración	`POST`	`/v1/auth/token`	Obtener token de acceso.	Sí, por solicitud	Ninguno
Integración	`POST`	`/v1/auth/revoke`	Revocar el token utilizado.	Sí	security.token_revoked
Integración	`GET`	`/v1/integration`	Consultar identidad de la integración.	No	Ninguno
Integración	`GET`	`/v1/integration/status`	Consultar disponibilidad y estado general.	No	Ninguno
Integración	`GET`	`/v1/integration/capabilities`	Consultar experiencias y funciones habilitadas.	No	Ninguno
Integración	`GET`	`/v1/integration/defaults`	Consultar moneda, vigencias y valores efectivos.	No	Ninguno
Referencia	`GET`	`/v1/reference/api-version`	Consultar versión del contrato.	No	Ninguno
Referencia	`GET`	`/v1/reference/payment-options`	Consultar QR y transferencia habilitables.	No	Ninguno
Referencia	`GET`	`/v1/reference/statuses`	Consultar catálogo de estados.	No	Ninguno
Referencia	`GET`	`/v1/reference/errors`	Consultar catálogo de errores.	No	Ninguno
Referencia	`GET`	`/v1/reference/events`	Consultar catálogo de webhooks.	No	Ninguno
Referencia	`GET`	`/v1/reference/report-types`	Consultar tipos de reporte.	No	Ninguno
Referencia	`GET`	`/v1/reference/changelog`	Consultar cambios contractuales.	No	Ninguno

Ejemplo: obtener token

POST <YUPY_API_BASE_URL>/v1/auth/token
Content-Type: application/json

{
  "client_id": "<YUPY_CLIENT_ID>",
  "client_secret": "<YUPY_CLIENT_SECRET>"
}

{
  "access_token": "<OPAQUE_ACCESS_TOKEN>",
  "token_type": "Bearer",
  "expires_in_seconds": 3600,
  "expires_at": "2026-07-20T15:00:00-05:00",
  "environment": "sandbox",
  "request_id": "req_01JXYZ"
}

Ejemplo: capacidades

GET /v1/integration/capabilities

{
  "environment": "sandbox",
  "payment_experiences": [
    "web_checkout",
    "chat_pos"
  ],
  "payment_options": [
    "qr",
    "bank_transfer"
  ],
  "wallets": [
    "yape",
    "plin"
  ],
  "evidence_upload": true,
  "ocr": true,
  "webhooks": true,
  "reports": true,
  "request_id": "req_01JXYZ"
}

Administración de integraciones y credenciales

Estas operaciones corresponden a administradores autorizados de la empresa y pueden ejecutarse desde la consola de YUPY.

Audiencia	Método	Ruta propuesta	Uso	Idempotencia	Eventos o callbacks relacionados
Administración	`GET`	`/v1/admin/integrations`	Listar integraciones de la empresa.	No	Ninguno
Administración	`GET`	`/v1/admin/integrations/{id}`	Consultar integración.	No	Ninguno
Administración	`POST`	`/v1/admin/integrations/{id}/credentials`	Generar credencial inicial.	Sí	security.credential_created
Administración	`POST`	`/v1/admin/integrations/{id}/rotate-credentials`	Generar nueva credencial y transición.	Sí	security.credential_rotated
Administración	`POST`	`/v1/admin/integrations/{id}/revoke-credentials`	Revocar credencial.	Sí	security.credential_revoked
Administración	`POST`	`/v1/admin/integrations/{id}/activate`	Activar integración.	Sí	integration.activated
Administración	`POST`	`/v1/admin/integrations/{id}/deactivate`	Desactivar integración.	Sí	integration.deactivated
Administración	`GET`	`/v1/admin/integrations/{id}/history`	Consultar auditoría.	No	Ninguno

Ejemplo: rotar credenciales

POST /v1/admin/integrations/int_01JXYZ/rotate-credentials
Idempotency-Key: 2b963f69-75ac-4e94-a6bd-f811b93c805f

{
  "transition_requested": true
}

{
  "result": "credential_rotated",
  "integration_id": "int_01JXYZ",
  "client_id": "cli_01JNEW",
  "client_secret": "<SHOWN_ONCE>",
  "previous_credential_status": "transition_active",
  "transition_expires_at": "2026-07-23T23:59:59-05:00",
  "request_id": "req_01JXYZ"
}

Perfil principal de cobro

La configuración ordinaria es un perfil principal por empresa. YUPY lo configura durante el setup y la empresa puede modificarlo con permisos.

Audiencia	Método	Ruta propuesta	Uso	Idempotencia	Eventos o callbacks relacionados
Administración	`POST`	`/v1/admin/payment-profiles`	Crear perfil principal de cobro.	Sí	payment_profile.created
Administración	`GET`	`/v1/admin/payment-profiles`	Listar perfiles autorizados.	No	Ninguno
Administración	`GET`	`/v1/admin/payment-profiles/{id}`	Consultar perfil.	No	Ninguno
Administración	`PATCH`	`/v1/admin/payment-profiles/{id}`	Modificar datos permitidos.	Sí	payment_profile.updated
Administración	`POST`	`/v1/admin/payment-profiles/{id}/activate`	Activar perfil.	Sí	payment_profile.activated
Administración	`POST`	`/v1/admin/payment-profiles/{id}/deactivate`	Desactivar perfil.	Sí	payment_profile.deactivated
Administración	`POST`	`/v1/admin/payment-profiles/{id}/validate`	Validar configuración.	Sí	Ninguno
Administración	`GET`	`/v1/admin/payment-profiles/{id}/history`	Consultar cambios históricos.	No	Ninguno

Ejemplo: validar perfil

POST /v1/admin/payment-profiles/prf_01JXYZ/validate

{
  "valid": true,
  "payment_options": [
    "qr",
    "bank_transfer"
  ],
  "warnings": [],
  "request_id": "req_01JXYZ"
}

Errores principales

HTTP	Código	Uso	Reintentar
401	`invalid_credentials`	Credenciales inválidas.	No, corregir credenciales.
401	`credential_revoked`	Credencial revocada.	No, rotar.
401	`access_token_expired`	Token vencido.	Sí, obtener otro token.
403	`environment_not_allowed`	Credencial de otro ambiente.	No.
403	`permission_denied`	Falta permiso administrativo.	No.
409	`credential_rotation_in_progress`	Ya existe una rotación activa.	Consultar estado.
422	`payment_profile_invalid`	Perfil incompleto o inconsistente.	Corregir datos.

API Technical Docs