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 end user 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

The NotifyDepositUrl and NotifyWithdrawUrl REST HTTP notification endpoints must be configured by the operator, while configuration of the NotifyErrorUrl endpoint is optional.

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

1. Using the same issuer, audience and secret keys outlined in the API Authentication section 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 need to 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 end user 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. End user 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": "PZXRKTTAT",
    "FirstName": "MSPXJ",
    "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,
    "OperatorLimits": {
        "MinDeposit": 1.00,
        "MaxDeposit": 100.00,
        "RemainingDailyDeposit": 999.99,
        "MinWithdraw": 1.00,
        "MaxWithdraw": 999999.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": "PZXRKTTAT",
    "FirstName": "MSPXJ",
    "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,
    "OperatorLimits": {
        "MinDeposit": 1.00,
        "MaxDeposit": 100.00,
        "RemainingDailyDeposit": 999.99,
        "MinWithdraw": 1.00,
        "MaxWithdraw": 999999.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 end user 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. End user’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 Withdrawls 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": "PZXRKTTAT",
    "FirstName": "MSPXJ",
    "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,
    "OperatorLimits": {
        "MinDeposit": 1.00,
        "MaxDeposit": 100.00,
        "RemainingDailyDeposit": 999.99,
        "MinWithdraw": 1.00,
        "MaxWithdraw": 999999.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": "PZXRKTTAT",
    "FirstName": "MSPXJ",
    "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,
    "OperatorLimits": {
        "MinDeposit": 1.00,
        "MaxDeposit": 100.00,
        "RemainingDailyDeposit": 999.99,
        "MinWithdraw": 1.00,
        "MaxWithdraw": 999999.99,
        "WalletBalance": 1000.0
    },
    "Error": {
        "ErrorCode": "1000",
        "ErrorMessage": "User Exited Flow.",
        "TransactionStage": "Withdrawal"
    }
}

Deposit/Withdraw Notification Request Parameters

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

OperatorLimits	Description	Example
MinDeposit	Minumum deposit amount	1.0
MaxDeposit	Maximum deposit amount	100.00
RemainingDailyDeposit	Remaining daily deposit amount	999.99
MinWithdraw	Minumum withdraw amount	1.00
MaxWithdraw	Maximum withdraw amount	999999.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 user 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