Skip to main content

XPayments Code

Before initiating the payment processing, it is necessary to obtain a token from the user's credit card. To do this, the user needs to be presented with a widget. Then, the obtained token should be sent to the init action.

widget_data​

To display the widget, we need to retrieve the data for it using the generate_widget_data request.

PATCH api/storefront/payment/{cart-id}/payment/{public-txn-id}

{
  "action": "generate_widget_data"
}

Response example:

{
    "id": "000012-UUSW",
    "status": "I",
    "value": 31.44,
    "type": "sale",
    "data": [],
    "backendTransactions": [],
    "processor": "XPay\\XPaymentsCloud\\Model\\Payment\\Processor\\XPaymentsCloud",
    "actionData": [
        {
            "name": "widgetConfig",
            "value": "{\"account\":\"bdab109195203204ngrokfree\",\"widgetKey\":\"g0SM0rSoV3KYJ0ZeuUOXG3mPgmw7Qts6\",\"showSaveCard\":true,\"customerId\":\"ofUHcmzsERQJVwOOGqO74jYRnLf3Fn8Z\",\"order\":{\"total\":31.44,\"currency\":\"USD\",\"tokenizeCard\":false},\"company\":{\"name\":\"*Your company name*\",\"countryCode\":\"US\"},\"language\":\"en\"}"
        }
    ],
    "actionMetaData": []
}

The data from the field widgetConfig needs to be used for generating the widget.

Testing page:

<html>
<body>

<div>
    <textarea></textarea>
</div>

<div id="xpayments-iframe-container"></div>
<form id="form" action="return.php">
    <input type="submit"/>
</form>

<div id="result">

</div>

<script src="assets/web/common/modules/XPay/XPaymentsCloud/lib/js/widget.js"></script>

<script type="application/javascript">

    let widget = new XPaymentsWidget()

    document.getElementsByTagName('textarea')[0].onchange = function () {
        widget.destroy();

        document.getElementById("result").innerText = '';

        if (!this.value) {
            return;
        }

        const data = JSON.parse(this.value);

        let widgetConfig = null;
        for (let d of data.actionData) {
            if (d.name === 'widgetConfig') {
                widgetConfig = JSON.parse(d.value);
            }
        }

        widgetConfig.container = '#xpayments-iframe-container';
        widgetConfig.form = 'form';
        widgetConfig.debug = true;

        widget.init(widgetConfig);
        widget.load();

        widget.on('success', function (params) {
            document.getElementById("result").innerText = JSON.stringify(params);
        })
    }

    document.getElementById("form").submit = function () {
        window.event.preventDefault();
    }

</script>
</body>
</html>

In addition, the following fields are added to widgetConfig: container (the location to render the widget) and form (the form associated with the widget). If you enter credit card data in the widget and then try to submit the form, a request will be made to XPayments, and as a result, a token will be received and displayed on the page. This token needs to be used in the init request.

init​

In the init request, the token obtained from the widget needs to be supplied. Additionally, in actionMetaData, the success_url needs to be specified; it will be employed for 3D Secure verification if required.

PATCH api/storefront/payment/{cart-id}/payment/{public-txn-id}

{
  "action": "init",
  "actionData": [
    {
        "name": "token",
        "value": "pNdjTogmnICPuShIIr9XdXKxNmIEwCmj"
    }
  ],
  "actionMetaData": [
      {
          "name": "success_url",
          "value": "http://xcart.test/payment_return/{cart-id}/{public-txn-id}"
      }
  ]
}

There can be two possible outcomes:

  1. Payment result: In the response, the transaction status will be either S (successful) or F (failed). In the first case, an order can be created, while in the second case, an error should be reported. Example response:
{
    "id": "000012-UUSW",
    "status": "S",
    "value": 31.44,
    "type": "auth",
    "data": [
        {
            "name": "xpaymentsPaymentId",
            "value": "07be6bf4cfeb90d368c84f81ff190c2a"
        },
        {
            "name": "xpaymentsMessage",
            "value": "This transaction was accepted"
        },
        {
            "name": "xpaymentsCardNumber",
            "value": "411111******1111"
        },
        {
            "name": "xpaymentsCardExpirationDate",
            "value": "03/2032"
        },
        {
            "name": "xpaymentsCardType",
            "value": "VISA"
        }
    ],
    "backendTransactions": [
        {
            "status": "S",
            "value": 31.44,
            "type": "auth",
            "data": [
                {
                    "name": "xpaymentsMessage",
                    "value": "This transaction was accepted"
                }
            ]
        }
    ],
    "processor": "XPay\\XPaymentsCloud\\Model\\Payment\\Processor\\XPaymentsCloud",
    "actionData": [],
    "actionMetaData": []
}
  1. 3D Secure verification: In this case, in the actionMetaData field, the response will contain a URL for redirection. The return handling is similar to that of web-based payment methods.
{
    "id": "000015-G3L7",
    "status": "P",
    "value": 9.04,
    "type": "sale",
    "data": [
        {
            "name": "xpaymentsPaymentId",
            "value": "ebd151ceca8aa315c86697b56763c808"
        }
    ],
    "backendTransactions": [],
    "processor": "XPay\\XPaymentsCloud\\Model\\Payment\\Processor\\XPaymentsCloud",
    "actionData": [],
    "actionMetaData": [
        {
            "name": "url",
            "value": "https://bdab109195203204ngrokfree.xpayments.com/payment.php?target=secure3d&token=ibZBwfJ7q8dTVAdbxTYGCEBzryECgDry"
        },
        {
            "name": "method",
            "value": "get"
        },
        {
            "name": "xpaymentsBuyWithWallet",
            "value": ""
        },
        {
            "name": "xpaymentsWalletId",
            "value": ""
        }
    ]
}

It is necessary to redirect the user to the URL specified in actionMetaData.

The return will occur to the URL specified in the init request.

Then, it will be required to make a pay request.

pay​

If a URL was returned as a result of the init request, after the return, it is necessary to make a pay request.

PATCH api/storefront/payment/{cart-id}/payment/{public-txn-id}

{
  "action": "pay"
}

Result example:

{
    "id": "000014-T7KW",
    "status": "S",
    "value": 9.04,
    "type": "sale",
    "data": [
        {
            "name": "xpaymentsPaymentId",
            "value": "3ce9b7dac8e920e7b212430303f06715"
        },
        {
            "name": "xpaymentsMessage",
            "value": "COMPLETED"
        },
        {
            "name": "xpaymentsDetails.avsCode",
            "value": "Y"
        },
        {
            "name": "xpaymentsDetails.cvvCode",
            "value": "S"
        },
        {
            "name": "xpaymentsDetails.responseCode",
            "value": "0000"
        },
        {
            "name": "xpaymentsDetails.sellerProtection",
            "value": "NOT_ELIGIBLE"
        },
        {
            "name": "xpaymentsAvsResult",
            "value": "Y"
        },
        {
            "name": "xpaymentsCvvResult",
            "value": "S"
        },
        {
            "name": "xpaymentsCardNumber",
            "value": "486871******7704"
        },
        {
            "name": "xpaymentsCardExpirationDate",
            "value": "01/2025"
        },
        {
            "name": "xpaymentsCardType",
            "value": "VISA"
        },
        {
            "name": "xpaymentsCardholder",
            "value": "Test Test"
        }
    ],
    "backendTransactions": [
        {
            "status": "S",
            "value": 9.04,
            "type": "capture",
            "data": [
                {
                    "name": "xpaymentsMessage",
                    "value": "COMPLETED"
                }
            ]
        }
    ],
    "processor": "XPay\\XPaymentsCloud\\Model\\Payment\\Processor\\XPaymentsCloud",
    "actionData": [],
    "actionMetaData": []
}