X-Payments:Payment information request

From X-Payments Help
Revision as of 17:01, 15 November 2016 by Dohtur (talk | contribs) (Response specification)
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

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

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)
maskedCardData (API 1.5 and later) container Container for Credit Card details that are allowed to be stored and displayed by PA-DSS
saveCard 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/* Fields with some specific data obtained from the 3-D Secure provider
advInfo container Container with information from the payment processor
advInfo/Message Message from the payment processor; contains error from the payment gateway if the transaction is declined
advInfo/txn_id Transaction ID at the payment gateway end
advInfo/AVS Some information about the AVS (code or message)
advInfo/CVV2 Some information about the CVV2 check (code or message)
fraudCheckData (API 1.7 and later). Container with some information related to the anti-fraud check.
fraudCheckData/code Internal code indicating the service that performed the anti-fraud check. Can be one of the following:
- kount: Kount anti-fraud screening service
- nofraud: NoFraud service
- gateway: internal payment gateway anti-fraud check
- xpayments: internal X-Payments anti-fraud check
fraudCheckData/service Human-readable name of the service that performed the anti-fraud check.
fraudCheckData/result Formalized result of the anti-fraud check:
- 0: Unknown result
- 1: Successful result; transaction passed the anti-fraud check
- 2: 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
- 3: Anti-fraud check was not passed; the transaction is declined.
fraudCheckData/transactionId Transaction ID at the side of the service that performed the anti-fraud check.
fraudCheckData/url URL to the transcation in the backend of the service that performed the anti-fraud check.
fraudCheckData/status Status of the anti-fraud check as it was returned by the service which had performed it.
fraudCheckData/score Anti-fraud score as it was calculated by the service which performed the anti-fraud check.
fraudCheckData/rules 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 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 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/data Some additional data related to the anti-fraud check
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>