# Create merchant charge

Creates a charge for in-person payment acceptance.

Payment methods:
- nfc: Returns NFC payload for Tap-to-Pay
- qr: Returns QR code data and image URL
- alias: Resolves alias and creates charge

Endpoint: POST /v1/charges
Version: 2.0.0
Security: oAuth2

## Header parameters:

  - `Idempotency-Key` (string)
    A unique key to make POST requests idempotent.

## Request fields (application/json):

  - `merchantId` (string, required)
    Example: "mrc_01JH..."

  - `amount` (number, required)
    Example: 150

  - `currency` (string, required)
    Example: "GTQ"

  - `paymentMethod` (string, required)
    - nfc: Tap-to-Pay via NFC
- qr: QR code payment
- alias: Alias/handle resolution
- card_present: Card present (chip/swipe)
    Enum: "nfc", "qr", "alias", "card_present"

  - `description` (string,null)
    Example: "Purchase at Store #123"

  - `reference` (string,null)
    External reference (POS transaction ID, order number)

  - `expiresIn` (integer,null)
    Expiration time in seconds (default 300 for QR)
    Example: 300

  - `metadata` (object,null)

## Response 201 fields (application/json):

  - `chargeId` (string, required)
    Example: "chg_01JH..."

  - `merchantId` (string, required)

  - `amount` (number, required)

  - `currency` (string, required)

  - `status` (string, required)
    Enum: "requires_payment", "processing", "succeeded", "failed", "cancelled", "refunded"

  - `paymentMethod` (string, required)
    - nfc: Tap-to-Pay via NFC
- qr: QR code payment
- alias: Alias/handle resolution
- card_present: Card present (chip/swipe)
    Enum: "nfc", "qr", "alias", "card_present"

  - `description` (string,null)

  - `reference` (string,null)

  - `qr` (object)

  - `qr.data` (string)
    QR payload (for rendering)

  - `qr.imageUrl` (string)
    Pre-rendered QR image URL

  - `qr.expiresAt` (string)

  - `payer` (object)

  - `payer.walletId` (string)

  - `payer.displayName` (string)

  - `txHash` (string,null)

  - `providerRef` (string,null)

  - `createdAt` (string, required)

  - `paidAt` (string,null)

## Response 400 fields (application/json):

  - `traceId` (string, required)
    Correlation id for troubleshooting
    Example: "trc_01JH8K5P3V9M2K5Q7W6J3Z1A9B"

  - `error` (object, required)

  - `error.code` (string)
    Example: "INVALID_REQUEST"

  - `error.message` (string)
    Example: "Invalid merchant ID"

  - `error.details` (object)


## Response 401 fields