Yaspa’s webhook notifications are standardized across US pay-ins and payouts as specified below for simplicity and so that related events can be traced back to their starting points. For example, required merchant-assigned parameters such as customerIdentifier and reference are echoed in every related webhook so that payment status updates can be mapped to the original payment request.
Payment webhook data also carry over to insights. If a first-time user submits a payment and the merchant is configured for insights webhooks, the insights webhooks will carry the same customer.Identifier and account.Identifier parameters so that the insights can be mapped back to the customer and the account they used for payment. Refer to the Intelligent Payments section for information about insights webhooks which follow a similar convention to the payment webhooks but use a different structure within the data object payload.
⚠️Yaspa webhooks omit null values and empty nested blocks unless noted otherwise. For example, a successful payment's webhook has no error object, and description is omitted if none was sent in the request. Any webhook may also contain additional optional parameters that aren't listed here or shown in the examples. Do not use strict-mode parsing on the examples in the product webhook sections, or on samples from testing.
Refer to Webhook Configuration & Processing for more information.
📘Yaspa is currently on webhook version 3. If you are integrated to version 2 ("version": "2" in the webhook data payload), please refer to the Webhook v2 Addendum or contact Yaspa to upgrade to version 3.
| Header | Description |
|---|
citizen-public-api-key | The merchant's public API key |
webhook-signature | Signature over the JSON serialization of the whole envelope |
citizen-signature | Signature over the JSON serialization of data only |
content-type | application/json |
user-agent | Only when the webhook has a customUserAgent configured |
ID | Unique identifier for the webhook which may be used to detect duplicates |
| Field | Type | Description |
|---|
type | string | Event that triggered the webhook: |
data | object | Event payload, see Data |
| Field | Type | Description |
|---|
id | string | Yaspa database identifier for the payment |
transactionId | string | Primary Yaspa transaction identifier, for merchants to trace |
version | string | Payload schema version |
transactionType | string | Type of transaction, such as "PAYIN" or "PAYOUT" |
transactionStatus | string | Status of the transaction when the webhook was sent |
createdAt | string | ISO 8601 datetime of transaction creation |
reference | string | Merchant-assigned payment identifier |
description | string | Merchant-assigned payment descriptor. Pay-in only. |
language | string | Two-character ISO 639-1 language code used by the customer |
tags | object | Merchant-assigned tags, as {string: string[]} |
metadata | object | Merchant- and system-set key/values, as {string: string[]}. Pay-in only. |
merchant | object | Receiving merchant and account information. See Merchant. |
customer | object | User information. See Customer. |
account | object | The user's account information. See Account. |
payment | object | Basic payment information. See Payment. |
journey | object | Journey type and flags. See Journey. |
error | object | Error data. See Error. |
review | object | Held payout information. Payout only. See Review. |
refund | object | Information about a refunded pay-in. See Refund. |
crypto | object | Crypto payment metadata. See Crypto. |
| Field | Type | Description |
|---|
id | string | Yaspa-assigned merchant identifier |
tradingName | string | The merchant's trading or doing-business-as name |
accountNumber | string | Account number of the merchant's virtual account |
bankCode | string | Routing number of the merchant's virtual account |
dedicatedAccountNumber | string | Per-customer receiving account number, for merchants that give each customer a dedicated account |
dedicatedBankCode | string | Bank code of the dedicated account |
bank | string | Yaspa banking partner holding the merchant's virtual account |
withdrawal | boolean | true only when a payout is a merchant withdrawal |
| Field | Type | Description |
|---|
identifier | string | User identifier the merchant sent in the customerIdentifier request parameter |
merchantCustomerId | string | Yaspa-assigned identifier for the merchant and user in combination |
emailAddress | string | Email address the user entered in the hosted journey |
details | object | Details about the user provided by the merchant. Typically excluded from US Product Suite webhooks for clarity. See Customer Details. |
nameCheck | object | Name match and scoring information at the time of the webhook. See Name Check. |
All values are as provided by the merchant in the request.
| Field | Type | Description |
|---|
firstName | string | First name |
lastName | string | Last name |
dob | string | Date of birth |
mobile | string | Mobile phone number |
sex | string | Sex |
nationality | string | Nationality |
street | string | Address street |
city | string | Address city |
state | string | Address state |
zip | string | Address zip code |
country | string | Address country |
address | object | Address. See Address. |
brandName | string | Lobby URL identifier |
affiliateId | string | Affiliate identifier |
customerValue | string | Customer value |
All values are as provided by the merchant in the request.
| Field | Type | Description |
|---|
address1 | string | Address line one |
address2 | string | Address line two |
city | string | City |
countryCode | string | Country |
stateCode | string | State |
zipCode | string | Zip code |
| Field | Type | Description |
|---|
nameCheckStatus | string | "PENDING", "PASS" or "FAIL" |
nameCheckScore | integer | Name match score between 0 and 100 |
merchantThreshold | integer | Pass threshold configured for the merchant |
nameCheckActions | array of strings | Configured actions: one or more of "MARK", "FLAG" and "ACT" |
flaggedForReview | boolean | true if the result was flagged for manual review |
stage | string | Stage in the journey where the name check ran |
nameCheckHistory | array | Per-rule scores, as {score, ruleName} |
nameCheckInputs | object | The names compared, as {kycName, accountHolderName} |
| Field | Type | Description |
|---|
identifier | string | Yaspa-assigned unique identifier for the account |
financialInstitution | string | Display name of the bank holding the account |
type | string | Type of account, such as CHECKING |
holderName | string | First and last name of the account holder |
numberLastFour | string | Last four digits of the account number, for example "1234" |
routingNumber | string | ABA routing number of the account |
verificationTransactionId | string | Transaction ID of the account verification session, if applicable |
counterPartyId | string | Yaspa counterparty identifier |
dataAccessStatus | string | "CONNECTED" if the bank account connection is active, otherwise omitted |
dataLastUpdated | string | ISO 8601 datetime when data was last retrieved from the bank |
| Field | Type | Description |
|---|
amount | string | Payment amount as a positive number to two decimal places |
currency | string | ISO 4217 currency code, "USD" |
giro | string | Payment rail used |
providerStatusCode | string | Provider-level ISO 20022-style status code |
networkTransactionId | string | Identifier for the payment assigned by the payment network |
providerPaymentId | string | Payout provider's payment identifier. Payout only. |
| Field | Type | Description |
|---|
type | string | Journey used for the transaction, typically "INTELLIGENT_PAYMENT" |
authType | string | Authorization type, nearly always "STANDARD" |
verified | boolean | true if the journey included account verification |
enhanced | boolean | true if this was an enhanced pay-in. Nearly always false. |
physicalQRCodeId | string | Identifier of the physical QR code used to start the journey from a QR code or terminal |
| Field | Type | Description |
|---|
code | string | Error code |
reason | string | Human-readable error reason mapped to the error code |
details | object | Additional structured details about the error. Polymorphic. |
| Field | Type | Description |
|---|
heldReason | string | Reason the payout was held for review. Payout only. |
rejectionReason | string | Reason the payout was rejected. Payout only. |
| Field | Type | Description |
|---|
reason | string | Reason for the refund |
status | string | Refund status |
createdAt | string | ISO 8601 datetime when the refund was created |
payoutTransactionId | string | Identifier of the refund transaction itself. Pay-in only. |
cancelledByTerminal | boolean | Whether a point-of-sale terminal cancelled the pay-in. Never null. |
dueToCancellation | boolean | Whether the refund was triggered by a cancellation |
payInTransactionId | string | Identifier of the transaction being refunded. Payout only. |
| Field | Type | Description |
|---|
transactionHash | string | On-chain transaction hash |
chain | string | Blockchain network |
token | string | Token or asset symbol |
amountReceived | string | Amount received on chain |
wallet.senderAddress | string | Sending wallet address |
wallet.recipientAddress | string | Receiving wallet address |
