## Create a payment (agent pays on a customer's behalf)

**post** `/v3/payments`

Advances the pay flow for a connected customer handle and returns a
`status` describing where it is (`needs_connection`, `awaiting_user_action`,
`ready`, ...). A payment `id` appears once a card is minted. Idempotent on
the `Idempotency-Key` header.

### Body Parameters

- `amount_cents: number`

- `currency: string`

- `handle: string`

  Customer phone (E.164) or email.

- `description: optional string`

- `merchant: optional object { name, url }`

  - `name: optional string`

  - `url: optional string`

- `metadata: optional map[string]`

### Returns

- `Payment object { id, amount_cents, approval_url, 7 more }`

  - `id: optional string`

  - `amount_cents: optional number`

  - `approval_url: optional string`

    Present on `awaiting_user_action` once a card is on file and the
    charge needs the customer's passkey. Re-send the create request with
    the same `Idempotency-Key` to collect the payment after they approve.

  - `attach_url: optional string`

    Present on `awaiting_user_action` when the customer has no card on
    file yet. A hosted page — open it for them; it stays valid for about
    48 hours. Not returned on `needs_connection`: connect the handle first.

  - `currency: optional string`

  - `description: optional string`

  - `handle: optional string`

  - `merchant: optional object { name, url }`

    The merchant the card is minted against, echoed from the request.

    - `name: optional string`

    - `url: optional string`

  - `metadata: optional map[string]`

    Your own key/values, echoed back from the request.

  - `status: optional "needs_connection" or "connecting" or "awaiting_user_action" or 6 more`

    - `"needs_connection"`

    - `"connecting"`

    - `"awaiting_user_action"`

    - `"ready"`

    - `"authorized"`

    - `"succeeded"`

    - `"declined"`

    - `"canceled"`

    - `"expired"`

### Example

```http
curl https://api.linqapp.com/api/partner/v3/payments \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $LINQ_API_V3_API_KEY" \
    -d '{
          "amount_cents": 2500,
          "currency": "usd",
          "handle": "+14155550123",
          "description": "Burger order"
        }'
```

#### Response

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "amount_cents": 2500,
  "approval_url": "approval_url",
  "attach_url": "https://app.agentcard.sh/attach/eyJhbGciOi...",
  "currency": "usd",
  "description": "description",
  "handle": "+14155550123",
  "merchant": {
    "name": "DoorDash",
    "url": "doordash.com"
  },
  "metadata": {
    "foo": "string"
  },
  "status": "ready"
}
```