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

# Payments

> Payment methods, invoices, and payment states.

## Payment methods

`GET /retailer/v1/payment-methods` lists every active method — crypto coins, Lightning, and the internal *balance* method. Each record carries display data (`name`, `imageUrl`, `feeInfo`), constraints (`minAmountUSD`, `memoRequired`), and refund policy fields.

When a method is returned *with a checkout* (`availablePaymentMethods`), it gains an `eligible` boolean: `false` means the checkout total is below the method's `minAmountUSD`. Show ineligible methods greyed out with a tooltip rather than hiding them.

## The payment invoice

Creating a payment (one-call checkout, `POST /retailer/v1/checkouts/{id}/payment`, or a deposit with `paymentMethodId`) returns an invoice object. The fields you render depend on the provider type:

| Field                                | Meaning                                                                   |
| ------------------------------------ | ------------------------------------------------------------------------- |
| `paymentAddress`                     | Crypto address to pay to                                                  |
| `amount`, `currency`                 | Exact crypto amount to send, as a string (for example `"0.00016589"` BTC) |
| `memo` / `destinationTag`            | Required for XLM / XRP — payments without them can be lost                |
| `paymentUrl`                         | Redirect URL for hosted providers                                         |
| `qr.withAmount` / `qr.withoutAmount` | QR payload strings for wallet scanning                                    |
| `expiresAt`                          | Invoice expiry (epoch ms) — re-quote after this                           |
| `appliedAmount`, `appliedCurrency`   | What gets credited toward the checkout                                    |
| `providerAmount`, `providerCurrency` | What is invoiced at the provider                                          |

<Warning>
  When `memo` or `destinationTag` is present, your customer **must** include it in the transfer. Funds sent without it may not be credited.
</Warning>

### Expired invoices

Crypto invoices expire. Call `POST /retailer/v1/checkouts/{id}/payment` again with the same method — the provider deduplicates and returns the same invoice refreshed (new expiry, same address where possible).

## Aggregate payment state

`GET /retailer/v1/checkouts/{id}` (and the deposit detail endpoint) return a `payment` object summarizing all payments on the record:

```json theme={null}
{
  "state": "partial",
  "confirmedAmount": 30,
  "totalAmount": 50,
  "currency": "USDT",
  "payments": [
    {
      "paymentId": "pay_x1",
      "method": "USDT (TRC-20)",
      "amount": 50,
      "status": "confirming",
      "partialPayment": { "sentAmount": 30, "expectedAmount": 50, "currency": "USDT" }
    }
  ]
}
```

| `state`     | Meaning                         |
| ----------- | ------------------------------- |
| `pending`   | No payment detected yet         |
| `partial`   | Some value received, not enough |
| `confirmed` | Fully paid — fulfillment starts |
| `failed`    | Payment failed                  |

`partialPayment` shows crypto under-payment progress ("30 of 50 USDT received") so you can prompt the customer to send the remainder.

## Prepaid balance payments

Both surfaces can pay with the internal *balance* method:

* **B2B orders** always pay with balance — that is the surface's model.
* **Retailer checkouts** can pass the balance method id to prepay from your business balance instead of invoicing the customer.

Balance payments settle synchronously. If the deduction cannot confirm (typically insufficient balance), the call fails with `400 VALIDATION_ERROR` and the reason in `error.details.reason` — no order is left half-paid.

## Payment record statuses

Individual payment records move `pending → confirming → confirmed` or `failed`. `confirming` means the transaction is detected and awaiting network confirmations. The retailer webhook events [`payment.detected` and `payment.confirmed`](/webhooks/events) map to these transitions.