Webhooks

Webhooks follow this workflow:

Payloads & Templates

A payload is capable of accommodating various shapes and can be modified to incorporate specific variables corresponding to the relevant event.

Below is an instance of a Payment.Succeeded event's payload template and its resolved response after variable replacement.

Payload Template Example

{
  "action": "{{EventType}}",
  "payload": {
    "sessionIdentifier": "{{SessionIdentifier}}",
    "status": "{{Status}}",
    "referenceNumber": "{{ReferenceNumber}}",
    "amount": "{{Amount}}",
    "accountNumber": "{{AccountNumber}}",
    "accountName": "{{AccountName}}",
    "paymentIdentifier": "{{PaymentMetaJson_PaymentIdentifier}}",
    "amountFormatted": "{{AmountFormatted}}",
    "serviceFee": "{{ServiceFeeAmountMinor}}"
  }
}

Resolved Payload Example

{
  "action": "Payment.Succeeded",
  "payload": {
    "sessionIdentifier": "a6fb5g42-4280-46af-b04e-2c58067bc111",
    "status": "Succeeded",
    "referenceNumber": "NYDVNT-WSQPG",
    "amount": "300.34",
    "accountNumber": "123-45",
    "accountName": "John Smith",
    "paymentIdentifier": "",
    "amountFormatted": "$300.34",
    "serviceFee": "1012"
  }
}

Events Details

AutoPay.Enrolled

Variable Name	Description
AccountId	ID of the account enrolled in Autopay.
AccountName	Name on the account.
AccountNumber	Account number on the account.
ActivityType	Type of activity (enroll, update settings, cancel).
CustomerEmailAddress	Email address of the customer.
CustomerId	ID of the customer enrolled in Autopay.
DueDate	Due date of the account.
MaximumBalanceAllowed	Maximum balance allowed to be withdrawn for Autopay.
PaymentSourceDescription	Description of the payment source used for Autopay. (x ending in y).
ProcessingLeadTime	Days before due date the payment will process.
SubAccountNumber	SubAccount number on the account.

Payload Template Example

{
    "accountName": "{{AccountName}}",
    "subAccountNumber": "{{SubAccountNumber}}",
    "activityType": "{{ActivityType}}",
    "paymentSource": "{{PaymentSourceDescription}}",
    "processingLeadTime": "{{ProcessingLeadTime}}"
}

Resolved Payload Example

{
    "accountName": "John Smith",
    "subAccountNumber": "223",
    "activityType": "enroll",
    "paymentSource": "Visa ending with 1234",
    "processingLeadTime": "OnDueDate"
}

AutoPay.Unenrolled

Variable Name	Description
AccountId	ID of the account unenrolled in Autopay.
AccountName	Name on the account.
AccountNumber	Account number on the account.
ActivityType	Type of activity
CustomerEmailAddress	Email address of the customer.
CustomerId	ID of the customer unenrolled in Autopay.
DueDate	Due date of the account.
MaximumBalanceAllowed	Maximum balance allowed to be withdrawn for Autopay.
PaymentSourceDescription	Description of the payment source used for Autopay. (x ending in y).
ProcessingLeadTime	Days before due date the payment will process.
SubAccountNumber	SubAccount number on the account.

Payload Template Example

{
    "accountName": "{{AccountName}}",
    "accountNumber": "{{AccountNumber}}",
    "emailAddress": "{{CustomerEmailAddress}}",
    "dueDate": "{{DueDate}}",
}

Resolved Payload Example

{
    "accountName": "Mary Johnson",
    "accountNumber": "325",
    "emailAddress": "[email protected]",
    "dueDate": "04/22/23",
}

PaperlessBilling.Enrolled

Variable Name	Description
AccountEmailAddress	Email address of the account that enrolled in paperless billing.
AccountName	Name on the account that enrolled in paperless billing.
AccountNumber	Account number on the account that enrolled in paperless billing.
SubAccountNumber	SubAccount number on the account that enrolled in paperless billing.
UserEmailAddress	Email address of the user that enrolled in paperless billing.

Payload Template Example

{
  "businessUnitSlug": "{{JobExecution_BusinessUnitSlug}}",
  "accountNumber": "{{AccountNumber}}",
  "email": "{{AccountEmailAddress}}",
  "enrollingInPaperlessBilling": true,
  "onFailUrl": "{{InitiateFunctionOrchestration_FailExecutionUrl}}"
}

Resolved Payload Example

{
  "businessUnitSlug": "water-bill-pay",
  "accountNumber": "123",
  "email": "[email protected]",
  "enrollingInPaperlessBilling": true,
  "onFailUrl": "https://gateway.paystar.io/..."
}

PaperlessBilling.Unenrolled

Variable Name	Description
AccountEmailAddress	Email address of the account that unenrolled from paperless billing.
AccountName	Name on the account that unenrolled from paperless billing.
AccountNumber	Account number on the account that unenrolled from paperless billing.
SubAccountNumber	SubAccount number on the account that unenrolled from paperless billing.
UserEmailAddress	Email address of the user that unenrolled from paperless billing.

Payload Template Example

{
  "businessUnitSlug": "{{JobExecution_BusinessUnitSlug}}",
  "accountNumber": "{{AccountNumber}}",
  "email": "{{AccountEmailAddress}}",
  "enrollingInPaperlessBilling": false,
}

Resolved Payload Example

{
  "businessUnitSlug": "water-bill-pay",
  "accountNumber": "123",
  "email": "[email protected]",
  "enrollingInPaperlessBilling": false,
}

Payment.AdjustmentFound

Variable Name	Description
AccountId	The ID of the account on the payment.
AccountNumber	The account number of the account on the payment.
AdjustmentAmount	Amount in the adjustment.
AdjustmentAmountFormattedUsd	The adjustment amount formatted in USD.
AdjustmentCode	Code of the adjustment.
AdjustmentDate	Date of the adjustment.
AdjustmentId	ID of the adjustment.
AdjustmentType	Type of the adjustment.
AmountValue	Amount of the transaction.
AuthCode	AuthCode of the transaction.
BatchId	ID of the batch.
BusinessUnitId	ID of the business unit the adjustments were found in.
Channel	Channel the payment was made in.
MerchantNumber	Merchant number of the adjustment.
PaymentId	ID of the payment.
PaymentReferenceNumber	Reference number on the transaction.
PaymentStatus	Status of the payment.
PaymentType	Type of payment. (Ex. Base Payment, Service Fee)
ServiceFeeAmount	Amount of the service fee in the payment.
SubAccountNumber	The subaccount number of the account on the payment.
TransactionId	ID of the transaction.
TransactionReferenceNumber	The reference number of the transaction.
TransactionType	Type of transaction. (Ex. Sale)

Payload Template Example

{
  "adjustmentType": "{{AdjustmentType}}",
  "accountNumber": "{{AccountNumber}}",
  "amountFormatted": "{{AdjustmentAmountFormattedUsd}}",
  "transactionReferenceNumber": "{{TransactionReferenceNumber}}",
  "paymentType": "{{PaymentType}}",
  "channel": "{{Channel}}"
}

Resolved Payload Example

{
  "adjustmentType": "ACH Return",
  "accountNumber": "1234",
  "amountFormatted": "$200.50",
  "transactionReferenceNumber": "242424242",
  "paymentType": "Base Payment",
  "channel": "QuickPay"
}

Payment.Declined

Variable Name	Description
AccountCreateMethod	The creation method of the account in the payment. (Ex. Manual, Imported)
AccountName	Name on the account of the payment.
AccountNumber	Account number of the payment.
AccountNumberLast4	Last 4 of the card/account number of the payment.
AccountType	The payment source's account type. (Ex. Visa)
Amount	Amount that was paid in the payment.
AmountFormatted	Amount that was paid in the payment formatted as currency.
AmountMinor	Amount that was paid in minor format.
Balance	Balance of the payment.
BalanceMinor	Account balance in minor format.
BusinessUnitId	ID of the business unit the payment was made in.
BusinessUnitName	Name of the business unit the payment was made in.
Channel	Payment channel the payment was made in. (Ex. POS, Quickpay)
CreatedByUserName	Name of the user who created the payment.
CurrencyCode	Currency code of the business unit the payment was made in.
DueDate	Due date of the payment.
GatewayErrorMessage	Error message from the gateway
LateFee	Late fee of the payment.
LateFeeMinor	Late fee in minor format.
PaymentCreatedDateUtc	Date the payment was created in UTC.
PaymentDescriptor	Description of what is being paid.
PaymentMetaJson	The meta JSON of the payment.
PaymentSourceType	Source type of the payment. (Ex. Credit Card, ACH)
PaymentType	Type of payment. (Ex. Base Payment, Service Fee)
ReferenceNumber	The payment's reference number.
ServiceFeeAmountMinor	Amount of the payment that represents fees related to processing the payment.
ServiceFeeAmountFormatted	Service fee amount formatted for display.
SessionIdentifier	Payment session identifier.
Status	Status of the payment.
SubAccountNumber	Subaccount number of the payment.

Payload Template Example

{
  "action": "{{EventType}}",
  "payload": {
    "sessionIdentifier": "{{SessionIdentifier}}",
    "status": "{{Status}}",
    "referenceNumber": "{{ReferenceNumber}}",
    "amount": "{{Amount}}",
    "accountNumber": "{{AccountNumber}}",
    "accountName": "{{AccountName}}",
    "paymentIdentifier": "{{PaymentMetaJson_PaymentIdentifier}}",
    "amountFormatted": "{{AmountFormatted}}",
    "serviceFee": "{{ServiceFeeAmountMinor}}"
  }
}

Resolved Payload Example

{
  "action": "Payment.Declined",
  "payload": {
    "sessionIdentifier": "a6fb5g44-4280-46af-b04e-2c58067bc111",
    "status": "Declined",
    "referenceNumber": "NYDVNT-WSQPG",
    "amount": "300.34",
    "accountNumber": "123-45",
    "accountName": "William Davis",
    "paymentIdentifier": "",
    "amountFormatted": "$300.30",
    "serviceFee": "1012"
  }
}

Payment.Refunded

Variable Name	Description
AccountId	ID of the account that had the refunded payment.
AccountNumberLast4	Last 4 of the card/account number that was used to make the payment.
Amount	Amount that was refunded.
AmountFormatted	Amount that was refunded formatted as currency.
Channel	Payment channel of the payment.
CreatedByUserName	Name of whoever initiated the payment.
GatewayErrorMessage	Error message from the gateway.
PaymentDescriptor	Descriptor of the payment. Could be the account number or what they paid for.
ReferenceNumber	Reference number of the payment.
Status	Status of the payment.

Payload Template Example

{
    "last4": "{{AccountNumberLast4}}",
    "channel": "{{Channel}}",
    "status": "{{Status}}",
    "amount": "{{Amount}}",
    "amountFormatted": "{{AmountFormatted}}"
}

Resolved Payload Example

{
    "last4": "3443",
    "channel": "POS",
    "status": "Pending",
    "amount": "100.34",
    "amountFormatted": "$100.34"
}

Payment.Succeeded

Variable Name	Description
AccountCreateMethod	The creation method of the account in the payment. (Ex. Manual, Imported)
AccountName	Name on the account of the payment.
AccountNumber	Account number of the payment.
AccountNumberLast4	Last 4 of the card/account number of the payment.
AccountType	The payment source's account type. (Ex. Visa)
Amount	Amount that was paid in the payment.
AmountFormatted	Amount that was paid in the payment formatted as currency.
AmountMinor	Amount that was paid in minor format.
Balance	Balance of the payment.
BalanceMinor	Account balance in minor format.
BusinessUnitId	ID of the business unit the payment was made in.
BusinessUnitName	Name of the business unit the payment was made in.
Channel	Payment channel the payment was made in. (Ex. POS, Quickpay)
CreatedByUserName	Name of the user who created the payment.
CurrencyCode	Currency code of the business unit the payment was made in.
DueDate	Due date of the payment.
GatewayErrorMessage	Error message from the gateway
LateFee	Late fee of the payment.
LateFeeMinor	Late fee in minor format.
PaymentCreatedDateUtc	Date the payment was created in UTC.
PaymentDescriptor	Description of what is being paid.
PaymentMetaJson	The meta JSON of the payment.
PaymentSourceType	Source type of the payment. (Ex. Credit Card, ACH)
PaymentType	Type of payment. (Ex. Base Payment, Service Fee)
ReferenceNumber	The payment's reference number.
ServiceFeeAmountMinor	Amount of the payment that represents fees related to processing the payment.
ServiceFeeAmountFormatted	Service fee amount formatted for display.
SessionIdentifier	Payment session identifier.
Status	Status of the payment.
SubAccountNumber	Subaccount number of the payment.

Payload Template Example

{
  "action": "{{EventType}}",
  "payload": {
    "sessionIdentifier": "{{SessionIdentifier}}",
    "status": "{{Status}}",
    "referenceNumber": "{{ReferenceNumber}}",
    "amount": "{{Amount}}",
    "accountNumber": "{{AccountNumber}}",
    "accountName": "{{AccountName}}",
    "paymentIdentifier": "{{PaymentMetaJson_PaymentIdentifier}}",
    "amountFormatted": "{{AmountFormatted}}",
    "serviceFee": "{{ServiceFeeAmountMinor}}"
  }
}

Resolved Payload Example

{
  "action": "Payment.Succeeded",
  "payload": {
    "sessionIdentifier": "a6fb5g42-4280-46af-b04e-2c58067bc111",
    "status": "Succeeded",
    "referenceNumber": "NYDVNT-WSQPG",
    "amount": "300.34",
    "accountNumber": "123-45",
    "accountName": "John Smith",
    "paymentIdentifier": "",
    "amountFormatted": "$300.34",
    "serviceFee": "1012"
  }
}

Payment.Voided

Variable Name	Description
AccountId	ID of the account that had the voided payment.
AccountNumberLast4	Last 4 of the card/account number that was used to make the payment.
Amount	Amount that was voided.
AmountFormatted	Amount that was voided formatted as currency.
Channel	Payment channel of the payment.
CreatedByUserName	Name of whoever initiated the payment.
GatewayErrorMessage	Error message from the gateway.
PaymentDescriptor	Descriptor of the payment. Could be the account number or what they paid for.
ReferenceNumber	Reference number of the payment.
Status	Status of the payment.

Payload Template Example

{
    "last4": "{{AccountNumberLast4}}",
    "channel": "{{Channel}}",
    "amountFormatted": "{{AmountFormatted}}",
    "status": "{{Status}}",
    "referenceNumber": "ReferenceNumber",
    "amount": "{{Amount}}"
}

Resolved Payload Example

{
    "last4": "4422",
    "channel": "QuickPay",
    "amountFormatted": "$50.40",
    "status": "Successful",
    "referenceNumber": "NYDVMM-WSQAA",
    "amount": "50.40"
}

Webhook Security

In order to validate webhooks are from Paystar, the partner will be provided a symmetric key used for verification. Once a key has been received, the sample code provided here (https://dotnetfiddle.net/6qbu2T) may be used as an example to validate them.

Example Webhook

Headers

"x-paystar-timestamp": "2021-02-26T21:29:58.0759011Z",
"x-paystar-signature": "sha1=dbf85449017bfe94069b1fb23e3674f1d2def1cb"

Body

{
  "action": "Payment.Succeeded",
  "payload": {
    "sessionIdentifier": "f476323d-8252-4dda-871c-660e5c4f0a59",
    "amount": 10.50,
    "amountFormatted": "$10.50",
    "referenceNumber": "MXEJGX-5QYV",
    "status": "Succeeded",
    "accountNumber": "1234",
    "accountName": "Customer Name",
    "[CustomField1]": "gg4b7b71-8dd0-416d-bc58-888348ba3c81",
    "[CustomField2]": "Commercial"
  }
}