Notification Callback URLs

Operators need to implement transaction notification endpoint(s) in order to be notified of events and transactions as they occur. Operators will use this information to synchronize patron data between Pavilion and the operator's systems.

note

In order to notify operators, the callback endpoint must be configured to receive notification callbacks for deposit and withdrawal transactions.

Notification Callback Specification

Operators must specify the following endpoints:

Endpoint	Description
NotifyDepositUrl	Required
NotifyWithdrawUrl	Required
NotifyErrorUrl	Optional

These HTTP requests must be authenticated via JWT bearer token. They are expected to be signed by either:

1. Using the same issuer, audience and secret keys provided by Pavilion Payments as outlined in the Generate JWT page or
2. Using authentication details provided by the operator. It is recommended that operators validate these JWTs before acting upon the request.

If an operator is securing their notification callback endpoints using their own authentication process (option 2 above), the parameters listed below must be shared with the Pavilion VIP Connect team. The JWT generated using the parameters below are expected to be sent in the request header from the operator’s callback endpoint for authentication purposes.

Claim	Value
iss	The configured Operator ID
aud	vip-api
secret key	(256 bit base 64 encoded key)

POST https://operatorsite/api/NotifyDeposit

This method is used to notify operators of requests made by the patron for a deposit transaction. VIP Connect will make an authenticated request to the callback URL configured. This method will also be used to notify the operator of deposit errors if a notify error endpoint has not been configured.

Example Scenario:

1. Patron makes a successful deposit request on the VIP Connect web component.
2. Upon successful response from the Pavilion service, VIP Connect calls the operator’s notification callback URL to notify the operator of the deposit request made.
3. Operator's callback endpoint acknowledges the request.

note

If the operator has deposit approvals enabled, the notification will include an IsApproval property and when set to true a deposit approval must be sent back to Pavilion via the Deposit Approval endpoint.

Deposit Notification Example Request:

{
    "PatronId": "0ef56720-47b6-46bc-9a3a-b81bd511d10a",
    "TransactionId": "MOCK81023210643",
    "Amount": 43.0,
    "BankName": "U.S. Bank National Association",
    "MaskedBankAccountNumber": "************5555",
    "UnmaskedBankAccountNumber": null,
    "BankRoutingNumber": "122105155",
    "VipCardNumber": "7210642759",
    "LastName": "Smith",
    "FirstName": "John",
    "HomePhoneNumber": "8433200399",
    "Location": "127.0.0.1",
    "TransactionType": "Deposit",
    "Timestamp": "2024-05-03T19:59:43.7453307+00:00",
    "InstantPaymentEligible": false,
    "FundTransferType": "Unknown",
    "Error": null,
    "ProductType": "Online",
    "IsApproval": false,
    "OneClickDiscountApplied": false,
    "WarrantyMode":"", 
    "IsWarrantied":true,
    "OperatorLimits": {
        "RemainingDailyDeposit": 999.99,
        "WalletBalance": 1000.0
    }
}

Deposit Error Notification Example Request:

{
    "PatronId": "0ef56720-47b6-46bc-9a3a-b81bd511d10a",
    "TransactionId": "MOCK81023210643",
    "Amount": 43.0,
    "BankName": "U.S. Bank National Association",
    "MaskedBankAccountNumber": "************5555",
    "UnmaskedBankAccountNumber": null,
    "BankRoutingNumber": "122105155",
    "VipCardNumber": "7210642759",
    "LastName": "Smith",
    "FirstName": "John",
    "HomePhoneNumber": "8433200399",
    "Location": "127.0.0.1",
    "TransactionType": "Deposit",
    "Timestamp": "2024-05-03T19:59:43.7453307+00:00",
    "InstantPaymentEligible": false,
    "FundTransferType": "Unknown",
    "ProductType": "Online",
    "IsApproval": false,
    "OneClickDiscountApplied": false,
    "WarrantyMode":"", 
    "IsWarrantied":true,
    "OperatorLimits": {
        "RemainingDailyDeposit": 999.99,
        "WalletBalance": 1000.0
    },
    "Error": {
        "ErrorCode": "1000",
        "ErrorMessage": "User Exited Flow.",
        "TransactionStage": "Deposit"
    }
}

note

TransactionId is assigned by the Operator. Max Length: 25 characters, Min Length: 8 characters

Response

Status	Description
200 OK	API received the request and responded

POST https://operatorsite/api/NotifyWithdrawal

This method is used to notify operators of requests made by the patron for a withdrawal transaction. VIP Connect will make an authenticated request to the callback URL configured. This method will also be used to notify the operator of withdrawal errors if a notify error endpoint has not been configured.

Example Scenario:

1. The patron’s withdrawal request is directly sent to the operator via the notification callback URL configured.
2. VIP Connect notifies the operator of the request, without any further action.
3. Operator’s callback endpoint will acknowledge the request.
4. After receiving this notification the operator approves or rejects the requested withdrawal. This is discussed in the Handle Withdrawals section.

Withdraw Notification Example Request:

{
    "PatronId": "0ef56720-47b6-46bc-9a3a-b81bd511d10a",
    "TransactionId": "MOCK81023210643",
    "Amount": 43.0,
    "BankName": "U.S. Bank National Association",
    "MaskedBankAccountNumber": "************5555",
    "UnmaskedBankAccountNumber": null,
    "BankRoutingNumber": "122105155",
    "VipCardNumber": "7210642759",
    "LastName": "Smith",
    "FirstName": "John",
    "HomePhoneNumber": "8433200399",
    "Location": "127.0.0.1",
    "TransactionType": "Withdraw",
    "Timestamp": "2024-05-03T19:59:43.7453307+00:00",
    "InstantPaymentEligible": true,
    "FundTransferType": "RTP",
    "Error": null,
    "ProductType": "Online",
    "IsApproval": true,
    "OneClickDiscountApplied": false,
    "WarrantyMode":"", 
    "IsWarrantied":true,
    "OperatorLimits": {
        "RemainingDailyDeposit": 999.99,
        "WalletBalance": 1000.0
    }
}

Withdrawal Error Notification Example Request:

{
    "PatronId": "0ef56720-47b6-46bc-9a3a-b81bd511d10a",
    "TransactionId": "MOCK81023210643",
    "Amount": 43.0,
    "BankName": "U.S. Bank National Association",
    "MaskedBankAccountNumber": "************5555",
    "UnmaskedBankAccountNumber": null,
    "BankRoutingNumber": "122105155",
    "VipCardNumber": "7210642759",
    "LastName": "Smith",
    "FirstName": "John",
    "HomePhoneNumber": "8433200399",
    "Location": "127.0.0.1",
    "TransactionType": "Withdraw",
    "Timestamp": "2024-05-03T19:59:43.7453307+00:00",
    "InstantPaymentEligible": true,
    "FundTransferType": "RTP",
    "Error": null,
    "ProductType": "Online",
    "IsApproval": true,
    "OneClickDiscountApplied": false,
    "WarrantyMode":"", 
    "IsWarrantied":true,
    "OperatorLimits": {
        "RemainingDailyDeposit": 999.99,
        "WalletBalance": 1000.0
    }
    "Error": {
        "ErrorCode": "1000",
        "ErrorMessage": "User Exited Flow.",
        "TransactionStage": "Withdrawal"
    }
}

Deposit/Withdraw Notification Request Parameters

| Parameter Name | Description | Type | Example | | ----------------------------|-----------------------------------------------------|------------------|----------------|---------------------------------------| | PatronId | End user ID | String | 0ef56720-47b6-46bc-9a3a-b81bd511d10a | | TransactionId* | Unique ID to identify deposit/withdraw request | Alphanumeric | MOCK81023210643 | | Amount | Transaction amount | decimal | 27.50 | | BankName | Patron selected bank name | String | BANK OF AMERICA, NA | | MaskedBankAccountNumber | Patron selected bank account number (masked) | String | ****0865 | | UnmaskedBankAccountNumber | Full bank account number selected by the patron (if feature is enabled) | String | 12340865 | | BankRoutingNumber | Routing number for bank selected | String | 061000052 | | VipCardNumber | VIP account number | String | 714524259 | | FirstName | Patron's first name | String | John | | LastName | Patron's last name | String | Smith | | HomePhoneNumber | Patron's home phone number | String | 8433200399 | | Location | Device location (IP address of the device) | String | 127.0.0.1 | | TransactionType | Transaction type of the request | String | deposit | | Timestamp | Timestamp value when approval request sent | DateTime | 2023-08-10T19:17:23.563715+00:00 |
| InstantPaymentEligible | Indicates if the bank supports instant payment | Boolean | false | | FundTransferType | Fund transfer type for Withdraw Approval call (Unknown, ACH, RTP, INP, SDA). See the parameters list for more details. | String | RTP | | ProductType | VIP product type (VIP Preferred or VIP Online) | String | preferred | | IsApproval | Used if deposit approval is enabled | Boolean | false | | OneClickDiscountApplied | Discount on transaction enabled for operator (eligibility determined by oneClickDiscountEligible from Account Inquiry response) | Boolean | false | | WarrantyMode | Warranty mode set by operator for this transaction | String | NOWARRANTY | | IsWarrantied | Indicates if transaction was warrantied | Boolean | true | | OperatorLimits | Operator limit information that needs to be sent for Deposit Approval | Object | See below |
| Error | Error notification | Object | See below |

OperatorLimits	Description	Example
RemainingDailyDeposit	Remaining daily deposit amount	999.99
WalletBalance	Patron wallet balance	1000.0

Error	Description	Example
ErrorCode	Error code	1000
ErrorMessage	Error message	User Exited Flow
Transactionstage	Transaction Stage	Deposit

Possible ProductType Values	Description
preferred	VIP Preferred
online	VIP Online

note

TransactionId is assigned by the Operator. Max Length: 25 characters, Min Length: 8 characters

Response

Status	Description
200 OK	API received the request and responded

POST https://operatorsite/api/NotifyError

This method is used to notify operators of errors that have occurred during a transaction. VIP Connect will make an authenticated request to the callback URL configured. This endpoint is also used to notify the operator if the patron cancels their transaction.

note

If the operator does not make this endpoint available then deposit errors and withdrawal errors will be sent to the operator's notify deposit endpoint and notify withdrawal endpoint, respectively. This is also true for deposit cancelations and withdrawal cancelations.

Example Scenario:

1. An error has occurred during a transaction.
2. VIP Connect notifies the operator of the request, without any further action.
3. Operator’s callback endpoint will acknowledge the request.
4. After receiving this notification the operator may choose to log the error, or perform some customer service function.

Example Request:

{
    "TransactionId": "MOCK81023210643",
    "VipCardNumber": "7210536159",
    "PatronId": null,
    "SessionId": "8033ff2f-5aaf-4414-9c43-05fd0bae6087",
    "Timestamp": "2023-08-10T21:13:15.176162+00:00",
    "ErrorCode": "1000",
    "TransactionStage": "Deposit",
    "ErrorMessage": "User Exited Flow."
}

Request Parameters

Parameter Name	Description	IsRequired	Type	Example
TransactionId*	Unique ID to identify deposit/withdraw request	Yes	String	MOCK81023210643
VipCardNumber	VIP account number	No	String	7210536159
PatronId	End user ID	No	String	ba8941c3-3a2e-470e-9add-7f8dca7d7fb8
SessionId	Session ID	Yes	String	8033ff2f-5aaf-4414-9c43-05fd0bae6087
Timestamp	Timestamp value when approval request sent	Yes	DateTime	2023-08-10T21:13:15.176162+00:00
TransactionStage	Transaction stage where the error occurred	Yes	String	Deposit
ErrorCode	Error code	Yes	String	1000
ErrorMessage	Details about the error	Yes	String	User Exited Flow.

note

TransactionId is assigned by the Operator. Max Length: 25 characters, Min Length: 8 characters

Response

Status	Description
200 OK	API received the request and responded