> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xerobi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Payment API FAQ

> Frequently asked questions about the Xerobi Payment Gateway API

## Payment Processing

### How do I create a payment intent?

> [accordion] Basic payment intent creation
>
> To create a payment intent, send a POST request to `/payment_intents` with the amount, currency, and description:
>
> ```bash theme={null}
> curl -X POST "https://api.hixbe.com/payment/payment_intents" \
>   -H "Authorization: Bearer YOUR_API_KEY" \
>   -H "Xerobi-Version: 2026-01-01" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "amount": 1000,
>     "currency": "USD",
>     "description": "Order #12345"
>   }'
> ```
>
> The response includes a client secret for frontend integration.

> [accordion] What currencies are supported?
>
> Xerobi supports all major currencies including USD, EUR, GBP, CAD, AUD, and many others. The currency must be specified as a three-letter ISO code.

> [accordion] How do I handle different payment methods?
>
> You can accept various payment methods by creating payment methods and attaching them to payment intents or customers. Supported methods include credit cards, debit cards, and digital wallets.

### Payment Confirmation

> [accordion] When should I confirm a payment intent?
>
> Confirm the payment intent when you're ready to charge the customer. This typically happens after collecting payment details on the frontend using the client secret.

> [accordion] What happens if confirmation fails?
>
> If confirmation fails, the payment intent status will be `requires_payment_method` or `requires_action`. Check the `last_payment_error` field for details about the failure.

> [accordion] Can I confirm payments server-side only?
>
> Yes, you can confirm payments entirely server-side by providing the payment method details directly in the confirmation request, though this requires PCI compliance.

## Customers and Payment Methods

### Managing Customers

> [accordion] When should I create customers?
>
> Create customers when you need to save payment methods for future use, implement subscriptions, or track payment history for specific users.

> [accordion] How do I attach payment methods to customers?
>
> First create a payment method, then attach it to a customer:
>
> ```javascript theme={null}
> // 1. Create payment method
> const paymentMethod = await api.createPaymentMethod({
>   type: 'card',
>   card: { number, exp_month, exp_year, cvc }
> });
>
> // 2. Attach to customer
> await api.attachPaymentMethodToCustomer(customerId, paymentMethod.id);
> ```

> [accordion] Can customers have multiple payment methods?
>
> Yes, customers can have multiple saved payment methods. You can list them and set a default payment method for easier checkout.

## Refunds and Disputes

### Processing Refunds

> [accordion] How do I process a refund?
>
> Create a refund by providing the payment intent ID and optionally the amount to refund:
>
> ```bash theme={null}
> curl -X POST "https://api.hixbe.com/payment/refunds" \
>   -H "Authorization: Bearer YOUR_API_KEY" \
>   -H "Xerobi-Version: 2026-01-01" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "payment_intent": "pi_1234567890",
>     "amount": 500
>   }'
> ```

> [accordion] Can I refund partial amounts?
>
> Yes, you can refund any amount up to the original payment amount. Multiple partial refunds are allowed as long as the total doesn't exceed the original payment.

> [accordion] How long do refunds take?
>
> Refunds typically process within 5-10 business days, depending on the customer's bank and payment method. You'll receive webhook notifications when the refund completes.

## Webhooks and Events

### Payment Webhooks

> [accordion] What webhook events should I listen for?
>
> Essential events to monitor:
>
> * `payment_intent.succeeded` - Payment completed successfully
> * `payment_intent.payment_failed` - Payment failed
> * `payment_intent.canceled` - Payment was canceled
> * `refund.succeeded` - Refund processed

> [accordion] How do I handle webhook retries?
>
> Xerobi automatically retries failed webhooks. Implement idempotency using event IDs to handle duplicate events safely.

> [accordion] Can I test webhooks?
>
> Yes, use the dashboard to send test webhook events to your endpoints during development.

## Security and Compliance

### PCI Compliance

> [accordion] How does Xerobi handle PCI compliance?
>
> Xerobi is PCI DSS Level 1 compliant. When using our hosted payment forms, sensitive card data never touches your servers, reducing your PCI scope.

> [accordion] What if I need to handle card data directly?
>
> If you must handle card data server-side, you'll need full PCI compliance. We recommend using our client-side integration instead.

> [accordion] Are payment methods tokenized?
>
> Yes, all payment methods are tokenized. We never store raw card numbers - only tokens that can be used for future payments.

## Testing and Sandbox

### Sandbox Environment

> [accordion] How do I test payments?
>
> Use our sandbox environment at `https://sandbox.api.hixbe.com`. Use test API keys and test card numbers like `4242 4242 4242 4242`.

> [accordion] What test cards are available?
>
> * `4242 4242 4242 4242` - Succeeds
> * `4000 0000 0000 0002` - Declined
> * `4000 0025 0000 3155` - Requires authentication

> [accordion] Do sandbox payments appear in production?
>
> No, sandbox and production are completely separate environments. Test data never affects live payments.

## Error Handling

### Common Payment Errors

> [accordion] CARD\_DECLINED - What does this mean?
>
> The customer's card was declined by their bank. Common reasons include insufficient funds, expired card, or bank restrictions.

> [accordion] INSUFFICIENT\_FUNDS - How to handle?
>
> The account doesn't have enough funds. Ask the customer to use a different payment method or add funds to their account.

> [accordion] PAYMENT\_INTENT\_EXPIRED - What happened?
>
> Payment intents expire after 24 hours by default. Create a new payment intent for the customer to try again.

## Integration Best Practices

### Performance and Reliability

> [accordion] How do I handle rate limits?
>
> Monitor the `X-RateLimit-Remaining` header and implement exponential backoff when approaching limits. Payment API allows 100 requests per minute.

> [accordion] Should I use idempotency keys?
>
> Yes, always use idempotency keys for payment operations to prevent duplicate charges if requests are retried.

> [accordion] How do I implement proper error handling?
>
> Check the `success` field in all responses. Handle different error codes appropriately and provide meaningful feedback to users.

## Billing and Pricing

### Understanding Costs

> [accordion] How am I charged for payments?
>
> You pay a percentage of each successful transaction plus a fixed fee per transaction. Check your dashboard for current pricing.

> [accordion] Are there fees for refunds?
>
> Refunds may incur processing fees depending on your pricing plan. Failed payments don't incur transaction fees.

> [accordion] How do I monitor my usage?
>
> Use the dashboard to track transaction volume, success rates, and costs in real-time.

## Need More Help?

> [card] [Payment API Docs](https://docs.xerobi.com/payment-api/introduction.md)
>
> Complete API reference

> [card] [Webhooks](https://docs.xerobi.com/faq-guides/webhooks.md)
>
> Set up payment notifications

> [card] [Error Handling](https://docs.xerobi.com/faq-guides/error-handling.md)
>
> Handle payment errors

> [card] [Best Practices](https://docs.xerobi.com/faq-guides/best-practices.md)
>
> Payment integration best practices

> [card] [Troubleshooting](https://docs.xerobi.com/faq-guides/troubleshooting)
>
> Payment-specific issues

> [card] [Support](mailto:support@xerobi.com)
>
> Contact our support team


## Related topics

- [Xerobi Payment API Introduction](https://docs.xerobi.com/payment-api/introduction.md)
- [Certification API FAQ](https://docs.xerobi.com/faq-guides/certification-api-faq.md)
- [SMS API FAQ](https://docs.xerobi.com/faq-guides/sms-api-faq.md)
- [API Versioning](https://docs.xerobi.com/faq-guides/versioning.md)
- [Time Synchronization FAQ](https://docs.xerobi.com/faq-guides/time-synchronization.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.