> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clausum.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Evaluación pay-in APM

> Transferencias bancarias, SPEI, billeteras, PIX — assess multi-país antes del capture

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:

```json theme={null}
{
  "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):

```json theme={null}
{
  "payment_method": {
    "type": "spei",
    "clabe": "646180157801012343",
    "country": "MX"
  }
}
```

## Chile (cuenta bancaria local)

```json theme={null}
{
  "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.

```json theme={null}
{
  "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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.