X-Payments:Payment information request

From X-Payments Help
Revision as of 15:27, 24 April 2018 by Dohtur (talk | contribs)
Jump to: navigation, search
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

Starting from API version 1.9, the Payment and transaction information request and response are identical to the Detailed payment information request and response.

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>
Retrieved from "https://www.x-payments.com/help/?title=X-Payments:Payment_information_request&oldid=1499"