---
title: "Announce a deposit you're expecting"
method: POST
path: "/v1/customers/{customerId}/deposit_intents"
tags: ["Deposits"]
---

# Announce a deposit you're expecting

`POST /v1/customers/{customerId}/deposit_intents`

## Request

- Base URL: `https://api.sandbox.alfredpay.io`
- URL: `https://api.sandbox.alfredpay.io/v1/customers/{customerId}/deposit_intents`
- Auth: one of:
  - HTTP bearer
  - API key in header `api-key` and API key in header `api-secret`

Registers an expected arrival before the money moves, and creates the `PAY_IN` transaction immediately at `PENDING_FUNDS` with `settlement_status: FUNDS_EXPECTED`. The transaction exists before the funds do.

What the intent means depends on the account it's against:

* On a `PAYMENT`-purpose account the intent is the locked order, and `onUnder` decides what happens if the payer sends less than expected.
* On a `CONVERSION` or `BALANCE` account it's an optional announcement.

The response carries an `indicativeRate` with `binding: false`. It's an indication, never a lock, and this endpoint accepts no `quoteId`.

**Wait on** `deposit_intent.matched` or `deposit_intent.expired`, then `deposit.credited`. See [Webhooks and events](/docs/webhooks-and-events).

## Headers

- `Idempotency-Key` string, uuid, required

## Request body

- DepositIntentCreate
  - `virtualAccountId` string, required
  - `expectedAmount` Money, required
    - `value` string, required
    - `currency` 'USD' | 'HKD' | 'CNY' | 'MXN' | 'DOP' | 'COP' | 'BRL' | 'ARS' | 'CLP' | 'PEN' | 'BOB' | 'PYG' | 'USDC' | 'USDT', required: Fourteen members, reconciled to the countries a customer can be onboarded in. USDC and USDT are stablecoins and require `chain`.
  - `tolerance` object, required: Set independently, never a symmetric percentage.
    - `underPct` string, required
    - `overPct` string, required
  - `onOver` 'convert_all' | 'hold_surplus' | 'refund_surplus', required
  - `onUnder` 'resize' | 'block' | 'requote' | 'refund', required: Applies on a PAYMENT-purpose account. resize keeps the locked rate and shrinks the quantity; requote re-prices at today's rate; block holds until the shortfall is made up or the intent expires; refund returns the receipt.
  - `expiresAt` string, date-time, required
  - `reference` string: Quoted by the payer. Stage 0 of attribution, and the only reliable match key.
  - `payment_flow_id` string
  - `metadata` Metadata: Client-supplied key–value pairs, echoed on the object and every event about it.

## Response `201`

Created

- DepositIntent: Present on every money object. The four machines move independently.
  - `transaction_id` string, required
  - `transaction_type` 'PAY_IN' | 'PAY_OUT' | 'CONVERSION', required
  - `pay_in_subtype` 'COLLECTION' | 'ON_RAMP' | 'USD_STABLE_DEPOSIT' | 'null', nullable
  - `pay_out_subtype` 'OFF_RAMP' | 'FIAT_WITHDRAWAL' | 'CRYPTO_WITHDRAWAL' | 'CROSS_BORDER_PAYOUT' | 'null', nullable
  - `conversion_subtype` 'OTC_TRADE' | 'BALANCE_CONVERSION' | 'null', nullable
  - `transaction_status` 'CREATED' | 'PENDING_VALIDATION' | 'PENDING_FUNDS' | 'PENDING_COMPLIANCE' | 'PENDING_RFI' | 'APPROVED_FOR_EXECUTION' | 'PROCESSING' | 'COMPLETE' | 'FAILED' | 'CANCELLED' | 'BLOCKED', required: Business lifecycle, customer-facing. Terminal values are COMPLETE, FAILED, CANCELLED, BLOCKED.
  - `compliance_status` 'NOT_REQUIRED' | 'PENDING_SCREENING' | 'PENDING_KYT' | 'CLEARED' | 'ALERTED' | 'RFI_REQUESTED' | 'PAUSED' | 'ESCALATED' | 'RELEASED' | 'BLOCKED', required
  - `settlement_status` 'NOT_STARTED' | 'FUNDS_EXPECTED' | 'FUNDS_RECEIVED' | 'FUNDS_HELD' | 'FUNDS_RELEASED' | 'SETTLED' | 'PARTIALLY_SETTLED' | 'FAILED' | 'RETURNED', required: Leg-level and financial. "Delayed settlement" is a settlement value with the parent still PROCESSING, never a business status.
  - `reconciliation_summary` 'ALL_MATCHED' | 'PARTIAL_MATCH' | 'HAS_BREAK', required: Derived, visibility only. Never blocks transaction_status.
  - `payment_flow_id` string, nullable: Relates independent transactions in one flow. One completing never completes another.
  - `resource_version` integer: Monotonic per resource. Apply events in this order.
  - `created_at` string, date-time
  - `updated_at` string, date-time
  - `id` string
  - `customerId` string
  - `virtualAccountId` string
  - `expectedAmount` Money
    - `value` string, required
    - `currency` 'USD' | 'HKD' | 'CNY' | 'MXN' | 'DOP' | 'COP' | 'BRL' | 'ARS' | 'CLP' | 'PEN' | 'BOB' | 'PYG' | 'USDC' | 'USDT', required: Fourteen members, reconciled to the countries a customer can be onboarded in. USDC and USDT are stablecoins and require `chain`.
  - `tolerance` object
    - `underPct` string
    - `overPct` string
  - `onOver` 'convert_all' | 'hold_surplus' | 'refund_surplus'
  - `onUnder` 'resize' | 'block' | 'requote' | 'refund': Applies on a PAYMENT-purpose account. resize keeps the locked rate and shrinks the quantity; requote re-prices at today's rate; block holds until the shortfall is made up or the intent expires; refund returns the receipt.
  - `expiresAt` string, date-time
  - `reference` string
  - `indicativeRate` object: Non-binding, always.
    - `fromCurrency` 'USD' | 'HKD' | 'CNY' | 'MXN' | 'DOP' | 'COP' | 'BRL' | 'ARS' | 'CLP' | 'PEN' | 'BOB' | 'PYG' | 'USDC' | 'USDT': Fourteen members, reconciled to the countries a customer can be onboarded in. USDC and USDT are stablecoins and require `chain`.
    - `toCurrency` 'USD' | 'HKD' | 'CNY' | 'MXN' | 'DOP' | 'COP' | 'BRL' | 'ARS' | 'CLP' | 'PEN' | 'BOB' | 'PYG' | 'USDC' | 'USDT': Fourteen members, reconciled to the countries a customer can be onboarded in. USDC and USDT are stablecoins and require `chain`.
    - `rate` string
    - `quotedAt` string, date-time
    - `binding` false
  - `matchedDepositId` string, nullable

## Other responses

- `400`: Malformed request, so a missing required field, a wrong type or a bad enum.
- `404`: The resource does not exist, or belongs to another partner.
- `422`: Semantically invalid. The request is well-formed but violates a business rule. `param` names the field.

## Changes

- **2026-11-03** `20fef4fd2ab3`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/alfredpay/apis/alfred-penny-api-client-documentation/changes/v1/customers/:customerId/deposit_intents/post.md)

---

[API](https://skmtc.dev/alfredpay/apis/alfred-penny-api-client-documentation.md) - [All operations](https://skmtc.dev/alfredpay/apis/alfred-penny-api-client-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/alfredpay/apis/alfred-penny-api-client-documentation/revisions/20fef4fd2ab3?raw)