> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jenzy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a desk order

> Consume a quote. A to-bank order needs a `beneficiary` and holds `from_amount` of your stablecoin balance at once; the response is `accepted`. A from-bank order takes no beneficiary and holds nothing; the response is `awaiting_instructions` — wait for `order.awaiting_funds`, then wire `funding.amount` with `funding.reference` before `expires_at`. Orders are filled by hand by Jenzy’s desk, so they take hours to days; there is no cancel endpoint. Requires an `Idempotency-Key`: a retry with the same key and body returns the original order.



## OpenAPI

````yaml /v2/openapi.json post /orders
openapi: 3.1.0
info:
  title: Jenzy Hermes Multi-asset API
  version: 2.0.0
  description: >-
    Hold and pay out across the assets enabled for your organization. Every
    amount is an exact decimal string beside an `asset` field. Authenticate with
    the same `jz_live_…` API key as `/v1`.
servers:
  - url: https://api.jenzy.com/v2
    description: Production
security: []
paths:
  /orders:
    post:
      summary: Create a desk order
      description: >-
        Consume a quote. A to-bank order needs a `beneficiary` and holds
        `from_amount` of your stablecoin balance at once; the response is
        `accepted`. A from-bank order takes no beneficiary and holds nothing;
        the response is `awaiting_instructions` — wait for
        `order.awaiting_funds`, then wire `funding.amount` with
        `funding.reference` before `expires_at`. Orders are filled by hand by
        Jenzy’s desk, so they take hours to days; there is no cancel endpoint.
        Requires an `Idempotency-Key`: a retry with the same key and body
        returns the original order.
      parameters:
        - schema:
            type: string
            description: >-
              Required. A key you mint per order intent (a UUID works). Replays
              of the same key + body return the original response; the same key
              with a different body is a 409.
          required: true
          description: >-
            Required. A key you mint per order intent (a UUID works). Replays of
            the same key + body return the original response; the same key with
            a different body is a 409.
          name: Idempotency-Key
          in: header
        - $ref: '#/components/parameters/HermesOrg'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderCreate'
      responses:
        '201':
          description: >-
            Created: `accepted` (to-bank order, stablecoin held) or
            `awaiting_instructions` (from-bank order).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          description: Malformed body or missing `Idempotency-Key`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Missing, malformed, or revoked API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '402':
          description: >-
            `insufficient_funds`: your available stablecoin balance is short of
            `from_amount`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: >-
            Organization suspended, request IP not on the allowlist, no
            multi-asset access yet (`onboarding_incomplete` /
            `access_suspended`), or the desk is not enabled for your
            organization (`corridor_not_enabled`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: No quote with this id in your organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: >-
            `quote_used` — this quote already has an order; `client_ref_used` —
            this `client_ref` is on another order of yours; or `conflict` — this
            `Idempotency-Key` was used with a different body, or its original
            request is still in progress.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '422':
          description: >-
            `quote_expired` — take a new quote; `beneficiary_required` (to-bank
            order without one); `beneficiary_not_allowed` (from-bank order with
            one).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '503':
          description: >-
            The desk is closed (`service_maintenance` / `service_incident`; `GET
            /v2/orders/corridors` shows every corridor closed), or the `/v2`
            shutter is closed. Nothing was created; retry later.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      security:
        - ApiKeyAuth: []
components:
  parameters:
    HermesOrg:
      name: HERMES-ORG
      in: header
      required: false
      description: >-
        The id of one of your Child orgs. The call then acts on that Child org,
        not on your organization. If you do not send it, the call acts on your
        organization. An id that is not one of your Child orgs gives `404`.
      schema:
        type: string
        format: uuid
        example: 3f1c2a9e-8b7d-4e21-9a6f-0c5d4b3e2a10
  schemas:
    OrderCreate:
      type: object
      properties:
        quote_id:
          type: string
          format: uuid
          description: A `quote_id` from `POST /v2/orders/quotes`, not yet expired or used.
        client_ref:
          type: string
          minLength: 1
          maxLength: 64
          description: >-
            Your reference for this order, at most 64 characters, unique across
            your orders; reuse is `client_ref_used` (409). Jenzy does not send
            it to the bank.
          example: inv-1042
        beneficiary:
          $ref: '#/components/schemas/OrderBeneficiary'
      required:
        - quote_id
        - client_ref
    Order:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The order id — your handle for polling and support.
        client_ref:
          type: string
          example: inv-1042
        from_asset:
          type: string
          minLength: 1
          description: >-
            An asset code as `GET /v2/assets` lists it — uppercase, never
            compound (`USDC`, `USD`; never `USDC-ETHEREUM`). Network and rail
            live on the payment object.
          example: USDT
        from_amount:
          type: string
          description: >-
            What you pay, in `from_asset`. On a to-bank order this is held from
            your balance at creation.
          example: '1000'
        to_asset:
          type: string
          minLength: 1
          description: >-
            An asset code as `GET /v2/assets` lists it — uppercase, never
            compound (`USDC`, `USD`; never `USDC-ETHEREUM`). Network and rail
            live on the payment object.
          example: BIF
        to_amount:
          type: string
          description: >-
            What the beneficiary receives (to-bank order) or you are credited
            (from-bank order), in `to_asset`.
          example: '2850500'
        rate:
          type: string
          description: 'The quote’s rate: corridor currency per one stablecoin.'
          example: '2850.5'
        status:
          type: string
          enum:
            - accepted
            - processing
            - awaiting_instructions
            - awaiting_funds
            - proof_submitted
            - funds_confirmed
            - expired
            - completed
            - failed
            - cancelled
          description: >-
            To-bank order: `accepted` (your stablecoin is held) → `processing`
            (the desk is paying the beneficiary) → `completed` | `failed` |
            `cancelled`. From-bank order: `awaiting_instructions` →
            `awaiting_funds` (see `funding`; wire before `expires_at`) →
            `proof_submitted` → `funds_confirmed` → `completed` | `expired` |
            `failed` | `cancelled`. There is no cancel endpoint; ask Jenzy
            operations.
          example: accepted
        failure:
          type:
            - object
            - 'null'
          properties:
            code:
              type: string
              enum:
                - unable_to_fill
                - beneficiary_rejected
                - funds_not_received
                - not_delivered
                - other
            message:
              type: string
          required:
            - code
            - message
          description: >-
            Set only on `failed`: one of the published codes with its fixed
            message.
        refund:
          type: object
          properties:
            status:
              type: string
              enum:
                - pending
                - returned
          required:
            - status
          description: >-
            Present on a to-bank order that failed after the coins had left.
            `pending` — your stablecoin is on its way back; `returned` — it has
            been credited to your balance as a collection.
        beneficiary:
          type: object
          properties:
            name:
              type: string
            bank_name:
              type: string
            account_number:
              type: string
            branch:
              type: string
          required:
            - name
            - bank_name
            - account_number
          description: To-bank orders only, exactly as you sent it.
        funding:
          type: object
          properties:
            bank_name:
              type: string
            account_name:
              type: string
            account_number:
              type: string
            reference:
              type: string
              description: >-
                Write this on your transfer. It is how the desk matches your
                money to this order.
            amount:
              type: string
              description: Exactly `from_amount`.
            asset:
              type: string
              description: Exactly `from_asset`.
            deadline:
              type: string
              format: date-time
              description: Equals `expires_at`.
          required:
            - bank_name
            - account_name
            - account_number
            - reference
            - amount
            - asset
            - deadline
          description: >-
            From-bank orders only, present from `awaiting_funds`: where to wire
            your `from_amount`. Immutable once set.
        proofs:
          type: object
          properties:
            funding:
              type: object
              properties:
                uploaded_at:
                  type: string
                  format: date-time
                rejected_reason:
                  type: string
                  description: Present when the desk rejected this proof; upload a new one.
              required:
                - uploaded_at
          description: Your newest funding proof on a from-bank order, if any.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
          description: >-
            From-bank orders only: the funding deadline. Past it with no proof
            the order is `expired`.
        receipt_url:
          type:
            - string
            - 'null'
          format: uri
          description: >-
            The public link to the receipt of an order that pays a bank
            beneficiary. Send it to your beneficiary: the page shows the status
            of the payment, not your fee or rate. Null on an order that pays
            you. In the sandbox the link is on `track.sandbox.jenzy.com`.
      required:
        - id
        - client_ref
        - from_asset
        - from_amount
        - to_asset
        - to_amount
        - rate
        - status
        - failure
        - proofs
        - created_at
        - updated_at
        - receipt_url
    ErrorEnvelope:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - validation_error
                - unauthorized
                - forbidden
                - not_found
                - conflict
                - rate_limited
                - internal_error
                - unknown_institution
                - invalid_mobile_number
                - invalid_account_number
                - mobile_number_institution_mismatch
                - service_unavailable
                - sandbox_only
                - insufficient_funds
                - rail_disabled
                - amount_limit_exceeded
                - org_limit_exceeded
                - service_incident
                - service_maintenance
                - onboarding_incomplete
                - access_suspended
                - corridor_not_enabled
                - unsupported_pair
                - invalid_wallet_address
                - rate_unavailable
                - quote_expired
                - quote_used
                - limit_exceeded
                - amount_below_minimum
                - unsupported_asset
                - unsupported_network
                - unsupported_media_type
                - payload_too_large
                - client_ref_used
                - beneficiary_required
                - beneficiary_not_allowed
                - proof_not_expected
                - invalid_beneficiary
                - beneficiary_exists
                - beneficiary_not_active
                - invoice_required
                - prohibited_industry
              description: >-
                Stable identifier a client may branch on — never renamed or
                removed.
            message:
              type: string
          required:
            - code
            - message
      required:
        - error
    OrderBeneficiary:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 200
          description: The account holder, as it appears at their bank.
          example: Aline Niyonzima
        bank_name:
          type: string
          minLength: 1
          maxLength: 200
          description: >-
            The bank, by name — free text. There is no institution list for
            corridor currencies; the desk pays by hand and screens what you
            send.
          example: Banque de Crédit de Bujumbura
        account_number:
          type: string
          minLength: 1
          maxLength: 200
          description: >-
            As the bank prints it. Stored and forwarded as sent, never
            normalised or verified.
          example: '0001234567'
        branch:
          type: string
          minLength: 1
          maxLength: 200
          description: Optional branch name or code, where the account format needs one.
          example: Rohero
      required:
        - name
        - bank_name
        - account_number
      description: >-
        Required on a to-bank order (stablecoin → corridor currency): who
        receives the fiat. Must be absent on a from-bank order
        (`beneficiary_not_allowed`).
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      description: 'Your Jenzy API key: `Authorization: Bearer jz_live_…`'

````

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