---
title: "Register payment instrument"
method: POST
path: "/payment-instruments"
tags: ["payments"]
---

# Register payment instrument

`POST /payment-instruments`

Register a payment instrument for use in order creation.

## Request body

- EvmAuthCaptureEscrowInstrument — Base definition for any payment instrument.
  - `id` string, required — Unique instrument identifier.
  - `handler_id` string, required — Handler instance identifier.
  - `type` 'evm_auth_capture_escrow', required — Instrument category (e.g., 'card', 'tokenized_card').
  - `billing_address` PostalAddress
    - `extended_address` string — Address extension (apartment number, C/O, etc.).
    - `street_address` string — The street address.
    - `address_locality` string — City or locality.
    - `address_region` string — State, province, or region.
    - `address_country` string — Country (ISO 3166-1 alpha-2 recommended).
    - `postal_code` string — Postal code.
    - `first_name` string — Contact first name.
    - `last_name` string — Contact last name.
    - `phone_number` string — Contact phone number.
  - `credential` PaymentCredential — Base definition for any payment credential.
    - `type` string, required — Credential type discriminator.
  - `display` object — Display information for the instrument. Each payment instrument schema defines its specific display properties, as outlined by the payment handler.
  - `payment_info_hash` string, required — Hash identifying the on-chain payment authorization.
  - `operator` string, required — Operator address.
  - `payer` string, required — Payer address.
  - `chain_id` integer, required — EVM chain id.
  - `contract` string, required — Escrow contract address.
  - `receiver` string, required — Receiver address for captures.
  - `token` EvmToken, required — EVM token identifier used for auth/capture settlement.
    - `address` string — ERC-20 contract address. Omit for native gas tokens.
    - `symbol` string, required — Token symbol (e.g., USDC).
    - `decimals` integer, required — Token decimals.
  - `max_amount` EvmAmount, required — Amount denominated in an EVM token. Value is in atomic token units.
    - `value` string, required — Value in atomic token units as an integer string.
    - `currency` EvmCurrency, required — EVM token currency descriptor.
      - `chain_id` integer, required — EVM chain id.
      - `address` string, required — Token contract address.
      - `decimals` integer, required — Decimal places for the token.
  - `preapproval_expires_at` string, date-time, required — Pre-approval expiration (RFC 3339).
  - `authorization_expires_at` string, date-time, required — Authorization expiration (RFC 3339).
  - `refund_expires_at` string, date-time, required — Refund expiration (RFC 3339).
  - `nonce` string, required — Unique nonce for payment info hash computation.
  - `amount` EvmAmount, required — Amount denominated in an EVM token. Value is in atomic token units.
    - `value` string, required — Value in atomic token units as an integer string.
    - `currency` EvmCurrency, required — EVM token currency descriptor.
      - `chain_id` integer, required — EVM chain id.
      - `address` string, required — Token contract address.
      - `decimals` integer, required — Decimal places for the token.

## Response `201`

Payment instrument registered.

- EvmAuthCaptureEscrowInstrument — Base definition for any payment instrument.
  - `id` string, required — Unique instrument identifier.
  - `handler_id` string, required — Handler instance identifier.
  - `type` 'evm_auth_capture_escrow', required — Instrument category (e.g., 'card', 'tokenized_card').
  - `billing_address` PostalAddress
    - `extended_address` string — Address extension (apartment number, C/O, etc.).
    - `street_address` string — The street address.
    - `address_locality` string — City or locality.
    - `address_region` string — State, province, or region.
    - `address_country` string — Country (ISO 3166-1 alpha-2 recommended).
    - `postal_code` string — Postal code.
    - `first_name` string — Contact first name.
    - `last_name` string — Contact last name.
    - `phone_number` string — Contact phone number.
  - `credential` PaymentCredential — Base definition for any payment credential.
    - `type` string, required — Credential type discriminator.
  - `display` object — Display information for the instrument. Each payment instrument schema defines its specific display properties, as outlined by the payment handler.
  - `payment_info_hash` string, required — Hash identifying the on-chain payment authorization.
  - `operator` string, required — Operator address.
  - `payer` string, required — Payer address.
  - `chain_id` integer, required — EVM chain id.
  - `contract` string, required — Escrow contract address.
  - `receiver` string, required — Receiver address for captures.
  - `token` EvmToken, required — EVM token identifier used for auth/capture settlement.
    - `address` string — ERC-20 contract address. Omit for native gas tokens.
    - `symbol` string, required — Token symbol (e.g., USDC).
    - `decimals` integer, required — Token decimals.
  - `max_amount` EvmAmount, required — Amount denominated in an EVM token. Value is in atomic token units.
    - `value` string, required — Value in atomic token units as an integer string.
    - `currency` EvmCurrency, required — EVM token currency descriptor.
      - `chain_id` integer, required — EVM chain id.
      - `address` string, required — Token contract address.
      - `decimals` integer, required — Decimal places for the token.
  - `preapproval_expires_at` string, date-time, required — Pre-approval expiration (RFC 3339).
  - `authorization_expires_at` string, date-time, required — Authorization expiration (RFC 3339).
  - `refund_expires_at` string, date-time, required — Refund expiration (RFC 3339).
  - `nonce` string, required — Unique nonce for payment info hash computation.
  - `amount` EvmAmount, required — Amount denominated in an EVM token. Value is in atomic token units.
    - `value` string, required — Value in atomic token units as an integer string.
    - `currency` EvmCurrency, required — EVM token currency descriptor.
      - `chain_id` integer, required — EVM chain id.
      - `address` string, required — Token contract address.
      - `decimals` integer, required — Decimal places for the token.

## Other responses

- `400` — Invalid instrument data.
- `422` — Validation errors.

---

[API](https://skmtc.net/palette-labs-inc/apis/local-protocol.md) · [All operations](https://skmtc.net/palette-labs-inc/apis/local-protocol/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/palette-labs-inc/local-protocol/revisions/7db6ad75e16d/schema)