GuidesAPI ReferenceDiscussions
Guides

VIP Preferred Deposit (ACH)

Suggest Edits

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

The following method IDs are covered in this section:

IDNameCredit/Debit State
252VIPPreferredDepositDepositedByProvider (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:

FieldValue
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
StateTwo 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 ExpirationThe 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:

keydescription
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:

keydescription
ErrorCodePossible ErrorCodes:
- ValidationError
- UserNotEnrolled (The Merchant should proceed to enrollment)
- UserEnrollmentDeclined (The Customer should contact Customer support)
- ProviderTechnicalError
ErrorMessageError Description.
UserIDThe 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, requiredThe 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>
ErrorCodeDescriptionErrorMessage
100ValidationErrorInvalid Banking Information
1015ProviderTechnicalErrorUnexpected 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.

PaymentStatesDescription
DepositedByProviderSuccess state.
RefusedByProviderRefused by provider.
DepositErrorReportedByProviderError 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 the 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 flowThe 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 CodeError MessageDescriptionSample Customer Error MessageNext step
02Application PendingDeclineDECLINED - 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
14Card Reported Lost or StolenCard Reported LostENROLLMENT 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
18Fraud activity has been detected on this accountFraud DetectedENROLLMENT 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
19Customer is Self-Excluded from this propertySelf-Exclusion MatchSELF-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.
15Various messagesInvalid data detected in the enrollment requestEDIT 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.
17VariousInvalid Banking InformationINVALID 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
26VariousProblem with Driver’s LicenseRETRY 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

Updated over 1 year ago