Webhooks are a crucial mechanism for merchants to receive notifications about Payout creation and Payout status changes. All Payout webhooks have a webhook_type that begins with PAYOUT_.

Webhook processing and Security

Yaspa Webhooks are sent via HTTPS and are signed. For information on processing and around Webhook security see the section here - Webhooks.

Payout Webhook Status Types

Webhook	Description	Payout Transaction Status
`PAYOUT_QUEUED`	Payout was added to the queue for approval	`QUEUED`
`PAYOUT_ERROR`	An error occurred	`ERROR` or `FAILED`
`PAYOUT_REJECTED`	Payout that was in 'queued' was rejected	`CANCELLED BY MERCHANT`
`PAYOUT_EXPIRED`	The user has dropped out of the journey before the payout has been queued or accepted	`EXPIRED`
`PAYOUT_ACCEPTED`	The payout has been accepted by the sending bank	`ACCEPTED`

Payout Webhook Parameters

Parameter	Description
`citizenTransactionId`	Citizen transaction ID
`merchantId`	The ID of your merchant
`merchantTradingName`	The trading name of your merchant
`customerIdentifier`	customer ID in your system
`transactionStatus`	The payout status
`creationDate`	Date of creation
`citizenCounterPartyId`	The ID of the counterparty (e.g. the customer)
`currency`	The currency of the payout
`paymentGiro`	Payment rail used (e.g. `FPS`)
`merchantBank`	The bank of the merchant
`counterPartyBank`	The bank of the customer requesting the payout
`counterPartyBankCode`	The bank code of the customer
`counterPartyAccountNumber`	The account number of the customer
`counterPartyAccountName`	The account name of the customer
`searchableText`	A string you can use to search for this payout
`amount`	The amount of the payout
`reference`	The reference attached to the payout
`payload`	Meta-data associated with the payout
`payloadEncrypted`	Boolean value indicating whether the payload is encrypted

Payout Status

The events above each contain a status; the table below provides more details on what each status means.

TransactionStatus	Description	Terminal Status
CREATED	The journey has begun and the user is about to request the bank they want to be paid into (for hosted journeys)
QUEUED	The payout has been added to a queue and is pending an approval decision by the merchant	Yes
ACCEPTED	The payout has been accepted for processing by the bank
CANCELLED_BY_MERCHANT	The queued payout has been rejected by the merchant	Yes
EXPIRED	The payout has expired without the user authorising it	Yes
FAILED	The payout failed to be authorised by the bank	Yes
ERROR	The payout failed to be submitted	Yes

When a terminal status is reached under normal operation, there will be no further events for the payout. merchants should configure the admin dashboard to receive all terminal webhooks. Non-terminal Webhooks can mostly be ignored, unless the merchant has special requirements or wants a more complete log of the customer's progress.