Frequently Asked Questions (FAQ) – Retrieving Public Key & HMAC Secret Key

  1. How can I retrieve my Public Key and HMAC Secret Key?

To retrieve your Public Key and HMAC Secret Key, follow these steps:

  1. Log in to the portal.

  2. Navigate to Settings from the dashboard.

  3. Select Store Info:

  4. Click on Key Details:

  5. Retrieve Keys and Secrets:

image-20250130-102154.png

  1. Where can I find the Key Details section?

The Key Details section is available under Settings > Store Info. Click on Key Details to access your required keys.

  1. What is the Public Key used for?

The Public Key is used for encryption and secure communication between your application and the portal.

  1. What is the API HMAC Secret Key?

The API HMAC Secret Key is used to authenticate API requests, ensuring the integrity and security of the transmitted data.

  1. What is the Webhook HMAC Secret Key?

The Webhook HMAC Secret Key is used to validate webhook notifications received from the system, confirming that they originate from an authorized source.

  1. Can I regenerate my keys?

Yes, in some cases, you may have the option to regenerate keys from the Key Details section. However, be cautious, as regenerating keys may require updating your integrations accordingly. If you update the keys on the XPay portal you need to make sure to update on the app environment (where they integrating our SDK).

  1. Who should have access to these keys?

These keys should be accessed only by authorized personnel, as they are critical for secure system integration and communication.

Frequently Asked Questions (FAQ) - keyValue and encpKeyValue in confirmPayment() Method

1. What are keyValue and encpKeyValue parameters in the confirmPayment() method?

keyValue and encpKeyValue are dynamic values required to confirm a payment using the confirmPayment() method. These values are unique for each transaction and are necessary for securely processing payments.

2. How can we obtain keyValue and encpKeyValue?

These values should be fetched dynamically through an API call. They are not static keys that can be retrieved from the dashboard.

3. Which API provides these values?

The relevant API call to obtain keyValue and encpKeyValue is available in the XPay API documentation. Kindly refer to the API Docs: Postman API Documentation.

4. Can we store keyValue and encpKeyValue for reuse?

No, these values are dynamically generated for each transaction and should be fetched in real time when confirming payment.

5. How does the payment flow work?

For a better understanding of the payment flow, you can refer to the XPay public demo repository: GitHub Repository.

6. What happens if keyValue and encpKeyValue are not correctly fetched?

The payment confirmation process will fail if these values are not correctly retrieved. Ensure that the correct API call is made before invoking confirmPayment().

FAQ: Generating X-Signature for Payment Intents

  1. What is the X-signature in the API request?

The X-Signature is a SHA-256 HMAC signature used for verifying the authenticity of API requests for payment intents. It ensures that the request is coming from a trusted source and has not been tampered with.

  1. How is the X-Signature generated?

The X-signature is generated using a combination of the HMAC secret key and SHA-256 hashing algorithm. The specific process involves hashing the request payload or required parameters using the secret key.

  1. What server-side languages can be used to generate the X-Signature?

You can generate the X-Signature using any server-side language that supports HMAC with SHA-256. Examples include:

  1. Sample X-Signature Generation in Node.js

Here is a sample implementation in Node.js:

const crypto = require('crypto');
function generateXSignature(secret, data) {
    return crypto.createHmac('sha256', secret)
                 .update(data)
                 .digest('hex');
}
const secretKey = 'your_secret_key';
const requestData = 'your_request_payload';
const xSignature = generateXSignature(secretKey, requestData);
console.log('X-Signature:', xSignature);

  1. Where can I find a reference implementation?

A reference implementation for generating the X-Signature is available in the server.js file of the sample repository provided by the API documentation. https://github.com/XStakCommerce/xpay-element-public-demo/tree/stage

  1. What should I do if I encounter errors?

If you receive errors while generating the X-Signature, check the following:

  1. Who should I contact for support?

If you continue to face issues, please reach out to the support team with details of your implementation, including:

For further assistance, refer to the API documentation or the sample repository for additional guidance.

 

FAQ: Invalid Signature Key in Headers

Issue:

When making an API request, the following error is returned:

{
    "success": false,
    "responseStatus": "BAD_REQUEST",
    "message": "Invalid signature key in headers",
    "error": {}
}

Possible Causes and Solutions:

1. Incorrect Signature Calculation

2. Mismatched API Payload and Signature Payload

3. Incorrect HMAC Secret Key

4. Incorrect Header Formatting

5. Missing or Incorrect gateway_instance_id

Correct Example of API Request Payload:

{
    "amount": 10,
    "currency": "PKR",
    "payment_method_types": "card",
    "customer": {
        "name": "John Doe",
        "email": "john.doe@example.com",
        "phone": "+920123456789"
    },
    "shipping": {
        "address1": "123 Street",
        "city": "Lahore",
        "country": "Pakistan",
        "province": "Punjab",
        "zip": "54000"
    },
    "metadata": {
        "order_reference": "ORDER12345"
    },
    "gateway_instance_id": "your_gateway_instance_id"
}

Final Checks Before Sending Request:

  1. Verify Payload: The payload used for signing must be the same as the request payload.

  2. Correct Secret Key: Use the exact API HMAC Secret.

  3. Check Headers: Ensure the signature is correctly formatted.

  4. Gateway Instance ID: Confirm it is correctly retrieved.

  5. Signature Algorithm: Use HMAC-SHA256 for signing.

If the issue persists, double-check the implementation of the signing process and compare it with the API documentation.

Frequently Asked Questions (FAQ) - XPay Android SDK Integration

1. How do I create a Payment Intent?

To create a Payment Intent, send a request to the following API endpoint:

POST https://xstak-pay-stg.xstak.com/public/v1/payment/intent

Request Format (Raw JSON):

{
    "amount": 10,
    "currency": "PKR",
    "payment_method_types": "card",
    "customer": {
        "name": "John",
        "email": "john@gmail.com",
        "phone": "+923095601232"
    },
    "shipping": {
        "address1": "48 LOO Road",
        "city": "Lahore",
        "country": "Pakistan",
        "province": "Punjab",
        "zip": "54000"
    },
    "metadata": {
        "order_reference": ""
    },
    "gateway_instance_id": "102040" // Retrieve from gateways in settings
}

2. What response should I expect from a successful Payment Intent creation?

{
    "success": true,
    "responseStatus": "OK",
    "message": "Request processed successfully.",
    "data": {
        "_id": "xpay_pi_<payment_intent_id>",
        "pi_client_secret": "xpay_pi_<payment_intent_id>_cs_<client_secret>",
        "created_at": "<timestamp>",
        "amount": 10,
        "currency": "PKR"
    }
}

3. Why am I getting "Invalid Payment Intent" when confirming the payment?

Possible Causes:

4. How do I confirm a Payment Intent in the XPay Android SDK?

Use the following method in your Android application:

paymentElement.confirmPayment(
    "Test User",
    PI_SECRET_ID,
    ENCRYPTED_KEY_ID,
    this::paymentResponse
);

private Unit paymentResponse(String response) {
    Log.e("Payment Response Data", response);
    return Unit.INSTANCE;
}

5. What are the correct values to pass in the SDK?

private static final String PI_SECRET_ID = "xpay_pi_<id>_cs_<secret>";
private static final String ENCRYPTED_KEY_ID = "-----BEGIN PUBLIC KEY-----\n<your_public_key>\n-----END PUBLIC KEY-----\n";

6. What dependencies should I include for the XPay SDK?

For staging:

implementation ("com.github.XStakCommerce:XPay-Element-Android-Native-SDK:stage-1.0.0")

Ensure your Gradle settings include the required repositories.

7. What if I still encounter issues?

XPay Swift SDK - Frequently Asked Questions (FAQ)

1. What is the XPay Swift SDK?

The XPay Swift SDK is a payment integration solution for iOS applications that allows seamless transaction processing with XPay’s payment gateway.

2. How do I install the XPay Swift SDK?

You can install the SDK using Swift Package Manager (SPM) or manually by downloading the framework from the official repository.

3. What iOS versions are supported?

The SDK supports iOS 13 and later.

4. How do I initialize the SDK?

To initialize the SDK, you need to:

5. What payment methods are supported?

The SDK supports various payment methods, including credit/debit cards, mobile wallets, and bank transfers (depending on merchant configuration).

6. How do I make a payment request?

Use the XPay.shared.createPaymentRequest() method with the necessary transaction details, including:

7. How can I handle payment success or failure?

The SDK provides callbacks to handle payment responses:

8. Does the SDK support subscription payments?

Yes, the SDK supports subscription-based payments, allowing recurring billing setup for merchants.

9. How do I handle errors and exceptions?

Error handling is managed through predefined error codes and messages, which can be retrieved from the SDK response.

10. Is the SDK secure?

Yes, the SDK follows industry-standard encryption and security protocols, including PCI DSS compliance, to ensure safe transactions.

11. Can I customize the payment UI?

Yes, the SDK provides customization options to modify UI elements according to your app’s design.

12. Where can I get support for integration issues?

You can refer to the official documentation or contact XPay support for any integration-related queries.

XPay Swift SDK – New Features FAQ

1. What new features have been introduced in the XPay Swift SDK?

We have recently introduced the following key features:

2. How do subscription/recurring payments work?

The SDK enables merchants to set up automated recurring payments for customers. Once configured, payments are processed at scheduled intervals without requiring manual input.

3. Can users manage their subscriptions?

Yes, merchants can provide options for customers to modify, pause, or cancel subscriptions through their app’s settings.

4. What is payment routing, and how does it help?

Payment routing ensures optimal gateway selection for each transaction based on predefined rules such as:

This improves transaction success rates and reduces failures.

5. How does automatic retry work in case of payment failure?

If a payment fails on one gateway, the SDK automatically retries it on an alternative payment gateway (if configured) to increase the likelihood of a successful transaction.

6. Is payment routing configurable for merchants?

Yes, merchants can define custom rules and priorities for routing payments based on their business needs.

7. Does automatic retry apply to all payment methods?

Automatic retries are applicable based on the payment method and merchant settings, ensuring a seamless retry process without requiring user intervention.

8. How does this improve the payment success rate?

By intelligently routing payments and automatically retrying failures, the SDK significantly reduces failed transactions, ensuring a smoother checkout experience.

9. Are these features enabled by default?

Merchants need to configure these features via their XPay account settings to activate them for their business.

10. Where can I get support for setting up these features?

We’d be happy to walk you through these features in detail. Please let us know a suitable time for a call with our team to discuss the implementation and benefits further.

XPay SDKs – Frequently Asked Questions (FAQ)

1. What are the XPay SDKs?

The XPay SDKs for Android (Kotlin) and iOS (Swift) provide seamless payment integration for mobile applications using XPay’s payment gateway.

2. Where can I find the SDKs and integration documentation?

You can access the complete documentation, including SDK links and sample integrations, here:
🔗 XPay Developer API Docs

3. What platforms do the SDKs support?

4. What payment methods are supported?

Both SDKs support:

5. How do I install the SDKs?

6. How do I integrate the SDK into my mobile app?

The documentation provides step-by-step integration guides and sample implementations to simplify the process.

7. What are the key features of the SDKs?

The SDKs include:
✅ Subscription/Recurring Payments – Automate recurring transactions.
✅ Payment Routing – Intelligent routing across multiple gateways.
✅ Automatic Retries – Retry failed payments on alternate gateways.
✅ Customizable UI – Modify payment UI elements to match your app’s design.

8. How do I handle payment responses?

The SDKs provide callbacks for:

9. How secure are the XPay SDKs?

Both SDKs follow PCI DSS compliance and end-to-end encryption to ensure secure transactions.

10. Where can I get support for integration issues?

If you have any questions, please refer to the documentation or reach out to the XPay support team for assistance.

XPay Integration – Web & Backend FAQ

1. Do I need an SDK for backend integration?

No, backend integration only requires REST API calls. There is no SDK needed for the backend.

2. If I’m integrating XPay on the web, what should I use?

For web applications, you should use the XPay JavaScript SDK, which provides an end-to-end integration for handling payments.

3. Where can I find the JavaScript SDK integration guide?

The GitHub repository contains a fully integrated JavaScript SDK example, which you can refer to for implementation. The link is available in the XPay Developer API Docs:
🔗 XPay Developer API Docs

4. Does XPay provide UI components for web payments?

Yes, the JavaScript SDK includes pre-built UI components to streamline the payment process.

5. If I am using PHP for my backend, do I need an SDK?

No, PHP or any backend system only needs to interact with XPay via REST APIs for payment processing.

6. What functionalities does the JavaScript SDK cover?

The JavaScript SDK handles:
✅ Payment processing
✅ Subscription payments
✅ Payment routing & retries
✅ Secure tokenization

7. Can I customize the payment flow on my web application?

Yes, the JavaScript SDK allows UI and functional customizations to match your business needs.

XPay Integration – FAQ

1. Where can I find step-by-step integration instructions?

A detailed step-by-step guide is available in the Notion document provided by XPay. Please refer to it for complete instructions.

2. Is there a demo app available for testing?

Yes, you can check the demo app for Android Native, which provides practical insights into the integration process.

3. What platforms are supported for integration?

4. What functionalities are covered in the Notion guide?

The document includes:
✅ SDK setup and installation
✅ API integration details
✅ Payment processing steps
✅ Subscription & recurring payments
✅ Error handling & troubleshooting

Here’s a detailed FAQ tailored for API users based on the content in the provided links. This FAQ addresses common queries related to integrating with XPay through its REST API:

XPay API Integration FAQ

1. What is the XPay API?

The XPay API is a set of RESTful API endpoints designed to integrate payment processing into your website or application. It allows you to manage transactions, create payment links, process payments, and retrieve payment statuses.

2. How do I get started with XPay API integration?

To start using the XPay API:

  1. Obtain API Credentials: You'll need your Account ID, Email, and Password to authenticate API requests.

  2. Access the API Base URL: The API Base URL for staging is https://xstak-pay-stg.xstak.com.

  3. Consult Documentation: Refer to the Postman collection and the API documentation for step-by-step integration instructions.

  4. Test in Staging Environment: Use the staging environment to test your integration before going live.

3. What credentials do I need for integrating XPay API?

To integrate with the XPay API, you need:

These details will allow you to make secure API requests and interact with the system.

4. How do I authenticate API requests?

The XPay API uses standard authentication mechanisms such as API key-based authentication to authenticate all requests.

Refer to the API documentation for the exact headers and authentication method to use.

5. How do I create a payment link via the XPay API?

To create a payment link through the XPay API:

  1. Call the Payment Links API: Use the appropriate endpoint to generate a new payment link.

  2. Provide Payment Details: You’ll need to pass parameters such as the payment amount, description, and any other necessary details.

  3. Receive Payment Link: After successfully creating the link, the API will return the payment URL, which you can share with the customer.

Refer to the API documentation for detailed instructions on making the correct API call.

6. How can I process payments using the XPay API?

To process payments, you will:

  1. Create a Payment Request: Submit the transaction details to the XPay API.

  2. Wait for Response: The API will return a response with the payment status (success, failure, etc.).

  3. Handle Responses: Based on the response, you can display appropriate messages to users or trigger further actions like order processing.

You can refer to the Postman collection for sample requests and responses.

7. What is the XPay API base URL for making requests?

The base URL for making API requests in the staging environment is:

Ensure all API calls are made to this base URL during testing.

8. How do I check the status of a payment via the XPay API?

To check the payment status:

Refer to the API documentation for the exact API call and required parameters.

9. How can I manage refunds via the XPay API?

The XPay API allows for refund requests to be processed.

10. What is the XPay staging environment, and how can I use it for testing?

XPay provides a staging environment for testing your integration before going live.

11. Can I integrate XPay with an existing website or platform?

Yes, you can integrate the XPay API with your existing platform:

Refer to the API documentation for the endpoints and methods that will work with your platform.

12. Is there an API for handling backend payment processing?

Yes, the XPay API is designed for backend integration:

13. How do I integrate payment processing into my mobile application using XPay?

For mobile app integration (iOS/Android), use the appropriate SDK:

14. Can I customize the payment form on my website?

Yes, you can customize the payment form by modifying the design and layout to fit your website's theme. However, for payment processing, the form needs to meet security standards set by XPay.

Refer to the integration documentation to ensure you're meeting the security requirements while customizing the form.

15. Where can I find the XPay API documentation and sample integrations?

You can access the XPay API documentation and sample integrations in the following resources:

16. Do you provide any sample integrations for testing?

Yes, XPay provides a sample integration to help you understand how the API works. You can access the sample integration in the GitHub repository, which contains working code for processing payments and handling transactions.

17. What do I do if I encounter issues during integration?

If you encounter issues during integration, the first step is to:

Here is a comprehensive FAQ covering all possible client queries related to XPay API integration:

XPay API - Comprehensive FAQ

General Questions

1. What is XPay, and how does it work?

XPay is a payment gateway that enables businesses to accept online payments through various methods, including credit/debit cards, mobile wallets, and bank transfers. It provides a REST API for integrating payment processing into websites and applications.

2. Who can use XPay API?

XPay API is designed for:

3. What are the key benefits of using XPay API?

Integration & Authentication

4. What are the steps to integrate XPay API into my system?

  1. Sign up for an XPay account.

  2. Obtain API credentials (Account ID, Email, and Password).

  3. Access the staging environment for testing.

  4. Review the API documentation and sample integrations.

  5. Implement API calls for payments, refunds, and status checks.

  6. Perform end-to-end testing.

  7. Go live with production credentials.

5. What is the API base URL for staging and production?

6. How do I authenticate API requests?

XPay uses API key-based authentication. Your Account ID and Password must be included in the request headers to authenticate API calls.

Payment Processing

7. How can I process a payment through the XPay API?

  1. Create a payment request using the API.

  2. Send transaction details (amount, currency, customer info, etc.).

  3. Redirect the customer to the payment page (if applicable).

  4. Receive a payment response (success, failure, or pending).

8. Can I accept international payments with XPay?

Yes, XPay supports multiple currencies and international transactions, subject to merchant account settings.

9. What payment methods does XPay support?

10. What happens if a transaction fails?

If a payment fails, the API response will include a failure reason, such as:

Merchants can prompt users to retry the payment or use an alternative method.

Payment Links & Checkout Flow

11. How do I create a payment link using the API?

  1. Call the Create Payment Link API endpoint.

  2. Pass required parameters like amount, currency, and description.

  3. Receive a unique payment link in response.

  4. Share the link with customers via email, SMS, or chat.

12. Can I customize the payment page?

Yes, merchants can customize:

Refer to the developer guide for customization options.

13. How can I redirect customers after payment?

Use the redirect URL parameter in your API request to specify where the customer should be sent after payment success/failure.

Refunds & Chargebacks

14. How do I process a refund via API?

  1. Call the Refund API with the original transaction ID.

  2. Specify the amount to refund (full or partial).

  3. Receive a response confirming the refund status.

15. How long does a refund take to process?

Refunds usually take 5-7 business days, depending on the payment method and bank policies.

16. Can I cancel a payment before processing?

Yes, payments in a pending state can be canceled using the Cancel Payment API.

17. What happens if a customer disputes a transaction?

Chargebacks are handled by the bank. Merchants will be notified via API and required to provide transaction proof.

Security & Compliance

18. Is XPay API PCI DSS compliant?

Yes, XPay follows PCI DSS compliance to ensure secure transactions.

19. How do I ensure API security?

20. Does XPay support tokenization?

Yes, card tokenization is supported to allow secure one-click payments without storing sensitive card details.

Transaction Monitoring & Reporting

21. How can I check payment status?

Call the Payment Status API with the transaction ID to retrieve the latest payment status.

22. Can I download transaction reports?

Yes, XPay provides API endpoints to fetch transaction history and reports in CSV or JSON format.

23. How do I get notified about payment updates?

Merchants can use Webhooks to receive real-time notifications for:

Error Handling & Troubleshooting

24. What should I do if I get an API error?

Check the error code and message in the API response. Common errors include:

25. Where can I find API logs for debugging?

API logs are available in the developer dashboard for tracking request/response details.

26. How do I resolve timeout issues?

Ensure you have a stable internet connection and check for network latency. Increase the API timeout limit if necessary.

27. What if I face integration issues?

Going Live & Production Setup

28. How do I move from staging to production?

  1. Complete testing in the staging environment.

  2. Submit a request for live credentials.

  3. Update API base URL to the production endpoint.

  4. Perform a live test transaction.

29. What are the requirements for production approval?

Merchants must provide:

Support & Additional Resources

30. Where can I find XPay API documentation?

You can access the API documentation here:
📌 Postman Collection: XPay API Documentation
📌 GitHub Repository: XPay Sample Integration

31. How do I contact XPay support?

For integration assistance, reach out to XPay developer support via:

Here’s the FAQ addressing the client's query regarding Payment Intent API flow and integration on the app side:

XPay API - Payment Intent & App Integration FAQ

1. How does the payment flow work on the website versus the app?

2. When are clientSecret and encryption keys received?

These parameters are not received after the payment, but rather after the Payment Intent API call. They are used to confirm the payment in the next step.

3. Why is there a difference between website and app flows?

The website flow uses direct script verification before making the Payment Intent API call, whereas the app flow requires calling the Payment Intent API first to generate the required parameters for payment confirmation.

4. What should be done to integrate payments on the app?

Follow these steps:

  1. Call the Payment Intent API first.

  2. Extract clientSecret and encryption keys from the response.

  3. Use these parameters in the confirmPayment SDK method to complete the payment.

5. What happens if the confirmation step is skipped?

If the confirmPayment SDK method is not called using the received parameters, the payment will not be processed, and the transaction will remain incomplete.

6. Where can I find more details on integrating payments in the app?

Refer to the XPay API documentation for app-specific integration guidelines:
📌 Postman Collection: XPay API Documentation
📌 GitHub Repository: XPay SDK & Sample Code

XPay API - 2D Payment Exception FAQ

1. What is the issue with 2D payments on the Android app?

When attempting a 2D payment on the Android app, an exception is thrown because 2D Secure (2DS) payments are not supported. These transactions are automatically declined by the payment gateway.

2. What is a 2D payment?

A 2D payment is a transaction where card authentication does not require an additional security layer, such as OTP verification (One-Time Password) or biometric authentication. These payments are considered high risk and are usually blocked by gateways.

3. Why does the payment gateway decline 2D payments?

Most modern payment gateways follow 3D Secure (3DS) protocols, which add an extra layer of security to protect against fraud. Transactions without this security layer (i.e., 2D payments) are automatically rejected.

4. How can we resolve the 2D payment issue?

To ensure successful transactions, 3D Secure (3DS) authentication must be enabled. This means:

5. How can I check if a card supports 3DS?

6. Can 2D payments be enabled manually?

No, 2D payments cannot be enabled, as they are blocked by the gateway for security reasons. All payments must follow 3D Secure (3DS) authentication standards.

7. Where can I find more information on supported payment methods?

For details on payment methods and security requirements, refer to:
📌 XPay API Documentation: XPay API Docs
📌 GitHub Repository: XPay SDK & Sample Code

XPay API - 3D Secure (3DS) Authentication FAQ

1. What is 3D Secure (3DS) authentication?

3D Secure (3DS) is an additional security layer for online card payments that helps prevent fraud by authenticating the cardholder during a transaction.

2. What are the different versions of 3D Secure?

3. What is the difference between Frictionless and Challenge authentication in 3DS2?

Type

Card Example

OTP Required?

Description

3DS1

5506900140100305

✅ Yes

OTP-based authentication, requires manual input.

3DS2 - Frictionless

5123456789012346

❌ No

Authentication happens in the background without user input.

3DS2 - Challenge

5123450000000008

✅ Yes

Requires OTP or biometric verification before processing.

4. How does Frictionless authentication work in 3DS2?

5. When is Challenge authentication used in 3DS2?

6. Which authentication method is more secure?

7. What happens if a transaction does not support 3DS?

8. How can I test 3DS transactions?

You can use the following test cards for different scenarios:

For more details, refer to:
📌 XPay API Documentation: XPay API Docs
📌 GitHub Repository: XPay SDK & Sample Code

XPay API - Payment Intent (PI) and Client Secret FAQ

1. What is pi_client_secret in XPay API?

The pi_client_secret is a unique identifier required for confirming a payment. It is generated when a Payment Intent (PI) is created.

2. Is pi_client_secret the same as PI ID?

No, pi_client_secret is NOT the same as the Payment Intent (PI) ID. It is a separate parameter included in the API response when creating a Payment Intent.

3. Where can I find pi_client_secret?

It is present in the Create Payment Intent API response. You must store this value and use it for the payment confirmation process.

4. What is the difference between PI ID and pi_client_secret?

Parameter

Description

Payment Intent ID (PI ID)

A unique identifier for tracking the payment transaction.

pi_client_secret

A secret key required to confirm the payment securely.

5. Why is pi_client_secret necessary?

6. Do I need to store pi_client_secret?

Yes, you should store pi_client_secret temporarily until the payment is successfully confirmed.

7. Can I use the PI ID instead of pi_client_secret for payment confirmation?

No, the pi_client_secret is mandatory for confirming a payment. The PI ID alone is insufficient.

8. Where can I find more details about Payment Intent API?

For API documentation and integration examples, check:
📌 XPay API Documentation: XPay API Docs
📌 GitHub Repository: XPay SDK & Sample Code

XPay API - "Payment Method is Already Attached" Error FAQ

1. What does the "Payment Method is Already Attached" error mean?

This error occurs when the same Payment Method (e.g., card details) is being used multiple times within the same Payment Intent (PI). The payment method is already linked to the PI and does not need to be reattached

2. Why am I getting this error?

You may be encountering this issue due to one of the following reasons:

3. How can I fix this issue?

Here are a few solutions:
✅ Check if the Payment Intent (PI) has already been captured or confirmed before making another request.
✅ Do not reattach the payment method if it has already been linked to the PI.
✅ Ensure that duplicate API calls are not being made in your integration.
✅ If payment has already been processed, create a new Payment Intent for a new transaction instead of reusing the same one.

4. How do I verify if a Payment Intent has already been captured?

You can check the status of the Payment Intent via the API before proceeding with another payment request. Look for the following statuses:

5. Where can I find more details on Payment Intent handling?

📌 XPay API Documentation: XPay API Docs
📌 GitHub Repository: XPay SDK & Sample Code

XPay API - Handling success Key in confirmPayment Response

1. Why am I getting undefined for responseStatus, success, and data in confirmPayment?

If responseStatus, success, and data are undefined, it usually means:

2. How can I properly handle the success key?

Instead of directly destructuring success, handle the response using message and error keys:

✅ Correct Approach:

javascript

CopyEdit

const response = await xpay.confirmPayment("card", clientSecret, customer, encryptionKey); if (response) { const { message, error } = response; if (!error) { console.log("Payment successful:", message); } else { console.log("Payment failed:", message); } } else { console.log("No response received from confirmPayment API."); }

3. Why is error used instead of success?

In the confirmPayment response:

4. What should I check if the issue persists?

5. Where can I find more details on API responses?

📌 XPay API Documentation: XPay API Docs
📌 GitHub Repository: XPay SDK & Sample Code

XPay API - Retrieving Complete Transaction Details

1. How can I retrieve complete transaction details, including card and payment details?

To fetch detailed transaction information, including card details and payment details, follow these methods:

A. Retrieve Payment Intent API (Get PI Details)

📌 API Name: Retrieve Payment Intent
🔗 Documentation: XPay API Docs

Request:

http

CopyEdit

GET /v1/payment_intents/{paymentIntentId}

Required Parameters:

Limitations:

B. Webhook for Full Transaction Details

For complete transaction details, including card details, payment details, and the timeline of events, use the webhook.

📌 Webhook contains:
✔ Transaction timeline (payment status updates)
✔ Card details (masked card number, issuer, etc.)
✔ Payment details (amount, currency, gateway response, etc.)

🔗 Webhook Guide: Available in the XPay API Docs

Steps to Use Webhook:

  1. Register a webhook endpoint in your system.

  2. Capture the transaction data sent by XPay on payment updates.

  3. Parse the webhook payload to retrieve full transaction details.

2. Why doesn’t the Retrieve Payment Intent API return full transaction details?

3. Where can I see full transaction details like in XPay Admin Panel (/xpay/transactions/{transactionID})?

To retrieve details similar to what is available at https://xap-stage.xstak.com/xpay/transactions/{transactionID}, use the Webhook API, as it includes:

📌 Alternative:

4. How can I confirm that my webhook is working?

  1. Ensure your webhook URL is registered in the XPay system.

  2. Use a tool like Postman or RequestBin to inspect incoming webhook data.

  3. Check logs in your system to verify if XPay is sending webhook events.

🔗 Webhook Documentation: Available in the Postman API Collection

5. Summary: Best Approach to Get Full Transaction Details

Requirement

API to Use

Contains Complete Transaction Info?

Basic Payment Intent details

Retrieve Payment Intent API

❌ Limited details

Complete transaction details (card info, timeline, etc.)

Webhook API

✅ Yes

XPay API - ConfirmPayment SDK Method & API Calls

1. What API calls do I need to make for a complete payment process?

For a full transaction flow in XPay, you need to follow these steps:

Step

API Name

Purpose

API Endpoint (Postman Docs)

1️⃣ Create Payment Intent

Create Payment Intent API

Initializes a payment intent & returns pi_client_secret

View API

2️⃣ Confirm Payment (SDK Method, Not API)

confirmPayment SDK Method

Confirms payment using pi_client_secret

Handled via SDK (not API)

3️⃣ Capture Authorized Payment (If using authorization flow)

Capture an Authorized Amount API

Captures a pre-authorized payment

View API

4️⃣ Retrieve Payment Intent Details

Get PI Details API

Retrieves status & details of a payment intent

View API

2. Where is the ConfirmPayment API?

There is no separate API for confirmPayment. This is an SDK method that must be called after creating a payment intent.

📌 How to use ConfirmPayment in SDK?

const { message, responseStatus, success, data } = await xpay.confirmPayment( "card", // Payment method clientSecret, // Received from Create Payment Intent API customer, // Customer details encryptionKey // Required encryption key );

Handling Success Response:

const { message, error } = await xpay.confirmPayment(...); if (!error) { console.log("Payment successful"); } else { console.log("Payment failed"); }

🔗 SDK Documentation: Refer to Notion Guide

3. What is pi_client_secret, and where do I get it?

📌 Example Create Payment Intent Response:

json
{ "id": "pi_123456789", "client_secret": "pi_client_secret_abc123", "status": "requires_confirmation" }

4. When should I call the Capture an Authorized Amount API?

📌 Example Request to Capture Payment:

http
POST /v1/payment_intents/{paymentIntentId}/capture

🔗 View API Documentation

5. How do I get full transaction details after confirming payment?

🔗 Retrieve Payment Intent API: View API
🔗 Webhook API (Recommended for full details): View API

6. Summary: Complete Payment Flow

Step

Required Action

API/Method

1️⃣ Create Payment Intent

Initialize payment & get client_secret

Create Payment Intent API

2️⃣ Confirm Payment

Confirm using SDK

confirmPayment SDK Method

3️⃣ Capture (if applicable)

Capture an authorized payment

Capture an Authorized Amount API

4️⃣ Retrieve Transaction Details

Get payment details

Get PI Details API / Webhook