Receive a Meld webhook event

curl --request POST \
  --url https://api.sumvin.com/v0/webhooks/meld/events \
  --header 'Content-Type: application/json' \
  --data '
{
  "eventType": "<string>",
  "eventId": "<string>",
  "timestamp": "<string>",
  "payload": {
    "paymentTransactionId": "<string>",
    "paymentTransactionStatus": "<string>",
    "transactionType": "<string>",
    "externalCustomerId": "<string>",
    "customerId": "<string>",
    "externalSessionId": "<string>",
    "sessionId": "<string>",
    "serviceProvider": "<string>",
    "paymentMethodType": "<string>",
    "sourceAmount": 123,
    "sourceCurrencyCode": "<string>",
    "destinationAmount": 123,
    "destinationCurrencyCode": "<string>",
    "createdAt": "<string>",
    "updatedAt": "<string>"
  }
}
'

import requests

url = "https://api.sumvin.com/v0/webhooks/meld/events"

payload = {
    "eventType": "<string>",
    "eventId": "<string>",
    "timestamp": "<string>",
    "payload": {
        "paymentTransactionId": "<string>",
        "paymentTransactionStatus": "<string>",
        "transactionType": "<string>",
        "externalCustomerId": "<string>",
        "customerId": "<string>",
        "externalSessionId": "<string>",
        "sessionId": "<string>",
        "serviceProvider": "<string>",
        "paymentMethodType": "<string>",
        "sourceAmount": 123,
        "sourceCurrencyCode": "<string>",
        "destinationAmount": 123,
        "destinationCurrencyCode": "<string>",
        "createdAt": "<string>",
        "updatedAt": "<string>"
    }
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    eventType: '<string>',
    eventId: '<string>',
    timestamp: '<string>',
    payload: {
      paymentTransactionId: '<string>',
      paymentTransactionStatus: '<string>',
      transactionType: '<string>',
      externalCustomerId: '<string>',
      customerId: '<string>',
      externalSessionId: '<string>',
      sessionId: '<string>',
      serviceProvider: '<string>',
      paymentMethodType: '<string>',
      sourceAmount: 123,
      sourceCurrencyCode: '<string>',
      destinationAmount: 123,
      destinationCurrencyCode: '<string>',
      createdAt: '<string>',
      updatedAt: '<string>'
    }
  })
};

fetch('https://api.sumvin.com/v0/webhooks/meld/events', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sumvin.com/v0/webhooks/meld/events",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'eventType' => '<string>',
    'eventId' => '<string>',
    'timestamp' => '<string>',
    'payload' => [
        'paymentTransactionId' => '<string>',
        'paymentTransactionStatus' => '<string>',
        'transactionType' => '<string>',
        'externalCustomerId' => '<string>',
        'customerId' => '<string>',
        'externalSessionId' => '<string>',
        'sessionId' => '<string>',
        'serviceProvider' => '<string>',
        'paymentMethodType' => '<string>',
        'sourceAmount' => 123,
        'sourceCurrencyCode' => '<string>',
        'destinationAmount' => 123,
        'destinationCurrencyCode' => '<string>',
        'createdAt' => '<string>',
        'updatedAt' => '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sumvin.com/v0/webhooks/meld/events"

	payload := strings.NewReader("{\n  \"eventType\": \"<string>\",\n  \"eventId\": \"<string>\",\n  \"timestamp\": \"<string>\",\n  \"payload\": {\n    \"paymentTransactionId\": \"<string>\",\n    \"paymentTransactionStatus\": \"<string>\",\n    \"transactionType\": \"<string>\",\n    \"externalCustomerId\": \"<string>\",\n    \"customerId\": \"<string>\",\n    \"externalSessionId\": \"<string>\",\n    \"sessionId\": \"<string>\",\n    \"serviceProvider\": \"<string>\",\n    \"paymentMethodType\": \"<string>\",\n    \"sourceAmount\": 123,\n    \"sourceCurrencyCode\": \"<string>\",\n    \"destinationAmount\": 123,\n    \"destinationCurrencyCode\": \"<string>\",\n    \"createdAt\": \"<string>\",\n    \"updatedAt\": \"<string>\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sumvin.com/v0/webhooks/meld/events")
  .header("Content-Type", "application/json")
  .body("{\n  \"eventType\": \"<string>\",\n  \"eventId\": \"<string>\",\n  \"timestamp\": \"<string>\",\n  \"payload\": {\n    \"paymentTransactionId\": \"<string>\",\n    \"paymentTransactionStatus\": \"<string>\",\n    \"transactionType\": \"<string>\",\n    \"externalCustomerId\": \"<string>\",\n    \"customerId\": \"<string>\",\n    \"externalSessionId\": \"<string>\",\n    \"sessionId\": \"<string>\",\n    \"serviceProvider\": \"<string>\",\n    \"paymentMethodType\": \"<string>\",\n    \"sourceAmount\": 123,\n    \"sourceCurrencyCode\": \"<string>\",\n    \"destinationAmount\": 123,\n    \"destinationCurrencyCode\": \"<string>\",\n    \"createdAt\": \"<string>\",\n    \"updatedAt\": \"<string>\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sumvin.com/v0/webhooks/meld/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"eventType\": \"<string>\",\n  \"eventId\": \"<string>\",\n  \"timestamp\": \"<string>\",\n  \"payload\": {\n    \"paymentTransactionId\": \"<string>\",\n    \"paymentTransactionStatus\": \"<string>\",\n    \"transactionType\": \"<string>\",\n    \"externalCustomerId\": \"<string>\",\n    \"customerId\": \"<string>\",\n    \"externalSessionId\": \"<string>\",\n    \"sessionId\": \"<string>\",\n    \"serviceProvider\": \"<string>\",\n    \"paymentMethodType\": \"<string>\",\n    \"sourceAmount\": 123,\n    \"sourceCurrencyCode\": \"<string>\",\n    \"destinationAmount\": 123,\n    \"destinationCurrencyCode\": \"<string>\",\n    \"createdAt\": \"<string>\",\n    \"updatedAt\": \"<string>\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "detail": "No wallet found with ID 12345 for this user.",
  "error_code": "WAL-404-001",
  "instance": "/v0/wallets/12345",
  "status": 404,
  "title": "Wallet Not Found",
  "trace_id": "abc123-def456-ghi789",
  "type": "https://api.sumvin.com/errors/wal-404-001"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Webhooks

Receive a Meld webhook event

Receives signed webhook events from Meld for the configured tenant. Used for KYC status changes, ramp transaction lifecycle (TRANSACTION_CRYPTO_PENDING, TRANSACTION_CRYPTO_TRANSFERRING, TRANSACTION_CRYPTO_COMPLETE, TRANSACTION_CRYPTO_FAILED), and bank-linking events. The exact strings appear on the request body’s eventType field.

Signature scheme: Each request carries two headers that must both be present:

meld-signature — base64url-encoded HMAC-SHA256 over the canonical string "{timestamp}.{url}.{body}", signed with the configured Meld webhook secret. The encoding is base64url with padding.
meld-signature-timestamp — unix epoch seconds at which Meld signed the request.

The {url} segment is the full public URL Meld signed against (scheme + host + path + query). Behind a proxy or load balancer, the request’s effective scheme must reflect X-Forwarded-Proto so that verification matches.

Timestamp tolerance: Requests with a timestamp more than 300 seconds (5 minutes) from server time are rejected before HMAC compute, in either direction.

Failure modes: A missing or invalid signature returns 401 with error code MLD-401-001. The detail is a fixed string and never echoes the client-supplied signature or timestamp. Successful delivery returns 200; replays of the same eventId are accepted as 200 no-ops so Meld’s retries are safe. Handler exceptions surface as 5xx so Meld will retry — silent 200-on-error swallowing is no longer permitted.

POST

webhooks

meld

events

Receive a Meld webhook event

curl --request POST \
  --url https://api.sumvin.com/v0/webhooks/meld/events \
  --header 'Content-Type: application/json' \
  --data '
{
  "eventType": "<string>",
  "eventId": "<string>",
  "timestamp": "<string>",
  "payload": {
    "paymentTransactionId": "<string>",
    "paymentTransactionStatus": "<string>",
    "transactionType": "<string>",
    "externalCustomerId": "<string>",
    "customerId": "<string>",
    "externalSessionId": "<string>",
    "sessionId": "<string>",
    "serviceProvider": "<string>",
    "paymentMethodType": "<string>",
    "sourceAmount": 123,
    "sourceCurrencyCode": "<string>",
    "destinationAmount": 123,
    "destinationCurrencyCode": "<string>",
    "createdAt": "<string>",
    "updatedAt": "<string>"
  }
}
'

import requests

url = "https://api.sumvin.com/v0/webhooks/meld/events"

payload = {
    "eventType": "<string>",
    "eventId": "<string>",
    "timestamp": "<string>",
    "payload": {
        "paymentTransactionId": "<string>",
        "paymentTransactionStatus": "<string>",
        "transactionType": "<string>",
        "externalCustomerId": "<string>",
        "customerId": "<string>",
        "externalSessionId": "<string>",
        "sessionId": "<string>",
        "serviceProvider": "<string>",
        "paymentMethodType": "<string>",
        "sourceAmount": 123,
        "sourceCurrencyCode": "<string>",
        "destinationAmount": 123,
        "destinationCurrencyCode": "<string>",
        "createdAt": "<string>",
        "updatedAt": "<string>"
    }
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    eventType: '<string>',
    eventId: '<string>',
    timestamp: '<string>',
    payload: {
      paymentTransactionId: '<string>',
      paymentTransactionStatus: '<string>',
      transactionType: '<string>',
      externalCustomerId: '<string>',
      customerId: '<string>',
      externalSessionId: '<string>',
      sessionId: '<string>',
      serviceProvider: '<string>',
      paymentMethodType: '<string>',
      sourceAmount: 123,
      sourceCurrencyCode: '<string>',
      destinationAmount: 123,
      destinationCurrencyCode: '<string>',
      createdAt: '<string>',
      updatedAt: '<string>'
    }
  })
};

fetch('https://api.sumvin.com/v0/webhooks/meld/events', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sumvin.com/v0/webhooks/meld/events",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'eventType' => '<string>',
    'eventId' => '<string>',
    'timestamp' => '<string>',
    'payload' => [
        'paymentTransactionId' => '<string>',
        'paymentTransactionStatus' => '<string>',
        'transactionType' => '<string>',
        'externalCustomerId' => '<string>',
        'customerId' => '<string>',
        'externalSessionId' => '<string>',
        'sessionId' => '<string>',
        'serviceProvider' => '<string>',
        'paymentMethodType' => '<string>',
        'sourceAmount' => 123,
        'sourceCurrencyCode' => '<string>',
        'destinationAmount' => 123,
        'destinationCurrencyCode' => '<string>',
        'createdAt' => '<string>',
        'updatedAt' => '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sumvin.com/v0/webhooks/meld/events"

	payload := strings.NewReader("{\n  \"eventType\": \"<string>\",\n  \"eventId\": \"<string>\",\n  \"timestamp\": \"<string>\",\n  \"payload\": {\n    \"paymentTransactionId\": \"<string>\",\n    \"paymentTransactionStatus\": \"<string>\",\n    \"transactionType\": \"<string>\",\n    \"externalCustomerId\": \"<string>\",\n    \"customerId\": \"<string>\",\n    \"externalSessionId\": \"<string>\",\n    \"sessionId\": \"<string>\",\n    \"serviceProvider\": \"<string>\",\n    \"paymentMethodType\": \"<string>\",\n    \"sourceAmount\": 123,\n    \"sourceCurrencyCode\": \"<string>\",\n    \"destinationAmount\": 123,\n    \"destinationCurrencyCode\": \"<string>\",\n    \"createdAt\": \"<string>\",\n    \"updatedAt\": \"<string>\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sumvin.com/v0/webhooks/meld/events")
  .header("Content-Type", "application/json")
  .body("{\n  \"eventType\": \"<string>\",\n  \"eventId\": \"<string>\",\n  \"timestamp\": \"<string>\",\n  \"payload\": {\n    \"paymentTransactionId\": \"<string>\",\n    \"paymentTransactionStatus\": \"<string>\",\n    \"transactionType\": \"<string>\",\n    \"externalCustomerId\": \"<string>\",\n    \"customerId\": \"<string>\",\n    \"externalSessionId\": \"<string>\",\n    \"sessionId\": \"<string>\",\n    \"serviceProvider\": \"<string>\",\n    \"paymentMethodType\": \"<string>\",\n    \"sourceAmount\": 123,\n    \"sourceCurrencyCode\": \"<string>\",\n    \"destinationAmount\": 123,\n    \"destinationCurrencyCode\": \"<string>\",\n    \"createdAt\": \"<string>\",\n    \"updatedAt\": \"<string>\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sumvin.com/v0/webhooks/meld/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"eventType\": \"<string>\",\n  \"eventId\": \"<string>\",\n  \"timestamp\": \"<string>\",\n  \"payload\": {\n    \"paymentTransactionId\": \"<string>\",\n    \"paymentTransactionStatus\": \"<string>\",\n    \"transactionType\": \"<string>\",\n    \"externalCustomerId\": \"<string>\",\n    \"customerId\": \"<string>\",\n    \"externalSessionId\": \"<string>\",\n    \"sessionId\": \"<string>\",\n    \"serviceProvider\": \"<string>\",\n    \"paymentMethodType\": \"<string>\",\n    \"sourceAmount\": 123,\n    \"sourceCurrencyCode\": \"<string>\",\n    \"destinationAmount\": 123,\n    \"destinationCurrencyCode\": \"<string>\",\n    \"createdAt\": \"<string>\",\n    \"updatedAt\": \"<string>\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "detail": "No wallet found with ID 12345 for this user.",
  "error_code": "WAL-404-001",
  "instance": "/v0/wallets/12345",
  "status": 404,
  "title": "Wallet Not Found",
  "trace_id": "abc123-def456-ghi789",
  "type": "https://api.sumvin.com/errors/wal-404-001"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Headers

meld-signature

string | null

meld-signature-timestamp

string | null

X-Timestamp-Format

string

Controls how timestamp fields are serialized in JSON response bodies.

Default (header omitted or any other value): epoch milliseconds as integers. iso8601: UTC ISO 8601 strings of the form YYYY-MM-DDTHH:MM:SSZ.

Example: with X-Timestamp-Format: iso8601, the field value 1704067200000 becomes "2024-01-01T00:00:00Z".

Affected fields (recursively, in dicts and arrays): any field whose name ends in _at, plus the literal field names timestamp, period_start, and period_end. All other fields are passed through unchanged.

Only iso8601 is recognized. Any other value (or omitting the header) yields the default epoch-ms representation; the server does not reject unknown values, so this is documented as an example rather than an enum to keep generated clients permissive.

Example:

"iso8601"

Body

application/json

eventType

string

required

Meld event type (e.g. TRANSACTION_CRYPTO_COMPLETE).

eventId

string

required

Unique identifier for the webhook delivery.

timestamp

string

required

Provider-emitted event timestamp.

payload

MeldWebhookEventPayload · object

required

Inner payload of a Meld webhook event for ramp transaction lifecycle.

Captures the documented fields Meld sends in the payload envelope for TRANSACTION_CRYPTO_* events. Marked extra="allow" so future Meld fields are preserved without breaking parsing. Fields are optional except paymentTransactionId, which always identifies the ramp transaction.

Show child attributes

Response

Webhook received

⌘I

Introduction

Quickstarts

Guides

Product Guides

API Reference

Receive a Meld webhook event

Headers

Body

Response