XPay Payment Usecases

1. Credit Card Transaction (Customer-In-Transaction)

The create PI API and SDK will be used to collect a payment.

a. Create PI API

javascript

curl --location 'https://xstak-pay-stg.xstak.com/public/v1/payment/intent' \
--header 'x-api-key: {{x-api-key}}' \
--header 'x-account-id: {{x-account-id}}' \
--header 'x-signature: {{x-signature}}' \
--header 'Content-Type: application/json' \
--data '{
    "amount": 10,
    "currency": "PKR",
    "payment_method_types": "card",
    "customer": {
        "name": "",
        "email": "",
        "phone": ""
    },
    "shipping": {
        "address1": "",
        "city": "",
        "country": "", // complete country name
        "province": "",
        "zip": ""
    },
    "metadata": {
        "order_reference": ""
    },
    "gateway_instance_id": "" // get from gateways in the settings
}'

b. XPay SDK

javascript

import React, { useState } from 'react';
import { PaymentElement, useXpay } from '@xstak/xpay-element';
export const Payment = () => {
    const options = {
        override: true,
        fields: {
          creditCard: {
            placeholder: "4234 1234 1234 1234",
            label: "Enter your credit card",
          },
          exp: {
            placeholder: "Exp. Date",
          },
        },
        style: {
          ".input": {
            "border": "1px solid black",
            "border-radius": "15px"
           },
          ".invalid": {},
          ".label": {
            "font-size": "18px"
           },
          ":focus": {},
          ":hover": {},
          "::placeholder": {},
          "::selection": {},
        },
      };
    const xpay = useXpay();
    const pay = async() => { 
const { message, error } = await xpay.confirmPayment("card", payment_intent.client_secret, customer = {name: ‘Dane Joe}, payment_intent.encryptionKey);
    }
    return(
        <>
        <PaymentElement options={options} onReady={(event) => {
            console.log("ready event", event);
          }} />
        <Button type="primary" onClick={pay}>
          Pay Now
        </Button>
        </>
    )
}

2. Create a token (Customer-in-Transaction)

The payment API flow integration remains unchanged, just reason: “token” to be added in metadata object of Create PI API payload.

javascript

metadata: {
	"reason": "token"
}

3. Recurring Payments using saved cards/tokens

To make a tokenized payment call, the following API to be used.

javascript

curl --location -g '{{base_url}}/public/v1/payment/intent/tokenized/payment' \
--header 'x-api-key: {{x-api-key}}' \
--header 'x-account-id: {{x-account-id}}' \
--header 'x-signature: {{x-signature}}' \
--header 'Content-Type: application/json' \
--data-raw '{
	"amount": 10,
	"currency": "PKR",
	"payment_method_types": "token",
	"customer": {
    	"name": "Guest User",
    	"email": "guest@gmail.com",
    	"phone":"03415555555"
	},
	"shipping": {
    	"address1": "abc",
    	"city": "Islamabad",
    	"country": "Pakistan",
    	"phone": "03415555555",
    	"zip": "12345",
    	"shipping_method": "Standard"
	},
	"metadata": {
    	"order_reference": "XX-Order-1"
	},
	"token":"xpay_token_a5d1e0ef0d22982992a"
}'

b. For XPay managed recurring payments, Please refer to subscriptions for this.

4. Refund

XPay supports refunding a captured transaction via API and XAP.

a. API

javascript

curl --location 'https://xstak-pay-stg.xstak.com/public/v1/refund' \
--header 'x-api-key: {{x-api-key-sk}}' \
--header 'x-account-id: {{x-account-id}}' \
--header 'x-signature: {{signature}}' \
--header 'Content-Type: application/json' \
--data '{
    "payment_intent_id": "",
    "refunded_amount": "2",
    "reason": "Customer refunded order",
    "metadata": {
        "order_id": "ref_order_number-911"
    }
}'

5. Manage Saved Cards/tokens

💡

The merchant will save token id, at least, and other essential data at their end and show when user want to pay with the token.

Get Token Details

javascript

curl --location -g '{{base_url}}/public/v1/payment/intent/tokenized/payment' \
--header 'x-api-key: {{x-api-key}}' \
--header 'x-account-id: {{x-account-id}}' \
--header 'x-signature: {{x-signature}}' \
--header 'Content-Type: application/json' \
--data-raw '{
	"amount": 10,
	"currency": "PKR",
	"payment_method_types": "token",
	"customer": {
    	"name": "Guest User",
    	"email": "guest@gmail.com",
    	"phone":"03415555555"
	},
	"shipping": {
    	"address1": "abc",
    	"city": "Islamabad",
    	"country": "Pakistan",
    	"phone": "03415555555",
    	"zip": "12345",
    	"shipping_method": "Standard"
	},
	"metadata": {
    	"order_reference": "XX-Order-1"
	},
	"token":"xpay_token_a5d1e0ef0d22982992a"
}'

Delete Token

javascript

curl --location -g --request DELETE '{{base_url}}/public/v1/token/xpay_token_a5d1e0ef0d22982992a'

6. BIN Discounts via SDK

The developer will add the following SDK method in the code and attach a callback function to listen to the binDiscount event.

javascript

xpay.on('binDiscount', callback)

7. Routing Rules with Custom Attributes

XPay allows you to create routing rules based on custom rule attributes. A single routing rule can contain multiple custom attributes, enabling flexible and precise transaction routing. Routing rules can be created on the XPay Merchant Portal.

When creating a payment intent, include the custom attribute value as a string in the metadata object using the key:

javascript

metadata: {
  "rule_attribute": "bill_payment"
}

XPay evaluates this value against the configured routing rules and applies the matching rule during payment processing.

XPay PI Statuses