X-Payments:Payment initialisation request

From X-Payments Help
Revision as of 14:42, 20 July 2016 by Dohtur (talk | contribs)
Jump to: navigation, search

Request specification

Field Required Type Description
target Y string, 128 Must equal payment
action Y string, 128 Must equal init
confId Y integer Payment module configuration ID
refId Y string, 128 Order ID in the online store
returnUrl Y URL, 255 URL of the page to redirect the customer after payment
callbackUrl Y URL, 255 URL to which X-Payments sends background requests with service information
language N code of ISO 639-1 (Alpha-2) Language code. If not specified - en
cart Y container A container with addresses description
cart/billingAddress Y container A container with the billing address description
cart/billingAddress/firstname Y string, 255
cart/billingAddress/lastname N string, 255
cart/billingAddress/company N string, 255
cart/billingAddress/address Y string, 255
cart/billingAddress/city Y string, 255
cart/billingAddress/state Y string, 255
cart/billingAddress/country Y string, 2 ISO 3166-1 alpha-2 Country code https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
cart/billingAddress/zipcode Y string, 32
cart/billingAddress/email Y emai, 255l
cart/billingAddress/phone Y string, 255
cart/billingAddress/fax N string, 255
cart/shippingAddress Y container A container with the shipping address description
cart/shippingAddress/firstname Y string, 255
cart/shippingAddress/lastname N string, 255
cart/shippingAddress/company N string, 255
cart/shippingAddress/address Y string, 255
cart/shippingAddress/city Y string, 255
cart/shippingAddress/state Y string, 255
cart/shippingAddress/country Y string, 2 ISO 3166-1 alpha-2 Country code https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
cart/shippingAddress/zipcode Y string, 32
cart/shippingAddress/email Y email, 255
cart/shippingAddress/phone Y string, 255
cart/shippingAddress/fax N string, 255
cart/items Y container A container with product description
cart/items/sku Y string, 64 SKU (product code)
cart/items/name Y string, 255 Product name
cart/items/price Y currency Product item price
cart/items/quantity N integer Ordered number of products. If not specified - 1
cart/login Y string, 255 Unique customer ID in the online store (login, username, userid, etc.)
cart/currency N string, 3 Payment currency code (ISO 4217 Alpha-3). If not specified, default payment configuration currency is used
cart/shippingCost - currency Shipping cost. By default - 0
cart/taxCost - currency Tax amount. By default - 0
cart/discount - currency Discount amount. By default - 0
cart/totalCost Y currency Total payment amount. Must equal to a sum of cart/items/price * cart/items/quantity + cart/shippingCost + cart/taxCost - cart/discount
cart/description - string, 65536
cart/merchantEmail Y email, 255
cart/forceTransactionType - one of values: A or S or empty
A - authorize
S - sale 		A flag of forced Sale or Authorize operation. Overrides the setting from the payment configuration. If the value is empty or the field is omitted, the operation is performed according to the payment configuration settings.
api_version Y string Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
template
(supported by API 1.3 and later) 		N string The name of a template in X-Payments requested by the store. Forces the use of the specified template for the payment. If the string passed in this field does not match any template available in X-Payments, it will be ignored.
saveCard
(supported by API 1.3 and later) 		N string Customer's choice at checkout ("Y" if customer would like to save the card)
cart/kountCustomerUniq
(supported by API 1.6 and later) 		N string, 32 This field is a unique customer identifier in the Kount system, which is send as a UNIQ field.


List of template names in X-Payments 2.1.x (API v1.3):

  • default: A template for the separate page. Used if the payment form is displayed on a separate page of your checkout process (not iframe).
  • fast: Iframe for X-Cart 4 Fast Lane Checkout. Used for X-Cart 4 with the Fast Lane Checkout module. The payment form is displayed at the last step of the checkout process.
  • lite: Iframe for X-Cart 4 One Page Checkout. Used for X-Cart 4 with the One Page Checkout module. The payment form is displayed in the payment section at checkout.
  • magento_iframe: Iframe for Magento. Use this template for Magento and iframe.
  • mobile: Template for mobile devices. Used with the X-Cart Mobile module.
  • xc5: Iframe for X-Cart 5. Used for X-Cart 5 and iframe.

Request example

<api_version>1.6</api_version>
<target>payment</target>
<action>init</action>
<confId>1</confId>
<refId>100001</refId>
<cart>
    <login>customer</login>
    <billingAddress>
        <firstname>John</firstname>
        <lastname>Young</lastname>
        <address>1610 N Main St</address>
        <city>Kissimmee</city>
        <state>FL</state>
        <country>US</country>
        <zipcode>34744</zipcode>
        <company></company>
        <email>user@example.com</email>
        <phone>18005551234</phone>
        <fax></fax>
    </billingAddress>
    <shippingAddress>
        <firstname>John</firstname>
        <lastname>Young</lastname>
        <address>1610 N Main St</address>
        <city>Kissimmee</city>
        <state>FL</state>
        <country>US</country>
        <zipcode>34744</zipcode>
        <company></company>
        <email>user@example.com</email>
        <phone>18005551234</phone>
        <fax></fax>
    </shippingAddress>
    <items type="cell">
        <sku>10022</sku>
        <name>Yoda Plush Backpack</name>
        <price>34.99</price>
        <quantity>1</quantity>
    </items>
    <currency>USD</currency>
    <shippingCost>15.95</shippingCost>
    <taxCost>0</taxCost>
    <discount>0</discount>
    <totalCost>49.98</totalCost>
    <description>Order #100001</description>
    <merchantEmail>merchant@example.com</merchantEmail>
    <forceTransactionType></forceTransactionType>
</cart>
<returnUrl>https://example.com/xcart/payment/cc_xpc.php</returnUrl>;
<callbackUrl>https://example.com/xcart/payment/cc_xpc.php</callbackUrl>;
<language>en</language>

Response specification

Field Type Description
token string,32 Temporary payment token, expires immediately after the customer has submitted the cardholder data form
txnId string,32 A unique payment ID. Is used for all further requests to this payment through the API.

Response example

<data>
  <token>1f4aa2c4d4b2261600b080d5ba5f3957</token>
  <txnId>918799f09b48fd2e45e9946401c30d52</txnId>
  <error></error>
  <error_message></error_message>
  <is_error_message></is_error_message>
  <version>3.0.1</version>
</data>

Response example (error)

<data>
  <error>502</error>
  <error_message>Payment configuration with "100" configuration ID is not initialized</error_message>
  <is_error_message></is_error_message>
</data>

Response example (another error)

<data>
  <error>1503</error>
  <error_message>The city field is missing or incorrect</error_message>
  <is_error_message>1</is_error_message>
</data>


If all is well, and you have got a token and a txnId, the next step is Redirecting a customer to the cardholder data entering page

Retrieved from "https://www.x-payments.com/help/?title=X-Payments:Payment_initialisation_request&oldid=756"