# Create a Payment

Create a payment with `POST /v1/payments`.

For normal mock testing, use the same chain and asset in `receive` and `pay_with`. The API separates these fields so the contract can support more payment and settlement routes in future releases.

## Request

```bash
curl -X POST "https://mock.artum.app/v1/payments" \
  -H "Authorization: Bearer $ARTUM_MOCK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_1001_create_payment" \
  -H "X-Artum-Mock-Scenario: happy_path" \
  -d '{
    "order_id": "order_1001",
    "receive": {
      "chain": "bsc-mainnet",
      "asset": "bsc-usdt",
      "amount": "100000000000000000000",
      "address": "0x8ba1f109551bD432803012645Ac136ddd64DBA72"
    },
    "settlement": {
      "mode": "same_chain_merchant_payout"
    },
    "pay_with": [
      {
        "chain": "bsc-mainnet",
        "asset": "bsc-usdt"
      }
    ],
    "refund_to": {
      "chain": "bsc-mainnet",
      "address": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F"
    },
    "expires_at": "2026-05-13T15:30:00Z",
    "metadata": {
      "customer_id": "cus_1001"
    }
  }'
```

## Important Fields

* `order_id` is your internal order identifier.
* `receive.chain` is the chain where you want to receive settlement.
* `receive.asset` is the asset you want to receive.
* `receive.amount` is a raw integer token amount as a string.
* `receive.address` is the merchant payout address.
* `settlement.mode` is currently `same_chain_merchant_payout` in the mock API.
* `pay_with` contains the chain and asset the customer can pay with. The current mock API supports exactly one item.
* `refund_to` is the address used for refund handling.
* `expires_at` is an ISO 8601 timestamp.

In the current mock scope, `same_chain_merchant_payout` means the merchant receives the same chain payout represented by `receive`. Future releases can add more settlement modes without changing the basic payment object shape.

## Amounts

Amounts are raw token units, not decimal strings.

For an 18-decimal token:

```
100 USDT = 100000000000000000000
```

Get `decimals` from `GET /v1/chains/{chain}/assets`. See [Amounts and Decimals](/concepts/amounts-and-decimals.md).

## Fees

The customer should pay `instructions.amounts.due`.

The merchant receives `instructions.amounts.settlement`.

Artum's service fee is `instructions.amounts.fee` and is added on top of the settlement amount in the current mock flow. Network gas fees are separate from this service fee. See [Fees](/concepts/fees.md).

## Response

The response includes invoice instructions:

```json
{
  "id": "pay_mock_000001",
  "status": "awaiting_payment",
  "attempts": [
    {
      "id": "att_mock_000001",
      "instructions": {
        "type": "evm_invoice_address",
        "chain": "bsc-mainnet",
        "asset": "bsc-usdt",
        "invoice_address": "0x0000000000000000000000000000000000000001",
        "amounts": {
          "due": "100500000000000000000",
          "settlement": "100000000000000000000",
          "fee": "500000000000000000"
        }
      }
    }
  ]
}
```

Send the customer to pay `instructions.amounts.due` to `instructions.invoice_address` on `instructions.chain` with `instructions.asset`.

`instructions.type` tells the client how to interpret the instructions object. The current mock uses `evm_invoice_address`; future non-EVM rails can introduce different instruction types with different fields.

## Observed Transfer

After the mock API observes a transfer, the payment moves from `awaiting_payment` to `payment_detected` and includes a deposit similar to:

```json
{
  "status": "payment_detected",
  "attempts": [
    {
      "status": "payment_detected",
      "funding": {
        "amount_received_pending": "100500000000000000000",
        "amount_received_finalized": "0"
      },
      "deposits": [
        {
          "status": "pending",
          "confirmations": 0,
          "confirmations_required": 16
        }
      ]
    }
  ]
}
```

While finality progresses, the same deposit moves through `confirming` with `confirmations` values such as `4`, `8`, and `12`. At `16/16`, the deposit becomes `finalized` and finalized funding is reflected in `amount_received_finalized`.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.artum.app/payments/create-payment.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.