X-Payments:Payment information request

X-Payments API

1. API versions supported
2. Samples
3. API requests
   • Request/Response encryption
   • Encryption and communication
   • cURL as a means of sending requests
   • Data types
4. API Requests from the store to X-Payments
   1. Admin area/X-Payments configuration
      • Test connection request
      • Payment configurations list request
   2. Payment creation (Regular payment and tokenization)
      • Payment initialisation request
      • Charge again transaction request (Tokenization)
   3. Payment information
      • Payment information request
      • Detailed payment and transaction information request
   4. Actions on payments (secondary actions)
      • Capture authorized transaction request
      • Void authorized transaction request
      • Refund captured transaction request
      • Accept potentially fraudulent transaction request
      • Decline potentially fraudulent transaction request
5. Callback requests (web-hooks) from X-Payments to the store
   • Callback request with service payment information
   • Check cart callback request
6. Browser-related
   • Redirecting a customer to the cardholder data entering page
   • Communication between X-Payments iframe and the store
7. Appendix A. Status codes.
   • Payment status codes
   • Operation status codes
8. See also

Request specification

Field	Required	Type	Description
target	Y	string, 128	Must equal payment
action	Y	string, 128	Must equal get_info
txnId	Y	string, 32	Unique payment ID
refresh	N	0 or 1	A flag specifying that the data in X-Payments must be overwritten by the data from the payment gateway. By default - 0
api_version	Y	string	Must equal one of the following: 1.2, 1.3, 1.4, 1.5 etc.

Request example

<api_version>1.7</api_version>
<target>payment</target>
<action>get_info</action>
<txnId>e619c5c346cdc845ba44d00b0e76896a</txnId>

Response specification (API 1.9 and later)

Field	Type	Description
payment	container	Container with the same payment info as returned in response for API 1.8
transactions	container	Transaction list
transactions/date	integer, 11	Transaction date (Unix timestamp)
transactions/action	string, 255	Transaction name
transactions/status	string, 255	Transaction status
transactions/message	string, 65536	Gateway transaction message
transactions/total	string, 32	Transaction amount and currency
transactions/txnid	string, 255	Gateway transaction unique ID
transactions/payment_status	string, 255	The payment status after the transaction
transactions/fields	container	Transaction additional fields list
transactions/fields/name	string, 255	Field name
transactions/fields/name	string, 255	Field value

Response specification (API 1.8 and earlier)

Field	Type	Description
status	integer, 1	Payment status code
message	string, 65536	Human readable message containing the payment status
isFraudStatus	0 or 1	Means that the payment is blocked by the gateway, because the customer has not passed the gateway security check
currency	string, 3	Payment currency code
amount	currency	Payment total
authorized	currency	Authorized payment total
chargedAmount	currency	Charged payment total
capturedAmount	currency	Captured amount of the authorized amount
capturedAmountAvail	currency	Amount that is authorized and can be captured
voidedAmount	currency	Amount that is authorized but voided
voidedAmountAvail	currency	Amount that is authorized and can be voided
refundedAmount	currency	Amount that can be refunded
refundedAmountAvail	currency	Amount that can be refunded
fraudAuthorized	currency	A part of the authorized amount that was blocked by the gateway because the customer had not passed the gateway security check
fraudCharged	currency	A part of the charged amount that was blocked by the gateway because the customer had not passed the gateway security check
authorizeInProgress	currency	A part of the authorized amount that is being handled by the gateway
chargeInProgress	currency	A part of the charged amount that is being handled by the gateway
transactionInProgress	0 or 1	Are there any payment transactions handled by the gateway?
capturedAmountAvailMin	currency	Minimum amount that can be captured from the authorized amount
capturedAmountAvailGateway	currency	Amount that can be captured from the authorized amount through the gateway
capturedAmountAvailMinGateway	currency	Minimum amount that can be captured from the authorized amount through the gateway
voidedAmountAvailGateway	currency	Amount that can be voided from the authorized amount through the gateway
refundedAmountAvailGateway	currency	Amount that can be refunded from the authorized amount through the gateway
txnId	string, 32	Unique payment ID
lastMessage	string, 65536	Last gateway message
error	string, 128	Error code
error_message	string, 65536	Error message
cardValidation (API 1.5 and later)	container	Container for Address validation system (AVS)
cardValidation/avs_z (API 1.5 and later)	string	Flag for AVS ZIP-code ("0" - unknown, "1" - matches, "2" - does not match)
cardValidation/avs_c (API 1.5 and later)	string	Flag for AVS cardholder name ("0" - unknown, "1" - matches, "2" - does not match)
cardValidation/avs_a (API 1.5 and later)	string	Flag for AVS street address ("0" - unknown, "1" - matches, "2" - does not match)
cardValidation/cvv (API 1.5 and later)	string	Flag for CVV/CVV2/CVD ("0" - unknown, "1" - matches, "2" - does not match)
maskedCardData (API 1.5 and later)	container	Container for Credit Card details that are allowed to be stored and displayed by PA-DSS
maskedCardData/first6 (API 1.5 and later)	string	First six digits of the credit card number
maskedCardData/last4 (API 1.5 and later)	string	Last four digits of the credit card number
maskedCardData/type (API 1.5 and later)	string	Credit card type: VISA, MC, AMEX, etc
maskedCardData/expire_month (API 1.5 and later)	string	Credit card expiration month
maskedCardData/expire_year (API 1.5 and later)	string	Credit card expiration year
saveCard	string Y/N	Whether the customer chose to save the card for future orders in the shop
3dsecure (API 1.6 and later)	container	Detailed information about the 3-D Secure check
3dsecure/*	string	Fields with some specific data obtained from the 3-D Secure provider
advInfo	container	Container with information from the payment processor
advInfo/Message	string	Message from the payment processor; contains error from the payment gateway if the transaction is declined
advInfo/txn_id	string	Transaction ID at the payment gateway end
advInfo/AVS	string	Some information about the AVS (code or message)
advInfo/CVV2	string	Some information about the CVV2 check (code or message)
fraudCheckData (API 1.7 and later).	container	Container with some information related to the anti-fraud check.
fraudCheckData/code	string	Internal code indicating the service that performed the anti-fraud check. Can be one of the following: - kount: Kount anti-fraud screening service (API 1.7) - nofraud: NoFraud service (API 1.7) - antifraud (API 1.8) - gateway: internal payment gateway anti-fraud check - xpayments: internal X-Payments anti-fraud check
fraudCheckData/service	string	Human-readable name of the service that performed the anti-fraud check.
fraudCheckData/result	string	Formalized result of the anti-fraud check: - 0: Unknown result - 1: Successful result; transaction passed the anti-fraud check - 2: (API 1.7) Transaction should be reviewed by the merchant, or is still being reviewed by the anti-fraud service, and the exact result will be known later.   OR:      (API 1.8) Transaction should be reviewed by the merchant. - 3: Anti-fraud check was not passed; the transaction is declined. -4: (API 1.8) Transaction is still being reviewed by the anti-fraud service, and the exact result will be known later.
fraudCheckData/transactionId	string	Transaction ID at the side of the service that performed the anti-fraud check.
fraudCheckData/url	string	URL to the transcation in the backend of the service that performed the anti-fraud check.
fraudCheckData/status	string	Status of the anti-fraud check as it was returned by the service which had performed it.
fraudCheckData/score	string	Anti-fraud score as it was calculated by the service which performed the anti-fraud check.
fraudCheckData/rules	string	List of the triggered rules, configured or defined at the side of the service that performed the anti-fraud check. The rules are separated with a line-break.
fraudCheckData/errors	string	List of errors generated when the check was performed. These errors are returned by the service that performed the anti-fraud check. The errors are separated with a line-break.
fraudCheckData/warnings	string	List of warnings generated when the check was performed. These warnings are returned by the service that performed the anti-fraud check. Warnings are separated with a line-break.
fraudCheckData/additionalData (API 1.8)	string	Some additional data related to the anti-fraud check
fraudCheckData/module (API 1.8)	string	Antifraud service module name: Kount, NoFraud, Signifyd

Note: Fields ending in "Gateway" contain amounts that can be used in transactions through the gateway. For example, if a sum of $100 was authorized, and then a capture transaction was emulated for $100, the next refund operation will be available in the emulation mode only. The value of the refundedAmountAvailGateway field will be equal to 0.

Response example

<data>
  <status>4</status>
  <message>Payment is charged</message>
  <isFraudStatus></isFraudStatus>
  <currency>USD</currency>
  <amount>34.99</amount>
  <authorized>0.00</authorized>
  <chargedAmount>34.99</chargedAmount>
  <capturedAmount>0.00</capturedAmount>
  <capturedAmountAvail>0.00</capturedAmountAvail>
  <voidedAmount>0.00</voidedAmount>
  <voidedAmountAvail>0.00</voidedAmountAvail>
  <refundedAmount>0.00</refundedAmount>
  <refundedAmountAvail>34.99</refundedAmountAvail>
  <fraudAuthorized>0.00</fraudAuthorized>
  <fraudCharged>0.00</fraudCharged>
  <authorizeInProgress>0.00</authorizeInProgress>
  <chargeInProgress>0.00</chargeInProgress>
  <advinfo>
    <Message>This transaction was accepted</Message>
    <txn_id>16202</txn_id>
  </advinfo>
  <transactionInProgress></transactionInProgress>
  <capturedAmountAvailMin>0.00</capturedAmountAvailMin>
  <capturedAmountAvailGateway>0.00</capturedAmountAvailGateway>
  <capturedAmountAvailMinGateway>0.00</capturedAmountAvailMinGateway>
  <voidedAmountAvailGateway>0.00</voidedAmountAvailGateway>
  <refundedAmountAvailGateway>34.99</refundedAmountAvailGateway>
  <cardValidation>
    <avs_z>0</avs_z>
    <avs_c>0</avs_c>
    <avs_a>0</avs_a>
    <cvv>0</cvv>
  </cardValidation>
  <maskedCardData>
    <first6>540400</first6>
    <last4>0001</last4>
    <type>MC</type>
    <expire_month>11</expire_month>
    <expire_year>2017</expire_year>
  </maskedCardData>
  <saveCard>N</saveCard>
  <3dsecure>
    <s3d_enrolled>Y</s3d_enrolled>
    <s3d_eci></s3d_eci>
    <s3d_cavv></s3d_cavv>
    <s3d_xid></s3d_xid>
    <s3d_pares></s3d_pares>
    <s3d_error>N</s3d_error>
    <s3d_message></s3d_message>
    <s3d_txnid></s3d_txnid>
    <s3d_authid></s3d_authid>
    <s3d_int_reason></s3d_int_reason>
    <s3d_orderid></s3d_orderid>
    <cavv></cavv>
  </3dsecure>
  <fraudCheckData type="cell">
    <code>kount</code>
    <service>KOUNT Antifraud screening service</service>
    <result>2</result>
    <transactionId>P5YM0KV9W8BH</transactionId>
    <url>https://awc.test.kount.net/workflow/detail.html?id=P5YM0KV9W8BH</url>;
    <status>R</status>
    <score>29</score>
    <rules type="cell">702656 Billing Country not equal to BIN Country (Visa/MC)</rules>
  </fraudCheckData>
  <fraudCheckData type="cell">
    <code>nofraud</code>
    <service>NoFraud service</service>
    <result>1</result>
    <transactionId>waakazdi</transactionId>
    <url>https://portal.nofraud.com/transaction/waakazdi</url>;
    <status>pass</status>
  </fraudCheckData>
  <txnId>e619c5c346cdc845ba44d00b0e76896a</txnId>
  <lastMessage>This transaction was accepted</lastMessage>
  <error></error>
  <error_message></error_message>
  <is_error_message></is_error_message>
  <version>3.0.1</version>
</data>

Response example (with error)

<data>
  <error>508</error>
  <error_message>Payment with txn id "e7f398cee98ec062abac0d2c937da181" is not found</error_message>
  <is_error_message></is_error_message>
</data>