Appearance
Webhook Event Types
This document provides detailed information about the different webhook event types supported by the StableMint API and their respective payload structures.
Overview
StableMint 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.
Event Types
InwardPaymentReconciled
This event is triggered when an inward payment (deposit) has been successfully reconciled.
Payload Structure
json
{
"sessionId": "session_123456789",
"amount": 100.00,
"currency": "EUR",
"paymentMethod": "bank_transfer",
"paymentReference": "REF123456789",
"notificationType": "InwardPaymentReconciled",
"userId": "user_123456789",
"userCountryCode": "DE",
"idempotencyKey": "idem_123456789",
"websiteReference": "order_123456789",
"customFields": {
"key1": "value1",
"key2": "value2"
},
"accountBicCode": "DEUTDEFF",
"accountName": "John Doe",
"accountAddress": "123 Main St, Berlin, Germany",
"accountIban": "DE89370400440532013000",
"status": "reconciled"
}Key Fields
| Field | Description |
|---|---|
sessionId | Unique identifier for the payment session |
amount | The amount of the reconciled payment |
currency | The currency of the payment (e.g., EUR) |
paymentMethod | The method used for the payment |
userCountryCode | The country code of the debtor |
accountBicCode | The BIC code of the debtor's bank |
accountName | The name on the debtor's account |
accountAddress | The address associated with the debtor's account |
accountIban | The IBAN of the debtor's account |
status | Always "reconciled" for this event type |
InwardPaymentFailed
This event is triggered when an inward payment (deposit) fails to process.
Payload Structure
json
{
"sessionId": "session_123456789",
"amount": 100.00,
"currency": "EUR",
"paymentMethod": "bank_transfer",
"paymentReference": "REF123456789",
"notificationType": "InwardPaymentFailed",
"userId": "user_123456789",
"idempotencyKey": "idem_123456789",
"websiteReference": "order_123456789",
"customFields": {
"key1": "value1",
"key2": "value2"
},
"status": "failed",
"reason": "abandoned"
}Key Fields
| Field | Description |
|---|---|
sessionId | Unique identifier for the payment session |
amount | The amount of the attempted payment |
currency | The currency of the attempted payment (e.g., EUR) |
paymentMethod | The method used for the payment attempt |
paymentReference | A unique reference for the payment |
reason | The reason why the payment failed |
status | Always "failed" for this event type |
OutwardPaymentSent
This event is triggered when an outward payment (withdrawal) has been successfully sent.
Payload Structure
json
{
"amount": 100.00,
"currency": "EUR",
"remittanceInformation": "Withdrawal REF123456789",
"paymentReference": "REF123456789",
"paymentMethod": "bank_transfer",
"notificationType": "OutwardPaymentSent",
"userId": "user_123456789",
"userEmail": "[email protected]",
"creditorBic": "DEUTDEFF",
"creditorName": "Jane Smith",
"creditorAddress": "456 Main St, Frankfurt, Germany",
"creditorAccount": "DE89370400440532013000",
"debtorBic": "SOGEFRPP",
"debtorName": "StableMint",
"debtorAccount": "FR7630007000110009970004942",
"withdrawalReason": "regular_withdrawal",
"idempotencyKey": "idem_123456789",
"websiteReference": "withdrawal_123456789",
"customFields": {
"key1": "value1",
"key2": "value2"
},
"status": "sent"
}Key Fields
| Field | Description |
|---|---|
amount | The amount of the withdrawal |
currency | The currency of the withdrawal (e.g., EUR) |
paymentReference | A unique reference for the withdrawal |
paymentMethod | The method used for the withdrawal |
remittanceInformation | Information that appears on the transaction statement |
creditorBic | The BIC code of the creditor's bank |
creditorName | The name of the creditor (recipient) |
creditorAccount | The IBAN of the creditor's account |
debtorBic | The BIC code of the debtor's bank (StableMint) |
debtorName | The name of the debtor (StableMint) |
debtorAccount | The IBAN of the debtor's account (StableMint) |
withdrawalReason | The reason for the withdrawal |
status | Always "sent" for this event type |
OutwardPaymentFailed
This event is triggered when an outward payment (withdrawal) fails to process.
Payload Structure
json
{
"amount": 100.00,
"currency": "EUR",
"remittanceInformation": "Withdrawal REF123456789",
"paymentReference": "REF123456789",
"notificationType": "OutwardPaymentFailed",
"userId": "user_123456789",
"userEmail": "[email protected]",
"creditorBic": "DEUTDEFF",
"creditorName": "Jane Smith",
"creditorAddress": "456 Main St, Frankfurt, Germany",
"creditorAccount": "DE89370400440532013000",
"debtorBic": "SOGEFRPP",
"debtorName": "StableMint",
"debtorAccount": "FR7630007000110009970004942",
"withdrawalReason": "regular_withdrawal",
"failureReason": "invalid_account_details",
"idempotencyKey": "idem_123456789",
"websiteReference": "withdrawal_123456789",
"customFields": {
"key1": "value1",
"key2": "value2"
},
"status": "failed"
}Key Fields
| Field | Description |
|---|---|
amount | The amount of the attempted withdrawal |
currency | The currency of the withdrawal (e.g., EUR) |
paymentReference | A unique reference for the withdrawal |
remittanceInformation | Information that appears on the transaction statement |
creditorBic | The BIC code of the creditor's bank |
creditorName | The name of the creditor (recipient) |
creditorAccount | The IBAN of the creditor's account |
withdrawalReason | The reason for the withdrawal |
failureReason | The reason why the withdrawal failed |
status | Always "failed" for this event type |
Common Fields Across Event Types
All event payloads include these common fields:
| Field | Description |
|---|---|
notificationType | The type of notification/event |
userId | The unique identifier for the user |
idempotencyKey | A key to ensure idempotent processing (if provided in the original request) |
websiteReference | Your reference for this transaction (if provided in the original request) |
customFields | Any additional custom data provided in the original request |
Testing Webhook Events
You can test your webhook implementation by using the StableMint 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].