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

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.
What arrives at your endpoint: a signed POST with a JSON body.
Verify X-Payve-Signature against the raw body before you parse it. See Verify signatures.

Read this first

Field names in data are snake_case (public_id, source_amount), unlike API responses, which are camelCase (publicId, sourceAmount). Map them deliberately.
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.
data carries more fields than these samples show. Rely only on the fields documented on this page. Others can change or disappear without notice.
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

string
The transaction’s numeric id. Use it in URLs such as GET /v1/payouts/{id}.
string
The public id: pyt_, pin_ or cnv_ followed by 16 hex characters.
string
Your Payve account id.
string
payout, payin or conversion.
string
The detailed state. See the warning above.
string | null
Extra detail when there is some.
string | null
How the money moved: bank_transfer, mobile_money, virtual_account or card. null on a conversion.
string
The currency debited (payout, conversion) or received (pay-in).
string
The amount in source_currency, in minor units. On a pay-in, the amount the payer sent.
string
The currency delivered. The same as source_currency unless currencies were converted.
string
The amount in destination_currency, in minor units. On a pay-in, the net amount credited to your wallet.
string
Payve’s fee, in minor units of fee_currency.
string | null
The currency of the fee.
string
Tax withheld on the transaction, in minor units. "0" when none.
string | null
What the tax is. null when none.
string | null
The exchange rate applied, as a decimal string.
string | null
The quote used, if any.
object | null
The payout recipient, as you sent it. null on a pay-in or conversion.
object | null
The payer, as you sent it on a pay-in. null otherwise.
string
Your own reference. On a payout where you sent none, this is the public id.
string | null
The narration you sent on a payout.
string | null
A plain-language explanation, mainly on failures.
string
When the transaction was created. ISO 8601, UTC.
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

The payout arrived.
Do: mark your payment as sent. Your wallet was debited source_amount plus fee_amount.

Pay-ins

A pay-in was received.
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.
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.

Conversions

A conversion completed. The destination wallet was credited.
Do: record the conversion. source_amount left the source wallet and destination_amount reached the destination wallet.

Resent events

When you call a resend-webhook endpoint, Payve sends a fresh event. It differs from the automatic one in three ways.
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.
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.