VIP Preferred Deposit (ACH)

VIP Cashline / VIP Preferred Deposit allows to pay by eChecks in the US.

The following method IDs are covered in this section:

ID	Name	Credit/Debit State
252	VIPPreferredDeposit	DepositedByProvider (13)

Payment method interaction type: Synchronous execution (see Interaction Types).

With Global Payment’s VIP Preferred program, customers are given a 7-day revolving ACH/check-cashing limit, which allows guests to cash checks at all gaming establishments that participate in the VIP Preferred Network.

📘
VIP Preferred Deposit Returns
Refer to VIP Preferred Deposit Return for information on how to correctly handle the notifications for VIP Preferred Deposit Returns

Redirect Integration

Payment Method VIPPreferredDeposit is also available in Checkout.

The following mandatory user related data needs to be provided by the merchant in the getRedirectDataRequest.redirectParameters.user section for this payment method to work:

Field	Value
firstname required	Customer First Name
lastname required	Customer Last Name
dateOfBirth required	Customers Date of Birth
address.street or address.houseNumber or address.HouseNumberExtension conditional	Users/Customers address: at least one of these fields need to be provided: Street, HouseNumber, HouseNumberExtension
address.postalCode required	Users/Customers address: Zip code/Postal code
address.city required	Users/Customers address: City
address.state required	Users/Customers address: State
address.countryCode2 required	Users/Customers address: Country
telephoneNumber required	Customers home phone number
email required	Customers email Note: in previous versions of VIP preferred this element was optional, but it has become mandatory

Example of getRedirectData request for a Redirect Deposit(252), redirection to the Selection Page(= directly to PXP Checkout selection page):

<getRedirectDataRequest 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>
    <redirectParameters xsi:type="paymentMethodSelectionWithDetailsRedirectParameters">
        <shopID>{{shop}}</shopID>
        <httpMethod>GET</httpMethod>
        <returnUrl>http://return</returnUrl>
        <languageCode>en</languageCode>
        <currencyCode>usd</currencyCode>
        <countryCode>us</countryCode>
        <additionalDetails>
            <detail xsi:type="keyStringValuePair">
                <key>Description</key>
                <value>some description</value>
            </detail>
        </additionalDetails>
        <user>
            <id>{{newUserID}}</id>
            <username>{{newUserName}}</username>
            <firstname>Sherlock</firstname>
            <lastname>Holmes</lastname>
            <currencyCode>USD</currencyCode>
            <languageCode>EN</languageCode>
            <email>{{newUserEmail}}</email>
             <address>
            <street>Geneva Street</street>
               <houseNumber>5</houseNumber>
               <postalCode>61259</postalCode>
               <city>Illinois City</city>
               <state>IL</state>
               <countryCode2>US</countryCode2>
               <telephoneNumber>{{phoneNumber}}</telephoneNumber>
            </address>
             <dateOfBirth>1985-10-10T00:00:00</dateOfBirth>
            <gender>Female</gender>
         </user>
        <merchantTransactionID>{{checkoutMerchantTransactionID}}</merchantTransactionID>
        <grossAmount>100.00</grossAmount>
        <minPaymentLimitAmount>10</minPaymentLimitAmount>
        <maxPaymentLimitAmount>3000</maxPaymentLimitAmount>
        <expirationTimeSpanInSeconds>3600</expirationTimeSpanInSeconds>
        <successUrl>http://success</successUrl>
        <pendingUrl>http://pending</pendingUrl>
        <errorUrl>http://error</errorUrl>
        <cancelUrl>http://cancel</cancelUrl>
        <refusedUrl>http://refused</refusedUrl>
        <paymentDirection>Deposit</paymentDirection>
    </redirectParameters>
</getRedirectDataRequest>

Example of getRedirectData request for a Redirect Deposit(252), redirection to the Detail Page(= directly to PXP Checkout detail page):

<getRedirectDataRequest 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>
    <redirectParameters xsi:type="paymentMethodDetailsRedirectParameters">
        <shopID>{{shop}}</shopID>
        <httpMethod>GET</httpMethod>
        <returnUrl>http://return</returnUrl>
        <languageCode>en</languageCode>
        <currencyCode>usd</currencyCode>
        <countryCode>us</countryCode>
        <additionalDetails>
             <detail xsi:type="keyStringValuePair">
                <key>Description</key>
                <value>my payment description</value>
            </detail>
        </additionalDetails>
        <user>
            <id>{{newUserID}}</id>
            <username>{{newUserName}}</username>
            <firstname>Sherlock</firstname>
            <lastname>Holmes</lastname>
            <currencyCode>USD</currencyCode>
            <languageCode>EN</languageCode>
            <email>{{newUserEmail}}</email>
             <address>
            <street>Geneva Street</street>
               <houseNumber>5</houseNumber>
               <postalCode>61259</postalCode>
               <city>Illinois City</city>
               <state>IL</state>
               <countryCode2>US</countryCode2>
               <telephoneNumber>{{phoneNumber}}</telephoneNumber>
            </address>
             <dateOfBirth>1985-10-10T00:00:00</dateOfBirth>
            <gender>Female</gender>
         </user>
        <merchantTransactionID>{{checkoutMerchantTransactionID}}</merchantTransactionID>
        <grossAmount>30.00</grossAmount>
        <minPaymentLimitAmount>10</minPaymentLimitAmount>
        <maxPaymentLimitAmount>3000</maxPaymentLimitAmount>
        <expirationTimeSpanInSeconds>3600</expirationTimeSpanInSeconds>
       <successUrl>http://www.google.com/result?param1=success?status=success</successUrl>
        <pendingUrl>http://www.google.com/result?param1=pending?status=pending</pendingUrl>
        <errorUrl>http://www.google.com/result?param1=error?status=error</errorUrl>
        <cancelUrl>http://www.google.com/result?param1=cancel?status=cancel</cancelUrl>
        <refusedUrl>http://www.google.com/result?param1=refuse?status=refuse</refusedUrl>
        <paymentMethodID>252</paymentMethodID>
        <isPaymentMethodChangeAllowed>false</isPaymentMethodChangeAllowed>
    </redirectParameters>
</getRedirectDataRequest>

**Example getRedirectDataResponse"

<getRedirectDataResponse xmlns=http://www.cqrpayments.com/PaymentProcessing xmlns:xsd=http://www.w3.org/2001/XMLSchema xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance>
    <redirectData>
        <redirectUrl>https://payments.test2.kalixa.com/Checkout/PaymentMethods/252?requestData=m30h4kblzqatlb15f4qxdulb_b093063c-2017-4f56-96d4-346c3bad6d8b</redirectUrl>
    </redirectData>
</getRedirectDataResponse>

The below screenshot shows an example of the payment selection page with VIP Preferred listed as one of the payment methods.

Account Enquiry Check

An account enquiry check is initiated in the backend once the the customer selected the VIP Preferred payment method from the Payment method selection page.
PXP will check if an existing VIP Preferred number is associated with the customer.
- If there is an already existing VIP Preferred Number for the customer then customer is redirected to the PXP Checkout details page.
- If no existing VIP Preferred Number is found with the customer then customer is redirected to VIP Preferred Number Lookup page.
  - If customer already has the VIP Preferred number then customer can enter the VIP Preferred Number and will be redirected to the PXP checkout details page once validated with the VIP Preferred network.
  - If the customer´s VIP Preferred Number is not successfully validated on the VIP Preferred Number Lookup page then it is redirected to the error url
- Customer can also perform the enrollment with the VIP Preferred payment using the "Signup with VIP Preferred" link available on the VIP Preferred Number Lookup page.

🚧
Closed accounts
Anytime an account is closed/declined by Global Payments, the account inquiry response will not return any limit or banking information.

The below screenshot shows an example of the VIP Preferred Lookup Page using which customer can enter their VIP Preferred number if it is already available with them.

Customer using VIP Preferred payment for the first time (Enrollment flow)

Customer using VIP Preferred payment for the first time will get enrollment screen in the PXP checkout to enroll in the VIP Preferred network.
Customer needs to enter the mandatory parameter listed in User Enrrollment section.
After the successful enrollment, customer is redirected to the PXP checkout details page. PXP Checkout displays the bank account that has been added during enrollment process.

Customer should enter following information to Enroll successfully in VIP Preferred Network

key (value type, account type, required)	Value
Type of Identification (String, required)	Values: DL = Driver’s License ST = State ID MI = Military ID Max Length: 2 characters
State	Two letter state code. Ignore this value when ID type is military ID. Max Length: 2 characters
Identification Number (String, required)	The number associated with IDType. Max Length: 30 characters Min Length: 6 characters
Identification Number Expiration	The expiration associated with IDType (optional).
Social Security Number (String, required)	The customer’s social security number. Max Length: 9 digits Min Length: 8 digits if not empty
Account Number (String, required)	The customer’s bank account number. Max Length: 18 digits
Routing Number (String, required)	The routing number of the bank. Max Length: 9 digits

The below screenshot shows an example of the Enrollment page to enroll the customer to the VIP Preferred Network.

Customer using VIP Preferred payment for the subsequent time

After successful Account Equiry check, customer is redirected to the PXP checkout details page
Available Balance, Bank Name and Routing Number is displayed to the customer in PXP checkout.
- Customer initiates the payment using Pay Now button. A backend notification is sent to the merchant to confirm the deposit.
  - On Successful confirmation from the merchant payment is initiated with the Provider.
  - If merchant decides to reject the deposit or any communication error is occured then customer is redirected to the error url.
- On Successful transaction with the provider, payment status will be DepositedByProvider and merchant can display the success information to the customer.
- On failed transaction with the provider, payment status will be RefusedByProvider and merchant can display the failure information to the customer.

The below screenshot shows an example of the payment details page with registered payment accounts by the customer.

Add a new bank account

Customer can register upto 3 Bank Accounts with the VIP Preferred Number.
"Add new Bank Account" link is displayed on the PXP checkout page. If already 3 accounts are registered then link is not displayed to the customer.

The below screenshot shows an example of the page to add a new bank account

Backend2BackendIntegration

Before doing a deposit or withdrawal with the VIP Preferred product, the merchant should - when the customer selects the payment option - perform an Account Inquiry through the getPaymentInputDataList as described below.

📘
User enrolled
If the user is enrolled, PXP Financial returns the VIP Preferred Account Number, the available balance and 1 or more bank accounts (with bank name, routing number and account number).
Display then the available balance, the bank account with masked account number and ask the user to enter an amount for the deposit.
Initiate the payment with the selected bank account and the entered amount as either a deposit or withdrawal transaction.

The provider describes below that for a user called 'Rollin Z Dice' the available balance is displayed on the merchant website. It displays also the bank account and the entry field for a amount to deposit in the following manner:

📘
User not enrolled
If the user is not enrolled, the merchant should display the enrollment screen and ask the user to enroll with the VIP Preferred Network.
Enrollment happens right on the merchants page: Ask for various user data including ID details and banking details. Check that the user accepts provider´s terms and conditions, then call PXP Financial for the enrollment.

Backend2BackendIntegration - Account Inquiry

getPaymentInputDataList will return the details of the VIP Preferred Account, including the cardholder information, and the account balance.

The following table contains the fields to be sent in the details collection of getPaymentInputDataListRequest xml section:

key (value type, account type, required)	value
VIPPreferredAccountNumber (String, conditional)	The customer account number at GlobalPayments provider. VIPPreferredAccountNumber or IDNumber is required. Max Length: 16 digits
IDType (String, conditional)	Required if IDNumber is used. Max Length: 2 characters. Possible values: DL = Driver’s License ST = State ID MI = Military ID SS = Social Security Number (SSN)
IDNumber (String, conditional)	The number associated with IDType. IDType is required if IDNumber is used. Min Length: 6 characters or digits. Max Length: 30 characters or digits.
IDState (String, conditional)	Two letter state code. Required only if IDType is DL. Max Length: 2 characters.

Example getPaymentInputDataListRequest:

<getPaymentInputDataListRequest xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <merchantID>YourMerchantID</merchantID>
    <shopID>YourShopID</shopID>
    <user>
        <id>422c62c8-9b60-40f8-a9fa-75c027b180df</id>
    </user>
    <paymentMethodID>252</paymentMethodID>
    <details>
        <data xsi:type="keyStringValuePair">
            <key>IDNumber</key>
            <value>662-05-1234</value>
        </data>
        <data xsi:type="keyStringValuePair">
            <key>IDType</key>
            <value>SS</value>
        </data>
        <data xsi:type="keyStringValuePair">
            <key>IDState</key>
            <value>IL</value>
        </data>
    </details>
</getPaymentInputDataListRequest>

Possible keys in getPaymentInputDataListResponse in case of success:

key	description
VIPPreferredAccountNumber	Last 10 digits of customer’s account number at Global Payments provider.
AvailableAmount	Customer’s available amount for transactions. Range: 1.00 – 999999.99
NumberOfBankAccounts	Number of bank accounts associated with this customer. From 0 to 4 bank accounts.
CheckBankName	The name of the bank on the check. Max Length: 30 characters
CheckRoutingNumber	The routing number of the bank. Max Length: 9 digits
CheckAccountNumber	The customer’s bank account number. Not masked. Max Length: 18 digits
UserID	The User ID.

Example getPaymentInputDataListResponse:

<getPaymentInputDataListResponse xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <paymentInputDataList>
        <paymentInputData>
            <data xsi:type="keyStringValuePair">
                <key>VIPPreferredAccountNumber</key>
                <value>7770001070</value>
            </data>
            <data xsi:type="keyDecimalValuePair">
                <key>AvailableAmount</key>
                <value>29797.00</value>
            </data>
            <data xsi:type="keyIntValuePair">
                <key>NumberOfBankAccounts</key>
                <value>2</value>
            </data>
            <data xsi:type="keyStringValuePair">
                <key>CheckBankName</key>
                <value>Bank Of Global US 1</value>
            </data>
            <data xsi:type="keyStringValuePair">
                <key>CheckRoutingNumber</key>
                <value>559012131</value>
            </data>
            <data xsi:type="keyStringValuePair">
                <key>CheckAccountNumber</key>
                <value>815564641309</value>
            </data>
            <data xsi:type="keyStringValuePair">
                <key>UserID</key>
                <value>422c62c8-9b60-40f8-a9fa-75c027b180df</value>
            </data>
        </paymentInputData>
        <paymentInputData>
            <data xsi:type="keyStringValuePair">
                <key>VIPPreferredAccountNumber</key>
                <value>7770001070</value>
            </data>
            <data xsi:type="keyDecimalValuePair">
                <key>AvailableAmount</key>
                <value>29797.00</value>
            </data>
            <data xsi:type="keyIntValuePair">
                <key>NumberOfBankAccounts</key>
                <value>2</value>
            </data>
            <data xsi:type="keyStringValuePair">
                <key>CheckBankName</key>
                <value>Bank Of Global US 2</value>
            </data>
            <data xsi:type="keyStringValuePair">
                <key>CheckRoutingNumber</key>
                <value>559012132</value>
            </data>
            <data xsi:type="keyStringValuePair">
                <key>CheckAccountNumber</key>
                <value>815564641308</value>
            </data>
            <data xsi:type="keyStringValuePair">
                <key>UserID</key>
                <value>422c62c8-9b60-40f8-a9fa-75c027b180df</value>
            </data>
        </paymentInputData>
    </paymentInputDataList>
</getPaymentInputDataListResponse>

<getPaymentInputDataListResponse xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <paymentInputDataList>
        <paymentInputData>
            <data xsi:type="keyStringValuePair">
                <key>ErrorCode</key>
                <value>UserNotEnrolled</value>
            </data>
            <data xsi:type="keyStringValuePair">
                <key>ErrorMessage</key>
                <value>No Account on File</value>
            </data>
            <data xsi:type="keyStringValuePair">
                <key>UserID</key>
                <value>422c62c8-9b60-40f8-a9fa-75c027b180df</value>
            </data>
        </paymentInputData>
    </paymentInputDataList>
</getPaymentInputDataListResponse>

<getPaymentInputDataListResponse xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<paymentInputDataList>
<paymentInputData>
<data xsi:type="keyStringValuePair">
<key>VIPPreferredAccountNumber</key>
<value>7774650431</value>
</data>
<data xsi:type="keyDecimalValuePair">
<key>AvailableAmount</key>
<value>4500.00</value>
</data>
<data xsi:type="keyIntValuePair">
<key>NumberOfBankAccounts</key>
<value>0</value>
</data>
<data xsi:type="keyStringValuePair">
<key>UserID</key>
<value>2342342344</value>
</data>
</paymentInputData>
</paymentInputDataList>
</getPaymentInputDataListResponse>

Possible keys in getPaymentInputDataListResponse in case of failure:

key	description
ErrorCode	Possible ErrorCodes: - ValidationError - UserNotEnrolled (The Merchant should proceed to enrollment) - UserEnrollmentDeclined (The Customer should contact Customer support) - ProviderTechnicalError
ErrorMessage	Error Description.
UserID	The User ID.

Example getPaymentInputDataListResponse (Failure):

<getPaymentInputDataListResponse xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <paymentInputDataList>
        <paymentInputData>
            <data xsi:type="keyStringValuePair">
                <key>ErrorCode</key>
                <value>UserNotEnrolled</value>
            </data>
            <data xsi:type="keyStringValuePair">
                <key>ErrorMessage</key>
                <value>No Account on File</value>
            </data>
            <data xsi:type="keyStringValuePair">
                <key>UserID</key>
                <value>422c62c8-9b60-40f8-a9fa-75c027b180df</value>
            </data>
        </paymentInputData>
    </paymentInputDataList>
</getPaymentInputDataListResponse>

🚧
Account closed
Anytime an account is closed/declined by Global Payments, the account inquiry response will not return any limit or banking information.

Backend2BackendIntegration - Deposit initiation

The following parameters can be provided in initiatePaymentRequest.specificPaymentData:

key (value type, account type, required)	value
VIPPreferredAccountNumber (string, required)	VIP Preferred Account Number

The following parameters a required for the bank account to be passed within
initiatePaymentRequest.specificPaymentAccountData:

key (value type, account type, required)	value
AccountNumber (string, required	The customer´s bank account number.
BankSortCode (string, required)	The routing number of the bank.
BankCountryCode2 (string, required)	Country code of the bank.

Example initiatePaymentRequest:

<?xml version="1.0" encoding="utf-16"?>
<initiatePaymentRequest xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <merchantID>YourMerchantID</merchantID>
  <shopID>YourShopID</shopID>
  <merchantTransactionID>bb436955-71bd-4a57-a922-a87801413cde</merchantTransactionID>
  <paymentMethodID>252</paymentMethodID>
  <amount currencyCode="USD">10</amount>
  <userID>d408bdff-b980-4762-8ffd-1cdf26</userID>
  <userData>
    <username>d408bdff-b980-4762-8ffd-1cdf26</username>
  </userData>
  <userIP>127.0.0.1</userIP>
  <userSessionID>93b45b68-efcd-48c9-b80a-011f1e2f762f</userSessionID>
  <creationTypeID>1</creationTypeID>
  <specificPaymentData>
    <data xsi:type="keyStringValuePair">
      <key>VIPPreferredAccountNumber</key>
      <value>1234567890123456</value>
    </data>
  </specificPaymentData>
  <paymentAccount>
    <specificPaymentAccountData xmlns="http://www.cqrpayments.com/PaymentProcessing">
      <data xsi:type="keyStringValuePair">
        <key>BankCountryCode2</key>
        <value>US</value>
      </data>
      <data xsi:type="keyStringValuePair">
        <key>AccountNumber</key>
        <value>12345678901234567</value>
      </data>
      <data xsi:type="keyStringValuePair">
        <key>BankSortCode</key>
        <value>123456789</value>
      </data>
    </specificPaymentAccountData>
  </paymentAccount>
</initiatePaymentRequest>

Example initiatePaymentResponse:

<?xml version="1.0" encoding="utf-16"?>
<initiatePaymentResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <payment xmlns="http://www.cqrpayments.com/PaymentProcessing" xsi:type="q1:paymentWithPaymentAccount">
    <merchantID>YourMerchantID</merchantID>
    <shopID>YourShopID</shopID>
    <paymentMethod>
      <key>252</key>
      <value>VIPPreferredDeposit</value>
    </paymentMethod>
    <merchantTransactionID>bb436955-71bd-4a57-a922-a87801413cde</merchantTransactionID>
    <paymentID>ea0256a0-0f98-4c7c-ba6a-0ae0ec192909</paymentID>
    <userID>d408bdff-b980-4762-8ffd-1cdf26</userID>
    <paymentProvider>
      <key>155</key>
      <value>GlobalPayments</value>
    </paymentProvider>
    <amount currencyCode="USD">10</amount>
    <creationType>
      <key>1</key>
      <value>User</value>
    </creationType>
    <userIP>127.0.0.1</userIP>
    <state>
      <id>55a64589-78ac-40a2-b43c-57a82903f428</id>
      <definition>
        <key>29</key>
        <value>DepositedByProvider</value>
      </definition>
      <createdOn>2017-05-22T10:33:37.242211Z</createdOn>
      <paymentStateDetails>
        <detail xsi:type="keyStringValuePair">
          <key>ProviderResponseCode</key>
          <value>00</value>
        </detail>
        <detail xsi:type="keyStringValuePair">
          <key>ProviderTransactionTypeID</key>
          <value>0</value>
        </detail>
        <detail xsi:type="keyStringValuePair">
          <key>ProviderTransactionTimeStamp</key>
          <value>20170102152331</value>
        </detail>
        <detail xsi:type="keyStringValuePair">
          <key>ProviderCustomerFullName</key>
          <value>ROLLIN Z DICE</value>
        </detail>
        <detail xsi:type="keyStringValuePair">
          <key>ProviderCustomerIDType</key>
          <value>DL</value>
        </detail>
        <detail xsi:type="keyStringValuePair">
          <key>ProviderCustomerIDState</key>
          <value>IL</value>
        </detail>
        <detail xsi:type="keyStringValuePair">
          <key>ProviderCustomerIDNumber</key>
          <value>*******8909</value>
        </detail>
        <detail xsi:type="keyStringValuePair">
          <key>CurrentBusinessDayCheckTotal</key>
          <value>100,00</value>
        </detail>
      </paymentStateDetails>
    </state>
    <isExecuted>true</isExecuted>
    <baseAmount currencyCode="EUR">7.51</baseAmount>
    <paymentDetails>
      <detail xsi:type="keyStringValuePair">
        <key>ProviderAuthorizationID</key>
        <value>999680</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>ProviderTransactionID</key>
        <value>ABC99999999999999999</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>ProviderExternalID</key>
        <value>133</value>
      </detail>
    </paymentDetails>
    <paymentAccount>
      <paymentAccountID>ce1cb0f5-6150-4d4c-924b-d9f2c13f4049</paymentAccountID>
    </paymentAccount>
  </payment>
</initiatePaymentResponse>

Backend2BackendIntegration - Add Bank account

Up to 4 bank accounts can be associated with a VIP Preferred Account Number. One account is added during user enrollment. Additional accounts can be added with the account registration call below.

Existing account can be removed only by contacting GlobalPayment´s CAMS helpdesk.

📘
Test suggestion

Enroll a user

Execute getPaymentInputData -> make sure he has 1 bank account

Execute account registration

execute getPaymentInputData -> make sure he has 2 bank accounts

done

The following table contains the fields to be sent in the specificPaymentAccountData details collection of registerPaymentAccount xml section:

key (value type, account type, required)	value
BankCountryCode2 (string, required)	Country code of the bank account
BankSortcode (string, required)	Sort code of the bank account
AccountNumber (string, required)	Account number of the bank account. Minimum 4 digits, maximum 18 digits.
AccountOwnerTokenOnProvider string, required)	VIPPreferredAccount number.

Example registerPaymentAccount request:

<?xml version="1.0" encoding="utf-8"?>
<registerPaymentAccountRequest xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.cqrpayments.com/PaymentProcessing">
  <merchantID>B2BTestMerchant</merchantID>
  <userID>testuser2</userID>
  <paymentAccountID>4df901a0-51a7-47f0-9f86-59a0add9f926</paymentAccountID>
  <paymentAccountTypeID>5</paymentAccountTypeID>
  <isActive>true</isActive>
  <isVisible>true</isVisible>
  <paymentMethodID>252</paymentMethodID>
  <specificPaymentAccountData>
    <data xsi:type="keyStringValuePair">
      <key>BankCountryCode2</key>
      <value>SE</value>
    </data>
    <data xsi:type="keyStringValuePair">
      <key>BankSortCode</key>
      <value>83279</value>
    </data>
    <data xsi:type="keyStringValuePair">
      <key>AccountNumber</key>
      <value>9048832662</value>
    </data>
    <data xsi:type="keyStringValuePair">
      <key>AccountOwnerTokenOnProvider</key>
      <value>5275057770001070</value>
    </data>
  </specificPaymentAccountData>
  <paymentProviderID>155</paymentProviderID>
</registerPaymentAccountRequest>

Example registerPaymentAccount response for a successful case:

<?xml version="1.0" encoding="utf-8"?>
<registerPaymentAccountResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.cqrpayments.com/PaymentProcessing" />

Example registerPaymentAccount response for a unsuccessful case:

<?xml version="1.0" encoding="utf-8"?>
<paymentServiceException xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.cqrpayments.com/PaymentProcessing">
                <ExtensionData />
                <id>5321f2a8-82f7-400e-9965-8bf159dca847</id>
                <errorCode>100</errorCode>
                <errorMessage>Invalid Banking Information</errorMessage>
</paymentServiceException>

ErrorCode	Description	ErrorMessage
100	ValidationError	Invalid Banking Information
1015	ProviderTechnicalError	Unexpected Error

Notifications

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

PaymentStates	Description
DepositedByProvider	Success state.
RefusedByProvider	Refused by provider.
DepositErrorReportedByProvider	Error happened during payment processing.

Example handlePaymentStateChangedNotificationRequest:

<?xml version="1.0" encoding="utf-16"?>
<handlePaymentStateChangedNotificationRequest xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <payment xmlns="http://www.cqrpayments.com/PaymentProcessing" xsi:type="q1:paymentWithPaymentAccount">
    <merchantID>YourMerchantID</merchantID>
    <shopID>YourShopID</shopID>
    <paymentMethod>
      <key>252</key>
      <value>VIPPreferredDeposit</value>
    </paymentMethod>
    <merchantTransactionID>bb436955-71bd-4a57-a922-a87801413cde</merchantTransactionID>
    <paymentID>ea0256a0-0f98-4c7c-ba6a-0ae0ec192909</paymentID>
    <userID>d408bdff-b980-4762-8ffd-1cdf26</userID>
    <paymentProvider>
      <key>155</key>
      <value>GlobalPayments</value>
    </paymentProvider>
    <amount currencyCode="USD">10.0000</amount>
    <creationType>
      <key>1</key>
      <value>User</value>
    </creationType>
    <userIP>127.0.0.1</userIP>
    <state>
      <id>55a64589-78ac-40a2-b43c-57a82903f428</id>
      <definition>
        <key>29</key>
        <value>DepositedByProvider</value>
      </definition>
      <createdOn>2017-05-22T10:33:37.243</createdOn>
      <description />
      <paymentStateDetails>
        <detail xsi:type="keyStringValuePair">
          <key>ProviderResponseCode</key>
          <value>00</value>
        </detail>
        <detail xsi:type="keyIntValuePair">
          <key>ProviderTransactionTypeID</key>
          <value>0</value>
        </detail>
        <detail xsi:type="keyStringValuePair">
          <key>ProviderCustomerFullName</key>
          <value>ROLLIN Z DICE</value>
        </detail>
        <detail xsi:type="keyStringValuePair">
          <key>ProviderCustomerIDType</key>
          <value>DL</value>
        </detail>
        <detail xsi:type="keyStringValuePair">
          <key>ProviderCustomerIDState</key>
          <value>IL</value>
        </detail>
        <detail xsi:type="keyStringValuePair">
          <key>ProviderCustomerIDNumber</key>
          <value>*******8909</value>
        </detail>
        <detail xsi:type="keyStringValuePair">
          <key>ProviderTransactionTimeStamp</key>
          <value>20170102152331</value>
        </detail>
        <detail xsi:type="keyDecimalValuePair">
          <key>CurrentBusinessDayCheckTotal</key>
          <value>100.000000000</value>
        </detail>
      </paymentStateDetails>
    </state>
    <isExecuted>true</isExecuted>
    <baseAmount currencyCode="EUR">7.5100</baseAmount>
    <paymentDetails>
      <detail xsi:type="keyStringValuePair">
        <key>ProviderExternalID</key>
        <value>133</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>ProviderTransactionID</key>
        <value>ABC99999999999999999</value>
      </detail>
      <detail xsi:type="keyStringValuePair">
        <key>ProviderAuthorizationID</key>
        <value>999680</value>
      </detail>
    </paymentDetails>
    <paymentAccount>
      <paymentAccountID>ce1cb0f5-6150-4d4c-924b-d9f2c13f4049</paymentAccountID>
    </paymentAccount>
  </payment>
</handlePaymentStateChangedNotificationRequest>

User Enrollment

For user enrollment in the VIP Preferred API the following steps should be considered:

❗️
GlobalPayments User Enrollment
Step 1
The merchant system has to register a user with the following required details:
FirstName, Lastname, DateOfBirth
Street, HouseNumber, HouseNumberExtension (one of the 3 values is mandatory)
City, State, ZIP Code, Country
Home phone number
Email address (Note: email has become mandatory with version 2.9 from VIP Preferred)
This user´s userID value is to be passed in the POST request in step 2.
Step 2
The merchant system makes a POST request to the Kalixa Backend Service REST API(v5) in order to create a user enrollment. For more details how to build a request, see Payment Service v5 API.
Step 3
The Kalixa Backend Service REST API(v5) returns a response which contains the last state of the user enrollment.

📘
Older vs. Newer Enrollment
On the older enrollment flow, IDType, IDState and IDNumber is mandatory. The older flow thus requires he entry of the user´s driver´s license.
The newer enrollment flow has to be activated for the merchant. In this flow, the ID fields are optional.
The merchant should either send IDType, IDState and obviously ID Number, or omit all 3 fields.
In addition the userIP address should be sent.

The following parameters can be provided in the POST request to the Kalixa Backend Service REST API (v5).

key (value type, account type, required)	value
UserID (String, required)	The User ID. Taken from the user to be registered respectively the user returned by the GetPaymentInputDataList request.

Parameters in the details collection of the POST request to Kalixa Backend Service REST API(v5):

key (value type, account type, required)	value
CheckRoutingNumber (String, required)	The routing number of the bank. Max Length: 9 digits
CheckAccountNumber (String, required)	The customer’s bank account number. Max Length: 18 digits
IDType (String, required)	Values: DL = Driver’s License ST = State ID MI = Military ID Max Length: 2 characters
IDState (String, required)	Two letter state code. Ignore this value when ID type is military ID. Max Length: 2 characters
IDNumber (String, required)	The number associated with IDType. Max Length: 30 characters Min Length: 6 characters
ID Expiration (String, optional)	The expiration associated with IDType (optional).
SocialSecurityNumber (String conditional))	The customer’s social security number. This field has to be provided in case it will be used later on in the Account Inquiry transaction. Max Length: 9 digits Min Length: 8 digits if not empty
UserIP (String, required on newer flow	The customer´s (end user´s) IP address

Note. the field Amount should be left blank.

📘
Provider Testing
For testing purposes make sure to change Social Security Number and Driver´s License number. The userID is not sent to provider, is it only used to fetch user details such as firstName, lastName and DOB.
Make sure to provide a valid routing number - see e.g. this site.

Example of UserEnrollment request:

{
  "MerchantID":"{{merchant}}",
"ClientSystemUserEnrollmentId":"c1da2b74-b4a1-4faf-a9ec-82f16380dec3",
"Type":"account.globalpayments",
"UserID":"2342342344",
"Details":
{
"CheckRoutingNumber":"559012138",
"CheckAccountNumber":"91971309",
"IDType":"DL",
"IDState":"IL",
"IDNumber":"WX0072150301",
"SocialSecurityNumber":"228780411"
}
}

{
    "MerchantID": "{{merchant}}",
    "ClientSystemUserEnrollmentId": "c16d01e3-1125-4350-8f15-37edd9f21ff6",
    "Type": "account.globalpayments",
    "UserID": "hc20220722113104",
    "Details": {
        "CheckRoutingNumber": "061000052",
        "CheckAccountNumber": "5656039106",
        "IDType": "DL",
        "IDState": "IL",
        "IDNumber": "306541595",
        "SocialSecurityNumber": "328752345",
        "UserIP":"2a02:8388:7004:9100:98ea:aee5:313:af8c"
    }
}

{
  "MerchantID":"B2BTestMerchant",
  "ClientSystemUserEnrollmentId":"UserEnrollment123",
  "Type":"account.globalpayments",
  "UserID":"03053348-f823-4143-8339-2e2e56f86599",
  "Details":
  {
    "ReturnUrl":null,
    "MemberNumber":null,
    "MerchantName":null,
    "OperatorID":null,
    "LocationName":null,
    "CardNumber":null,
    "CheckRoutingNumber":"062206596",
    "CheckAccountNumber":"112233445566778899",
    "IDType":"DL",
    "IDState":"IL",
    "IDNumber":"A12345678000",
    "IDExpiration":null,
    "SocialSecurityNumber":null,
    "Amount":null,
    "TimeZone":null,
    "TracingID":"7c0ac5d1-3704-41cc-90d9-2482be0ee481"
  }
}

Parameters in the POST response from the Kalixa Backend Service REST API(v5) in case of successful response:

key (value type, account type, required)	value
TransactionTimeStamp (String, required)	The time stamp of this transaction based on the Time Zone of the merchant. YYYYMMDDHHMMSS format.
AccountNumber (String, required)	VIP Preferred Account number. Max Length: 16 digits
TransactionID (String, required)	Assigned by the LightSpeed SSL Gateway. Max Length: 25 digits, Min Length: 8 digits
Amount (String, required)	The credit limit of the new account. Range: 1.00 –
AvailableAmount (String, required)	Cardholder’s available credit for transactions settling the next business day. Range: 1.00 – 25000.00 (The provider returns both a TOTAL AMOUNT and an AVAILABLE AMOUNT. As some states have state limits, a user may have a 10.000 USD Amount, but only 3.000 USD available due to restrictions.)
CustomerName (String, required)	FNAME, MNAME, and LNAME combined into a single field. Max Length: 40 characters
IDType (String, required)	Values: DL = Driver’s License ST = State ID MI = Military ID Max Length: 2 characters
IDState (String, required)	Two letter state code. Ignore this value when ID type is military ID. Max Length: 2 characters
IDNumber (String, required)	The number associated with IDType. Max Length: 30 characters Min Length: 6 characters
OperatorID (String, required)	The terminal operator or cashier ID number. Max Length: 30 characters
errorCode (*String, required, available on configuration)	Provider error code.

Example of UserEnrollment response:

{
  "ID":"4fe14096-9c10-43c3-91b6-601ebacb1678",
  "StateName":"Enrolled",
  "Details":
  { 
   "TransactionTimeStamp":"20170522024323",
   "VIPPreferredAccountNumber":"5275057770001070",
   "TransactionID":"987654321",
   "Amount":"10000.99",
   "AvailableAmount":"999.01",
   "CustomerName":"Stephan M. Smith",
   "IDType":"DL",
   "IDState":"IL",
   "IDNumber":"A12345678000",
   "OperatorID":"4545478776565"
  } 
}

{
    "id": "d3848585-d972-4f1a-8b50-e68324b61ddd",
    "state": "Enrolled",
    "details": {
        "TransactionTimeStamp": "20180117101226",
        "VIPPreferredAccountNumber": "7770200060",
        "TransactionID": "C0A8461E016104ADAF5800579",
        "Amount": "",
        "AvailableAmount": "777.00",
        "CustomerName": "ROLLIN FARFARAWAY",
        "IDType": "DL",
        "IDState": "IL",
        "IDNumber": "*******8909",
        "OperatorID": ""
    }
}

{
    "code": "ValidationError",
    "details": {
        "validationErrors": "The ID Number was entered incorrectly"
    }
}

{
    "code": "UserEnrollmentDeclined",
    "details": {
        "error": "Fraud activity has been detected on this account"
    }
}

{
    "code": "ProviderTechnicalError",
    "details": {
        "error": "Missing SSN",
        "errorCode": "99"
    }
}

{
    "id": "d8d5d172-c0b2-44a6-af5c-d4cd6a3bdb5e",
    "state": "Enrolled",
    "details": {
        "TransactionTimeStamp": "20220722023114",
        "VIPPreferredAccountNumber": "7210689038",
        "TransactionID": "0A7E90C80182253F316E04258",
        "Amount": "",
        "AvailableAmount": "004500.00",
        "CustomerName": "SHERLOCK HOLMES",
        "IDType": "DL",
        "IDState": "IL",
        "IDNumber": "****1595",
        "OperatorID": ""
    },
    "stateDescription": null
}

Parameters in the POST response from the Kalixa Backend Service REST API(v5) in case of error response:

key (value type, account type, required)	value
errorMessage (String, required)	(see below)

Please note the following description for error cases:

Error Code	Error Message	Description	Sample Customer Error Message	Next step
02	Application Pending	Decline	DECLINED - GENERAL ADVERSE ACTION (USE FCRA DECLINE MESSAGE) Unable to approve your Enrollment request at this time. Questions call Customer Case at XXX Reference Code E02	1. Display a message to the customer that includes "Notice of Decline" wording 2. Give the customer the option of calling CAMS
14	Card Reported Lost or Stolen	Card Reported Lost	ENROLLMENT DECLINED (USE FCRA DECLINE MESSAGE) The credentials that corresponds to this account have been reported as lost or stolen. Questions call Customer Care at XXX Reference Code E14	1. Display an error message to the customer 2. Give the customer the option of calling CAMS
18	Fraud activity has been detected on this account	Fraud Detected	ENROLLMENT DECLINED (USE FCRA DECLINE MESSAGE) Unable to approve your Enrollment request at this time. Questions call Customer Care at XXX Reference Code E18	1. Display a sanitized message to the customer that includes "Notice of Decline" wording 2. Give the customer the option of calling CAMS
19	Customer is Self-Excluded from this property	Self-Exclusion Match	SELF-EXCLUDED MATCH (USE FCRA DECLINE MESSAGE) We have detected a positive match with the list of Self-Excluded patrons. No Enrollment can be processed at this time. Questions call Customer Care at XXX Reference Code E19	1. Display an error message to the customer. 2. Give the customer the option of calling CAMS.
15	Various messages	Invalid data detected in the enrollment request	EDIT ERROR One or more of the data elements provided are incorrect: Invalid SSN Driver’s License Error Questions call Customer Care at XXX. Please reference Code E15	1. Display an error message to the customer 2. Customer can retry the transaction if they are able to fix the data in error 3. Give the customer the option of calling CAMS 4. If the error isn't something the customer can fix on the enrollment screen, give the customer the option of calling the Operator.
17	Various	Invalid Banking Information	INVALID BANKING Banking information is invalid, and an enrollment cannot be processed: Not ACH Capable Questions call Customer Care at XXX. Please reference Code E17	1. Display an error message to the customer 2. Customer can retry the transaction after they change the data in error 3. Give the customer the option of calling CAMS
26	Various	Problem with Driver’s License	RETRY Possible A formatting error has been detected with the ID. Please Retry or call Customer Care at XXX Reference Code E26 Invalid DL Format	1. Display an error message to the customer 2. Customer can retry the transaction after they change the data in error 3. Give the customer the option of calling CAMS

Provider Testing notes

Please be cautious when trying the enroll a person who is already enrolled. When either the SSN or the DL already exists on the system, the DOB is checked by GlobalPayments to make sure it also matches.

If it does not match, the system will return a message to contact the help desk.

The SSN needs to be 9 digits and if it matches somebody already enrolled, the DOB must also match.

📘
Data
Make sure that all the user details are present:

Firstname, MiddleName, Lastname, DOB

Housenumber, Mailing Address, Apartment number (one of those 3 values is mandatory)

City, State, Zip Code

Country

Home phone number

eMail address

Make sure that

user should be registered using US state code (see here)
put valid user data (e.g. a DL number according to the state, phone number with valid format)
when enrolling a new patron, make sure to use a different ID number (SSN), a different bank routing and check account number. For a list of valid routing number see e.g. this site.

CERT testing

Please use the following test data for CERT testing:

Name            SSN Number  House Number    Stree name  City    State   ZIP Code    Phone Number    Bank Routing    Bank Accont #
Ronni Hudson        517469491   8582    Peachtree Dunwoody Rd   Atlanta GA  30328   3126121702  061000052   5656039106
Haley Douglas       203786908   8583    Peachtree Dunwoody Rd   Atlanta GA  30328   3126121703  061000052   5656039107
Kendall Leslie      504231918   8584    Peachtree Dunwoody Rd   Atlanta GA  30328   3126121704  061000052   5656039108
Jerlene Hart        251800881   8585    Peachtree Dunwoody Rd   Atlanta GA  30328   3126121705  061000052   5656039109
Virgina Hayward     252096470   8586    Peachtree Dunwoody Rd   Atlanta GA  30328   3126121706  061000052   5685039110
Vivien Coulson      519053306   8587    Peachtree Dunwoody Rd   Atlanta GA  30328   3126121707  061000052   5685039111
Renaldo Royle       462655350   8588    Peachtree Dunwoody Rd   Atlanta GA  30328   3126121708  061000052   5685039112
Ernie Holmes        502805622   8589    Peachtree Dunwoody Rd   Atlanta GA  30328   3126121709  061000052   5685039113
Wilbert Connor      309786272   8590    Peachtree Dunwoody Rd   Atlanta GA  30328   3126121710  061000052   9685039114
Myrtle Cunningham   538781062   8591    Peachtree Dunwoody Rd   Atlanta GA  30328   3126121711  061000052   9685039115
Riva Ryan       525032916   8592    Peachtree Dunwoody Rd   Atlanta GA  30328   3126121712  061000052   9685039116

VIP Preferred Deposit (ACH)

📘
VIP Preferred Deposit Returns

Redirect Integration

Account Enquiry Check

🚧
Closed accounts

Customer using VIP Preferred payment for the first time (Enrollment flow)

Customer using VIP Preferred payment for the subsequent time

Add a new bank account

Backend2BackendIntegration

📘
User enrolled

📘
User not enrolled

Backend2BackendIntegration - Account Inquiry

🚧
Account closed

Backend2BackendIntegration - Deposit initiation

Backend2BackendIntegration - Add Bank account

📘
Test suggestion

Notifications

User Enrollment

❗️
GlobalPayments User Enrollment

📘
Older vs. Newer Enrollment

📘
Provider Testing

Provider Testing notes

📘
Data

CERT testing

📘VIP Preferred Deposit Returns

Redirect Integration

Account Enquiry Check

🚧Closed accounts

Customer using VIP Preferred payment for the first time (Enrollment flow)

Customer using VIP Preferred payment for the subsequent time

Add a new bank account

Backend2BackendIntegration

📘User enrolled

📘User not enrolled

Backend2BackendIntegration - Account Inquiry

🚧Account closed

Backend2BackendIntegration - Deposit initiation

Backend2BackendIntegration - Add Bank account

📘Test suggestion

Notifications

User Enrollment

❗️GlobalPayments User Enrollment

📘Older vs. Newer Enrollment

📘Provider Testing

Provider Testing notes

📘Data

CERT testing

📘
VIP Preferred Deposit Returns

🚧
Closed accounts

📘
User enrolled

📘
User not enrolled

🚧
Account closed

📘
Test suggestion

❗️
GlobalPayments User Enrollment

📘
Older vs. Newer Enrollment

📘
Provider Testing

📘
Data