X-Payments:How It Works

X-Payments user manual

1. X-Payments:General information
   • How It Works
   • Key features
2. What's New
   • What's New in X-Payments 3.1
   • What's New in X-Payments 3.0
3. System requirements
   • System requirements for X-Payments 3
   • System requirements for X-Payments 2.2
4. Installation
   • Installing X-Payments
   • Setting up file permissions for X-Payments
   • Getting started with X-Payments
5. Two-factor user authentication
   • Two-factor authentication (X-Payments 3)
   • Managing PIN codes (X-Payments 2.2 and earlier)
6. Configuring X-Payments
   • General settings
   • Online stores
   • Payment configurations
   • Encryption keys
   • 3D-Secure settings
   • KOUNT Antifraud screening
   • NoFraud fraud prevention
   • Signifyd fraud protection and chargeback prevention
7. Managing users
8. Customizing the interface
   • Customizing the interface (X-Payments 3)
   • Customizing the interface (X-Payments 2.2 and earlier)
9. Managing payments
10. Unistalling X-Payments
11. Upgrading
12. Moving X-Payments from one host to another
13. Viewing X-Payments logs
14. FAQ
15. Troubleshooting
16. Glossary
17. Supported payment gateways
    • Payment gateways supported by X-Payments 3.1
    • Payment gateways supported by X-Payments 3.0
    • Payment gateways supported by X-Payments 2.2
18. Popular Payment Methods Configuration Instructions
    • PayPal Payments Pro (PayPal API), PayPal Payments Pro (Payflow API), Payflow Pro
    • PayPal REST API
    • First Data Payeezy Gateway (ex- Global Gateway e4)
    • CyberSource - SOAP toolkit API

X-Payments flow via diagram

API Call

1) Store initiates an API call to X-Payments to create a payment (Created payments can be viewed on the 'Payments' page in X-Payments back end). At this step store sends to X-Payments all information about the customer (billing and shipping address) and the products being purchased (product quantities and cost). In addition to that, store instructs X-Payments as to which payment configuration should be used.

2) X-Payments validates this initial request from the store: checks whether the requested payment configuration is active, whether the payment currency passed on to X-Payments by the store matches the currency specified in the respective payment configuration in X-Payments, and makes some other internal checks; for instance, a check is conducted to ensure that the template files for the page where customers enter cardholder data have not been modified without approval by X-Payments admin. If everything is fine, X-Payments returns a payment "token" to the store (The token serves as a temporary identifier of the payment in X-Payments; it is generated as a result of the API call and is removed after the customer is redirected back to the store when the payment is completed). If a problem is detected, no token is sent to the store, and an internal error is generated in X-Payments. Detailed information about such errors can be found in the X-Payments and X-Cart logs:

• X-Payments: See the <xpay-dir>/var/log/api/YYYY-MM-DD/ directory
• X-Cart: See the <xcart-dir>/var/log/x-errors_xpay_connector-YYMMDD.php file

Payment

3) Customer is redirected to the X-Payments secure page where the form for entering credit card details is located. If the iframe is used, this redirect is not visible to customer, as the form is embedded into the checkout page.

4) Customer enters credit card details and submits the form. These details are sent to the payment gateway along with other data previously received by X-Payments (address details, products being purchased, etc).

5) Payment gateway operates with the bank to charge the card (or authorize the funds in case of an "auth only" transaction) and sends back to X-Payments the information about the transaction.

The log of communication between X-Payments and the payment gateway can be found in the <xpay-dir>/var/log/payment/YYYY-MM-DD/ directory.

Callback from gateway (PayPal) to X-Payments

6) Some payment gateways also send back to X-Payments an additional "callback" request. This "callback" request provides detailed information about the transaction and also helps to validate/confirm the transaction. Currently only PayPal Payments PRO operates in X-Payments in such a way. As an additional protection, X-Payments allows you to specify the IP addresses from which the gateway's callback requests can be received. Provided with a list of trusted Call-back IPs for PayPal, X-Payments will only accept "callback" requests coming from PayPal's server and ignore all other requests coming from anywhere else, should such requests be made. The list of PayPal's IP addresses can be found here: https://ppmts.custhelp.com/app/answers/detail/a_id/92 If you wish to use this additional protection, you can enter the necessary IP addresses into PayPal payment configuration settings in X-Payments back end.

The log of payment gateway callback request processing is saved to the <xpay-dir>/var/log/callback/YYYY-MM-DD/ directory.

Invoice

7) Customer is redirected back to the store where the Invoice page is displayed. If the transaction is declined by the payment gateway for some reason, the error page is displayed. Additional information about the reasons of the transaction being declined can be found in the X-Payments admin back end on the 'Payment details' page.

Callback from X-Payments to the store

8) Detailed information about the payment is sent to the store via a "callback" request. The same functionality ("callback" requests) is used to notify the store if the payment has been changed via X-Payments admin back end; for example, if a secondary transaction took place ('Capture' or 'Void' for an authorized transaction, 'Refund' for a charge).

X-Cart allows additional protection for callback requests from X-Payments: thus you can specify the IP addresses for X-Payments callbacks in X-Payments connector module settings: http://help.x-cart.com/index.php?title=X-Cart:X-Payments_Connector. X-Cart will accept only those callback requests that come from the specified IP addresses, others will be ignored.

Important: On some server configurations the IP address from which the callback request comes may not match the IP of the server where X-Payments is installed as illustrated below:

Even if X-Payments is installed on the 172.18.0.3 IP address, and is accessible via web by it, the outgoing request is received from the "proxy" of 172.18.0.0. So, it is recommended to verify the IP address for outgoing HTTPS connections with your hosting provider.

Note: If you use the X-Payments Hosted plan, you should use IP address 98.142.211.162 if your X-Payments account is v1.x or v2.x based or 104.200.146.25 if v3.x based.

The log of the X-Payments callback requests processing is saved to the following locations:

• X-Cart: See the <xcart-dir>/var/log/x-errors_xpay_connector-YYMMDD.php file if any error occurred.
• X-Payments: See the <xpay-dir>/var/log/payment/YYYY-MM-DD/ directory for the initial Authorize or Sale (Authorize and Capture at the same time or Auto settle) transaction and <xpay-dir>/var/log/admin/YYYY-MM-DD/ directory for the secondary Capture, Void or Refund transaction.