Skip to main content

​
Payment Processing

​
How do I create a payment intent?

To create a payment intent, send a POST request to /payment_intents with the amount, currency, and description:
curl -X POST "https://api.hixbe.com/payment/payment_intents" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Hixbe-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.
Hixbe supports all major currencies including USD, EUR, GBP, CAD, AUD, and many others. The currency must be specified as a three-letter ISO code.
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

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

Create customers when you need to save payment methods for future use, implement subscriptions, or track payment history for specific users.
First create a payment method, then attach it to a customer:
// 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);
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

Create a refund by providing the payment intent ID and optionally the amount to refund:
curl -X POST "https://api.hixbe.com/payment/refunds" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Hixbe-Version: 2026-01-01" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_intent": "pi_1234567890",
    "amount": 500
  }'
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.
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

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
Hixbe automatically retries failed webhooks. Implement idempotency using event IDs to handle duplicate events safely.
Yes, use the dashboard to send test webhook events to your endpoints during development.

​
Security and Compliance

​
PCI Compliance

Hixbe is PCI DSS Level 1 compliant. When using our hosted payment forms, sensitive card data never touches your servers, reducing your PCI scope.
If you must handle card data server-side, you’ll need full PCI compliance. We recommend using our client-side integration instead.
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

Use our sandbox environment at https://sandbox.api.hixbe.com. Use test API keys and test card numbers like 4242 4242 4242 4242.
  • 4242 4242 4242 4242 - Succeeds
  • 4000 0000 0000 0002 - Declined
  • 4000 0025 0000 3155 - Requires authentication
No, sandbox and production are completely separate environments. Test data never affects live payments.

​
Error Handling

​
Common Payment Errors

The customer’s card was declined by their bank. Common reasons include insufficient funds, expired card, or bank restrictions.
The account doesn’t have enough funds. Ask the customer to use a different payment method or add funds to their account.
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

Monitor the X-RateLimit-Remaining header and implement exponential backoff when approaching limits. Payment API allows 100 requests per minute.
Yes, always use idempotency keys for payment operations to prevent duplicate charges if requests are retried.
Check the success field in all responses. Handle different error codes appropriately and provide meaningful feedback to users.

​
Billing and Pricing

​
Understanding Costs

You pay a percentage of each successful transaction plus a fixed fee per transaction. Check your dashboard for current pricing.
Refunds may incur processing fees depending on your pricing plan. Failed payments don’t incur transaction fees.
Use the dashboard to track transaction volume, success rates, and costs in real-time.

​
Need More Help?

Payment API Docs

Complete API reference

Webhooks

Set up payment notifications

Error Handling

Handle payment errors

Best Practices

Payment integration best practices

Troubleshooting

Payment-specific issues

Support

Contact our support team