Cash Deposit 2023

Cash Deposit / Cage Deposit allows to process deposits at the cage inside of a physical casino.

When the merchant operator enters a username or eMail address or a telephone number into the cage page on Payment Service Admin (PS Admin), a specific API call is sent to the merchant to retrieve user details. This call has to be implemented by the merchant.

The new Cash deposit mask supports a search by phone number.

The customer has to be of legal age and must be in good standing. Users that are not eligible are to be flagged accordingly, or not to be returned at all. Identity has to be verified at the cage.

When the payment is initiated, a callback is sent to the merchant listener to approve or deny the payment.

The following method IDs are covered in this section:

ID	Name	Credit/Debit State
177	CashDeposit	DepositedByUser (525)

Flow overview

The following flow is used:

Sequence overview

The follwing flow also applies for the operator entering the eMail address, this has not yet been updated in the diagram below.

Redirect Integration

Not applicable.

Backend2BackendIntegration

Before the payment is progressed, the cage page inside of PS Admin sends a request to the merchant listener to lookup the details of the customer (player).

The merchant should return in the response the following details for the customer:
minLimit, maxLimit and limitCurrency, also email, FirstName, Lastname and date of birth, and identification Number (SSN (full or partial (masked), only for display).

Multiple currencies are supported. Data is not stored, only displayed.

If user cannot be found, an error message is shown.

Example getNewManualPaymentDetailsRequest:

<getNewManualPaymentDetailsRequest>
       <merchantID>Merchant</merchantID>
       <paymentMethodID>177</paymentMethodID>
       <userID>SomeUserID</userID>
       <username>SomeUserName</username>
       <email>[email protected]</email>
       <languageCode>EN</languageCode>
       <telephoneNumber xsi:nil="true" />
</getNewManualPaymentDetailsRequest>

<getNewManualPaymentDetailsRequest xmlns=http://www.cqrpayments.com/PaymentProcessing xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance xmlns:xsd=http://www.w3.org/2001/XMLSchema>
    <merchantID>Merchant</merchantID>
    <paymentMethodID>177</paymentMethodID>
    <userID xsi:nil="true" />
    <username xsi:nil="true" />
    <email xsi:nil="true" />
    <languageCode xsi:nil="true" />
    <telephoneNumber>123456</telephoneNumber>
</getNewManualPaymentDetailsRequest>

The request will include either the userID or the userName or the eMail or the telephoneNumber field.

Example getNewManualPaymentDetailsResponse:

<getNewManualPaymentDetailsResponse xmlns=http://www.cqrpayments.com/PaymentProcessing xmlns:xsd=http://www.w3.org/2001/XMLSchema xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance>
    <result>
        <userID>43c0fb36-dea1-443c-b9d4-df32b01bb5dd</userID>
        <merchantTransactionID>1064e3d3-98b1-47a3-8be2-ce09a40975ac</merchantTransactionID>
        <userDetails>
            <username></username>
            <firstname>Tele</firstname>
            <lastname>Number</lastname>
            <currencyCode>USD</currencyCode>
            <languageCode xsi:nil="true"></languageCode>
            <email>[email protected]</email>
            <address>
                <street>main street</street>
                <houseName>bwin</houseName>
                <houseNumber>1</houseNumber>
                <houseNumberExtension xsi:nil="true"></houseNumberExtension>
                <postalCode>21000</postalCode>
                <city>Vienna</city>
                <state>main state</state>
                <countryCode2>AT</countryCode2>
                <telephoneNumber>123456</telephoneNumber>
            </address>
            <dateOfBirth>2023-08-17T09:18:14.7657735Z</dateOfBirth>
            <gender>Male</gender>
            <identificationNumber>3526932</identificationNumber>
            <identificationNumberType xsi:nil="true"></identificationNumberType>
            <drivingLicenseNumber xsi:nil="true"></drivingLicenseNumber>
            <drivingLicenseIssuingState xsi:nil="true"></drivingLicenseIssuingState>
            <userStatus xsi:nil="true"></userStatus>
        </userDetails>
        <paymentDetails>
            <detail xsi:type="keyDecimalValuePair">
                <key>minLimit</key>
                <value>10</value>
            </detail>
            <detail xsi:type="keyDecimalValuePair">
                <key>maxLimit</key>
                <value>500</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>limitCurrency</key>
                <value>USD</value>
            </detail>
        </paymentDetails>
    </result>
    <status>
        <code>0</code>
        <description></description>
        <details></details>
    </status>
</getNewManualPaymentDetailsResponse>

According to the returned response message, the following information will be displayed to the cage clerk in the PS Admin.

When the user is not found, the following response should be returned by the merchant:

getNewManualPaymentDetailsResponse xmlns=http://www.cqrpayments.com/PaymentProcessing xmlns:xsd=http://www.w3.org/2001/XMLSchema xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance>
    <status>
        <code>2</code>
        <description>User not found. Please ensure correctness of User Name or Email Address entered.</description>
        <details></details>
    </status>
</getNewManualPaymentDetailsResponse>

Response Messages:

responseStatus.Code	Meaning	Display message
0	User Found / Eligible
2	User Not Found	The message passed in description will be used for display.

XSD

Please see below for the XSD. All the basic types are included in the main XSD, see here.

Messages:

   <s:element name="getNewManualPaymentDetailsRequest" type="getNewManualPaymentDetailsRequestData">
   </s:element>
   
	
	<s:element name="getNewManualPaymentDetailsListRequest" type="getNewManualPaymentDetailsRequestData">
	</s:element>
	
	<s:element name="getNewManualPaymentDetailsResponse">
		<s:complexType>
			<s:sequence>
				<s:element minOccurs="0" maxOccurs="1" name="result" type="getNewManualPaymentDetailsResult"/>
				<s:element minOccurs="1" maxOccurs="1" name="status" type="responseStatus"/>
				<s:any minOccurs="0" maxOccurs="unbounded" processContents="lax" namespace="##any" />
			</s:sequence>
		</s:complexType>
	</s:element>
	
	  <s:element name="getNewManualPaymentDetailsListResponse">
      <s:complexType>
         <s:sequence>
            <s:element minOccurs="1" maxOccurs="1" name="results">
               <s:complexType>
                  <s:sequence>
                     <s:element minOccurs="0" maxOccurs="unbounded" name="result" type="getNewManualPaymentDetailsResult" />
                  </s:sequence>
               </s:complexType>
            </s:element>
            <s:element minOccurs="1" maxOccurs="1" name="status" type="responseStatus"/>
            <s:any minOccurs="0" maxOccurs="unbounded" processContents="lax" namespace="##any" />
         </s:sequence>
      </s:complexType>
   </s:element>
   
Data elements:

   <s:complexType name="getNewManualPaymentDetailsRequestData">
      <s:sequence>
         <s:element minOccurs="1" maxOccurs="1" name="merchantID" type="stringID" />
         <s:element minOccurs="1" maxOccurs="1" name="paymentMethodID" type="positiveInt"/>
         <s:element minOccurs="0" maxOccurs="1" name="userID" type="stringID" nillable="true"/>
         <s:element minOccurs="0" maxOccurs="1" name="username" type="username" nillable="true"/>
         <s:element minOccurs="0" maxOccurs="1" name="email" type="emailAddress" nillable="true"/>
         <s:element minOccurs="0" maxOccurs="1" name="languageCode" type="twoLetterCode" nillable="true"/>
         <s:element minOccurs="0" maxOccurs="1" name="dateOfBirth" type="dateOfBirth" nillable="true"/>
         <s:element minOccurs="0" maxOccurs="1" name="firstName" type="personName" nillable="true"/>
         <s:element minOccurs="0" maxOccurs="1" name="lastName" type="personName" nillable="true"/>
         <s:element minOccurs="0" maxOccurs="1" name="telephoneNumber" type="secureString" nillable="true"/>
         <s:element minOccurs="0" maxOccurs="1" name="currencyID" type="threeLetterCode" nillable="true"/>
         <s:element minOccurs="0" maxOccurs="1" name="providerUserID" type="stringID" nillable="true"/>
      </s:sequence>
   </s:complexType>
   
  <s:complexType name="getNewManualPaymentDetailsResult">
      <s:sequence>
         <s:element minOccurs="0" maxOccurs="1" name="userID" type="stringID"/>
         <s:element minOccurs="0" maxOccurs="1" name="merchantTransactionID" type="merchantTransactionID" nillable="true"/>
         <s:element minOccurs="0" maxOccurs="1" name="userDetails" type="userDetails" nillable="true"/>
         <s:element minOccurs="1" maxOccurs="1" name="paymentDetails">
            <s:complexType>
               <s:sequence>
                  <s:element minOccurs="0" maxOccurs="unbounded" name="detail" type="keyValueBasePair"/>
               </s:sequence>
            </s:complexType>
         </s:element>
         <s:any minOccurs="0" maxOccurs="unbounded" processContents="lax" namespace="##any"/>
      </s:sequence>
   </s:complexType>
   
 	<s:complexType name="responseStatus">
		<s:sequence>
			<s:element minOccurs="1" maxOccurs="1" name="code" type="s:int"/>
			<s:element minOccurs="1" maxOccurs="1" name="description" type="s:string"/>
			<s:element minOccurs="1" maxOccurs="1" name="details">
				<s:complexType>
					<s:sequence>
						<s:element minOccurs="0" maxOccurs="1000" name="detail" type="keyValueBasePair"/>
					</s:sequence>
				</s:complexType>
			</s:element>
			<s:any minOccurs="0" maxOccurs="unbounded" processContents="lax" namespace="##any" />
		</s:sequence>
	</s:complexType>

Currency Handling

This section describes the options available for the merchant in order to manage currencies on the Cash Deposit page.

There are two options: single currency and multiple currencies.

When using multiple currencies a selection dropdown will be displayed to the operator to allow for the selection of the desired currency. With multiple currencies it is also possible to identify a preferred currency, which will be pre-selected in the dropdown if provided.

Option 1: Single currency

In order to display a single currency the merchant must provide the currency code along with a minimum and maximum limit.

Sample getNewManualPaymentDetailsResponse:

<paymentDetails xmlns="http://www.cqrpayments.com/PaymentProcessing">
	<detail xsi:type="keyDecimalValuePair">
		<key>minLimit</key>
		<value>10</value>
	</detail>
	<detail xsi:type="keyDecimalValuePair">
		<key>maxLimit</key>
		<value>100</value>
	</detail>
	<detail xsi:type="keyStringValuePair">
		<key>limitCurrency</key>
		<value>USD</value>
	</detail>
</paymentDetails>

Things to consider:

The “limitCurrency” detail is optional in a single currency response
If the limit currency is not provided, the currency code will be taken from the user details

Option 2: Multiple currencies

In order to display multiple currencies the merchant must provide each currency code with the appropriate minimum and maximum limit for that currency.

Sample getNewManualPaymentDetailsResponse:

<paymentDetails xmlns="http://www.cqrpayments.com/PaymentProcessing">
	<detail xsi:type="keyDecimalValuePair">
		<key>minLimitUSD</key>
		<value>10</value>
	</detail>
	<detail xsi:type="keyDecimalValuePair">
		<key>maxLimitUSD</key>
		<value>100</value>
	</detail>
	<detail xsi:type="keyDecimalValuePair">
		<key>minLimitCAD</key>
		<value>15</value>
	</detail>
	<detail xsi:type="keyDecimalValuePair">
		<key>maxLimitCAD</key>
		<value>150</value>
	</detail>
	<detail xsi:type="keyStringValuePair">
		<key>limitCurrency</key>
		<value>USD,CAD</value>
	</detail>
</paymentDetails>

Things to consider:

The “limitCurrency” detail is mandatory in a multiple currency response
The “limitCurrency” detail must contain a comma-separated list of all desired currencies
The “minLimit” and “maxLimit” details must be present for each of the desired currencies
The “minLimit” and “maxLimit” details must have a suffix with the appropriate currency code

Additionally, the merchant may include a preferred currency which will be preselected on the Cash Deposit page. This additional detail would be included as part of the multiple currency response as follows:

… 
<detail xsi:type="keyStringValuePair">
<key>preferredCurrency</key>
<value>USD</value>
</detail>
…

Payment flow

When the cage clerk creates a payment, a request is sent to the merchant backend. The merchant has the chance to accept or decline this payment.

Example handlePaymentStateChangedNotificationRequest:

<?xml version="1.0" encoding="utf-8"?>
<handlePaymentStateChangedNotificationRequest xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.cqrpayments.com/PaymentProcessing">
    <payment xsi:type="paymentWithPaymentAccount">
        <merchantID>MerchantID</merchantID>
        <shopID>ShopID</shopID>
        <paymentMethod>
            <key>177</key>
            <value>Cash Deposit</value>
        </paymentMethod>
        <merchantTransactionID>06129a57-d536-4bef-b9dc-f84efc893583</merchantTransactionID>
        <paymentID>072d3d6e-883f-49f1-bc27-80d1c1be9da0</paymentID>
        <userID>testuser</userID>
        <paymentProvider>
            <key>123</key>
            <value>Kalixa</value>
        </paymentProvider>
        <amount currencyCode="USD">21.0000</amount>
        <creationType>
            <key>1</key>
            <value>User</value>
        </creationType>
        <userIP>127.0.0.1</userIP>
        <state>
            <id>f31cab99-ffa1-4296-a363-a38703f94171</id>
            <definition>
                <key>370</key>
                <value>DuplicatePaymentValidationPassed</value>
            </definition>
            <createdOn>2019-12-30T10:02:16.933</createdOn>
            <paymentStateDetails xsi:nil="true" />
        </state>
        <isExecuted>true</isExecuted>
        <baseAmount currencyCode="EUR">20.0000</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderExternalID</key>
                <value>753876099</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>CustomerID</key>
                <value>44002388</value>
            </detail>
                    </paymentDetails>
        <paymentAccount>
            <paymentAccountID>0</paymentAccountID>
        </paymentAccount>
    </payment>
</handlePaymentStateChangedNotificationRequest>

Example handlePaymentStateChangedNotificationResponse (successful case):

<?xml version="1.0" encoding="utf-8"?>
<handlePaymentStateChangedNotificationResponse 
    xmlns="http://www.cqrpayments.com/PaymentProcessing" 
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <resultCode>
    <key>0</key>
    <value>ProcessedSuccessfully</value>
  </resultCode>
  <resultMessage>Approved payment</resultMessage>
</handlePaymentStateChangedNotificationResponse>

Example handlePaymentStateChangedNotificationResponse (rejected case):

<?xml version="1.0" encoding="utf-8"?>
<handlePaymentStateChangedNotificationResponse 
    xmlns="http://www.cqrpayments.com/PaymentProcessing"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <resultCode>
        <key>15</key>
        <value>BlockedByMerchant</value>
    </resultCode>
    <resultMessage>Rejected payment</resultMessage>
</handlePaymentStateChangedNotificationResponse>

*Example handlePaymentStateChangedNotificationResponse (error case)**:

<?xml version="1.0" encoding="utf-8"?>
<handlePaymentStateChangedNotificationResponse 
    xmlns="http://www.cqrpayments.com/PaymentProcessing"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <resultCode>
        <key>2</key>
        <value>UnknownState</value>
    </resultCode>
    <resultMessage>Rejected payment</resultMessage>
</handlePaymentStateChangedNotificationResponse>

Notifications

The standard notification mechanism is used for notifying the merchant in the background (asynchronously) about payment state changes. For more information see PaymentStateChangedNotification.

Example handlePaymentStateChangedNotificationRequest:

<?xml version="1.0" encoding="utf-8"?>
<handlePaymentStateChangedNotificationRequest xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.cqrpayments.com/PaymentProcessing">
    <payment xsi:type="paymentWithPaymentAccount">
        <merchantID>MerchantID</merchantID>
        <shopID>ShopID</shopID>
        <paymentMethod>
            <key>177</key>
            <value>Cash Deposit</value>
        </paymentMethod>
        <merchantTransactionID>06129a57-d536-4bef-b9dc-f84efc893583</merchantTransactionID>
        <paymentID>072d3d6e-883f-49f1-bc27-80d1c1be9da0</paymentID>
        <userID>testuser</userID>
        <paymentProvider>
            <key>123</key>
            <value>Kalixa</value>
        </paymentProvider>
        <amount currencyCode="USD">21.0000</amount>
        <creationType>
            <key>1</key>
            <value>User</value>
        </creationType>
        <userIP>127.0.0.1</userIP>
        <state>
            <id>f31cab99-ffa1-4296-a363-a38703f94171</id>
            <definition>
                <key>525</key>
                <value>DepositedByUser</value>
            </definition>
            <createdOn>2019-12-30T10:02:16.933</createdOn>
            <paymentStateDetails xsi:nil="true" />
        </state>
        <isExecuted>true</isExecuted>
        <baseAmount currencyCode="EUR">20.0000</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderExternalID</key>
                <value>753876099</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>CustomerID</key>
                <value>44002388</value>
            </detail>
                    </paymentDetails>
        <paymentAccount>
            <paymentAccountID>0</paymentAccountID>
        </paymentAccount>
    </payment>
</handlePaymentStateChangedNotificationRequest>