Webhook Event Types

This document provides detailed information about the different webhook event types supported by the Stable Mint API and their respective payload structures.

Overview

Stable Mint webhooks notify your application about various events related to payment processing. Each event type corresponds to a specific stage in the payment lifecycle and carries relevant data in its payload.

All payloads shown below use the Version 2 webhook format, where the event data is wrapped in an envelope with an eventId and a data object.

Available Events

Deposit Events

• partner.customer.deposit.created - New deposit request created
• partner.customer.deposit.initiated - Deposit initiated by the customer
• partner.customer.deposit.submitted - Deposit submitted to payment processor
• partner.customer.deposit.accepted - Deposit accepted and reconciled
• partner.customer.deposit.failed - Deposit failed to process
• partner.customer.deposit.completed - Deposit completed and funds settled

Withdrawal Events

• partner.customer.withdrawal.requested - Withdrawal request created
• partner.customer.withdrawal.accepted - Withdrawal accepted for processing
• partner.customer.withdrawal.sent - Withdrawal sent to beneficiary
• partner.customer.withdrawal.failed - Withdrawal failed to process

Token Transfer Events

• customer.token.transfer.in.initiated - Incoming token transfer initiated

Transaction Events

• transaction.status.changed - Transaction status changed

Partner Customer Events

Deposit Events

partner.customer.deposit.created

Triggered when a new deposit request is created for a partner customer.

{
    "eventId": "uuid",
    "data":
    {
        "eventType": "partner.customer.deposit.created",
        "timestamp": "2026-01-01T00:00:00Z",
        "amount": 0.00,
        "currency": "string",
        "customFields": {},
        "customerCitizenshipCountryCode": "string | null",
        "customerEmail": "string",
        "customerId": "string",
        "customerFullName": "string | null",
        "customerResidenceAddress": "string | null",
        "endToEndId": "string",
        "idempotencyKey": "string | null",
        "partnerName": "string",
        "paymentCountryCode": "string | null",
        "paymentMethod": "string",
        "reference": "string",
        "sessionId": "string",
        "websiteReference": "string | null"
    }
}

partner.customer.deposit.initiated

Triggered when a deposit has been initiated by the customer.

{
    "eventId": "uuid",
    "data":
    {
        "eventType": "partner.customer.deposit.initiated",
        "timestamp": "2026-01-01T00:00:00Z",
        "amount": 0.00,
        "currency": "string",
        "customFields": {},
        "customerEmail": "string",
        "customerId": "string",
        "endToEndId": "string",
        "idempotencyKey": "string | null",
        "paymentCountryCode": "string",
        "paymentMethod": "string",
        "reference": "string",
        "sessionId": "string",
        "userIpAddress": "string",
        "websiteReference": "string | null"
    }
}

partner.customer.deposit.submitted

Triggered when a deposit has been submitted to the payment processor.

{
    "eventId": "uuid",
    "data":
    {
        "eventType": "partner.customer.deposit.submitted",
        "timestamp": "2026-01-01T00:00:00Z",
        "amount": 0.00,
        "currency": "string",
        "customFields": {},
        "customerEmail": "string",
        "customerId": "string",
        "customerIpAddress": "string",
        "endToEndId": "string",
        "idempotencyKey": "string | null",
        "paymentCountryCode": "string",
        "paymentMethod": "string",
        "reference": "string",
        "sessionId": "string",
        "websiteReference": "string | null"
    }
}

partner.customer.deposit.accepted

Triggered when a deposit has been accepted and reconciled with the bank.

{
    "eventId": "uuid",
    "data":
    {
        "eventType": "partner.customer.deposit.accepted",
        "timestamp": "2026-01-01T00:00:00Z",
        "amount": 0.00,
        "currency": "string",
        "customFields": {},
        "customerEmail": "string | null",
        "customerId": "string",
        "debtorAccount": "string",
        "debtorAddress": "string | null",
        "debtorBic": "string",
        "debtorCountryCode": "string",
        "debtorName": "string",
        "endToEndId": "string",
        "idempotencyKey": "string | null",
        "paymentCountryCode": "string | null",
        "paymentMethod": "string",
        "reference": "string",
        "sessionId": "string",
        "websiteReference": "string | null"
    }
}

partner.customer.deposit.failed

Triggered when a deposit fails to process.

{
    "eventId": "uuid",
    "data":
    {
        "eventType": "partner.customer.deposit.failed",
        "timestamp": "2026-01-01T00:00:00Z",
        "amount": 0.00,
        "currency": "string",
        "customFields": {},
        "customerEmail": "string",
        "customerId": "string",
        "customerIpAddress": "string",
        "endToEndId": "string",
        "errorDetails": "string | null",
        "idempotencyKey": "string | null",
        "paymentCountryCode": "string",
        "paymentMethod": "string",
        "reference": "string",
        "sessionId": "string",
        "websiteReference": "string | null"
    }
}

partner.customer.deposit.completed

Triggered when a deposit has been fully completed and funds are settled.

{
    "eventId": "uuid",
    "data":
    {
        "eventType": "partner.customer.deposit.completed",
        "timestamp": "2026-01-01T00:00:00Z",
        "amount": 0.00,
        "blockchainTransactionHash": "string | null",
        "currency": "string",
        "customFields": {},
        "customerEmail": "string | null",
        "customerId": "string",
        "debtorAccount": "string",
        "debtorAddress": "string | null",
        "debtorBic": "string",
        "debtorCountryCode": "string",
        "debtorName": "string",
        "endToEndId": "string",
        "idempotencyKey": "string | null",
        "paymentCountryCode": "string | null",
        "paymentMethod": "string",
        "reference": "string",
        "sessionId": "string",
        "websiteReference": "string | null"
    }
}

---

Withdrawal Events

partner.customer.withdrawal.requested

Triggered when a withdrawal request is created.

{
    "eventId": "uuid",
    "data":
    {
        "eventType": "partner.customer.withdrawal.requested",
        "timestamp": "2026-01-01T00:00:00Z",
        "amount": 0.00,
        "creditorAccount": "string",
        "creditorAddress": "string | null",
        "creditorBic": "string | null",
        "creditorCountryCode": "string",
        "creditorName": "string",
        "currency": "string",
        "customFields": {},
        "customerEmail": "string",
        "customerId": "string",
        "customerIpAddress": "string",
        "customerIpCountryCode": "string",
        "idempotencyKey": "string | null",
        "reference": "string",
        "websiteReference": "string | null",
        "withdrawalReason": "string"
    }
}

partner.customer.withdrawal.accepted

Triggered when a withdrawal has been accepted for processing.

{
    "eventId": "uuid",
    "data":
    {
        "eventType": "partner.customer.withdrawal.accepted",
        "timestamp": "2026-01-01T00:00:00Z",
        "amount": 0.00,
        "creditorAccount": "string",
        "creditorAddress": "string | null",
        "creditorBic": "string | null",
        "creditorCountryCode": "string",
        "creditorName": "string",
        "currency": "string",
        "customFields": {},
        "customerEmail": "string",
        "customerId": "string",
        "customerIpAddress": "string",
        "customerIpCountryCode": "string",
        "idempotencyKey": "string | null",
        "reference": "string",
        "websiteReference": "string | null",
        "withdrawalReason": "string"
    }
}

partner.customer.withdrawal.sent

Triggered when a withdrawal has been successfully sent to the beneficiary.

{
    "eventId": "uuid",
    "data":
    {
        "eventType": "partner.customer.withdrawal.sent",
        "timestamp": "2026-01-01T00:00:00Z",
        "amount": 0.00,
        "creditorAccount": "string",
        "creditorAddress": "string | null",
        "creditorBic": "string | null",
        "creditorCountryCode": "string",
        "creditorName": "string",
        "currency": "string",
        "customFields": {},
        "customerEmail": "string",
        "customerId": "string",
        "customerIpAddress": "string",
        "customerIpCountryCode": "string",
        "idempotencyKey": "string | null",
        "reference": "string",
        "websiteReference": "string | null",
        "withdrawalReason": "string"
    }
}

partner.customer.withdrawal.failed

Triggered when a withdrawal fails to process.

{
    "eventId": "uuid",
    "data":
    {
        "eventType": "partner.customer.withdrawal.failed",
        "timestamp": "2026-01-01T00:00:00Z",
        "amount": 0.00,
        "creditorAccount": "string",
        "creditorAddress": "string | null",
        "creditorBic": "string | null",
        "creditorCountryCode": "string",
        "creditorName": "string",
        "currency": "string",
        "customFields": {},
        "customerEmail": "string",
        "customerId": "string",
        "customerIpAddress": "string",
        "customerIpCountryCode": "string",
        "errorDetails": "string | null",
        "idempotencyKey": "string | null",
        "reference": "string",
        "websiteReference": "string | null",
        "withdrawalReason": "string"
    }
}

---

Token Transfer Events

customer.token.transfer.in.initiated

Triggered when an incoming token transfer is initiated for a customer.

{
    "eventId": "uuid",
    "data":
    {
        "eventType": "customer.token.transfer.in.initiated",
        "timestamp": "2026-01-01T00:00:00Z",
        "amount": 0.00,
        "calldata": "string",
        "contractAddress": "string | null",
        "currency": "string",
        "customerGuid": "string",
        "partnerGuid": "string | null",
        "reference": "string",
        "walletAddressTo": "string"
    }
}

---

Transaction Events

transaction.status.changed

Triggered when a transaction status changes. This is a generic event that covers both deposit and withdrawal transactions.

{
    "eventId": "uuid",
    "data":
    {
        "eventType": "transaction.status.changed",
        "timestamp": "2026-01-01T00:00:00Z",
        "amount": 0.00,
        "currency": "string",
        "customerGuid": "string | null",
        "customFields": {},
        "idempotencyKey": "string | null",
        "originatingTransactionReference": "string | null",
        "partnerGuid": "string | null",
        "reference": "string",
        "status": "string",
        "transactionHash": "string | null",
        "transactionType": "string",
        "websiteReference": "string | null"
    }
}

---

Common Fields

Envelope Fields

The Version 2 envelope wraps every event:

Field	Type	Description
eventId	string	Unique identifier for this webhook delivery, useful for idempotency checks
data	object	The event payload containing the fields described in each event section

Base Fields

All event payloads include these fields in the data object:

Field	Type	Description
eventType	string	The type of event (e.g., partner.customer.deposit.created)
timestamp	string	ISO 8601 UTC timestamp of when the event occurred

Partner Customer Event Fields

All partner.customer.* events include in their data object:

Field	Type	Description
customerId	string	The unique identifier for the customer
reference	string	The unique reference for the transaction
amount	decimal	The transaction amount
currency	string	The currency code (e.g., EUR, USD)

Optional Fields

Many events include these optional fields when provided in the original request:

Field	Type	Description
idempotencyKey	string | null	A key to ensure idempotent processing
websiteReference	string | null	Your reference for this transaction
customFields	object | null	Any additional custom JSON data

Testing Webhook Events

You can test your webhook implementation by using the Stable Mint sandbox environment. This allows you to simulate different event types and ensure your application handles them correctly.

For more information on how to set up and handle webhooks, please refer to our Receiving Webhooks guide.

For any questions or assistance with webhook events, please contact us at [email protected].