Pagos

El objeto Payment

{
    "id": "pay_abc123def456",
    "reference": "ORDEN-001",
    "provider": "dinelco",
    "amount": 150000,
    "currency": "PYG",
    "status": "confirmed",
    "created_at": "2026-05-02T14:30:00+00:00",
    "updated_at": "2026-05-02T14:32:11+00:00",
    "confirmed_at": "2026-05-02T14:32:11+00:00",
    "failed_at": null,
    "expired_at": null,
    "rejection_reason": null,
    "metadata": { "order_id": 1042 },
    "customer_data": {
        "customerId": "user_42",
        "name": "Juan",
        "email": "juan@example.com"
    },
    "provider_data": {
        "operation_number": "0000123456",
        "authorization_number": "ABC123",
        "response_code": "0000"
    }
}

Campos

Campo	Tipo	Notas
`id`	string	`pay_xxxxxxxxxxxx`. Inmutable.
`reference`	string	Tu referencia interna (orden, ticket, etc.).
`provider`	enum	`dinelco` \| `bancard` \| `transferencia`.
`amount`	integer	Monto en unidad mínima de la moneda (PYG = guaraní).
`currency`	string	Solo `PYG` por ahora.
`status`	enum	Ver estados.
`created_at`	datetime	ISO 8601 con timezone.
`confirmed_at`	datetime?	Cuándo pasó a `confirmed`.
`failed_at`	datetime?	Cuándo pasó a `failed` o `rejected`.
`expired_at`	datetime?	Cuándo pasó a `expired`.
`rejection_reason`	string?	Motivo si está en `rejected`.
`metadata`	object?	Lo que vos mandaste al crear. Pasthru.
`customer_data`	object?	Snapshot inmutable del cliente al momento del cobro.
`provider_data`	object?	Datos específicos del proveedor (operation_number, etc.).

Estados (`status`)

Estado	Significado
`pending`	Creado, esperando que el cliente complete el pago.
`processing`	Esperando respuesta del proveedor (transitorio breve).
`confirmed`	Pagado con éxito.
`failed`	El proveedor rechazó el pago.
`rejected`	Operador rechazó manualmente un comprobante.
`receipt_uploaded`	Cliente subió comprobante de transferencia (esperando aprobación).
`expired`	TTL agotado sin completarse.
`cancelled`	Cancelado vía API antes de completarse.
`reversed`	Pago revertido (Dinelco antes del corte).

Endpoints

Crear un pago

POST /v1/payments

Body:

{
    "provider": "transferencia",
    "amount": 150000,
    "currency": "PYG",
    "reference": "ORDEN-001",
    "target_origin": [
        "https://tu-checkout.com",
        "https://app.tu-checkout.com"
    ],
    "customer": {
        "customerId": "user_42",
        "name": "Juan",
        "lastname": "Pérez",
        "email": "juan@example.com",
        "phone": "+595981234567",
        "ruc": "12345678-9"
    },
    "metadata": { "order_id": 1042 },
    "card_id": "card_xyz789"
}

Campos:

Campo	Requerido	Notas
`provider`	sí	`dinelco` \| `transferencia` (`bancard` próximamente).
`amount`	sí	Entero positivo.
`currency`	no	`PYG` (default).
`reference`	sí	Tu referencia única o legible.
`target_origin`	si Dinelco	String o array. Origen(es) donde se puede embeber el iframe. Ver nota abajo.
`customer`	no	Datos del cliente. `customerId` es tu `external_id`.
`metadata`	no	Object libre. Lo devolvemos tal cual en respuestas y webhook.
`card_id`	no	Si lo mandás, hace charge directo con esa card guardada (skipea iframe).

Respuesta — 201 Created:

{
    "data": {
        "id": "pay_abc123",
        "status": "pending",
        "provider_data": {
            "integrity_token": "eyJhbGc...",
            "session_id": 123456789
        }
    }
}

Sobre `target_origin`

Dinelco requiere declarar todos los orígenes desde donde el iframe pueda ser embebido. La regla es: si hay cualquier dominio o subdominio en tu lado donde podrías montar el checkout, tiene que estar en la lista.

Aceptamos string (un origen) o array (varios).
Cada item debe ser una URL absoluta (https://dominio.com), sin path ni trailing slash.
Wildcards no se soportan. Si tenés subdominios dinámicos (por sucursal, por cliente, etc.) tenés que enumerarlos uno por uno.
Los dominios del gateway (api.pay.ingalca.com, app.pay.ingalca.com) los agregamos nosotros automáticamente — no los incluyas.

Ejemplo si tu checkout vive en https://checkout.tudominio.com y también atendés desde una app móvil que abre https://m.tudominio.com:

"target_origin": [
    "https://checkout.tudominio.com",
    "https://m.tudominio.com"
]

Si te falta declarar un origen, el iframe no va a poder enviar mensajes a tu página y el pago va a quedar colgado del lado del usuario.

Listar pagos

GET /v1/payments

Query params:

Param	Notas
`status`	Filtrar por estado.
`provider`	Filtrar por proveedor.
`reference`	Búsqueda parcial en reference y `public_id`.
`customer_id`	`public_id` o `external_id` del customer.
`from`, `to`	Rango de fechas (ISO o `YYYY-MM-DD`).
`cursor`, `per_page`	Paginación.

Obtener un pago

GET /v1/payments/{id}

Devuelve el objeto completo, incluyendo provider_data y comprobantes (receipts[]) si es de transferencia.

Subir comprobante (transferencia)

POST /v1/payments/{id}/receipt

multipart/form-data con campo file (jpg/png/pdf, max 10MB) y opcional notes.

Aprobar / rechazar (transferencia)

POST /v1/payments/{id}/confirm   # body opcional: {"notes": "..."}
POST /v1/payments/{id}/reject    # body: {"reason": "..."}

Cancelar

POST /v1/payments/{id}/cancel

Solo aplica a pagos pending.

Reversar

POST /v1/payments/{id}/reverse

Solo aplica a Dinelco confirmados antes del corte de liquidación. Ver guía de reversa.