Event delivery to your webhook

HOOKeventDelivery

Jeton sends this request to the webhook URL set in the merchant portal.

Every delivery is an Event envelope, signed as the Standard Webhooks specification (https://www.standardwebhooks.com/) defines, so any of its libraries verifies it. Verify the signature before trusting the body:

key      = base64decode(secret without its "whsec_" prefix)
expected = "v1," + base64(HMAC-SHA256(key, "{webhook-id}.{webhook-timestamp}.{rawBody}"))

Compare in constant time against each space-separated entry of webhook-signature, and reject if |now - webhook-timestamp| > 300 s. While you rotate the secret, verify with the new one and fall back to the old one. webhook-id is the event id: a retried delivery carries the same one.

Every event goes to the v2 webhook's one address. The address and the secret are read at each attempt, so a change in the portal reaches deliveries still pending.

Respond 2xx within 10 s to acknowledge. Anything else — another status, no answer, an address that does not resolve or resolves to a private one — is retried 12 times over about three and a half days (immediately, then 3 s, 5 s, 15 s, 30 s, 1 m, 5 m, 15 m, 30 m, 1 h, 6 h, 24 h, 48 h), after which the delivery is exhausted and your webhook settings in the portal show the webhook failing until a later delivery succeeds. The event stays readable in GET /events.

Delivery semantics

At-least-once, unordered. Retries can reorder events. Deduplicate on id; for a given data.id, ignore any snapshot whose data.updatedAt is older than the last one you processed — the same field GET returns — or simply GET the resource when in doubt.
data is the full resource exactly as GET returned it at the moment of the event.
Only outcomes are delivered (listed in the introduction): one notification per result. GET /events also records the intermediate statuses, creation (*.pending) included, for UI and reconciliation.
Merchants are independent — another merchant's failing or slow endpoint never delays yours.

Parameters

webhook-idstringheaderrequired
The event id. A retried delivery carries the same one.
Example: evt_019985c24a6e7c3b9f102d5e8a1b3c4d
pattern ^evt_[0-9a-f]{32}$
webhook-timestampinteger (int64)headerrequired
Unix seconds when the delivery was signed.
webhook-signaturestringheaderrequired
v1, followed by the base64 signature; more than one space-separated entry is possible.
Example: v1,g0hM9SsE+OTPJTGt/tmIKtSyZlE3uFJELVlNIOLJ1OE=

Request body application/jsonrequired

objectstringrequired
Allowed values: event
idstringrequired
Stable across retries — deduplicate on this.
Example: evt_019985c24a6e7c3b9f102d5e8a1b3c4d
pattern ^evt_[0-9a-f]{32}$
typestringrequired
Allowed values: payment.pendingpayment.processingpayment.completedpayment.failedpayment.expiredpayment.cancelledpayment.refundedpayout.pendingpayout.processingpayout.completedpayout.failedpayout.cancelledtransfer.pendingtransfer.completedtransfer.failedfx_exchange.pendingfx_exchange.processingfx_exchange.completedfx_exchange.failedfx_exchange.cancelled
versionstringrequired
Envelope version. Additive changes — a new field, a new event type, a new enum value — never bump it.
Allowed values: 1
createdAtstring (date-time)required
RFC 3339, UTC, with millisecond precision.
Example: 2026-09-18T10:15:30.123Z
dataobjectrequired
The full resource as GET would return it at the time of the event.
One of
Payment
settledAmount, description and metadata are not reported yet. fee and completedAt appear once the payment is completed; payments completed before they were recorded do not carry them. updatedAt is the last change — a new status, or the customer opening the checkout — and never moves backwards.
objectstringrequired
Allowed values: payment
idstringrequired
A payment's id. Opaque — use it as you received it.
Example: pay_019985c24a6e7c3b9f102d5e8a1b3c4d
pattern ^pay_[0-9a-f]{32}$
merchantReferencestringrequired
Your own reference for this payment, as you sent it.
statusstringrequired
pending awaiting the customer — also after a failed attempt, while the customer may retry · processing customer acted, settlement in flight · completed funds credited · failed not used for payments: one never paid ends expired · cancelled · expired checkout TTL elapsed unpaid (a customer who committed just before the deadline can still turn it completed) · refunded. (partially_refunded is not reported yet.)
Allowed values: pendingprocessingcompletedfailedcancelledexpiredrefunded
amountMoneyrequired
Decimal amount as a string — never a float, never minor units. An amount you send may carry no more decimal places than its currency has (and never more than 8); trailing zeros do not count, so 10.100 EUR is fine and 10.123 EUR is 400 validation_failed on amount.value.
feeobject
Present once the payment is completed: the fee charged to you on it, in the payment's currency. You were credited amount less this.
methodstringrequired
Example: jeton_wallet
checkoutobject
Present while the payment is pending or processing.
customerCustomer
The payer. Only the e-mail is reported for now; name, phone, country and locale are not provided yet.
payerobject
Present once the payment is completed: the Jeton user who actually paid. Distinct from customer, which is what you sent. Pass payer.customerNumber as destination.customerNumber on POST /payouts to pay the same customer back.
languagestring
createdAtstring (date-time)required
RFC 3339, UTC, with millisecond precision.
Example: 2026-09-18T10:15:30.123Z
updatedAtstring (date-time)required
Last change. It never moves backwards, so use it to discard stale webhook snapshots.
Example: 2026-09-18T10:15:30.123Z
completedAtstring (date-time)
Present once the payment is completed — when the funds were credited.
Example: 2026-09-18T10:15:30.123Z
Payout
objectstringrequired
Allowed values: payout
idstringrequired
The ledger id of the payout's debit — the same entry GET /accounts/{accountId}/transactions shows.
Example: txn_AAAAAAAAB3Y
pattern ^txn_[A-Za-z0-9_-]{11}$
merchantReferencestring
Your own reference for this payout, as you sent it. Absent on a payout made without one (portal, batch).
statusstringrequired
Lifecycle of a payout. pending accepted, not sent yet (a payout held for review included — the hold is never named) · processing executing on the rail · completed · failed · cancelled withdrawn by the platform before it was sent. Terminal: completed, failed, cancelled.
Allowed values: pendingprocessingcompletedfailedcancelled
methodstringrequired
Which payout product moved the money — the same vocabulary payments use for money coming in. Derived by the server from the destination; it is never sent. It decides the fee, the limits and how the payout behaves: jeton_wallet settles instantly on the internal ledger, bank_transfer travels on a bank rail, crypto settles on-chain.
Allowed values: jeton_walletbank_transfercrypto
amountMoneyrequired
Decimal amount as a string — never a float, never minor units. An amount you send may carry no more decimal places than its currency has (and never more than 8); trailing zeros do not count, so 10.100 EUR is fine and 10.123 EUR is 400 validation_failed on amount.value.
feeobjectrequired
Fee charged on top of amount, in the payout currency. On the POST response, the fee quoted the moment before the payout was sent — a bank payout is charged exactly that; a read shows what the ledger charged.
totalDebitedobjectrequired
amount + fee: what leaves the source account.
destinationone ofrequired
Where the money went, as the ledger records it: a bank account's iban, accountHolderName, bic and country; a crypto wallet's network and address; a Jeton payout's individual by accountHolderName, the name the ledger shows — never by the customerNumber, email or phone it was sent to, and not on the POST response.
sourceAccountIdstringrequired
Opaque account identifier. Treat as a string; never parse or construct it.
Example: acc_AAAAAAAAAAc
pattern ^acc_[A-Za-z0-9_-]{11}$
railstring
How the money travelled within its method. sepa · sepa_instant · swift · instant_bank_transfer for bank_transfer, crypto for crypto, jeton_internal for jeton_wallet.
Allowed values: sepasepa_instantswiftinstant_bank_transfercryptojeton_internal
descriptionstring
failureobject
Present when status is failed.
updatedAtstring (date-time)required
The last change the ledger recorded on the payout.
Example: 2026-09-18T10:15:30.123Z
createdAtstring (date-time)required
RFC 3339, UTC, with millisecond precision.
Example: 2026-09-18T10:15:30.123Z
completedAtstring (date-time)
RFC 3339, UTC, with millisecond precision.
Example: 2026-09-18T10:15:30.123Z
Transfer
objectstringrequired
Allowed values: transfer
idstringrequired
The ledger id of the transfer's debit — the same entry GET /accounts/{accountId}/transactions shows.
Example: txn_AAAAAAAAB3Y
pattern ^txn_[A-Za-z0-9_-]{11}$
merchantReferencestring
Absent on a transfer made in the portal.
statusstringrequired
pending accepted, not settled yet · completed settled · failed refused, rejected or expired — no money moved.
Allowed values: pendingcompletedfailed
amountMoneyrequired
Decimal amount as a string — never a float, never minor units. An amount you send may carry no more decimal places than its currency has (and never more than 8); trailing zeros do not count, so 10.100 EUR is fine and 10.123 EUR is 400 validation_failed on amount.value.
feeobjectrequired
Charged on top of amount; zero between your own accounts.
totalDebitedobjectrequired
What leaves the source account: amount + fee.
sourceAccountIdstringrequired
Opaque account identifier. Treat as a string; never parse or construct it.
Example: acc_AAAAAAAAAAc
pattern ^acc_[A-Za-z0-9_-]{11}$
destinationTransferDestinationrequired
own_account with accountId, or business with exactly one of email and merchantNumber. On the resource: the type, and for own_account the accountId. A business's e-mail or number is not kept, and its account is never shown; counterpartyName on the ledger entry says who received it.
descriptionstring
failureobject
Present when status is failed.
createdAtstring (date-time)required
RFC 3339, UTC, with millisecond precision.
Example: 2026-09-18T10:15:30.123Z
updatedAtstring (date-time)required
RFC 3339, UTC, with millisecond precision.
Example: 2026-09-18T10:15:30.123Z
completedAtstring (date-time)
RFC 3339, UTC, with millisecond precision.
Example: 2026-09-18T10:15:30.123Z
FxExchange
objectstringrequired
Allowed values: fx_exchange
idstringrequired
An exchange's id. Opaque — use it as you received it.
Example: fx_019985c24a6e7c3b9f102d5e8a1b3c4d
pattern ^fx_[0-9a-f]{32}$
merchantReferencestring
Absent on an exchange made in the portal.
statusstringrequired
Allowed values: pendingprocessingcompletedfailedcancelled
sellMoneyrequired
Decimal amount as a string — never a float, never minor units. An amount you send may carry no more decimal places than its currency has (and never more than 8); trailing zeros do not count, so 10.100 EUR is fine and 10.123 EUR is 400 validation_failed on amount.value.
buyobject
The quoted amount until a venue exchange settles; then what it filled.
ratestring
The rate applied, as a string.
feeobject
Absent while it is not known — as on a portal exchange that has not executed yet, and on some older portal exchanges.
totalDebitedobject
Present with fee.
sellAccountIdstringrequired
Opaque account identifier. Treat as a string; never parse or construct it.
Example: acc_AAAAAAAAAAc
pattern ^acc_[A-Za-z0-9_-]{11}$
buyAccountIdstring
Opaque account identifier. Treat as a string; never parse or construct it.
Example: acc_AAAAAAAAAAc
pattern ^acc_[A-Za-z0-9_-]{11}$
createdAtstring (date-time)required
RFC 3339, UTC, with millisecond precision.
Example: 2026-09-18T10:15:30.123Z
updatedAtstring (date-time)required
RFC 3339, UTC, with millisecond precision.
Example: 2026-09-18T10:15:30.123Z
completedAtstring (date-time)
RFC 3339, UTC, with millisecond precision.
Example: 2026-09-18T10:15:30.123Z
deliveryobject
How the event's delivery to your webhook stands. Present in GET /events responses, never in the delivered payload — and absent for an intermediate status (only outcomes are delivered) and when your webhook did not take native v2 events when the event happened. failing is retrying after a failed attempt; exhausted ran out of retries.
- attemptsinteger
- lastAttemptAtstring (date-time)
  Absent until the first attempt.
  Example: 2026-09-18T10:15:30.123Z
- lastStatusCodeintegernullable
- statusstring
  Allowed values: pendingdeliveredfailingexhausted

Responses

Acknowledged.

Request body · application/json

{
  "object": "event",
  "id": "evt_019985c24a6e7c3b9f102d5e8a1b3c4d",
  "type": "payment.pending",
  "version": "1",
  "createdAt": "2026-09-18T10:15:30.123Z",
  "data": {
    "object": "payment",
    "id": "pay_019985c24a6e7c3b9f102d5e8a1b3c4d",
    "merchantReference": "string",
    "status": "pending",
    "amount": {
      "value": "149.90",
      "currency": "EUR"
    },
    "fee": {
      "value": "149.90",
      "currency": "EUR"
    },
    "method": "jeton_wallet",
    "checkout": {
      "url": "https://example.com",
      "expiresAt": "2026-09-18T10:15:30.123Z"
    },
    "customer": {
      "email": "[email protected]"
    },
    "payer": {
      "customerNumber": "string"
    },
    "language": "string",
    "createdAt": "2026-09-18T10:15:30.123Z",
    "updatedAt": "2026-09-18T10:15:30.123Z",
    "completedAt": "2026-09-18T10:15:30.123Z"
  },
  "delivery": {
    "attempts": 0,
    "lastAttemptAt": "2026-09-18T10:15:30.123Z",
    "lastStatusCode": 0,
    "status": "pending"
  }
}