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

# Create payment intent

> Create a new payment intent for checkout.

Creates a payment intent for the merchant identified by your API key.

* Base URL: `https://api.kryptopay.xyz`
* Auth: `Authorization: Bearer <api_key>`
* Mode is inferred from your API key (`testnet` or `mainnet`)

## Integration examples

### cURL

```bash theme={null}
curl -X POST "https://api.kryptopay.xyz/v1/payment_intents" \
  -H "Authorization: Bearer kp_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_units": 1500000,
    "chain": "base",
    "expires_in_minutes": 15,
    "lane": "sdk",
    "metadata": { "order_id": "ord_2026_1001" }
  }'
```

### Node.js (server)

```js theme={null}
const response = await fetch("https://api.kryptopay.xyz/v1/payment_intents", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.KRYPTOPAY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount_units: 1500000,
    chain: "base",
    expires_in_minutes: 15,
    lane: "sdk",
    metadata: { order_id: "ord_2026_1001" },
  }),
});

const intent = await response.json();
```

### Python (coming soon)

Python examples and helpers are planned. Until then, use normal HTTP requests with the same payload and Bearer auth.

## Field guide (plain language)

* `amount_units`: integer amount in smallest unit (USDC usually 6 decimals)
* `chain`: target chain (`base` or `polygon`)
* `wallet_address`: optional payout wallet override (`0x...`)
* `expires_in_minutes`: checkout expiry window (server clamps to `5..60`)
* `lane`: checkout lane (`sdk` or `manual`)
* `metadata`: your internal identifiers (`order_id`, `customer_id`, etc)
* `token`: currently `USDC`

## What you should persist

Persist at minimum:

* your internal order ID
* payment intent ID
* returned mode/chain
* status transitions in your backend

## Error handling checklist

* Retry transient failures (`500`, network)
* Do not retry auth failures (`api_key_missing`, `api_key_invalid`)
* Fix request shape for `invalid_body`
* Log full response body for debugging and support


## OpenAPI

````yaml POST /v1/payment_intents
openapi: 3.1.0
info:
  title: KryptoPay API
  version: 1.0.0
  description: Public KryptoPay API for merchant payment integrations.
servers:
  - url: https://api.kryptopay.xyz
    description: KryptoPay API
security: []
paths:
  /v1/payment_intents:
    post:
      tags:
        - Payment Intents
      summary: Create payment intent
      description: >-
        Creates a payment intent. Mode is derived from the API key and cannot be
        overridden by request payload.
      operationId: createPaymentIntent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePaymentIntentRequest'
            examples:
              sdkCheckout:
                summary: SDK checkout intent
                value:
                  amount_units: 1500000
                  chain: base
                  expires_in_minutes: 15
                  lane: sdk
                  metadata:
                    order_id: ord_2026_1001
      responses:
        '200':
          description: Payment intent created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePaymentIntentResponse'
        '400':
          description: Validation or request error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalidBody:
                  value:
                    error: invalid_body
                walletInvalid:
                  value:
                    error: wallet_invalid
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing:
                  value:
                    error: api_key_missing
                invalid:
                  value:
                    error: api_key_invalid
        '404':
          description: Related resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                merchant:
                  value:
                    error: merchant_not_found
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                conflict:
                  value:
                    error: conflict
        '500':
          description: Internal error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                internal:
                  value:
                    error: internal_error
      security:
        - bearerAuth: []
components:
  schemas:
    CreatePaymentIntentRequest:
      type: object
      required:
        - amount_units
      properties:
        amount_units:
          type: integer
          minimum: 1
          description: Payment amount in smallest token units (USDC uses 6 decimals).
        chain:
          type: string
          enum:
            - base
            - polygon
        wallet_address:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
          description: Optional recipient wallet override.
        expires_in_minutes:
          type: integer
          description: Intent expiry in minutes. Server clamps to 5..60.
        lane:
          type: string
          enum:
            - sdk
            - manual
        metadata:
          type: object
          additionalProperties: true
        token:
          type: string
          enum:
            - USDC
          description: Optional token selector. Currently USDC only.
      additionalProperties: false
    CreatePaymentIntentResponse:
      type: object
      required:
        - id
        - status
        - client_secret
        - mode
        - chain
        - chain_id
        - confirmations_required
        - amount_units
        - decimals
        - token_symbol
        - token_address
        - expected_wallet
        - expires_at
        - expires_in_minutes
        - lane
        - metadata
      properties:
        id:
          type: string
        status:
          type: string
          example: requires_payment
        client_secret:
          type: string
        mode:
          type: string
          enum:
            - testnet
            - mainnet
        chain:
          type: string
          enum:
            - base
            - polygon
        chain_id:
          type: integer
        confirmations_required:
          type: integer
        amount_units:
          type: integer
        decimals:
          type: integer
          example: 6
        token_symbol:
          type: string
          example: USDC
        token_address:
          type: string
        expected_wallet:
          type: string
        expires_at:
          type: string
          format: date-time
        expires_in_minutes:
          type: integer
        lane:
          type: string
          enum:
            - sdk
            - manual
        metadata:
          type: object
          additionalProperties: true
      additionalProperties: true
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
      additionalProperties: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key

````