> ## 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.

# APM pay-in assessment

> Bank transfers, SPEI, wallets, PIX — multi-country assess before capture

Alternative payment methods (APM) use the same **`POST /api/v1/assess`** endpoint as cards. Send the **payer origin account** in `payment_method` — not in `beneficiary` (that field is for payouts only).

## Two-phase assess (bank rails outside the funnel)

When the payer transfers **after** checkout (SPEI, CoDi, A2A, PIX, ACH), call assess twice with the same `order_id`:

| Phase | `assess_phase` | Origin account | Purpose |
| - | - | - | - |
| Pre-fund | `intention` | Not required | Score order before showing destination / payment reference |
| Post-fund | `settlement` | **Required** | Gate accept/reject when the bank confirms credit |

Default for cards / in-funnel wallets: omit the field or send `instant`.

On **settlement decline**, the response may include `refund_suggestion`. Auto-refund guidance is **opt-in** (`organizations.auto_refund_on_fraud_decline`, default **false**). Clausum never moves funds — your core/PSP executes refunds when you choose.

Declare merchant **collect** (pay-in destination) and **disburse** (payout origin) accounts in the dashboard (**Settings → Company**) or via `/api/v1/organization/treasury-accounts`. Send the collection account on assess as `destination.*` (never `beneficiary`). Settlement is hard-linked to intention by `order_id`.

Dashboard: **Simulation → Assess** presets `apm_intention` / `apm_settlement_*`. Demo: `/demo/checkout` SPEI funnel (intention → settlement).

## Canonical model

| Field | Purpose |
| - | - |
| `payment_method.account_number` | Origin account (CLABE, IBAN, PIX key, local account) |
| `payment_method.account_scheme` | `clabe` · `iban` · `pix_key` · `routing_account` · `national_account` · `account_hash` |
| `payment_method.country` | ISO-2 instrument country |
| `payment_method.clabe` | **Mexico alias** — same as `account_scheme: clabe` |
| `payment_method.wallet_id_hash` | Hashed wallet id (Mercado Pago, PayPal, etc.) |

## Mexico (SPEI / CLABE)

Canonical:

```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 (still supported):

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

## Chile (local bank account)

```json theme={null}
{
  "payment_method": {
    "type": "bank_transfer",
    "country": "CL",
    "account_scheme": "national_account",
    "account_number": "9876543210987"
  }
}
```

## Wallet

Always send payer identity (`email` or `customer_id`) plus `wallet_id_hash` when available.

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

## APM-specific signals

| Signal | Meaning |
| - | - |
| `apm_invalid_payer_account` | Invalid account for the inferred scheme (CLABE checksum, IBAN format, etc.) — not scored in `intention` |
| `apm_instrument_incomplete` | Bank rail without origin account (`instant`) |
| `apm_settlement_origin_missing` | Settlement without real origin account |
| `apm_wallet_without_identity` | Wallet without email or wallet hash |
| `apm_micro_transfer` | Small APM amount — account probing pattern |

`card_testing_amount` applies **only to card** instruments, not SPEI or wallets.

## Operations

For production velocity at scale, run SQL **`146_apm_velocity_buckets.sql`** after **`068_assess_scale_unlimited.sql`**. For the opt-in refund flag, run **`148_auto_refund_on_fraud_decline.sql`**. Full playbook: repository `docs/APM_PAYIN_ENGINE.md`.


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