Yaspa moved the US Product Suite to Webhook version 3 in October 2026. Merchants already integrated to version 2 ("version": "2" in the webhook data payload) are encouraged to upgrade to version 3 and may reference this addendum in the meantime.

Guaranteed Payments

Webhooks are sent as HTTPS POST requests, and a typical example of the request body is as follows:

{
  "type": "PAYIN_DECISION",
  "data": {
    "id": "69ab3af808d30a1a7b0611a5",
    "transactionId": "bc919c85-8071-3272-73e9-862dba",
    "merchantId": "68dba7fb9bb0a3111957f0b1",
    "merchantTradingName": "Halloween Shop",
    "customerIdentifier": "7fce2gqrdwld",
    "version": "2",
    "journeyType": "INTELLIGENT_PAYMENT",
    "transactionType": "PAYIN",
    "authType": "STANDARD",
    "transactionStatus": "ACCEPTED",
    "creationDate": 1772829432964,
    "testParameters": {},
    "language": "en",
    "userDetailsReference": {
      "documentId": "69ab3af808d30a1a7b0611a3",
      "index": 0
    },
    "showReceipt": false,
    "paymentMethod": "OTHER",
    "paymentGiro": "ACH",
    "customerAccountId": "CHECKING",
    "customerAccountNumber": "7890",
    "customerBankCode": "222222226",
    "customerName": "John Smith",
    "merchantAccountNumber": "cbe99239-943a-4ed7-98da-22da07e158b0",
    "merchantBankCode": "cbe99239-943a-4ed7-98da-22da07e158b0",
    "paymentAmount": "12.34",
    "paymentCurrency": "USD",
    "reference": "7fce2gqrdwld",
    "paymentProvider": "CITIZEN_TEST_BANK_US",
    "cancelledByTerminal": false,
    "retailRefundUnAcknowledgedPayins": false,
    "refundBecauseOfCancellation": false,
    "metaData": {},
    "physicalQRJourney": false,
    "enhancedPayIn": false,
    "payloadEncrypted": false,
    "verifiedJourney": true
  }
}

Webhooks often contain other body parameters, including optional parameters carried through the system and objects for tasks such as name matching. As such, it is critically important that webhook handlers do not use strict mode parsing on the example above or samples from testing. A selection of relevant parameters are defined in the table below:

Parameter	Type	Definition (assigned by Yaspa unless noted otherwise)
type	string	Type of webhook (see Guaranteed Payments)
id	string	Session identifier
transactionId	string	Transaction identifier
merchantId	string	Merchant identifier
merchantTradingName	string	Merchant trading name
customerIdentifier	string	User identifier provided by the merchant in the customerIdentifier parameter of the API request
version	string	API version
journeyType	string	Type of journey specified by the merchant in the journeyType parameter of the API request
transactionType	string	Type of payment or hosted session as identified in the API request URL
authType	string	Authorization/signing type
transactionStatus	string	Current status of the transaction (see Guaranteed Payments)
creationDate	number	Date transaction was created, unix timestamp in milliseconds
language	string	Language of the payment session
error	string	Error code, included for PAYIN_ERROR webhooks
errorReason	string	Long form explanation of the error code, included for PAYIN_ERROR webhooks
paymentMethod	string	Method of payment
paymentGiro	string	Payment rail used
customerAccountId	string	Type of account selected by the user for payment
customerAccountNumber	string	Last four digits of the user’s selected account number
customerBankCode	string	Routing number of the account selected by the user for payment
customerName	string	Account holder name for the account provided by the user for payment
merchantAccountNumber	string	Account number for the virtual account assigned to the merchant
merchantBankCode	string	Routing number for the virtual account assigned to the merchant
paymentAmount	string	Payment amount specified by the merchant in the API request
paymentCurrency	string	Payment currency specified by the merchant in the API request
reference	string	Transaction identifier provided by the merchant in the reference parameter of the API request
paymentProvider	string	Bank for the account selected by the user for payment

Payouts

Webhooks are sent as HTTPS POST requests, and a typical example of the request body is as follows:

{
  "type": "PAYOUT_ACCEPTED",
  "data": {
    "id": "69fb202ccbaf291786487d7d",
    "transactionId": "6e1105a9-7dcc-3f92-3b2c-e72aa5",
    "merchantId": "68dba7fb9bb0a3111957f0b1",
    "merchantTradingName": "Halloween Shop",
    "customerIdentifier": "9amqq4uk4au5",
    "version": "2",
    "journeyType": "HOSTED_PAYOUT",
    "authType": "STANDARD",
    "transactionStatus": "ACCEPTED",
    "creationDate": 1778065452182,
    "testParameters": {},
    "language": "en",
    "userDetailsReference": {
      "documentId": "69fb1fd6cbaf291786487d78",
      "index": 0
    },
    "citizenCounterPartyId": "69c15af567f8982c8166524c",
    "providerBankAccountId": "cbe99239-943a-4ed7-98da-22da07e158b0",
    "providerPaymentId": "mock-payout-tx-1778065474273",
    "currency": "USD",
    "paymentGiro": "ACH",
    "merchantBank": "DWOLLA",
    "counterPartyBank": "CITIZEN_TEST_BANK_US",
    "counterPartyBankCode": "222222226",
    "counterPartyAccountNumber": "7890",
    "counterPartyAccountName": "John Smith",
    "amount": "12.34",
    "reference": "ba4kz14pb7t4",
    "disableAddingNewBanks": true,
    "merchantWithdrawal": false,
    "payloadEncrypted": false,
    "verifiedJourney": false
  }
}

Parameter	Type	Definition (assigned by Yaspa unless noted otherwise)
type	string	Type of webhook (see Payouts)
id	string	Session identifier
transactionId	string	Transaction identifier
merchantId	string	Merchant identifier
merchantTradingName	string	Merchant trading name
customerIdentifier	string	User identifier provided by the merchant in the customerIdentifier parameter of the API request
version	string	API version
journeyType	string	Type of journey specified by the merchant in the journeyType parameter of the API request
authType	string	Authorization/signing type
transactionStatus	string	Current status of the transaction (see Payouts)
creationDate	number	Date transaction was created, unix timestamp in milliseconds
language	string	Language of the payment session
currency	string	Currency of the payout as specified by the merchant in the API request
paymentGiro	string	Payment rail used
merchantBank	string	Yaspa banking partner from which funds are credited
counterPartyBank	string	Bank selected by the user
counterPartyBankCode	string	Routing number for the user’s bank
counterPartyAccountNumber	string	Last four digits of the user’s selected account number
counterPartyAccountName	string	Account holder name for the account provided by the user for payment
amount	string	Payment amount specified by the merchant in the API request
reference	string	Transaction identifier provided by the merchant in the reference parameter of the API request
disableAddingNewBanks	boolean	True if specified as closed loop by the merchant in the API request, false otherwise