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

# App Payment Events

> app.payment.pending, app.payment.succeeded, and app.payment.failed for your app's own sales.

Three events share the `payment` resource. They are delivered in the
[Standard-Webhooks envelope](/docs/app-store/webhooks#event-envelope); the fields
below describe the `data` object. Every event requires the `read:self` scope.

| Event (`type`)          | Fires when                                    |
| ----------------------- | --------------------------------------------- |
| `app.payment.pending`   | A charge is created and awaiting confirmation |
| `app.payment.succeeded` | A charge succeeds                             |
| `app.payment.failed`    | A charge fails                                |

`app.payment.*` events cover **both** one-time purchases and subscription
charges; branch on `billing_reason` to tell them apart. The money and the access
state are separate events: a subscription's initial charge emits **both**
`app.payment.succeeded` (with `billing_reason: subscription_initial`) **and**
[`app.subscription.activated`](/docs/app-store/webhooks/subscriptions).

## Payment resource

`data.object` is `"payment"` for all three events.

| Field                 | Type           | Description                                                                                                 |
| --------------------- | -------------- | ----------------------------------------------------------------------------------------------------------- |
| `object`              | string         | Always `"payment"`                                                                                          |
| `id`                  | string         | Fanvue invoice number for the payment                                                                       |
| `status`              | string         | `pending` \| `succeeded` \| `failed`                                                                        |
| `billing_reason`      | string         | `one_time` \| `subscription_initial` \| `subscription_renewal`                                              |
| `gross`               | integer        | Gross amount in minor units                                                                                 |
| `currency`            | string \| null | ISO 4217 currency code                                                                                      |
| `reason`              | string \| null | Decline / failure message on `failed`; `null` for `pending` and `succeeded`                                 |
| `purchase_reference`  | string         | The `appotp_` purchase reference for a one-time purchase, or the subscription's billing reference otherwise |
| `client_reference_id` | string \| null | Reserved passthrough reference (currently always `null`)                                                    |
| `created_at`          | string \| null | ISO 8601 creation time                                                                                      |
| `paid_at`             | string \| null | ISO 8601 time the payment was paid (`null` until paid)                                                      |
| `item`                | object         | `{ uuid }` of the purchased pricing plan (`uuid` may be `null`)                                             |
| `app`                 | object         | `{ uuid }` of your app                                                                                      |
| `buyer`               | object         | `{ uuid }` of the buyer                                                                                     |
| `metadata`            | object         | Reserved passthrough metadata map (currently always empty)                                                  |

## Examples

### `app.payment.succeeded` (subscription initial charge)

```json theme={null}
{
  "id": "9f2c1e7a4b8d6f30a1c2e3d4b5a6978c0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b",
  "type": "app.payment.succeeded",
  "timestamp": "2026-06-17T13:12:45.123Z",
  "data": {
    "object": "payment",
    "id": "INV-2026-000123",
    "status": "succeeded",
    "billing_reason": "subscription_initial",
    "gross": 999,
    "currency": "USD",
    "reason": null,
    "purchase_reference": "sub_3f9a2b71-1c4e-4f8a-9d2b-7c6e5a4b3d21",
    "client_reference_id": null,
    "created_at": "2026-06-17T13:12:40.000Z",
    "paid_at": "2026-06-17T13:12:44.880Z",
    "item": { "uuid": "b2d7c9f0-4a13-4e6b-8f25-1a9c3e7d5b80" },
    "app": { "uuid": "a1c3e5f7-9b2d-4c6e-8a0f-2d4b6c8e0a13" },
    "buyer": { "uuid": "c4e6a8b0-2d4f-6a81-0c2e-4b6d8f0a2c46" },
    "metadata": {}
  }
}
```

A one-time purchase looks the same with `"billing_reason": "one_time"` and a
`purchase_reference` carrying the `appotp_` prefix; a renewal uses
`"billing_reason": "subscription_renewal"`.

### `app.payment.pending`

```json theme={null}
{
  "id": "1b2c3d4e5f60718293a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6",
  "type": "app.payment.pending",
  "timestamp": "2026-06-17T13:12:40.500Z",
  "data": {
    "object": "payment",
    "id": "INV-2026-000123",
    "status": "pending",
    "billing_reason": "one_time",
    "gross": 999,
    "currency": "USD",
    "reason": null,
    "purchase_reference": "appotp_3f9a2b71-1c4e-4f8a-9d2b-7c6e5a4b3d21",
    "client_reference_id": null,
    "created_at": "2026-06-17T13:12:40.000Z",
    "paid_at": null,
    "item": { "uuid": "b2d7c9f0-4a13-4e6b-8f25-1a9c3e7d5b80" },
    "app": { "uuid": "a1c3e5f7-9b2d-4c6e-8a0f-2d4b6c8e0a13" },
    "buyer": { "uuid": "c4e6a8b0-2d4f-6a81-0c2e-4b6d8f0a2c46" },
    "metadata": {}
  }
}
```

### `app.payment.failed`

```json theme={null}
{
  "id": "2c3d4e5f60718293a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7",
  "type": "app.payment.failed",
  "timestamp": "2026-06-17T13:12:45.000Z",
  "data": {
    "object": "payment",
    "id": "INV-2026-000123",
    "status": "failed",
    "billing_reason": "subscription_renewal",
    "gross": 999,
    "currency": "USD",
    "reason": "card_declined",
    "purchase_reference": "sub_3f9a2b71-1c4e-4f8a-9d2b-7c6e5a4b3d21",
    "client_reference_id": null,
    "created_at": "2026-06-17T13:12:40.000Z",
    "paid_at": null,
    "item": { "uuid": "b2d7c9f0-4a13-4e6b-8f25-1a9c3e7d5b80" },
    "app": { "uuid": "a1c3e5f7-9b2d-4c6e-8a0f-2d4b6c8e0a13" },
    "buyer": { "uuid": "c4e6a8b0-2d4f-6a81-0c2e-4b6d8f0a2c46" },
    "metadata": {}
  }
}
```

## Reconciling

Payments can be re-read by invoice number: `data.id` matches the
`invoiceNumber` path parameter on the app payments endpoints. See
[Reconciliation](/docs/app-store/webhooks#reconciliation).