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

# Webhook event object

> The shape of every webhook Payve sends: the request, the envelope, and a full payload for each of the seven events.

Every event has the same envelope. `data` holds the transaction.

```json
{
  "id": "evt_5d0a7c3e9b1f42866e0d1a2b3c4d5e6f",
  "type": "payout.successful",
  "merchantId": "318",
  "data": {},
  "createdAt": "2026-11-18T10:00:17.000Z"
}
```

| Field | Type | Meaning |
| - | - | - |
| `id` | string | The event id. The same on every retry. De-duplicate on it. |
| `type` | string | The event type. |
| `merchantId` | string | Your Payve account id. |
| `data` | object | The transaction, described below. |
| `createdAt` | string | When the event was created. ISO 8601, UTC. |

## The forms an event takes

The same event reaches you in one of three forms, depending on how you look at it and how it was sent.

> [tab] The HTTP request
>
> What arrives at your endpoint: a signed `POST` with a JSON body.
>
> ```http
> POST /webhooks/payve HTTP/1.1
> Content-Type: application/json
> X-Payve-Event: payout.successful
> X-Payve-Timestamp: 1763460017
> X-Payve-Signature: t=1763460017,v1=5c7e0d6a1b9f48e2c3a7d4f1e8b2a6c9d0e3f5a7b1c4d8e2f6a9b3c7d1e5f0a4
>
> {"id":"evt_5d0a7c3e9b1f42866e0d1a2b3c4d5e6f","type":"payout.successful","merchantId":"318","data":{...},"createdAt":"2026-11-18T10:00:17.000Z"}
> ```
>
> Verify `X-Payve-Signature` against the raw body before you parse it. See [Verify signatures](/webhooks/verify-signatures.md).

> [tab] Automatic event
>
> Sent by Payve when a transaction finishes. The event `id` starts with `evt_` and stays the same on every retry. Field names in `data` are snake\_case, and `data` holds the full transaction.
>
> ```json
> {
>   "id": "evt_5d0a7c3e9b1f42866e0d1a2b3c4d5e6f",
>   "type": "payout.successful",
>   "merchantId": "318",
>   "data": {
>     "id": "1842",
>     "public_id": "pyt_9c2e41b7a05d3f68",
>     "status": "successful",
>     "source_currency": "NGN",
>     "source_amount": "5000000"
>   },
>   "createdAt": "2026-11-18T10:00:17.000Z"
> }
> ```
>
> `data` is shortened here. The full payloads are under [Payloads by event](#payloads-by-event).

> [tab] Resent event
>
> Sent when you call a `resend-webhook` endpoint. The event `id` is a new UUID each time, field names in `data` are camelCase, and `data` is a summary.
>
> ```json
> {
>   "id": "0b7e3c52-9a1d-4f60-8e2b-6c4d1a9f3e70",
>   "type": "payout.successful",
>   "merchantId": 318,
>   "data": {
>     "id": 1842,
>     "publicId": "pyt_9c2e41b7a05d3f68",
>     "status": "successful",
>     "sourceCurrency": "NGN",
>     "sourceAmount": "5000000"
>   },
>   "createdAt": "2026-11-19T08:30:00.000Z"
> }
> ```
>
> `data` is shortened here. The full summaries are under [Resent events](#resent-events).

## Read this first

> [!WARNING]
>
> **Field names in `data` are snake\_case** (`public_id`, `source_amount`), unlike API responses,
> which are camelCase (`publicId`, `sourceAmount`). Map them deliberately.

> [!WARNING]
>
> **`data.status` is the detailed internal state**, not one of the four API statuses. A successful
> pay-in can read `credited`, `overpaid` or `underpaid`. Decide from the event `type`, then fetch
> the transaction if you need its API status.

> [!NOTE]
>
> `data` carries more fields than these samples show. Rely only on the fields documented on this
> page. Others can change or disappear without notice.

> [!NOTE]
>
> Numeric ids and amounts in `data` arrive as strings of digits, such as `"1842"` and `"5000000"`.
> Parse amounts as integers. Use `data.id` as the `{id}` in API URLs.

## Fields in `data`

**id** `string`

The transaction's numeric id. Use it in URLs such as `GET /v1/payouts/{id}`.

**public\_id** `string`

The public id: `pyt_`, `pin_` or `cnv_` followed by 16 hex characters.

**merchant\_id** `string`

Your Payve account id.

**kind** `string`

`payout`, `payin` or `conversion`.

**status** `string`

The detailed state. See the warning above.

**sub\_status** `string | null`

Extra detail when there is some.

**method** `string | null`

How the money moved: `bank_transfer`, `mobile_money`, `virtual_account` or `card`. `null` on a
conversion.

**source\_currency** `string`

The currency debited (payout, conversion) or received (pay-in).

**source\_amount** `string`

The amount in `source_currency`, in minor units. On a pay-in, the amount the payer sent.

**destination\_currency** `string`

The currency delivered. The same as `source_currency` unless currencies were converted.

**destination\_amount** `string`

The amount in `destination_currency`, in minor units. On a pay-in, the net amount credited to your
wallet.

**fee\_amount** `string`

Payve's fee, in minor units of `fee_currency`.

**fee\_currency** `string | null`

The currency of the fee.

**tax\_amount** `string`

Tax withheld on the transaction, in minor units. `"0"` when none.

**tax\_type** `string | null`

What the tax is. `null` when none.

**rate** `string | null`

The exchange rate applied, as a decimal string.

**quote\_id** `string | null`

The quote used, if any.

**beneficiary** `object | null`

The payout recipient, as you sent it. `null` on a pay-in or conversion.

**customer** `object | null`

The payer, as you sent it on a pay-in. `null` otherwise.

**merchant\_reference** `string`

Your own reference. On a payout where you sent none, this is the public id.

**narration** `string | null`

The narration you sent on a payout.

**user\_message** `string | null`

A plain-language explanation, mainly on failures.

**created\_at** `string`

When the transaction was created. ISO 8601, UTC.

**updated\_at** `string`

When the transaction last changed. ISO 8601, UTC.

## Payloads by event

Pick the event to see its full payload and what to do when it arrives.

### Payouts

> [tab] payout.successful
>
> The payout arrived.
>
> ```json
> {
>   "id": "evt_5d0a7c3e9b1f42866e0d1a2b3c4d5e6f",
>   "type": "payout.successful",
>   "merchantId": "318",
>   "data": {
>     "id": "1842",
>     "public_id": "pyt_9c2e41b7a05d3f68",
>     "merchant_id": "318",
>     "kind": "payout",
>     "status": "successful",
>     "sub_status": null,
>     "method": "bank_transfer",
>     "source_currency": "NGN",
>     "source_amount": "5000000",
>     "destination_currency": "NGN",
>     "destination_amount": "5000000",
>     "fee_amount": "5000",
>     "fee_currency": "NGN",
>     "tax_amount": "0",
>     "tax_type": null,
>     "rate": "1.0000000000",
>     "quote_id": "qte_4b1f0c9d2e7a6835",
>     "beneficiary": {
>       "type": "bank_account",
>       "accountNumber": "0123456789",
>       "bankCode": "058",
>       "holderName": "Ngozi Adeyemi",
>       "country": "NG"
>     },
>     "customer": null,
>     "merchant_reference": "invoice-1042",
>     "narration": "Invoice 1042",
>     "user_message": null,
>     "created_at": "2026-11-18T10:00:12.000Z",
>     "updated_at": "2026-11-18T10:00:17.000Z"
>   },
>   "createdAt": "2026-11-18T10:00:17.000Z"
> }
> ```
>
> **Do:** mark your payment as sent. Your wallet was debited `source_amount` plus `fee_amount`.

> [tab] payout.failed
>
> The payout did not arrive. The money is back in your wallet.
>
> ```json
> {
>   "id": "evt_a81c0f3d7e2b49650c1d2e3f4a5b6c7d",
>   "type": "payout.failed",
>   "merchantId": "318",
>   "data": {
>     "id": "1843",
>     "public_id": "pyt_2d7f90c1e4a8b365",
>     "merchant_id": "318",
>     "kind": "payout",
>     "status": "failed",
>     "method": "bank_transfer",
>     "source_currency": "NGN",
>     "source_amount": "2500000",
>     "destination_currency": "NGN",
>     "destination_amount": "2500000",
>     "fee_amount": "5000",
>     "fee_currency": "NGN",
>     "tax_amount": "0",
>     "tax_type": null,
>     "rate": "1.0000000000",
>     "quote_id": "qte_7c3a1e9f0b2d4865",
>     "beneficiary": {
>       "type": "bank_account",
>       "accountNumber": "0000000000",
>       "bankCode": "058",
>       "holderName": "Tunde Bello",
>       "country": "NG"
>     },
>     "customer": null,
>     "merchant_reference": "invoice-1043",
>     "narration": "Invoice 1043",
>     "user_message": "The recipient's bank is currently offline. Please try again later.",
>     "created_at": "2026-11-18T10:02:40.000Z",
>     "updated_at": "2026-11-18T10:02:41.000Z"
>   },
>   "createdAt": "2026-11-18T10:02:41.000Z"
> }
> ```
>
> **Do:** tell your user, using `user_message` when present. To try again, create a new payout with a new idempotency key.
>
> > [!NOTE]
> >
> > `data.status` on this event can be `failed` or another non-successful state such as `reversed`.
> > Every one of them means the payout did not arrive.

### Pay-ins

> [tab] payin.successful
>
> A pay-in was received.
>
> ```json
> {
>   "id": "evt_3e9b7a1c5d0f48267a8b9c0d1e2f3a4b",
>   "type": "payin.successful",
>   "merchantId": "318",
>   "data": {
>     "id": "1851",
>     "public_id": "pin_3f9a2c1d8e7b6a50",
>     "merchant_id": "318",
>     "kind": "payin",
>     "status": "successful",
>     "sub_status": null,
>     "method": "virtual_account",
>     "source_currency": "NGN",
>     "source_amount": "5000000",
>     "destination_currency": "NGN",
>     "destination_amount": "4970000",
>     "fee_amount": "25000",
>     "fee_currency": "NGN",
>     "tax_amount": "5000",
>     "tax_type": "etl_stamp_duty",
>     "rate": null,
>     "quote_id": null,
>     "beneficiary": null,
>     "customer": {
>       "name": "Chidi Okeke",
>       "email": "chidi@example.com"
>     },
>     "merchant_reference": "order-7781",
>     "narration": null,
>     "user_message": null,
>     "created_at": "2026-11-18T11:14:03.000Z",
>     "updated_at": "2026-11-18T11:16:29.000Z"
>   },
>   "createdAt": "2026-11-18T11:16:29.000Z"
> }
> ```
>
> **Do:** fetch the pay-in and fulfil the order if it is `successful` and not `underpaid`. In this sample the payer sent ₦50,000.00 (`source_amount`), and ₦49,700.00 (`destination_amount`) was credited after a ₦250.00 fee and ₦50.00 tax.
>
> > [!WARNING]
> >
> > This event is also sent when a payment link is overpaid or underpaid. `data.status` is then
> > `overpaid` or `underpaid`. An underpaid payment credits nothing. See [Payment
> > links](/guides/payment-links.md#overpayment-and-underpayment).

> [tab] payin.failed
>
> A pay-in failed. Nothing was credited.
>
> ```json
> {
>   "id": "evt_c47d2e8a0b6f41359d0e1f2a3b4c5d6e",
>   "type": "payin.failed",
>   "merchantId": "318",
>   "data": {
>     "id": "1852",
>     "public_id": "pin_8b1e6d4c2a9f7035",
>     "merchant_id": "318",
>     "kind": "payin",
>     "status": "failed",
>     "method": "card",
>     "source_currency": "NGN",
>     "source_amount": "1200000",
>     "destination_currency": "NGN",
>     "destination_amount": "1200000",
>     "fee_amount": "0",
>     "fee_currency": null,
>     "tax_amount": "0",
>     "tax_type": null,
>     "rate": null,
>     "quote_id": null,
>     "beneficiary": null,
>     "customer": {
>       "name": "Fatima Aliyu",
>       "email": "fatima@example.com"
>     },
>     "merchant_reference": "order-7782",
>     "narration": null,
>     "user_message": "The card was declined.",
>     "created_at": "2026-11-18T11:20:10.000Z",
>     "updated_at": "2026-11-18T11:20:44.000Z"
>   },
>   "createdAt": "2026-11-18T11:20:44.000Z"
> }
> ```
>
> **Do:** release the order or let the payer try again with a new pay-in.

> [tab] payin.expired
>
> A pay-in was not paid before its time ran out.
>
> ```json
> {
>   "id": "evt_f02a6c9e3d1b47584b5c6d7e8f9a0b1c",
>   "type": "payin.expired",
>   "merchantId": "318",
>   "data": {
>     "id": "1853",
>     "public_id": "pin_5a0c7e3b9d1f2846",
>     "merchant_id": "318",
>     "kind": "payin",
>     "status": "expired",
>     "method": "virtual_account",
>     "source_currency": "NGN",
>     "source_amount": "750000",
>     "destination_currency": "NGN",
>     "destination_amount": "750000",
>     "fee_amount": "0",
>     "fee_currency": null,
>     "tax_amount": "0",
>     "tax_type": null,
>     "rate": null,
>     "quote_id": null,
>     "beneficiary": null,
>     "customer": {
>       "name": "Amara Nwosu",
>       "email": "amara@example.com"
>     },
>     "merchant_reference": "order-7783",
>     "narration": null,
>     "user_message": null,
>     "created_at": "2026-11-18T09:00:00.000Z",
>     "updated_at": "2026-11-18T09:30:02.000Z"
>   },
>   "createdAt": "2026-11-18T09:30:02.000Z"
> }
> ```
>
> **Do:** cancel the order, or create a new pay-in if the payer still wants to pay. Tell the payer not to send money to the old account details.

### Conversions

> [tab] conversion.successful
>
> A conversion completed. The destination wallet was credited.
>
> ```json
> {
>   "id": "evt_7b3f1d9a5c0e42681e2f3a4b5c6d7e8f",
>   "type": "conversion.successful",
>   "merchantId": "318",
>   "data": {
>     "id": "1860",
>     "public_id": "cnv_6e2b9a0d4c1f7385",
>     "merchant_id": "318",
>     "kind": "conversion",
>     "status": "successful",
>     "sub_status": null,
>     "method": null,
>     "source_currency": "NGN",
>     "source_amount": "5000000",
>     "destination_currency": "GHS",
>     "destination_amount": "46500",
>     "fee_amount": "0",
>     "fee_currency": "NGN",
>     "tax_amount": "0",
>     "tax_type": null,
>     "rate": "0.0093000000",
>     "quote_id": "qte_1a9c3e7b5d0f2846",
>     "beneficiary": null,
>     "customer": null,
>     "merchant_reference": "treasury-2026-11-18",
>     "narration": null,
>     "user_message": null,
>     "created_at": "2026-11-18T12:00:00.000Z",
>     "updated_at": "2026-11-18T12:00:06.000Z"
>   },
>   "createdAt": "2026-11-18T12:00:06.000Z"
> }
> ```
>
> **Do:** record the conversion. `source_amount` left the source wallet and `destination_amount` reached the destination wallet.

> [tab] conversion.failed
>
> A conversion did not complete.
>
> ```json
> {
>   "id": "evt_1c8e4a0f6b2d49735c6d7e8f9a0b1c2d",
>   "type": "conversion.failed",
>   "merchantId": "318",
>   "data": {
>     "id": "1861",
>     "public_id": "cnv_0f4d8b2a6c9e1573",
>     "merchant_id": "318",
>     "kind": "conversion",
>     "status": "failed",
>     "method": null,
>     "source_currency": "NGN",
>     "source_amount": "9000000",
>     "destination_currency": "KES",
>     "destination_amount": "756000",
>     "fee_amount": "0",
>     "fee_currency": "NGN",
>     "tax_amount": "0",
>     "tax_type": null,
>     "rate": "0.0840000000",
>     "quote_id": "qte_9d5b1f3a7c0e2468",
>     "beneficiary": null,
>     "customer": null,
>     "merchant_reference": "treasury-2026-11-18-b",
>     "narration": null,
>     "user_message": null,
>     "created_at": "2026-11-18T12:05:00.000Z",
>     "updated_at": "2026-11-18T12:05:09.000Z"
>   },
>   "createdAt": "2026-11-18T12:05:09.000Z"
> }
> ```
>
> **Do:** check both wallet balances, then request a new quote and try again if you still want to convert.

## Resent events

When you call a `resend-webhook` endpoint, Payve sends a fresh event. It differs from the automatic one in three ways.

| Thing | Automatic event | Resent event |
| - | - | - |
| `id` | `evt_` and 32 hex characters | A UUID. New on every resend. |
| `data` names | snake\_case | camelCase |
| `data` size | The full transaction | A summary |

> [tab] Payout
>
> ```json
> {
>   "id": "0b7e3c52-9a1d-4f60-8e2b-6c4d1a9f3e70",
>   "type": "payout.successful",
>   "merchantId": 318,
>   "data": {
>     "id": 1842,
>     "publicId": "pyt_9c2e41b7a05d3f68",
>     "status": "successful",
>     "isCrossCurrency": false,
>     "sourceCurrency": "NGN",
>     "destinationCurrency": "NGN",
>     "sourceAmount": "5000000",
>     "destinationAmount": "5000000",
>     "feeAmount": "5000",
>     "feeCurrency": "NGN",
>     "rate": "1.0000000000",
>     "conversion": null,
>     "method": "bank_transfer",
>     "merchantReference": "invoice-1042",
>     "beneficiary": {
>       "type": "bank_account",
>       "accountNumber": "0123456789",
>       "bankCode": "058",
>       "holderName": "Ngozi Adeyemi",
>       "country": "NG"
>     },
>     "createdAt": "2026-11-18T10:00:12.000Z"
>   },
>   "createdAt": "2026-11-19T08:30:00.000Z"
> }
> ```

> [tab] Pay-in
>
> ```json
> {
>   "id": "7a1c9e04-3b5d-4c82-9f6e-2d8b0a4c6e19",
>   "type": "payin.successful",
>   "merchantId": 318,
>   "data": {
>     "id": 2107,
>     "publicId": "pin_3e8a1f6c0b9d2475",
>     "status": "credited",
>     "currency": "NGN",
>     "amount": "2500000",
>     "method": "virtual_account",
>     "merchantReference": "order-7781",
>     "createdAt": "2026-11-18T11:42:03.000Z"
>   },
>   "createdAt": "2026-11-19T08:30:00.000Z"
> }
> ```

> [tab] Conversion
>
> ```json
> {
>   "id": "c4f2a8d1-6e3b-4a97-b0c5-9e1d7f3a2b68",
>   "type": "conversion.successful",
>   "merchantId": 318,
>   "data": {
>     "id": 1990,
>     "publicId": "cnv_6d0b2f8e1a4c9375",
>     "status": "successful",
>     "sourceCurrency": "NGN",
>     "destinationCurrency": "GHS",
>     "sourceAmount": "10000000",
>     "destinationAmount": "98500",
>     "feeAmount": "0",
>     "rate": "0.0098500000",
>     "merchantReference": "treasury-2026-11-18",
>     "createdAt": "2026-11-18T12:05:44.000Z"
>   },
>   "createdAt": "2026-11-19T08:30:00.000Z"
> }
> ```

> [!WARNING]
>
> A resent pay-in that was overpaid or underpaid arrives with the type `payin.overpaid` or
> `payin.underpaid`, not `payin.successful`. Handle both names if you use resend.

> [!TIP]
>
> Write one small function that reads the public id from either shape: `data.public_id ??
>     data.publicId`. Then fetch the transaction and act on the API response, which has one shape.
