Evaluación pay-in APM

Los métodos de pago alternativos (APM) usan el mismo endpoint POST /api/v1/assess que las tarjetas. Envía la cuenta de origen del pagador en payment_method — no en beneficiary (ese campo es solo para payouts).

Assess en dos fases (rails fuera del funnel)

Cuando el pagador transfiere después del checkout (SPEI, CoDi, A2A, PIX, ACH), llama a assess dos veces con el mismo order_id:

Fase	`assess_phase`	Cuenta origen	Propósito
Pre-abono	`intention`	No requerida	Evaluar el pedido antes de mostrar CLABE destino / referencia
Post-abono	`settlement`	Requerida	Gate aceptar/rechazar cuando el banco confirma el crédito

Default para tarjetas / wallets in-funnel: omitir el campo o enviar instant. En decline de settlement, la respuesta puede incluir refund_suggestion. La guía de auto-reembolso es opt-in (organizations.auto_refund_on_fraud_decline, default false). Clausum nunca mueve fondos. Declara cuentas de recaudación (collect) y dispersión (disburse) en Configuración → Empresa. Envía el destino de cobro en destination.* (nunca beneficiary). Settlement se enlaza a intention por order_id. Dashboard: presets apm_intention / apm_settlement_*. Demo: /demo/checkout funnel SPEI.

Modelo canónico

Campo	Propósito
`payment_method.account_number`	Cuenta de origen (CLABE, IBAN, clave PIX, cuenta local)
`payment_method.account_scheme`	`clabe` · `iban` · `pix_key` · `routing_account` · `national_account` · `account_hash`
`payment_method.country`	País ISO-2 del instrumento
`payment_method.clabe`	Alias México — igual que `account_scheme: clabe`
`payment_method.wallet_id_hash`	Id de billetera hasheado (Mercado Pago, PayPal, etc.)

México (SPEI / CLABE)

Canónico:

{
  "amount": 1250.00,
  "amount_unit": "major",
  "currency": "MXN",
  "email": "payer@example.com",
  "payment_method": {
    "type": "bank_transfer",
    "country": "MX",
    "account_scheme": "clabe",
    "account_number": "646180157801012343",
    "bank_code": "646"
  },
  "device": { "ip": "203.0.113.10" }
}

Legacy (aún soportado):

{
  "payment_method": {
    "type": "spei",
    "clabe": "646180157801012343",
    "country": "MX"
  }
}

Chile (cuenta bancaria local)

{
  "payment_method": {
    "type": "bank_transfer",
    "country": "CL",
    "account_scheme": "national_account",
    "account_number": "9876543210987"
  }
}

Billetera

Siempre envía identidad del pagador (email o customer_id) más wallet_id_hash cuando esté disponible.

{
  "payment_method": {
    "type": "wallet",
    "wallet_type": "mercadopago",
    "wallet_id_hash": "<sha256>"
  },
  "email": "payer@example.com"
}

Señales específicas de APM

Señal	Significado
`apm_invalid_payer_account`	Cuenta inválida para el esquema inferido — no se puntúa en `intention`
`apm_instrument_incomplete`	Rail bancario sin cuenta de origen (`instant`)
`apm_settlement_origin_missing`	Settlement sin cuenta origen real
`apm_wallet_without_identity`	Billetera sin correo ni hash de billetera
`apm_micro_transfer`	Monto APM pequeño — patrón de sondeo de cuenta

card_testing_amount aplica solo a instrumentos de tarjeta, no SPEI ni billeteras.

Operaciones

Para velocidad en producción a escala, ejecuta SQL 146_apm_velocity_buckets.sql tras 068_assess_scale_unlimited.sql. Para el flag opt-in de reembolso, ejecuta 148_auto_refund_on_fraud_decline.sql. Playbook completo: repositorio docs/APM_PAYIN_ENGINE.md.

Primeros pasos

Integración por tipo de cliente

Soluciones y prevención

Capacidades — eventos y operaciones

Panel de control

Conceptos clave

Referencia

Evaluación pay-in APM

Assess en dos fases (rails fuera del funnel)

Modelo canónico

México (SPEI / CLABE)

Chile (cuenta bancaria local)

Billetera

Señales específicas de APM

Operaciones

​Assess en dos fases (rails fuera del funnel)

​Modelo canónico

​México (SPEI / CLABE)

​Chile (cuenta bancaria local)

​Billetera

​Señales específicas de APM

​Operaciones

Assess en dos fases (rails fuera del funnel)

Modelo canónico

México (SPEI / CLABE)

Chile (cuenta bancaria local)

Billetera

Señales específicas de APM

Operaciones