Tarjetas

El objeto Card

{
    "id": "card_xyz789abc012",
    "customer_id": "cust_qrs456tuv789",
    "provider": "dinelco",
    "status": "registered",
    "brand": "Visa",
    "last_four": "1096",
    "expires": "12/30",
    "registered_at": "2026-05-02T14:30:00+00:00"
}

Campos

Campo	Tipo	Notas
id	string	card_xxx. Inmutable.
customer_id	string	public_id del customer asociado.
provider	enum	dinelco (Bancard próximamente).
status	enum	pending | registered | invalid | deleted.
brand	string?	Visa, Mastercard, etc. Disponible cuando registered.
last_four	string?	Últimos 4 dígitos. Disponible cuando registered.
expires	string?	MM/YY. Disponible cuando registered.

El paymentToken se guarda encriptado del lado nuestro y nunca se devuelve en respuestas.

Endpoints

Iniciar catastro

POST /v1/cards

Body:

{
    "provider": "dinelco",
    "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"
    }
}

target_origin puede ser string (un origen) o array. Es requerido para Dinelco porque el iframe usa postMessage para comunicarse con tu página. Tenés que listar todos los dominios y subdominios desde donde podrías embeber el iframe (no se aceptan wildcards). Los dominios del gateway los agregamos nosotros. Más detalle en crear pago.

Respuesta — 201 Created:

{
    "data": {
        "card_id": "card_xyz789",
        "status": "pending",
        "registration": {
            "integrity_token": "eyJhbGc...",
            "session_id": 123456789,
            "validate_url": "https://test-checkout.dinelco.com.py:50106/registry?token=...",
            "expires_at": "2026-05-02T15:00:00+00:00"
        }
    }
}

Con validate_url embebés el iframe en tu frontend; ver guía de catastro.

Listar tarjetas

GET /v1/cards?customer_id=user_42

Query params:

Param	Notas
customer_id	Filtrar por external_id o public_id.
status	Filtrar por estado.
cursor, per_page	Paginación.

Obtener una tarjeta

GET /v1/cards/{id}

Cobrar con la tarjeta

POST /v1/cards/{id}/charge

Body:

{
    "amount": 50000,
    "reference": "SUSCRIPCION-MAY-2026",
    "metadata": { "subscription_id": 99 }
}

Respuesta — 201 Created. A diferencia del checkout, el cobro es sincrónico — la respuesta ya tiene el resultado:

{
    "data": {
        "id": "pay_def456",
        "status": "confirmed",
        "amount": 50000,
        "provider_data": {
            "operation_number": "0000123456",
            "authorization_number": "ABC123",
            "response_code": "0000"
        }
    }
}

Si el cobro fue rechazado, status será failed y provider_data.response_code contendrá el código del proveedor (ver errores).

Eliminar una tarjeta

DELETE /v1/cards/{id}

Hoy devuelve 501 Not Implemented — Dinelco no expone endpoint de unregister. Si querés “borrar” una tarjeta del lado tuyo, marcala como inactiva en tu app y no la uses más.