Difference between revisions of "X-Payments:Charge again transaction request (Tokenization)"

From X-Payments Help
Jump to: navigation, search
(Created page with "===Request specification=== {| cellspacing="0" cellpadding="2" border="1" | colspan="1" | '''Field''' | colspan="1" | '''Required''' | colspan="1" | '''Type''' | colspan="1"...")
 
m
 
(7 intermediate revisions by the same user not shown)
Line 1: Line 1:
 +
<noinclude>{{XP_API_TOC}}</noinclude>
 +
Detailed information about tokenization can be found here: [[X-Payments:Tokenization_and_Re-Use_of_Saved_Credit_Cards_(X-Payments_2.x_and_later)| Tokenization and Re-Use of Saved Credit Cards (X-Payments 2.x and later)]]
 +
 +
In general, the key features are:
 +
:* The credit card information itself is not stored in any way (neither in X-Payments, nor in the connected shopping cart).
 +
:* X-Payments stores a tokenized credit card internally. This is gateway-specific information, and, in some cases, it is not available to the connected shopping cart.
 +
:* The connected shopping cart can execute payment by token using txnId - a unique ID of the original payment which was processed using the real credit card details.
 +
 +
To be able to execute such a request, the following conditions must be met:
 +
:* The payment gateway supports the tokenization feature.
 +
:* Tokenization is enabled in the payment configuration in X-Payments (provided that there is such a setting). For example, this is true for Authorize.Net, NetBilling, Beanstream, etc.
 +
:* The buyer has chosen to save their credit card at checkout, or the card has been saved automatically for subscription/recurring payments.
 +
 
===Request specification===
 
===Request specification===
  
Line 41: Line 54:
 
| colspan="1" | string, 128
 
| colspan="1" | string, 128
 
| colspan="1" | Order ID in the online store
 
| colspan="1" | Order ID in the online store
 +
|-
 +
| colspan="1" | callbackUrl
 +
| colspan="1" | Y
 +
| colspan="1" | string
 +
| colspan="1" |  URL to which X-Payments sends background requests with service information
 +
|-
 +
| colspan="1" | cart
 +
| colspan="1" | N
 +
| colspan="1" | container
 +
| colspan="1" | A container with addresses, purchased items, etc. See: [[X-Payments:Payment_initialisation_request | Payment initialization request]]
 
|}
 
|}
  
Line 46: Line 69:
  
 
<pre>
 
<pre>
<txnId>e7f398cee98ec062abac0d2c937da181</txnId>
+
<api_version>1.7</api_version>
<amount>50.00</amount>
+
<target>payment</target>
 +
<action>recharge</action>
 +
<amount>12.99</amount>
 
<description>Recurring payment for the new issue of Playboy</description>
 
<description>Recurring payment for the new issue of Playboy</description>
 +
<refId>order_1234</refId>
 +
<callbackUrl>https://example.com/xcart/payment/cc_xpc.php</callbackUrl>;
 +
<txnId>143079cd2eec1645e332965f374f832a</txnId>
 +
</pre>
 +
 +
===Request example with detailed cart information===
 +
 +
<pre>
 +
<api_version>1.7</api_version>
 
<target>payment</target>
 
<target>payment</target>
 
<action>recharge</action>
 
<action>recharge</action>
<api_version>1.2</api_version>
+
<amount>49.98</amount>
 +
<description>Recurring payment for the new issue of Playboy</description>
 +
<refId>order_1234</refId>
 +
<callbackUrl>https://example.com/xcart/payment/cc_xpc.php</callbackUrl>;
 +
<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>Playboy</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>Recurring payment for the new issue of Playboy</description>
 +
    <merchantEmail>merchant@example.com</merchantEmail>
 +
    <forceTransactionType></forceTransactionType>
 +
</cart>
 +
<txnId>143079cd2eec1645e332965f374f832a</txnId>
 
</pre>
 
</pre>
  
Line 88: Line 169:
 
| colspan="1" | string
 
| colspan="1" | string
 
| colspan="1" |
 
| colspan="1" |
 +
|-
 +
| colspan="1" | payment
 +
| colspan="1" | container
 +
| colspan="1" | (Only API 1.9) Container with [[X-Payments:Payment_information_request#PaymentInfoSpecification | Payment information]]
 
|}
 
|}
 
<br /><br />
 
<br /><br />
 +
 +
===Response example===
 +
 +
<pre>
 +
<data>
 +
  <status>4</status>
 +
  <transaction_id>9f0811ad772a86aafb104d03afcb10ec</transaction_id>
 +
  <error></error>
 +
  <error_message></error_message>
 +
  <is_error_message></is_error_message>
 +
  <version>3.0.2</version>
 +
</data>
 +
</pre>

Latest revision as of 15:59, 24 April 2018

X-Payments API
  1. API versions supported
  2. Samples
  3. API requests
  4. API Requests from the store to X-Payments
    1. Admin area/X-Payments configuration
    2. Payment creation (Regular payment and tokenization)
    3. Payment information
    4. Actions on payments (secondary actions)
  5. Callback requests (web-hooks) from X-Payments to the store
  6. Browser-related
  7. Appendix A. Status codes.
  8. See also

Detailed information about tokenization can be found here: Tokenization and Re-Use of Saved Credit Cards (X-Payments 2.x and later)

In general, the key features are:

  • The credit card information itself is not stored in any way (neither in X-Payments, nor in the connected shopping cart).
  • X-Payments stores a tokenized credit card internally. This is gateway-specific information, and, in some cases, it is not available to the connected shopping cart.
  • The connected shopping cart can execute payment by token using txnId - a unique ID of the original payment which was processed using the real credit card details.

To be able to execute such a request, the following conditions must be met:

  • The payment gateway supports the tokenization feature.
  • Tokenization is enabled in the payment configuration in X-Payments (provided that there is such a setting). For example, this is true for Authorize.Net, NetBilling, Beanstream, etc.
  • The buyer has chosen to save their credit card at checkout, or the card has been saved automatically for subscription/recurring payments.

Request specification

Field Required Type Description
target Y string, 128 Must equal payment
action Y string, 128 Must equal recharge
txnId Y string, 32 Unique payment ID which references the token that will be used to identify the payment on the side of the payment gateway
amount Y currency The amount for which the "saved" card is to be charged using the token from the previous successful transaction
description Y string Description of the transaction
api_version Y string Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.
refId (supported by API 1.4 and later) N string, 128 Order ID in the online store
callbackUrl Y string URL to which X-Payments sends background requests with service information
cart N container A container with addresses, purchased items, etc. See: Payment initialization request

Request example

<api_version>1.7</api_version>
<target>payment</target>
<action>recharge</action>
<amount>12.99</amount>
<description>Recurring payment for the new issue of Playboy</description>
<refId>order_1234</refId>
<callbackUrl>https://example.com/xcart/payment/cc_xpc.php</callbackUrl>;
<txnId>143079cd2eec1645e332965f374f832a</txnId>

Request example with detailed cart information

<api_version>1.7</api_version>
<target>payment</target>
<action>recharge</action>
<amount>49.98</amount>
<description>Recurring payment for the new issue of Playboy</description>
<refId>order_1234</refId>
<callbackUrl>https://example.com/xcart/payment/cc_xpc.php</callbackUrl>;
<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>Playboy</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>Recurring payment for the new issue of Playboy</description>
    <merchantEmail>merchant@example.com</merchantEmail>
    <forceTransactionType></forceTransactionType>
</cart>
<txnId>143079cd2eec1645e332965f374f832a</txnId>

Response specification

Field Type Description
status integer, 1 Operation status code
data array
data[status] integer Status of the new payment (See Payment status codes)
data[transaction_id] string ID of the created payment for further references (capture/void/refund etc)
data[error] string
data[error_message] string
data[is_error_message] string
payment container (Only API 1.9) Container with Payment information



Response example

<data>
  <status>4</status>
  <transaction_id>9f0811ad772a86aafb104d03afcb10ec</transaction_id>
  <error></error>
  <error_message></error_message>
  <is_error_message></is_error_message>
  <version>3.0.2</version>
</data>