Skip to content

Document new webhook expired feature #122

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
diogonr merged 1 commit into from
May 20, 2026
Merged

Document new webhook expired feature #122

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
105 changes: 105 additions & 0 deletions docs/events/crypto-offramp.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ import TabItem from '@theme/TabItem';
| [`order:crypto-offramp:funds-sent`](#ordercrypto-offrampfunds-sent) | User has sent funds for their order. |
| [`order:crypto-offramp:funds-received`](#ordercrypto-offrampfunds-received) | User has sent funds for their order and we have received them. |
| [`order:crypto-offramp:completed`](#ordercrypto-offrampcompleted) | User's order has completed. |
| [`order:crypto-offramp:expired`](#ordercrypto-offrampexpired) | Transaction was abandoned actively or passively by the user. |
| [`order:crypto-offramp:failed`](#ordercrypto-offrampfailed) | User's order has failed. |
| [`order:crypto-offramp:refund:completed`](#ordercrypto-offramprefundcompleted) | User's order has been successfully refunded. |

Expand Down Expand Up @@ -428,6 +429,110 @@ The values for `destination.paymentMethod.type` can be found using our [REST API
</TabItem>
</Tabs>

## `order:crypto-offramp:expired`

Triggered when a transaction status is `expired`. This means the transaction was abandoned actively or passively by the user (`cancelled`, `expired`, `abandoned` or `pending`).

<Tabs>
<TabItem label="Schema" value="schema" default>

- `id`: UUID of the order.
- `status`: Status of the order (`expired`).
- `createdAt`: Timestamp at which the order was created.
- `updatedAt`: Timestamp at which the order was last updated.
- `origin`: Object containing information about what the user would have sent.
- `amount`: Amount the user would have sent.
- `rate`: Rate used to calculate the amount.
- `asset`: Cryptoasset the user would have sent.
- `network`: Network of the sending asset.
- `depositAddress`: Object containing information related to the deposit.
- `expiresAt`: Timestamp at which the deposit expires.
- `remindAt`: Timestamp at which the user is reminded.
- `tag`: Tag of the crypto transaction, used to complement the address.
- `type`: Tag type.
- `value`: Tag value.
- `value`: Address to which the user sends the funds.
- `destination`: Object containing information about what the user would have received.
- `amount`: Amount the user would have received.
- `rate`: Rate used to calculate the amount.
- `asset`: Currency code in the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) format used to receive the funds.
- `paymentMethod`: Object containing information about the payment method used.
- `type`: Type of payment method.
- `fees`: Array containing fees associated with the order.
- `amount`: Amount user was charged for this fee.
- `asset`: Asset used to charge the fee.
- `normalized`: Amount in USD that the user was charged for this fee.
- `type`: Type of fee (`network`, `deposit` or `partner`).
- `widget`: Widget associated with the session.
- `id` UUID of the widget.
- `name`: Name of the widget.
- `flow`: Flow associated with the widget.

:::note
The values for `destination.paymentMethod.type` can be found using our [REST API](../rest-api.md), via the [payment methods endpoint](https://api.topperpay.com/payment-methods/crypto-offramp).
:::

</TabItem>
<TabItem label="Example" value="example">

```js
{
"name": "order:crypto-offramp:expired",
"id": "011767df-de26-4ab2-80bd-f6ec001a0566",
"bootstrapTokenId": "5d1d3d2b-bb84-4d35-9cf2-9b089b51a219",
"data": {
// highlight-start
"id": "6d86e4d1-a8a4-47d7-99ee-5d3a46855968",
"status": "expired",
"createdAt": "2026-05-13T10:08:23.461Z",
"updatedAt": "2026-05-13T10:18:26.069Z",
"origin": {
"amount": "0.00039687",
"rate": "0.00001500335186165496",
"asset": "BTC",
"network": "bitcoin",
"depositAddress": {
"expiresAt": "2026-05-13T10:18:25.860Z",
"remindAt": "2026-05-13T10:14:25.860Z",
"value": "tb1qm3ay4wh2w5akd0esfy0vqcmjnexlaw69vhsfxv"
}
},
"destination": {
"amount": "25.63",
"rate": "66651.77283189396154181068",
"asset": "EUR",
"paymentMethod": {
"network": "card",
"type": "debit-card"
}
},
"fees": [
{
"amount": "0.00001233",
"asset": "BTC",
"normalized": "1",
"type": "deposit"
},
{
"amount": "0",
"asset": "BTC",
"normalized": "0",
"type": "deposit"
}
],
"widget": {
"id": "0f17e3e7-e269-4270-a5c6-1715b76f17da",
"name": "Topper",
"flow": "crypto_offramp"
}
// highlight-end
}
}
```

</TabItem>
</Tabs>

## `order:crypto-offramp:failed`

Triggered when a user's order has failed.
Expand Down
104 changes: 104 additions & 0 deletions docs/events/crypto-onramp.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ import TabItem from '@theme/TabItem';
| [`order:crypto-onramp:charged`](#ordercrypto-onrampcharged) | User has been charged for their order. |
| [`order:crypto-onramp:crypto-sent`](#ordercrypto-onrampcrypto-sent) | User's crypto delivery has started. |
| [`order:crypto-onramp:completed`](#ordercrypto-onrampcompleted) | User's order has completed. |
| [`order:crypto-onramp:expired`](#ordercrypto-onrampexpired) | Transaction was abandoned actively or passively by the user. |
| [`order:crypto-onramp:failed`](#ordercrypto-onrampfailed) | User's order has failed. |
| [`order:crypto-onramp:refund:completed`](#ordercrypto-onramprefundcompleted) | User's order has been successfully refunded. |

Expand Down Expand Up @@ -443,6 +444,109 @@ The values for `origin.paymentMethod.type` can be found using our [REST API](../
</TabItem>
</Tabs>

## `order:crypto-onramp:expired`

Triggered when a transaction status is `expired`. This means the transaction was abandoned actively or passively by the user (`cancelled`, `expired`, `abandoned` or `pending`).

<Tabs>
<TabItem label="Schema" value="schema" default>

- `id`: UUID of the order.
- `status`: Status of the order (`expired`).
- `createdAt`: Timestamp at which the order was created.
- `updatedAt`: Timestamp at which the order was last updated.
- `origin`: Object containing information about how the user would have paid.
- `amount`: Amount the user would have paid.
- `rate`: Rate used to calculate the amount.
- `asset`: Currency code in the [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) format used to make the payment.
- `paymentMethod`: Object containing information about the payment method used.
- `type`: Type of payment method.
- `destination`: Object containing information about what the user would have received.
- `amount`: Amount the user would have received.
- `rate`: Rate used to calculate the amount.
- `asset`: Cryptoasset the user would have received.
- `network`: Network of the receiving asset.
- `address`: Recipient wallet address.
- `tag` (_optional_): Tag of the crypto transaction, used to complement the `address`.
- `type`: Tag type (e.g.: `memo` or `destination-tag`).
- `value`: Tag value.
- `priority` (_optional_): Priority of the crypto transaction.
- `fees`: Array containing fees associated with the order.
- `amount`: Amount user was charged for this fee.
- `asset`: Asset used to charge the fee.
- `normalized`: Amount in USD that the user was charged for this fee.
- `type`: Type of fee (`network`, `deposit` or `partner`).
- `widget`: Widget associated with the session.
- `id` UUID of the widget.
- `name`: Name of the widget.
- `flow`: Flow associated with the widget.

:::note
The values for `origin.paymentMethod.type` can be found using our [REST API](../rest-api.md), via the [payment methods endpoint](https://api.topperpay.com/payment-methods/crypto-onramp).
:::

</TabItem>
<TabItem label="Example" value="example">

```js
{
"name": "order:crypto-onramp:expired",
"id": "00a991cf-a870-43af-88b8-43c51532831d",
"bootstrapTokenId": "141bfa06-481e-4684-96eb-cec4ad529616",
"data": {
// highlight-start
"id": "966b8e24-6a65-442a-942e-577f16288789",
"status": "expired",
"createdAt": "2023-06-12T17:21:21.240Z",
"updatedAt": "2023-06-12T17:31:21.240Z",
"origin": {
"amount": "100.00",
"rate": "1770.27534301775263314892",
"asset": "USD",
"paymentMethod": {
"type": "credit-card"
}
},
"destination": {
"amount": "0.047116964221968237",
"rate": "0.00056488387749632223",
"asset": "ETH",
"network": "ethereum",
"address": "0xb794F5eA0ba39494cE839613fffBA74279579268"
},
"fees": [
{
"amount": "14.17",
"asset": "USD",
"normalized": "14.17",
"type": "network"
},
{
"amount": "2.42",
"asset": "USD",
"normalized": "2.42",
"type": "deposit"
},
{
"amount": "1.00",
"asset": "USD",
"normalized": "1.00",
"type": "partner"
}
],
"widget": {
"id": "998544f2-5b01-4062-9394-22827ff5db6c",
"name": "ACME",
"flow": "crypto_onramp"
}
// highlight-end
}
}
```

</TabItem>
</Tabs>

## `order:crypto-onramp:failed`

Triggered when a user's order has failed.
Expand Down
2 changes: 2 additions & 0 deletions docs/webhooks.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ Full information about the available events and their associated payloads can be
| [`order:crypto-onramp:charged`](./events/crypto-onramp.mdx#ordercrypto-onrampcharged) | User has been charged for their order. |
| [`order:crypto-onramp:crypto-sent`](./events/crypto-onramp.mdx#ordercrypto-onrampcrypto-sent) | User's crypto delivery has started. |
| [`order:crypto-onramp:completed`](./events/crypto-onramp.mdx#ordercrypto-onrampcompleted) | User's order has completed. |
| [`order:crypto-onramp:expired`](./events/crypto-onramp.mdx#ordercrypto-onrampexpired) | Transaction was abandoned actively or passively by the user. |
| [`order:crypto-onramp:failed`](./events/crypto-onramp.mdx#ordercrypto-onrampfailed) | User's order has failed. |
| [`order:crypto-onramp:refund:completed`](./events/crypto-onramp.mdx#ordercrypto-onramprefundcompleted) | User's order has been successfully refunded. |

Expand All @@ -43,6 +44,7 @@ Full information about the available events and their associated payloads can be
| [`order:crypto-offramp:funds-sent`](./events/crypto-offramp.mdx#ordercrypto-offrampfunds-sent) | User has sent funds for their order. |
| [`order:crypto-offramp:funds-received`](./events/crypto-offramp.mdx#ordercrypto-offrampfunds-received) | User has sent funds for their order and we have received them. |
| [`order:crypto-offramp:completed`](./events/crypto-offramp.mdx#ordercrypto-offrampcompleted) | User's order has completed. |
| [`order:crypto-offramp:expired`](./events/crypto-offramp.mdx#ordercrypto-offrampexpired) | Transaction was abandoned actively or passively by the user. |
| [`order:crypto-offramp:failed`](./events/crypto-offramp.mdx#ordercrypto-offrampfailed) | User's order has failed. |
| [`order:crypto-offramp:refund:completed`](./events/crypto-offramp.mdx#ordercrypto-offramprefundcompleted) | User's order has been successfully refunded. |

Expand Down
Loading