FAQs - API users

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:

   • Within the Settings menu, locate and click on the Store Info option.

4. Click on Key Details:

   • In the Store Info section, find and click on the Key Details tab or button.

5. Retrieve Keys and Secrets:

   • Under the Key Details section, you will find the following credentials:

     • Public Key

     • Secret Key

     • API HMAC Secret

     • Webhook HMAC Secret

Open

6. 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.

3. What is the Public Key used for?

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

4. 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.

5. 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.

6. 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).

7. 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.

2. 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.

3. 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:

• Node.js

• Python

• PHP

• Java

• Ruby

4. Sample X-Signature Generation in Node.js

Here is a sample implementation in Node.js:

5. 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

6. What should I do if I encounter errors?

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

• Ensure you are using the correct secret key.

• Verify that the data being hashed matches the expected format.

• Confirm that your hashing algorithm is HMAC with SHA-256.

• Check for encoding issues (ensure consistent character encoding across systems).

• Refer to the sample implementation in the provided repository.

7. 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:

• The server-side language used

• A sample of the data being hashed

• Any error messages received

• Account ID

• Environment (Stage or Live)

• SDK version

• XPay PI ID

• Complete request and response

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:

Possible Causes and Solutions:

1. Incorrect Signature Calculation

• Ensure that the signature is generated using the exact payload that is being sent in the API request.

• Any modification to the payload after signature generation will result in an invalid signature.

2. Mismatched API Payload and Signature Payload

• The payload used for signing must be identical to the request payload.

• If any field is missing or changed after signature creation, the signature will be invalid.

3. Incorrect HMAC Secret Key

• Use the correct API HMAC Secret for signing the request.

• Example of an API HMAC Secret:

  5c0ed92e74148c8919d06666001c5005352f0e651fe08d6ac91cb7188da7f34c

• Ensure no extra spaces or incorrect characters are included.

4. Incorrect Header Formatting

• The signature should be included in the headers properly:

  Authorization: HMAC-SHA256 Signature={your_generated_signature}

• Ensure that the hashing algorithm used is SHA256.

5. Missing or Incorrect gateway_instance_id

• Ensure the gateway_instance_id is retrieved correctly from gateways settings.

• If missing or incorrect, update it accordingly.

Correct Example of API Request Payload:

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:

Request Format (Raw JSON):

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

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

Possible Causes:

• Ensure you are passing the correct pi_client_secret and encrypted_key values received in the Payment Intent response.

• Do not use a dummy gateway_instance_id. The system assigns a default test gateway automatically.

• If you receive an error while omitting gateway_instance_id, verify if a default test gateway is enabled in your settings.

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

Use the following method in your Android application:

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

• PI_SECRET_ID: The pi_client_secret received from the Payment Intent API.

• ENCRYPTED_KEY_ID: The encrypted public key required for secure transactions.

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

For staging:

Ensure your Gradle settings include the required repositories.

7. What if I still encounter issues?

• Double-check your API request format and required fields.

• Ensure you're using the latest SDK version and dependencies.

• Verify if the test gateway is correctly configured.

• Contact support with the request payload, response, and error logs for further assistance.

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:

• Import XPaySDK into your project.

• Configure API keys and environment settings.

• Call the XPay.shared.initialize() method with the required parameters.

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:

• Amount

• Currency

• Order ID

• Customer details

7. How can I handle payment success or failure?

The SDK provides callbacks to handle payment responses:

• Success: Returns a transaction ID and status.

• Failure: Returns an error code with a message.

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:

• Subscription/Recurring Payments – Allows automatic billing for subscriptions.

• Payment Routing – Routes payments across multiple gateways for better success rates.

• Automatic Retries – Retries failed transactions on alternative gateways automatically.

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:

• Payment method availability

• Transaction success rate

• Gateway downtime or performance metrics

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?

• iOS SDK – Supports iOS 13 and later (Swift)

• Android SDK – Supports Android 5.0 (Lollipop) and later (Kotlin)

4. What payment methods are supported?

Both SDKs support:

• Credit/Debit Cards

• Mobile Wallets

• Bank Transfers

• Subscription Payments (New Feature)

5. How do I install the SDKs?

• Swift SDK: Install via Swift Package Manager (SPM) or manually.

• Kotlin SDK: Install via Gradle using the provided repository link in the docs.

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:

• Success: Returns transaction details.

• Failure: Returns an error code and message for debugging.

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?

• Mobile: Android (Kotlin), iOS (Swift)

• Web: JavaScript SDK

• Backend: REST API (No SDK required)

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:

• Account ID: Unique identifier provided after account creation.

• Email and Password: Credentials used for API authentication.

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.

• Authentication Method: Use your Account ID and Password in the request header to authenticate API calls.

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:

• Staging Base URL: https://xstak-pay-stg.xstak.com

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:

• Use the Payment Status API Endpoint: You can pass a transaction ID or payment reference to retrieve the payment status.

• API Response: The response will include details such as whether the payment was successful, pending, or failed.

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.

• Refund API Endpoint: Use the specific endpoint to initiate a refund based on the transaction details.

• Parameters: Pass the transaction ID and the refund amount.

• Refund Confirmation: The API will return a response confirming the success or failure of the refund process.

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.

• Staging API Base URL: https://xstak-pay-stg.xstak.com

• XAP Staging URL: https://xap-stage.xstak.com

• Test Transactions: Use the staging environment to simulate real-world transactions and validate your integration.

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

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

• Use the Payment Links API to generate links for payments.

• Use the Transaction APIs to process payments and manage payment statuses.

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:

• REST API: You will interact with XPay through REST API calls to process payments, create payment links, and manage transactions.

• No SDK Required: Unlike frontend integration, backend processing does not require an SDK, only API calls.

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

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

• The JavaScript SDK can be used for web applications, while the mobile SDKs (Swift for iOS and Kotlin for Android) are used for native mobile apps.

• For backend integration, use the XPay REST API to handle payment processing.

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:

• Postman Collection: XPay API Collection on Postman

• GitHub Repository: XPay Sample Integration on GitHub

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:

• Check the API documentation for common integration mistakes.

• Validate your API credentials to ensure they are correctly configured.

• Test in the staging environment to ensure the issue isn’t related to your live account.

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:

• E-commerce platforms

• Subscription-based services

• Mobile apps

• Custom business applications

• Developers building checkout solutions

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

• Seamless integration into websites, mobile apps, and backend systems.

• Secure transactions with industry-standard encryption.

• Multiple payment methods supported.

• Real-time transaction monitoring.

• Easy API setup and extensive documentation.

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?

• Staging API URL: https://xstak-pay-stg.xstak.com

• Production API URL: Provided after successful testing and approval.

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?

• Credit/Debit Cards (Visa, Mastercard, etc.)

• Mobile Wallets

• Bank Transfers

• UPI Payments (if enabled)

• Other local payment methods

10. What happens if a transaction fails?

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

• Insufficient funds

• Card declined

• Invalid payment details

• Network issues

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:

• Branding (logo, colors, themes)

• Payment methods displayed

• Transaction messages and success pages

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?

• Use HTTPS for all API requests.

• Secure API keys and credentials.

• Implement token-based authentication if required.

• Monitor API logs for suspicious activities.

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:

• Payment success

• Payment failure

• Refund processed

• Chargeback initiated

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:

• 401 Unauthorized: Invalid API credentials

• 400 Bad Request: Missing or incorrect parameters

• 500 Internal Server Error: Server-side issue (retry later)

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?

• Review the Postman collection for sample API requests.

• Refer to the GitHub repository for working examples.

• Contact XPay support for assistance.

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:

• A verified business account.

• Compliance with security and fraud prevention guidelines.

• A successful test transaction history.

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:

• Email: support@xpay.com

• Live Chat: Available on the XPay portal

• Developer Community: Forums & Slack channels

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?

• On the website, the user enters card details, the script verifies the card, and then a Payment Intent API call is made. Upon successful payment, the response includes clientSecret and encryption keys.

• On the app, the process is slightly different:

  1. The Payment Intent API call happens first.

  2. The response contains clientsecret and encryption keys.

  3. These parameters are then used for the confirmPayment SDK method to complete the payment.

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:

• Use cards that support 3D Secure authentication.

• Ensure that the gateway being used supports 3DS transactions.

• Implement proper redirection or in-app handling for 3DS authentication (OTP verification, biometric, etc.).

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

• Contact the issuing bank to confirm if the card is 3DS enabled.

• Attempt the payment using a different 3DS-supported card.

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?

• 3DS1: The earlier version, where OTP (One-Time Password) is required for authentication.

• 3DS2: The latest version, which introduces two types of authentication:

  • Frictionless (No OTP required)

  • Challenge (OTP required)

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

4. How does Frictionless authentication work in 3DS2?

• If a card supports Frictionless 3DS2, the bank automatically verifies the transaction without requiring an OTP.

• This reduces customer friction and speeds up the checkout process.

5. When is Challenge authentication used in 3DS2?

• If a card requires Challenge 3DS2, the bank mandates OTP verification before processing the transaction.

• This happens for high-risk transactions, large amounts, or when additional verification is required.

6. Which authentication method is more secure?

• Both Frictionless and Challenge authentication are secure, as they follow 3DS2 security standards.

• Challenge authentication provides an extra layer of protection by ensuring that the actual cardholder is making the transaction.

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

• If a transaction is 2D Secure (2DS) (without 3D Secure), it will likely be declined by the gateway for security reasons.

• Merchants should ensure that all cards used support 3DS authentication.

8. How can I test 3DS transactions?

You can use the following test cards for different scenarios:

• 3DS1 Test Card: 5506900140100305 (OTP Required)

• 3DS2 Frictionless Test Card: 5123456789012346 (No OTP)

• 3DS2 Challenge Test Card: 5123450000000008 (OTP Required)

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?

5. Why is pi_client_secret necessary?

• It ensures that only authorized entities can confirm a payment.

• It helps maintain the security of the payment flow by preventing unauthorized access.

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:

• The payment method was already attached to the Payment Intent (PI) in a previous request.

• A duplicate API request is being made after the PI has already been confirmed or captured.

• The Payment Intent has already been completed, and another attempt is being made using the same payment method.

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:

• Succeeded: Payment has already been captured.

• Processing: The payment is still being processed.

• Requires Confirmation: The payment method is attached, but confirmation is pending.

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:

• There is an issue with the API request parameters (e.g., invalid clientSecret, customer, or encryptionKey).

• The API call is failing silently or not returning the expected response format.

• The confirmPayment function is not properly awaiting or handling the response.

2. How can I properly handle the success key?

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

✅ Correct Approach:

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:

• If error is false, it means the payment was successful.

• If error is true, it means the payment failed.

• success may not be explicitly returned, so handling error is the correct approach.

4. What should I check if the issue persists?

• Ensure clientSecret, customer, and encryptionKey are correct and valid.

• Check for network issues or API failures.

• Log the entire response to debug missing keys:

  javascript

  CopyEdit

  console.log("Full API Response:", response);

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:

CopyEdit

GET /v1/payment_intents/{paymentIntentId}

Required Parameters:

• paymentIntentId (PI ID) → The Payment Intent ID for which details are needed

Limitations:

• This API provides only basic payment intent details, not full transaction information.

• It does not return complete card or payment details.

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?

• The Retrieve Payment Intent API focuses only on the Payment Intent (PI), not the complete transaction.

• Detailed payment information (such as card details) is stored and sent only via webhook for security reasons.

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:

• Transaction ID

• Card details (masked card number)

• Gateway response

• Timeline of the transaction

📌 Alternative:

• If you need a custom API to fetch transaction details directly, check with the XPay support team for additional API access.

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

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:

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?

Handling Success Response:

🔗 SDK Documentation: Refer to Notion Guide

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

• pi_client_secret is not the Payment Intent ID (PI ID).

• It is returned in the Create Payment Intent API response and must be used in confirmPayment.

📌 Example Create Payment Intent Response:

• Use client_secret in the confirmPayment SDK method.

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

• If your payment flow uses authorization before capturing funds, you must call this API after payment confirmation to finalize the transaction.

• If you are using a direct payment flow, no need to call this API.

📌 Example Request to Capture Payment:

🔗 View API Documentation

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

• Use Retrieve Payment Intent API to check payment status.

• For complete details (card info, transaction timeline, etc.), use Webhook API.

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

6. Summary: Complete Payment Flow