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.

Available Events

Deposit Events

partner.customer.deposit.created - New deposit request created
partner.customer.deposit.submitted - Deposit submitted to payment processor
partner.customer.deposit.reconciled - Deposit reconciled with bank
partner.customer.deposit.accepted - Deposit accepted and funds available
partner.customer.deposit.failed - Deposit failed to process

Withdrawal Events

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

Deposit Events

partner.customer.deposit.created

This event is triggered when a new deposit request is created for a partner customer.

Payload Structure

json

{
  "notificationType": "partner.customer.deposit.created",
  "partnerId": "partner_123456789",
  "customerId": "customer_123456789",
  "reference": "DEP123456789",
  "amount": 100.00,
  "currency": "EUR",
  "sessionId": "session_123456789",
  "endToEndId": "E2E123456789",
  "paymentCountry": "DE",
  "paymentMethod": "bank_transfer",
  "partnerName": "Partner Company",
  "customerEmail": "[email protected]",
  "customerFullName": "John Doe",
  "customerCitizenshipCountryCode": "DE",
  "customerResidenceAddress": "123 Main St, Berlin, Germany",
  "idempotencyKey": "idem_123456789",
  "websiteReference": "order_123456789",
  "customFields": {
    "key1": "value1",
    "key2": "value2"
  },
  "blockchainDestinationType": "Partner", // 'Partner' | 'Customer'
  "blockchainDestinationAddress": "0x1234567890abcdef"
}

partner.customer.deposit.submitted

This event is triggered when a deposit has been submitted to the payment processor.

Payload Structure

json

{
  "notificationType": "partner.customer.deposit.submitted",
  "partnerId": "partner_123456789",
  "customerId": "customer_123456789",
  "reference": "DEP123456789",
  "amount": 100.00,
  "currency": "EUR",
  "externalPaymentId": "EXT_PAY_123456",
  "sessionId": "session_123456789",
  "customerEmail": "[email protected]",
  "paymentMethod": "bank_transfer",
  "paymentCountry": "DE",
  "endToEndId": "E2E123456789",
  "partnerIban": "DE89370400440532013000",
  "customerIpAddress": "192.168.1.1",
  "idempotencyKey": "idem_123456789",
  "websiteReference": "order_123456789",
  "customFields": {
    "key1": "value1",
    "key2": "value2"
  },
  "originalCurrency": "USD",
  "originalAmount": 110.00,
  "fxQuoteId": "FX_QUOTE_123",
  "fxQuoteExpiryTime": "2024-01-01T12:00:00Z"
}

partner.customer.deposit.reconciled

This event is triggered when a deposit has been successfully reconciled with the bank.

Payload Structure

json

{
  "notificationType": "partner.customer.deposit.reconciled",
  "partnerId": "partner_123456789",
  "customerId": "customer_123456789",
  "reference": "DEP123456789",
  "amount": 100.00,
  "currency": "EUR",
  "externalPaymentId": "EXT_PAY_123456"
}

partner.customer.deposit.accepted

This event is triggered when a deposit has been accepted and funds are available.

Payload Structure

json

{
  "notificationType": "partner.customer.deposit.accepted",
  "partnerId": "partner_123456789",
  "customerId": "customer_123456789",
  "reference": "DEP123456789",
  "amount": 100.00,
  "currency": "EUR"
}

partner.customer.deposit.failed

This event is triggered when a deposit fails to process.

Payload Structure

json

{
  "notificationType": "partner.customer.deposit.failed",
  "partnerId": "partner_123456789",
  "customerId": "customer_123456789",
  "reference": "DEP123456789",
  "amount": 100.00,
  "currency": "EUR",
  "reason": "insufficient_funds",
  "errorDetails": "The account has insufficient funds for this transaction",
  "sessionId": "session_123456789",
  "customerEmail": "[email protected]",
  "paymentMethod": "bank_transfer",
  "paymentCountry": "DE",
  "endToEndId": "E2E123456789",
  "partnerIban": "DE89370400440532013000",
  "customerIpAddress": "192.168.1.1",
  "idempotencyKey": "idem_123456789",
  "websiteReference": "order_123456789",
  "customFields": {
    "key1": "value1",
    "key2": "value2"
  }
}

Withdrawal Events

partner.customer.withdrawal.requested

This event is triggered when a withdrawal request is created.

Payload Structure

json

{
  "notificationType": "partner.customer.withdrawal.requested",
  "partnerId": "partner_123456789",
  "customerId": "customer_123456789",
  "reference": "WDL123456789",
  "amount": 100.00,
  "currency": "EUR",
  "beneficiaryAccount": "DE89370400440532013000",
  "beneficiaryName": "John Doe",
  "withdrawalReason": "CashOut",
  "customerEmail": "[email protected]",
  "customerIpAddress": "192.168.1.1",
  "customerIpCountryCode": "DE",
  "remittanceInformation": "Withdrawal for order #12345",
  "creditorAccount": "DE89370400440532013000",
  "creditorBic": "DEUTDEFF",
  "creditorCountryCode": "DE",
  "creditorName": "John Doe",
  "creditorAddress": "123 Main St, Berlin, Germany",
  "idempotencyKey": "idem_123456789",
  "websiteReference": "withdrawal_123456789",
  "customFields": {
    "key1": "value1",
    "key2": "value2"
  }
}

partner.customer.withdrawal.accepted

This event is triggered when a withdrawal has been accepted for processing.

Payload Structure

json

{
  "notificationType": "partner.customer.withdrawal.accepted",
  "partnerId": "partner_123456789",
  "customerId": "customer_123456789",
  "reference": "WDL123456789",
  "amount": 100.00,
  "currency": "EUR",
  "beneficiaryAccount": "DE89370400440532013000",
  "beneficiaryName": "John Doe",
  "withdrawalReason": "CashOut",
  "customerEmail": "[email protected]",
  "customerIpAddress": "192.168.1.1",
  "customerIpCountryCode": "DE",
  "remittanceInformation": "Withdrawal for order #12345",
  "creditorAccount": "DE89370400440532013000",
  "creditorBic": "DEUTDEFF",
  "creditorCountryCode": "DE",
  "creditorName": "John Doe",
  "creditorAddress": "123 Main St, Berlin, Germany",
  "idempotencyKey": "idem_123456789",
  "websiteReference": "withdrawal_123456789",
  "customFields": {
    "key1": "value1",
    "key2": "value2"
  }
}

partner.customer.withdrawal.failed

This event is triggered when a withdrawal fails to process.

Payload Structure

json

{
  "notificationType": "partner.customer.withdrawal.failed",
  "partnerId": "partner_123456789",
  "customerId": "customer_123456789",
  "reference": "WDL123456789",
  "amount": 100.00,
  "currency": "EUR",
  "reason": "invalid_account",
  "errorDetails": "The specified account number is invalid",
  "beneficiaryAccount": "DE89370400440532013000",
  "beneficiaryName": "John Doe",
  "withdrawalReason": "CashOut",
  "customerEmail": "[email protected]",
  "customerIpAddress": "192.168.1.1",
  "customerIpCountryCode": "DE",
  "remittanceInformation": "Withdrawal for order #12345",
  "creditorAccount": "DE89370400440532013000",
  "creditorBic": "DEUTDEFF",
  "creditorCountryCode": "DE",
  "creditorName": "John Doe",
  "creditorAddress": "123 Main St, Berlin, Germany",
  "idempotencyKey": "idem_123456789",
  "websiteReference": "withdrawal_123456789",
  "customFields": {
    "key1": "value1",
    "key2": "value2"
  }
}

partner.customer.withdrawal.sent

This event is triggered when a withdrawal has been successfully sent to the beneficiary.

Payload Structure

json

{
  "notificationType": "partner.customer.withdrawal.sent",
  "partnerId": "partner_123456789",
  "customerId": "customer_123456789",
  "reference": "WDL123456789",
  "amount": 100.00,
  "currency": "EUR",
  "externalPaymentId": "EXT_PAY_789456",
  "beneficiaryAccount": "DE89370400440532013000",
  "beneficiaryName": "John Doe",
  "withdrawalReason": "CashOut",
  "customerEmail": "[email protected]",
  "customerIpAddress": "192.168.1.1",
  "customerIpCountryCode": "DE",
  "remittanceInformation": "Withdrawal for order #12345",
  "creditorAccount": "DE89370400440532013000",
  "creditorBic": "DEUTDEFF",
  "creditorCountryCode": "DE",
  "creditorName": "John Doe",
  "creditorAddress": "123 Main St, Berlin, Germany",
  "idempotencyKey": "idem_123456789",
  "websiteReference": "withdrawal_123456789",
  "customFields": {
    "key1": "value1",
    "key2": "value2"
  }
}

Common Fields Across Event Types

All event payloads include these common fields:

Field	Description
`notificationType`	The type of notification/event (e.g., "partner.customer.deposit.created")
`partnerId`	The unique identifier for the partner
`customerId`	The unique identifier for the customer
`reference`	The unique reference for the transaction
`amount`	The transaction amount
`currency`	The currency code (e.g., EUR, USD)

Optional Fields

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

Field	Description
`idempotencyKey`	A key to ensure idempotent processing
`websiteReference`	Your reference for this transaction
`customFields`	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].

Webhook Event Types ​

Overview ​

Available Events ​

Deposit Events ​

Withdrawal Events ​

Deposit Events ​

partner.customer.deposit.created ​

Payload Structure ​

partner.customer.deposit.submitted ​

Payload Structure ​

partner.customer.deposit.reconciled ​

Payload Structure ​

partner.customer.deposit.accepted ​

Payload Structure ​

partner.customer.deposit.failed ​

Payload Structure ​

Withdrawal Events ​

partner.customer.withdrawal.requested ​

Payload Structure ​

partner.customer.withdrawal.accepted ​

Payload Structure ​

partner.customer.withdrawal.failed ​

Payload Structure ​

partner.customer.withdrawal.sent ​

Payload Structure ​

Common Fields Across Event Types ​

Optional Fields ​

Testing Webhook Events ​

Webhook Event Types

Overview

Available Events

Deposit Events

Withdrawal Events

Deposit Events

partner.customer.deposit.created

Payload Structure

partner.customer.deposit.submitted

Payload Structure

partner.customer.deposit.reconciled

Payload Structure

partner.customer.deposit.accepted

Payload Structure

partner.customer.deposit.failed

Payload Structure

Withdrawal Events

partner.customer.withdrawal.requested

Payload Structure

partner.customer.withdrawal.accepted

Payload Structure

partner.customer.withdrawal.failed

Payload Structure

partner.customer.withdrawal.sent

Payload Structure

Common Fields Across Event Types

Optional Fields

Testing Webhook Events