---
title: "Build a gross-inclusive v1.3 settlement instruction"
method: POST
path: "/v1/settlement/invoice"
tags: ["settlement"]
---

# Build a gross-inclusive v1.3 settlement instruction

`POST /v1/settlement/invoice`

## Request

- Base URL: `https://api.aifinpay.io`
- URL: `https://api.aifinpay.io/v1/settlement/invoice`
- Auth: none required

Requires a currently enabled canonical route. Rejects unknown assets, zero payout addresses, oversized orders and invalid expiry before returning calldata. The caller signs and submits from its own wallet.

## Request body

- union
  - object
    - `route_class` 'AIFP-1' | 'AIFP-2', required
    - `chain` string, required: network returned by GET /v1/settlement/routes
    - `asset` string, required: The route's native_asset or one of its stable_assets keys; case insensitive.
    - `gross_amount` string, required: Positive decimal uint256 in atomic units, at most 2^256-1. Includes the protocol fee.
    - `merchant_wallet` string, required
    - `provider_wallet` string
    - `order_id` string, required: Nonblank, at most 256 UTF-8 bytes. Bytes are validated separately from character length.
    - `valid_until` integer: Unix seconds, greater than the server's current time and no more than 1200 seconds ahead. Omit for 900 seconds; null is invalid.
  - object
    - `route_class` 'AIFP-1' | 'AIFP-2', required
    - `chain` string, required: network returned by GET /v1/settlement/routes
    - `asset` string, required: The route's native_asset or one of its stable_assets keys; case insensitive.
    - `gross_amount` string, required: Positive decimal uint256 in atomic units, at most 2^256-1. Includes the protocol fee.
    - `merchant_wallet` string
    - `provider_wallet` string, required
    - `order_id` string, required: Nonblank, at most 256 UTF-8 bytes. Bytes are validated separately from character length.
    - `valid_until` integer: Unix seconds, greater than the server's current time and no more than 1200 seconds ahead. Omit for 900 seconds; null is invalid.

## Response `200`

Successful response

- unknown

## Other responses

- `400`: AIFP-* error envelope. See backend/server.js safe error handler.
- `401`: AIFP-* error envelope. See backend/server.js safe error handler.
- `403`: AIFP-* error envelope. See backend/server.js safe error handler.
- `404`: AIFP-* error envelope. See backend/server.js safe error handler.
- `409`: Route is disabled, superseded, outside its validity window, unknown or not v1.3.
- `429`: AIFP-* error envelope. See backend/server.js safe error handler.
- `5XX`: AIFP-* error envelope. See backend/server.js safe error handler.

---

[API](https://skmtc.dev/aifinpay/apis/aifinpay-api.md) · [All operations](https://skmtc.dev/aifinpay/apis/aifinpay-api/llms.txt) · [OpenAPI document](https://skmtc.dev/aifinpay/apis/aifinpay-api/revisions/a9a644bb441d?raw)