API Reference
Base URL: https://fincobra.com
Checkout API
These endpoints are served by the checkout service and handle configuration, payment methods, invoices, payment pages, and API keys.
Configuration
| Method | Path | Auth | Description |
|---|---|---|---|
GET | /api/checkout/config | Session/Bearer | Get your checkout configuration |
PUT | /api/checkout/config | Session/Bearer | Create or update configuration |
POST | /api/checkout/config/webhook-secret/rotate | Session/Bearer | Rotate the webhook signing secret |
GET | /api/checkout/config/balance | Session/Bearer | Get wallet balance |
Payment methods
| Method | Path | Auth | Description |
|---|---|---|---|
GET | /api/checkout/payment-methods | Session/Bearer | List configured payment methods |
POST | /api/checkout/payment-methods | Session/Bearer | Create a payment method |
PUT | /api/checkout/payment-methods/:id | Session/Bearer | Update a payment method |
DELETE | /api/checkout/payment-methods/:id | Session/Bearer | Disable a payment method |
Invoices
POST /api/checkout/invoices can also return 403 when billing blocks new live invoice creation for the account.
| Method | Path | Auth | Description |
|---|---|---|---|
POST | /api/checkout/invoices | API Key or Session | Create a new invoice |
GET | /api/checkout/invoices | Session/Bearer | List invoices (with filters) |
GET | /api/checkout/invoices/export | Session/Bearer | Download filtered invoices as CSV |
GET | /api/checkout/invoices/stats | Session/Bearer | Get invoice count by status and exception state |
GET | /api/checkout/invoices/:id | API Key or Session | Get full invoice detail + QR code |
GET | /api/checkout/invoices/:id/payments | Session/Bearer | Get normalized payment events |
GET | /api/checkout/invoices/:id/status | API Key or Session | Get invoice status (lightweight) |
POST | /api/checkout/invoices/:id/exception/resolve | Session/Bearer | Resolve an open invoice exception |
POST | /api/checkout/address-transfer-withdrawals/confirm | Session/Bearer | Confirm a merchant-signed deterministic-address withdrawal transaction |
Payment page
| Method | Path | Auth | Description |
|---|---|---|---|
GET | /api/checkout/pay/:id | None | Public invoice data for payment page |
GET | /api/checkout/pay/:id/status | None | Lightweight public status for payment-page polling |
POST | /api/checkout/pay/:id/sync-wallet-payment | None | Sync a submitted wallet-contract transaction into invoice state |
API key management
| Method | Path | Auth | Description |
|---|---|---|---|
POST | /api/checkout/api-keys | Session/Bearer | Generate a new API key (max 3 active) |
GET | /api/checkout/api-keys | Session/Bearer | List active API keys |
DELETE | /api/checkout/api-keys/:keyId | Session/Bearer | Revoke an API key |
Authentication methods
| Method | Header/Cookie | Used for |
|---|---|---|
| API Key | X-Api-Key: fc_live_... | Integration-safe invoice routes |
| Session | session cookie (JWT) | Browser-based dashboard access |
| Bearer | Authorization: Bearer <jwt> | Server-to-server or mobile |
Common error format
All errors follow the same shape:
json
{
"error": "Human-readable error message"
}Validation errors may include additional detail:
json
{
"error": "Validation failed",
"details": { ... }
}HTTP status codes
| Code | Meaning |
|---|---|
200 | Success |
201 | Created (new invoice) |
400 | Validation error |
401 | Authentication failed |
404 | Resource not found |
409 | Conflict (duplicate payment method, duplicate external invoice ID, max keys reached) |
502 | Upstream service error (wallet balance) |
Rate limits
API key management endpoints have strict rate limits. Invoice creation and listing have moderate limits. If you exceed the limit, you'll receive a 429 Too Many Requests response.