Pay Tool Data

Special Notes:

Important: Sensitive data are passed to the method. To avoid logging of sensitive data, the CardNumberID argument must be escaped as this described in the section Important: Avoid Sensitive Data Logging. Avoiding sensitive data is obligatory, otherwise sensitive data will be logged.

  • Int PayToolCounter is a number of payment tool slots.
  • Str PayToolSlot_N defines payment method to pay an order. Generally, for credit card payments it is enough to submit the PayToolID and arbitrary the IPAddressID.

Pay Tool data are submitted as strings of the following format: <PayToolSlotName>=<PayToolSlotValue>.

Where:

  • <PayToolSlotName> is a name of the payment tool data slot.
  • <PayToolSlotValue> is a value of the payment tool data slot.

Billing supports the following payment tool data slots (they are validated by fraud screening):

Registered credit card:

  • PayToolID is an ID of registered payment method (if this field is specified all other fields can be empty).
  • IPAddressID is a customer's current IP address.

New Credit Card:

  • PayToolTypeID is a type of payment tool; it is 0 for the Credit card method.
  • CardTypeID is an ID of a payment system registered in Billing, for example, "Visa" or "MasterCard".
  • CardNumberID is a credit card number.

    Important: If a credit card number is not passed with the "XXX" prefix, the response will contain an unencrypted credit card number after calling the method.

  • CardHolderNameID is a card holder name.
  • CVCID is a credit card security code.
  • IssueNumID is a credit card issue number; this number can be skipped if a payment system does not require it.
  • StartDateID is a credit card start date; this value can be skipped if a payment system does not require it.
  • ExpDateID is a credit card expiration date in the MM/YY format.
  • BillingAddressID is a first billing address.
  • BillingAddress2ID is a second billing address.
  • BillingCityID is a card holder's city.
  • BillingStateID is a card holder's state.
  • BillingZipID is a card holder's ZIP or postal code.
  • BillingCountryID is a card holder's country.
  • BillingEmailID is a card holder's email address.
  • BillingPhoneCountryID is a phone code of a card holder's country.
  • BillingPhoneAreaID is a phone area code.
  • BillingPhoneNumberID is a phone number.
  • BillingPhoneExtensionID is a phone number extension.
  • BillingFaxCountryID is a fax code of a card holder's country.
  • BillingFaxAreaID is a fax phone area code.
  • BillingFaxNumberID is a fax number.
  • BillingFaxExtensionID is a fax number extension.
  • IPAddressID is a customer's current IP address.

Bank Account:

  • PayToolTypeID is a type of payment tool; it is 1 for a bank account.
  • BankNumberID is a customer's bank number.
  • AccountNumberID is a customer's bank account number.
  • AccountHolderNameID is an account holder name.
  • IPAddressID is a customer's current IP address.
  • PaySystemID is a customer's bank payment system.
  • BillingCountryID is a customer's country.

External Redirect:

  • PayToolTypeID is a type of payment tool; it is 2 for the External redirect method.
  • PluginID is an ID of a payment plug-in of the external redirect type, for example PayPal.
  • PayToolID is an ID of registered payment method (if this field is specified all other fields can be empty).
  • IPAddressID is a customer's current IP address.
  • originUrl (mandatory) is an URL of the payment originator.
  • callbackUrl ( mandatory) is an URL to return to with any status (some payment systems do not respond statuses on return, just transaction identifiers). To process the response, the JsonRedirectPayment_API method must be called after processing data received in the HTTP response.
  • callbackUrl3D (mandatory) is an URL to handle responses from a 3D-Secure gateway. To process the response, the JsonCallback3D_API method must be called after.
  • callbackUrlOk (mandatory) is an URL to return with the success status. To process the response, the JsonRedirectPayment_API method must be called after, with returnResult='ok' and HTTP data.
  • callbackUrlFail (mandatory) is an URL to return with the fail status. To process the response, the JsonRedirectPayment_API method must be called after, with returnResult='fail' and HTTP data.
  • notifyUrl (mandatory) is an URL to handle server-to-server notifications. To process the response, the JsonRedirectNotify_API method must be called after.

    Below, see the example of how these URLs are generated in a custom Online Store:

Copy 
// Callback URLs are based on the “Referer” header to resolve network path.
$refererParts = explode( '?', $_SERVER['HTTP_REFERER']);
$baseUrl = "https://my-custom-store/callback.php";
$PayToolData['originUrl']       =  $baseUrl;
$PayToolData['callbackUrl']     = "$baseUrl/{docId}/callback";
$PayToolData['callbackUrl3D']   = "$baseUrl/{docId}/3dsecure";
$PayToolData['callbackUrlOk']   = "$baseUrl/{docId}/ok/callback";
$PayToolData['callbackUrlFail'] = "$baseUrl/{docId}/fail/callback";
$PayToolData['notifyUrl']       = "$baseUrl/{docId}/notify";

Where {docId} is a placeholder for transaction ID.

Check/Cash:

  • PayToolTypeID is a type of payment tool; it is 3 for the Check/Cash method.
  • PluginID is an ID of a payment plug-in of the external redirect type; it is 0 for Check/Cash.
  • IPAddressID is a customer's current IP address.

Universal

  • PayToolTypeID is a type of payment tool; it is 6 for the Universal method.
  • PluginID is an ID of a payment plug-in of the external redirect type, for example PayPal.
  • PayToolID is an ID of registered payment method (if this field is specified all other fields can be empty).
  • IPAddressID is a customer's current IP address.

Modal Form

  • PayToolTypeID is a type of payment tool; it is 7 for the Modal Form method.
  • PluginID is an ID of a payment plug-in of the external redirect type, for example PayPal.
  • PayToolID is an ID of registered payment method (if this field is specified all other fields can be empty).
  • IPAddressID is a customer's current IP address.
  • originUrl (mandatory) is an URL of the payment originator.
  • callbackUrl ( mandatory) is an URL to return to with any status (some payment systems do not respond statuses on return, just transaction identifiers). To process the response, the JsonRedirectPayment_API method must be called after processing data received in the HTTP response.
  • callbackUrl3D (mandatory) is an URL to handle responses from a 3D-Secure gateway. To process the response, the JsonCallback3D_API method must be called after.
  • callbackUrlOk (mandatory) is an URL to return with the success status. To process the response, the JsonRedirectPayment_API method must be called after, with returnResult='ok' and HTTP data.
  • callbackUrlFail (mandatory) is an URL to return with the fail status. To process the response, the JsonRedirectPayment_API method must be called after, with returnResult='fail' and HTTP data.
  • notifyUrl (mandatory) is an URL to handle server-to-server notifications. To process the response, the JsonRedirectNotify_API method must be called after.

    Below, see the example of how these URLs are generated in a custom Online Store:

Copy 
// Callback URLs are based on the “Referer” header to resolve network path.
$refererParts = explode( '?', $_SERVER['HTTP_REFERER']);
$baseUrl = "https://my-custom-store/callback.php";
$PayToolData['originUrl']       =  $baseUrl;
$PayToolData['callbackUrl']     = "$baseUrl/{docId}/callback";
$PayToolData['callbackUrl3D']   = "$baseUrl/{docId}/3dsecure";
$PayToolData['callbackUrlOk']   = "$baseUrl/{docId}/ok/callback";
$PayToolData['callbackUrlFail'] = "$baseUrl/{docId}/fail/callback";
$PayToolData['notifyUrl']       = "$baseUrl/{docId}/notify";

Where {docId} is a placeholder for transaction ID.

UseFraudCheck data slot

UseFraudCheck is an additional data slot that can be used in any payment tool. It is designed to handle fraud screening start for 0-total orders. The UseFraudCheck slot can take the following values:

  • UseFraudCheck=true. The order will be screened.
  • UseFraudCheck=false. The order will not be screened.

If the UseFraudCheck data slot is not present in payment tool information:

  • If the method is called for a new customer account, the order will be screened.
  • If the method is called for an existing customer account, the order will not be screened.

Registered Credit Card Example:

Copy 
<!-- PayToolCounter -->
<value>
    <i4>2</i4>
</value>
<!-- Identifier of Payment tool registered
  on Customer's Account -->
<value>PayToolID=3</value>
<!-- IP Address -->
<value>IPAddressID=192.168.232.10</value>

New Credit Card Example:

Copy 
<!-- PayToolCounter -->
<value>
    <i4>22</i4>
</value>
<!-- Type of Payment tool. 0 means Credit Card -->
<value>PayToolTypeID=0</value>
<!-- Type of CC -->
<value>CardTypeID=Visa</value>
<!-- Card Number -->
<value>XXXCardNumberID=4111111111111111</value>
<!-- Cardholder name -->
<value>CardHolderNameID=JOHN SMITH</value>
<!-- Security code -->
<value>CVCID=123</value>
<!-- Expiration date -->
<value>ExpDateID=07/08</value>
<!-- IP Address -->
<value>IPAddressID=192.168.232.10</value>
<!-- Billing Address -->
<value>BillingAddressID=Sunrise Valley Drive</value>
<value>BillingAddress2ID=Suite 600</value>
<value>BillingCityID=New York</value>
<value>BillingCountryID=us</value>
<value>BillingStateID=NY</value>
<value>BillingZipID=12345</value>
<value>BillingEmailID=jsmith@tailor.com</value>
<value>BillingPhoneCountryID=1</value>
<value>BillingPhoneAreaID=201</value>
<value>BillingPhoneNumberID=4568523</value>
<value>BillingPhoneExtensionID=245</value>
<value>BillingFaxCountryID=1</value>
<value>BillingFaxAreaID=201</value>
<value>BillingFaxNumberID=4568523</value>
<value>BillingFaxExtensionID=235</value>

Bank Account:

Copy 
<!-- PayToolCounter -->
<value>
    <i4>7</i4>
</value>
<!-- Type of Payment tool. 1 means Bank Account -->
<value>PayToolTypeID=1</value>
<!-- Number of customer bank -->
<value>BankNumberID=45689</value>
<!-- Account Number -->
<value>AccountNumberID=356892145</value>
<!-- Accountholder name -->
<value>AccountHolderNameID=JOHN SMITH</value>
<!-- IP Address -->
<value>IPAddressID=192.168.232.10</value>
<!-- Customer bank payment system -->
<value>PaySystemID=DirectDebit</value>
<!-- Customer country -->
<value>BillingCountryID=us</value>

External Redirect:

Copy 
<!-- PayToolCounter -->
<value>
    <i4>4</i4>
</value>
<!-- Type of Payment tool. 2 means External Redirect -->
<value>PayToolTypeID=2</value>
<!-- Identifier of an external redirect payment plug-in -->
<value>PluginID=3</value>
<!-- Identifier of Payment tool registered
  on Customer's Account -->
<value>PayToolID=3</value>
<!-- IP Address -->
<value>IPAddressID=192.168.232.10</value>

Check/Cash Example:

Copy 
<!-- PayToolCounter -->
<value>
    <i4>3</i4>
</value>
<!-- Type of Payment tool. 3 means Check/Cash -->
<value>PayToolTypeID=3</value>
<!-- Identifier of payment plug-in Check/Cash -->
<value>PluginID=0</value>
<!-- IP Address -->
<value>IPAddressID=192.168.232.10</value>

Direct Debit (UK):

Copy 
<!-- PayToolCounter -->
<value>
    <i4>9</i4>
</value>
<!-- Type of Payment tool. 5 means Direct Debit (UK) -->
<value>PayToolTypeID=5</value>
<!-- Customer bank payment system -->
<value>PaySystemID=DirectDebit</value>
<!-- Paper Based Sign Up -->
<value>ABPaperBased=0</value>
<!-- Accountholder name -->
<value>ABAccountHolderNameID=John Smith</value>
<!-- Name of Bank -->
<value>ABBankNameID=Test Bank</value>
<!-- Account Number -->
<value>XXXABAccountNumberID=12345678</value>
<!-- Sort Code -->
<value>XXXABSortCodeID=123456</value>
<!-- Paperless Agreement Confirmation -->
<value>ABPaperlessAgreementConfirm=1</value>
<!-- Customer country -->
<value>BillingCountryID=gb</value>

© 2024 Ingram Micro, Inc. All Rights Reserved. Privacy Policy, Terms of Use and Legal

CloudBlue, an Ingram Micro business, uses cookies to improve the usability of our site. By continuing to use this site and/or logging in you are accepting the use of these cookies. For more information, visit our Privacy Policy.
I accept