DocsAPI Reference
Log In
Docs
Start typing to search…

Webhook Events

Webhook Events

Webhooks provide real-time notifications when transaction statuses change. Instead of polling for updates, Meld sends HTTP POST requests to your configured endpoint whenever events occur. You should use the webhooks as triggers to call the Meld transactions endpoint to fetch the latest details on the transaction.

Benefits

  • Real-time updates: Immediate notification of status changes
  • Reduced latency: No polling delays
  • Lower infrastructure cost: No need for frequent API calls
  • Reliable delivery: Built-in retry mechanisms

Event Structure

All webhook events share the same base structure:

Common Attributes

FieldTypeDescription
eventTypeStringType of event (e.g., TRANSACTION_CRYPTO_PENDING)
eventIdStringMeld's unique identifier for this event
timestampOffsetDateTimeWhen the event was created
accountIdStringYour Meld account identifier
profileIdStringWebhook profile responsible for sending this event
versionDateAPI version (e.g., 2025-03-01)
payloadObjectEvent-specific data containing transaction details
transactionTypeStringCRYPTO_PURCHASE, CRYPTO_SELL, or CRYPTO_TRANSFER

Payload Fields

The payload object contains transaction-specific information:

FieldTypeDescription
accountIdStringMeld account identifier
customerIdStringMeld's internal customer identifier
externalCustomerIdStringYour customer ID (if provided during session creation)
externalSessionIdStringYour session ID (if provided during session creation)
paymentTransactionIdStringMeld's unique transaction identifier
paymentTransactionStatusStringCurrent transaction status
sessionIdStringMeld's internal session identifier
⚠️

Note: For PENDING_CREATED status, sessionId and externalSessionId may be missing as the transaction hasn't been tied to a session yet. You can safely ignore these early-stage webhooks if needed.

Event Types

TRANSACTION_CRYPTO_PENDING

Triggered when a user starts the payment process (logged in, completed KYC).

{
  "eventType": "TRANSACTION_CRYPTO_PENDING",
  "eventId": "AAsuLXHXD3mS1cjNBuHHzv",
  "timestamp": "2022-02-24T16:36:41.717262Z",
  "accountId": "W2aRZnYGPwhBWB94iFsZus",
  "profileId": "W9ka8vLE4ufBkSg3BEciZb",
  "version": "2025-03-01",
  "payload": {
    "requestId": "f07f1accb7404aec9bd9a5d64975eed1",
    "accountId": "W2aRZnYGPwhBWB94iFsZus",
    "paymentTransactionId": "W9k9Tg12BFk1i68WpQYQY8",
    "customerId": "W9k9TfNSJRZ6rDBe95bUA2",
    "externalCustomerId": "customer_1234443",
    "externalSessionId": "test_session1",
    "paymentTransactionStatus": "PENDING",
    "transactionType": "CRYPTO_PURCHASE",
    "sessionId": "WeQBQxGxq3AyHdcaoUDoAJ"
  }
}

TRANSACTION_CRYPTO_TRANSFERRING

Triggered when payment is approved and crypto transfer begins.

{
  "eventType": "TRANSACTION_CRYPTO_TRANSFERRING",
  "eventId": "NQ7wCUFFuAgUCVyZkRu9cH",
  "timestamp": "2022-02-15T23:05:43.782919Z",
  "accountId": "W2aRZnYGPwhBWB94iFsZus",
  "profileId": "W9ka8vLE4ufBkSg3BEciZb",
  "version": "2025-03-01",
  "payload": {
    "requestId": "f07f1accb7404aec9bd9a5d64975eed2",
    "accountId": "W2aRZnYGPwhBWB94iFsZus",
    "paymentTransactionId": "W9kNggNMASvX8NVK8LFCWg",
    "customerId": "W9jtN15ukoLJKgQe8Xb5MS",
    "externalCustomerId": "customer_1234443",
    "externalSessionId": "test_session1",
    "paymentTransactionStatus": "SETTLING",
    "transactionType": "CRYPTO_PURCHASE",
    "sessionId": "WeQBQxGxq3AyHdcaoUDoAJ"
  }
}

TRANSACTION_CRYPTO_COMPLETE

Triggered when transaction completes successfully (crypto delivered).

{
  "eventType": "TRANSACTION_CRYPTO_COMPLETE",
  "eventId": "4cpRbNMyteKPzivtZ2RT4o",
  "timestamp": "2022-02-24T00:24:53.650382Z",
  "accountId": "W2aRZnYGPwhBWB94iFsZus",
  "profileId": "W9ka8vLE4ufBkSg3BEciZb",
  "version": "2025-03-01",
  "payload": {
    "requestId": "f07f1accb7404aec9bd9a5d64975eed3",
    "accountId": "W2aRZnYGPwhBWB94iFsZus",
    "paymentTransactionId": "W9jHTkUEacFrcBuEPjXtdE",
    "customerId": "W9jtN15ukoLJKgQe8Xb5MS",
    "externalCustomerId": "customer_1234443",
    "externalSessionId": "test_session1",
    "paymentTransactionStatus": "SETTLED",
    "transactionType": "CRYPTO_PURCHASE",
    "sessionId": "WeQBQxGxq3AyHdcaoUDoAJ"
  }
}

TRANSACTION_CRYPTO_FAILED

Triggered when transaction fails or encounters an error.

{
  "eventType": "TRANSACTION_CRYPTO_FAILED",
  "eventId": "AvCd2ZKy5PCdzyCYRU7ENe",
  "timestamp": "2022-02-24T20:05:13.909581Z",
  "accountId": "W2aRZnYGPwhBWB94iFsZus",
  "profileId": "W9ka8vLE4ufBkSg3BEciZb",
  "version": "2025-03-01",
  "payload": {
    "requestId": "f07f1accb7404aec9bd9a5d64975eed4",
    "accountId": "W2aRZnYGPwhBWB94iFsZus",
    "paymentTransactionId": "W9kLVLCaQSXz8pgaUHYK4E",
    "customerId": "W9kL817BBS7bNEwxAZaX4z",
    "externalCustomerId": "customer_9888888",
    "externalSessionId": "test_session1",
    "paymentTransactionStatus": "ERROR",
    "transactionType": "CRYPTO_PURCHASE",
    "sessionId": "WeQBQxGxq3AyHdcaoUDoAJ"
   }
}

Implementation Tips

Response Requirements: Your webhook endpoint must return a 2xx HTTP status code to acknowledge receipt.

Retry Logic: Meld automatically retries failed webhook deliveries with exponential backoff.

Idempotency: Use eventId to handle duplicate deliveries safely.

Error Handling: Implement graceful error handling for malformed or unexpected webhook payloads.

Updated 24 days ago