---
title: "POST /v1/merchants"
method: POST
path: "/v1/merchants"
tags: ["aifp"]
---

# POST /v1/merchants

`POST /v1/merchants`

## Request

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

## Request body

- object
  - `settlement_version` '1.2' | '1.4': Explicit settlement generation. Omission defaults to 1.2 at registration and preserves the current selection on update. Selecting 1.4 does not enable operator deployment flags; quote-time readiness still applies.
  - `settlement_chain` string: Canonical settlement network compatible with the merchant's immutable network_mode. Omission preserves the current selection (or its legacy default). This field does not change the payout wallet.
  - `name` string, required: Merchant display name; server validates 3–80 trimmed characters.
  - `pay_to` object, required: Public merchant payout destinations, not payment instructions. At least one valid configured family is required. Recognized EVM network aliases may accompany the same EVM address; unknown keys are rejected. PATCH preserves omitted families; null clears only that family. Payout changes require owner step-up on the dashboard route. Stored NEAR/Aptos fields do not activate settlement or agent wallet claims.
    - `evm` string, nullable: One EVM address shared across EVM networks; validated for checksum and known burn addresses.
    - `polygon` string, nullable: Legacy alias for evm. Supplied aliases must identify the same EVM address.
    - `solana` string, nullable: Base58-encoded 32-byte public Solana address.
    - `near` string, nullable: Lowercase NEAR account ID. Format only, not account existence or ownership.
    - `aptos` union: Nonzero Aptos address: full 32-byte 0x hex or a one-digit special notation. Stored as lowercase full 32-byte hex.
      - string
      - string

## Response `201`

Successful response

## 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.
- `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)