ALalfredpay
Deposits

Announce a deposit you're expecting

Changed on

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.

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
    • HTTP bearer
    • or API key in header api-key and API key in header api-secret

Headers

Idempotency-Keystring uuid required

Required on every state-changing POST, simulators included; the only exempt POST is …/verifications/preflight. Replay (same key, same body) returns the original response with Idempotent-Replayed: true; same key with a different body → 409 idempotency_conflict. Keys are UUIDs, scoped to the API key, retained for 24 hours.

Request body

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

expiresAtstring date-time required
referencestring

Quoted by the payer. Stage 0 of attribution, and the only reliable match key.

payment_flow_idstring
metadataMetadata

Client-supplied key–value pairs, echoed on the object and every event about it.

Example request

{
  "expectedAmount": {
    "value": "10000.00"
  },
  "tolerance": {
    "underPct": "2.0",
    "overPct": "5.0"
  }
}

Response

Created

transaction_idstring 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_idstring nullable

Relates independent transactions in one flow. One completing never completes another.

resource_versioninteger

Monotonic per resource. Apply events in this order.

created_atstring date-time
updated_atstring date-time
idstring
customerIdstring
virtualAccountIdstring
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.

expiresAtstring date-time
referencestring
matchedDepositIdstring nullable

Example response

{
  "expectedAmount": {
    "value": "10000.00"
  }
}

Changes