> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.crisscross.money/common-issues/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.crisscross.money/_mcp/server.

# Common Issues

> A guide to resolving common integration challenges merchants may encounter while working with CrissCross.

### Overview

While CrissCross aims to provide a seamless payment processing experience, some issues may arise due to integration challenges, configuration errors, or external dependencies. This guide highlights common issues merchants encounter and how to resolve them.

---

### Common Issues and Solutions

1. **Invalid or Expired Access Token (401 Unauthorized)**
   * **Issue**: Requests fail with a 401 error.
   * **Cause**: Missing, incorrect, or expired OAuth access token used in the request.
   * **Solution**: Verify that you are sending a valid access token in the `Authorization: Bearer ...` header. Request a new token from the Authentication API (`POST /v1/auth/oauth2/token`) using your `client_id` and `client_secret` if the token has expired.

2. **Payment Declined by Issuer (402 Payment Declined)**
   * **Issue**: Payment requests are declined by the customer’s bank.
   * **Cause**: Insufficient funds, incorrect payment details, or card restrictions.
   * **Solution**: Suggest the customer try a different payment method or contact their bank for details.

3. **Incorrect Webhook Configuration**
   * **Issue**: Webhook notifications are not being received.
   * **Cause**: Incorrect endpoint configuration or blocked traffic.
   * **Solution**: Ensure the webhook endpoint is correctly configured and accessible. Verify any firewall rules that may block incoming requests.

4. **Mismatched Currency Code in Transactions**
   * **Issue**: Payments are rejected due to unsupported currency codes.
   * **Cause**: Currency code mismatch between the merchant and the payment processor.
   * **Solution**: Ensure the currency code is supported by both CrissCross and the payment processor. Use the currency compatibility matrix in the dashboard.

5. **Duplicate Transactions Due to Retries**
   * **Issue**: Multiple payments are processed for a single order.
   * **Cause**: Manual retries by merchants during automatic CrissCross retries.
   * **Solution**: Monitor CrissCross’s retry logic and avoid triggering manual retries when automatic retries are active.

6. **Timeouts During Payment Processing**
   * **Issue**: Payments fail with a timeout error.
   * **Cause**: Network issues or a slow response from the payment processor.
   * **Solution**: Implement retries with exponential backoff or use CrissCross’s automatic retry feature.

7. **Missing Payment Methods in Checkout**
   * **Issue**: Some expected payment methods are not shown in the hosted checkout.
   * **Cause**: Payment methods may not be enabled for the merchant's account.
   * **Solution**: Verify the payment method configurations in the dashboard and ensure all relevant methods are enabled.

---

### Best Practices for Issue Resolution

* **Monitor Logs and Metrics**: Regularly monitor your integration logs and CrissCross metrics to identify issues early.
* **Use Webhooks for Real-Time Alerts**: Configure webhooks to stay informed about payment statuses and issues.
* **Keep Your Credentials and Webhooks Secure**: Store your `client_secret` and access tokens securely (e.g. in environment variables or a secrets manager), rotate credentials periodically, and secure webhook endpoints to prevent unauthorized access.

> Troubleshooting common problems with CrissCross integrations