1. Credit Card Transaction (Customer-In-Transaction)
The create PI API and SDK will be used to collect a payment.
a. Create PI API
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": {
"_id": "xpay_cus_6c7512fab0e8f8fc194", // if customer is already created
"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
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.
If customer already exists and then customer._id is passed then token is linked to that customer for future payments.
metadata: {
"reason": "token"
},
"customer": {
"_id": "xpay_cus_6c7512fab0e8f8fc194", // pass, if customer is already created
"name": "John Doe",
"email": "john@doe.com",
"phone": "03001234567"
},3. Recurring Payments using saved cards/tokens
- To make a tokenized payment call, the following API to be used.
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
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
- Get Token Details
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
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.
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:
metadata: {
"rule_attribute": "bill_payment"
}XPay evaluates this value against the configured routing rules and applies the matching rule during payment processing.
8. Bin Discounts
XPay now supports BIN discounts, allowing merchants to offer card BIN-based promotions during payment processing. Eligible BIN discounts are validated and applied through XPay based on the configured discount rules, enabling customers to receive applicable discounts at checkout
When creating a payment intent, pass the discount flag value true as a boolean in the main payload using the key:
"apply_bin_discount": trueXPay evaluates this value against the configured bin configurations and applies the matching config during payment processing.
9. Bin Discount with Taxes
BIN Discount now supports tax calculations. During payment processing, tax information can be passed to XPay, which will calculate and apply the tax amount after the BIN discount has been applied. This ensures that taxes are calculated on the discounted amount rather than the original transaction amount if the tax type is exclusive.
When creating a payment intent, pass the tax information as a object in the main payload using the key:
"apply_bin_discount": true
"tax_info": {
"rate": 8,
"additional_charges": 1000, // optional
"type": "exclusive" // exclusive
}XPay calculates the taxes and apply after discounts against the passed config during payment processing.
10. Card Validation with Bin Applied
As part of the Bin Discounts, the platform will support merchant-managed BIN discounts. Pass the applied_bin during PI create, the system will use this value to verify the card during payment processing.
When creating a payment intent, pass the bin number as a string in the main payload using the key:
"applied_bin": "123456" // 6 digits or 8 digitsXPay verify the card number with applied bin during payment processing.