---
title: "Create payment"
method: POST
path: "/payments"
tags: ["Payments"]
---

# Create payment

`POST /payments`

Creates a fiat pre-fund/settlement or a crypto payout. The request body must match one of the four documented shapes; submitting both `total` and `quantity` on a payout is rejected.

## Headers

- `X-SCX-SIGNED` string, required
- `X-SCX-TIMESTAMP` string, required
- `X-Simulator-Scenario` string

## Request body

- union — Exactly one of the following payload shapes must be submitted. Providing both `total` and `quantity` on a payout is rejected by the validator.
  - object
    - `participant_code` string, required — Participant the fiat transaction belongs to.
    - `external_account_id` string, uuid, required — External fiat account previously linked via `POST /payments/external_accounts`.
    - `currency` string, required — Fiat currency of the transaction (ISO 4217 3-letter code).
    - `amount` string, required — Transaction amount in `currency` units.
    - `transfer_type` 'credit' | 'debit', required — Direction of funds. `debit` pulls funds from the external account (pre-fund); `credit` sends funds to the external account.
    - `network` string[] — Ordered preference list of fiat rails. When omitted, the service selects the best eligible rail.
    - `description` string — Bank statement descriptor. Will appear on statements as `ZH <description>` (effective max 15 chars including the `ZH` prefix).
    - `account_label` string — Account label for routing the payment to a specific labeled account. Defaults to `general`.
    - `ach_agreement_acceptance` object — Optional ACH authorization acceptance evidence for debit transactions.
      - `timestamp` number, required — Unix timestamp in milliseconds when the customer accepted the agreement.
      - `version` string, required — Version of the ACH agreement that was accepted.
  - object
    - `participant_code` string, required — Participant the fiat transaction belongs to.
    - `external_account_id` string, uuid, required — External fiat account that will settle the trade.
    - `trade_id` string, uuid, required — Identifier of the trade to settle via ACH.
    - `description` string — Optional free-text description.
    - `account_label` string — Account label on the customer side. Defaults to `general`.
  - object
    - `participant_code` string, required — Participant the payout belongs to.
    - `obo_participant` OBOParticipantEntity, required
      - `participant_code` string — The identifier of the participant making the request
      - `account_group` string — The identifier of the the account group
      - `account_label` string — The account label associated with the account
    - `external_account_id` string, uuid, required — External crypto account that will receive the payout.
    - `asset` string, required — Asset to be delivered to the external account.
    - `quoted_asset` string, required — Currency the payout is priced in.
    - `payment_type` 'payout', required
    - `total` string, required — Payout total expressed in the `quoted_asset`.
    - `description` string — Optional free-text description carried through to the resulting payment record.
  - object
    - `participant_code` string, required — Participant the payout belongs to.
    - `obo_participant` OBOParticipantEntity, required
      - `participant_code` string — The identifier of the participant making the request
      - `account_group` string — The identifier of the the account group
      - `account_label` string — The account label associated with the account
    - `external_account_id` string, uuid, required — External crypto account that will receive the payout.
    - `asset` string, required — Asset to be delivered to the external account.
    - `quoted_asset` string, required — Currency the payout is priced in.
    - `payment_type` 'payout', required
    - `quantity` string, required — Payout quantity expressed in the `asset`.
    - `description` string — Optional free-text description carried through to the resulting payment record.

## Response `201`

Successfully created payment. Returns the created resource with generated IDs and timestamps.

- union
  - object
    - `request_id` string, uuid — Request identifier echoed back from the request.
    - `transaction_id` string, uuid — Identifier of the created fiat transaction. Use `/payments/status` to poll for lifecycle updates.
    - `external_account_id` string, uuid — External fiat account used for the transaction.
    - `trade_id` string — Linked trade identifier when the fiat transaction settles a trade. Empty string for stand-alone pre-funds.
    - `description` string — Echoed `description` from the request (if any).
    - `amount` string — Transaction amount in the `currency` unit.
    - `status` 'submitted' | 'pending' | 'pending_trade' | 'posted' | 'settled' | 'cancelled' | 'failed' | 'returned' | 'returned_settled' | 'rejected' | 'retried' | 'unspecified' — Initial ACH transfer status. Typically `submitted`.
    - `transfer_type` 'credit' | 'debit' | 'unspecified' — Whether the platform is crediting (pay-out) or debiting (pre-fund) the external account.
    - `network` 'ach' | 'same_day_ach' | 'wire' | 'rtp' | 'unspecified' — Fiat rail selected for this transaction.
    - `participant_code` string — Participant the transaction is associated with.
    - `account_label` string — Account label on the participant side.
    - `currency` string — Fiat currency of the transaction.
    - `created_at` string, date-time — Creation time of the transaction. Omitted when the transaction is in `pending_trade` because the underlying transfer has not been created yet.
    - `ach_agreement_acceptance` object — Present only when the client submitted `ach_agreement_acceptance` on the request and it was persisted.
      - `timestamp` number — Unix timestamp in seconds when the acceptance was signed.
      - `version` string — Version of the ACH agreement that was accepted.
  - object
    - `request_id` string, uuid — Request identifier echoed back from the request.
    - `participant_code` string — Participant the payout belongs to.
    - `platform_code` string — Platform that initiated the payout.
    - `obo_participant` OBOParticipantEntity
      - `participant_code` string — The identifier of the participant making the request
      - `account_group` string — The identifier of the the account group
      - `account_label` string — The account label associated with the account
    - `payment_id` string, uuid — Identifier of the created payout. Use `/payments/{payment_id}` to fetch lifecycle state.
    - `asset` string — Asset delivered to the external account.
    - `network` string — Blockchain network the payout is settled on.
    - `quoted_asset` string — Currency the payout amount was quoted in.
    - `status` 'submitted' | 'pending' | 'posted' | 'settled' | 'failed' | 'initialized' | 'abandoned' | 'unspecified' — Initial payout status; typically `submitted`.
    - `external_account_id` string, uuid — External crypto account receiving the payout.
    - `total` string — Payout total in the `quoted_asset`. Present when the request supplied `total`.
    - `quantity` string — Payout quantity in the `asset`. Present when the request supplied `quantity`.
    - `reference_id` string — Platform-supplied reference identifier passed through from the generating token. Empty string when not supplied.
    - `created_at` string, date-time — Creation time of the payout.

## Other responses

- `400` — Bad Request
- `403` — Forbidden
- `404` — Not Found
- `500` — Internal Server Error
- `503` — Service Unavailable

---

[API](https://skmtc.net/zerohash/apis/zerohash-api.md) · [All operations](https://skmtc.net/zerohash/apis/zerohash-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/zerohash/zerohash-api/revisions/8b647d934363/schema)