Chargebee Integration Guide
Alternative Payments can work alongside Chargebee without requiring an ERP or accounting platform in the middle. This guide explains how to wire the two systems together using the AP public API, which payment collection methods are available, how to keep payment status in sync via webhooks, and what the current limitations are.
Overview
There is no turnkey Chargebee connector — the integration requires a small amount of custom code on your side. The pattern is straightforward:
Chargebee invoice created → your backend calls the AP API to create a matching customer and invoice.
AP processes the payment → AP fires an
invoice_paidwebhook to your endpoint.Your backend marks the invoice paid in Chargebee → the two systems stay in sync.
All payments run on AP's rails (card or ACH into payouts). AP acts as the processor for every invoice run through it; payments from third-party processors cannot be recorded through the partner API.
Authentication
The AP public API uses OAuth 2.0 client_credentials. Obtain a token before making any API calls:
curl -X POST https://public-api.demo.alternativepayments.io/oauth/token \
-H "Authorization: Basic BASE64(client_id:client_secret)" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials"The response includes an access_token valid for 3600 seconds. Pass it as a Bearer token on all subsequent requests:
Authorization: Bearer <access_token>Your client_id and client_secret are available in the Partner Dashboard under API Keys. The scopes required for a Chargebee integration are: customers:write, customers:read, invoices:write, invoices:read, payments:write, payments:read, and webhooks:write.
Step 1 — Create Customers
Mirror each Chargebee customer into AP using POST /customers. Store the Chargebee customer ID in the external_id field so you can look up the AP customer record from a Chargebee event later.
Required scope: customers:write
The response includes the AP-assigned id alongside the external_id you supplied:
Store the AP id — you will need it when creating invoices and payments.
Step 2 — Create Invoices
When Chargebee generates an invoice, call POST /invoices to create a corresponding invoice in AP.
Required scope: invoices:write
The due_date field accepts YYYY-MM-DD format and defaults to the creation date if omitted.
Step 3 — Collect Payment
AP supports four payment collection methods. Choose the one that fits your workflow:
Option A — Charge a saved card or bank account (server-side)
If the customer already has a saved payment method on file, charge it directly via POST /payments.
Required scope: payments:write
The payment_method field accepts card or standard_ach.
Option B — Per-invoice hosted payment link
Generate a one-click payment URL for a specific invoice and send it to the customer (for example, embed it in a Chargebee invoice email).
Required scope: invoices:read
Option C — Hosted payment page (checkout token)
Generate a short-lived JWT for AP's hosted checkout page. The customer lands on a fully hosted payment form without your backend handling card data.
Required scope: checkout:write
The token is valid for one hour. Redirect the customer to the AP checkout URL with the token.
Option D — Embedded checkout
Use the /checkout/v1 JWT-authenticated endpoints to embed the AP payment form directly inside your own UI. The checkout token from Option C is reused as the Bearer token for all /checkout/v1 calls.
Step 4 — Sync Payment Status Back to Chargebee via Webhooks
Subscribe to AP webhook topics to receive real-time payment status events. When AP fires invoice_paid, call the Chargebee API to mark the corresponding invoice paid.
Required scope: webhooks:write
Repeat for each topic you want to monitor. The topics most relevant to a Chargebee sync are:
invoice_paid
Invoice fully paid — use this to mark the invoice paid in Chargebee
payment_succeeded
Individual payment captured successfully
payment_failed
Payment attempt failed
payment_refunded
Refund issued
payment_chargeback
Dispute opened — may require intervention
payout_paid
Funds settled to your bank account
All webhook payloads share the same envelope structure:
For invoice_paid, entity_id is the AP invoice ID. Use data.customer_id to look up the corresponding Chargebee customer via the external_id you stored in Step 1.
Integration Flow Summary
Caveats
No turnkey Chargebee connector
AP does not provide a pre-built Chargebee integration. You write the glue code: listen for Chargebee invoice events, call the AP API, and handle AP webhooks to write status back to Chargebee. The integration is lightweight — typically two webhook handlers and a few API calls — but it is custom code.
AP must be the processor
AP processes every payment that flows through it on its own rails (card and ACH into payouts). Recording payments that were originally processed by a third-party processor — for example, keeping an existing processor for some invoices and only logging those transactions in AP — is not supported through the partner API. If you are migrating from another processor, AP replaces it entirely for the invoices you run through AP.
For questions about scopes, webhook delivery, and retry behavior, see the FAQ and Webhooks reference pages.
Last updated
Was this helpful?