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.

10211021

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.

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.

10901090

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.

984984

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.

10361036

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

979979

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 imagines that a user called 'Rollin Z Dice' is displayed the available balance, the bank account and the entry field for a amount to deposit in the following manner:

546546

Note: support for adding a bank account is not available at the moment.

📘

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>

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

  1. Enroll a user
  2. Execute getPaymentInputData -> make sure he has 1 bank account
  3. Execute account registration
  4. execute getPaymentInputData -> make sure he has 2 bank accounts
  5. 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.

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)

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

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":"BorgataNJ",
"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":"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"
    }
}

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