---
title: "Execute a conversion"
method: POST
path: "/v1/customers/{customerId}/conversions"
tags: ["Conversions"]
---

# Execute a conversion

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

## Request

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

Consumes a quote. The body is `quoteId` and `metadata`, nothing else: the customer plus the quote's currency pair fully determine which balance is debited and which is credited.

Don't run a conversion ahead of a cross-currency payout. The payout converts natively, and doing it separately creates a second transaction you don't need.

**Wait on** `conversion.updated`. See [Webhooks and events](/docs/webhooks-and-events).

## Headers

- `Idempotency-Key` string, uuid, required

## Request body

- object
  - `quoteId` string, required
  - `payment_flow_id` string
  - `metadata` Metadata: Client-supplied key–value pairs, echoed on the object and every event about it.

## Response `201`

Created

- Conversion: 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
  - `quoteId` string
  - `sell` object
    - `currency` string
    - `chain` string, nullable
    - `amount` string
  - `buy` object
    - `currency` string
    - `chain` string, nullable
    - `amount` string
  - `executionRate` string, nullable
  - `fees` Fee[]
    - `type` 'provider' | 'network' | 'alfred' | 'conversion' | 'payout'
    - `amount` string
    - `currency` string

## Other responses

- `202`: Accepted but routed to policy review, so `PENDING_COMPLIANCE` with `PAUSED`.
- `409`: `quote_expired` or `quote_consumed`.
- `422`: `insufficient_balance`

## 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/conversions/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)