{
"transaction": {
"id": "uspay-h4n2qz8kx1cvb7twm3rd9pol",
"type": "DEPOSIT",
"createdAt": "2026-09-25T14:02:11.000Z",
"updatedAt": "2026-09-26T13:30:05.512Z",
"completedAt": "2026-09-26T13:30:05.512Z",
"status": "COMPLETED",
"referenceNumber": "MA0F0FXM9BZT8V",
"debitAmount": "2500.00",
"netDebitAmount": "2500.00",
"debitCurrency": "USD",
"debitParty": {
"partyType": "PAYER",
"payer": {
"displayName": "Northwind Realty LLC",
"accountNumber": "****1234",
"institutionName": "First Example Bank",
"bankCode": "123456780"
}
},
"debitRail": "US.USD.ACH",
"debitReference": "123456780000001",
"creditAmount": "2500.00",
"creditCurrency": "USD",
"creditInstrument": {
"instrumentType": "ACCOUNT",
"account": {
"id": "uspay-e1vitcef84g1ekzio62mwe3x",
"displayName": "USD Balance",
"currency": "USD"
}
},
"fees": [],
"exchangeRate": "1.00",
"tags": []
},
"metadata": {
"userId": "ususr-c2yulm8b8phkkjpbzra2s263",
"programId": "usrem-bvjxs5xuca4oa093pax3p6p2"
}
}Transaction
Learn when transaction webhooks are sent and what data they include.
{
"transaction": {
"id": "uspay-h4n2qz8kx1cvb7twm3rd9pol",
"type": "DEPOSIT",
"createdAt": "2026-09-25T14:02:11.000Z",
"updatedAt": "2026-09-26T13:30:05.512Z",
"completedAt": "2026-09-26T13:30:05.512Z",
"status": "COMPLETED",
"referenceNumber": "MA0F0FXM9BZT8V",
"debitAmount": "2500.00",
"netDebitAmount": "2500.00",
"debitCurrency": "USD",
"debitParty": {
"partyType": "PAYER",
"payer": {
"displayName": "Northwind Realty LLC",
"accountNumber": "****1234",
"institutionName": "First Example Bank",
"bankCode": "123456780"
}
},
"debitRail": "US.USD.ACH",
"debitReference": "123456780000001",
"creditAmount": "2500.00",
"creditCurrency": "USD",
"creditInstrument": {
"instrumentType": "ACCOUNT",
"account": {
"id": "uspay-e1vitcef84g1ekzio62mwe3x",
"displayName": "USD Balance",
"currency": "USD"
}
},
"fees": [],
"exchangeRate": "1.00",
"tags": []
},
"metadata": {
"userId": "ususr-c2yulm8b8phkkjpbzra2s263",
"programId": "usrem-bvjxs5xuca4oa093pax3p6p2"
}
}Authorizations
Meridian signs every webhook it sends you.
Headers on every delivery:
- X-Meridian-Api-Key
- X-Meridian-Timestamp
- X-Meridian-Signature
X-Meridian-Signature is the lowercase hex HMAC-SHA256 of apiKey + timestamp + "POST" + path + body, keyed with your webhook secret. The path is the path of your webhook URL, without any query string. The body is the raw request body, byte for byte. Recompute the signature and reject the request if it does not match. See Security.
Headers
The resource this event is about. Always transaction for this webhook.
"transaction"Which event fired. transaction_created when a transaction is first recorded, transaction_status_updated when its status is written.
transaction_created, transaction_status_updated Your webhook API key. Meridian issues it separately from your REST API credentials, and uses one key for every webhook event. Use it to choose the webhook secret to verify with. The key on its own does not prove the request came from Meridian; the signature does.
When Meridian signed this delivery attempt, in milliseconds since the Unix epoch. Every retry is signed again, so each attempt has a new timestamp. Reject requests whose timestamp is far from your own clock.
^[0-9]+$Body
A transaction, in the same shape as GET /v1/transactions/{transactionId}. Fields with no value are left out rather than sent as null.
Show child attributes
Show child attributes
Identifies the user and program the event belongs to.
Show child attributes
Show child attributes
Response
Return any 2xx status within 10 seconds to acknowledge the webhook.