# Creddot Docs


- **Get started**
- [Introduction](/docs): Accept payments, send money and sell bills from your own product with the Creddot API.
- [Quickstart](/docs/quickstart): Take your first test payment in about ten minutes.
- [Authentication](/docs/authentication): API keys, secrets, permissions and the headers every request needs.
- [Test mode](/docs/test-mode): Build and test every flow with test keys and simulated outcomes.
- [Amounts, idempotency and errors](/docs/conventions): Conventions shared by every endpoint.

- **Guides**
- [Accept payments with hosted checkout](/docs/guides/accept-payments): Checkout sessions in depth, from creating one to fulfilling the order.
- [Webhooks](/docs/guides/webhooks): Get told when payments, payouts and subscriptions change, and verify every event.
- [Bank transfer and USSD from your own UI](/docs/guides/bank-transfer-ussd): Server-side collections when you show payment instructions yourself.
- [Payouts](/docs/guides/payouts): Send money from your Creddot wallet to any Nigerian bank account.
- [Bills](/docs/guides/bills): Sell airtime, data, electricity, TV and internet from your wallet.
- [Payment links and invoices](/docs/guides/payment-links-invoices): Collect payments without building a checkout page.
- [Subscriptions](/docs/guides/subscriptions): Recurring billing with plans, renewals, reminders and grace periods.
- [Refunds](/docs/guides/refunds): Return a full or partial payment to the customer.
- [Go live checklist](/docs/guides/go-live): What to check before switching to live keys.

- **Reference**
- API reference
  - [API reference](/docs/api-reference): Every endpoint of the Creddot merchant API, with a Try it panel.
  - Bills
    - [Get a bill payment and its token](/docs/api-reference/bills/get-a-bill-payment-and-its-token)
    - [List bill categories](/docs/api-reference/bills/list-bill-categories): Uses the environment attached to the API key. VTpass is selected by default; pass FLUTTERWAVE to use the secondary provider.
    - [List bill payments](/docs/api-reference/bills/list-bill-payments): The API-key environment is authoritative; an environment query value is ignored.
    - [List bill products or variations](/docs/api-reference/bills/list-bill-products-or-variations)
    - [List billers/services for a provider category](/docs/api-reference/bills/list-billers-services-for-a-provider-category)
    - [Pay a bill from the merchant wallet](/docs/api-reference/bills/pay-a-bill-from-the-merchant-wallet): Reserves the selected environment wallet before dispatch. Success consumes the reservation, a definite failure releases it, and an unknown provider outcome remains PROCESSING for requery. Payments are never automatically retried through the secondary provider.
    - [Requery a pending bill payment](/docs/api-reference/bills/requery-a-pending-bill-payment): Checks the original provider only and finalizes reserved wallet funds when a definitive outcome is returned.
    - [Validate a bill customer](/docs/api-reference/bills/validate-a-bill-customer): Validates a meter, smartcard, internet account, or phone number with the selected provider before payment.
  - Checkout
    - [Create a hosted checkout session](/docs/api-reference/checkout/create-a-hosted-checkout-session): Creates a single-use hosted checkout in the API key environment. Redirect the customer to checkoutUrl. Card details are collected only by Creddot checkout; they never pass through the merchant server.
    - [Get a hosted checkout session](/docs/api-reference/checkout/get-a-hosted-checkout-session): Requires collections:create. Use on your return page or after a webhook to confirm the order is paid: status PAID means a payment succeeded. Scoped to the API key merchant and environment.
  - Collections
    - [Initialize a server-side collection](/docs/api-reference/collections/initialize-a-server-side-collection): Requires collections:create. Supports bank transfer, USSD, and QR without accepting raw card data. Use POST /v1/checkout/sessions for card-capable hosted checkout. Atomically records a pending transaction before provider initialization. Retry with the same key and body to replay the initial response.
  - Customers
    - [Create a customer in the API key environment](/docs/api-reference/customers/create-a-customer-in-the-api-key-environment)
    - [Enable or disable a customer](/docs/api-reference/customers/enable-or-disable-a-customer)
    - [Get a customer](/docs/api-reference/customers/get-a-customer)
    - [List customers in the API key environment](/docs/api-reference/customers/list-customers-in-the-api-key-environment)
    - [Soft-delete a customer](/docs/api-reference/customers/soft-delete-a-customer)
    - [Update a customer](/docs/api-reference/customers/update-a-customer)
  - Invoices
    - [Create an invoice draft](/docs/api-reference/invoices/create-an-invoice-draft)
    - [Get an invoice](/docs/api-reference/invoices/get-an-invoice)
    - [List invoices in the API key environment](/docs/api-reference/invoices/list-invoices-in-the-api-key-environment)
    - [Send an invoice and create its checkout link](/docs/api-reference/invoices/send-an-invoice-and-create-its-checkout-link)
  - Payment links
    - [Create a reusable Pay Link](/docs/api-reference/payment-links/create-a-reusable-pay-link)
    - [Disable a Pay Link](/docs/api-reference/payment-links/disable-a-pay-link)
    - [Get Pay Link details and progress](/docs/api-reference/payment-links/get-pay-link-details-and-progress)
    - [List Pay Links in the API key environment](/docs/api-reference/payment-links/list-pay-links-in-the-api-key-environment)
    - [Record an offline payment against a Pay Link](/docs/api-reference/payment-links/record-an-offline-payment-against-a-pay-link)
    - [Update an active Pay Link](/docs/api-reference/payment-links/update-an-active-pay-link)
    - [Void an offline Pay Link payment](/docs/api-reference/payment-links/void-an-offline-pay-link-payment)
  - Payouts
    - [Queue a payout](/docs/api-reference/payouts/queue-a-payout): Requires payouts:create. Validates the recipient, atomically reserves funds, and writes a durable payout-dispatch record before BullMQ sends it to Paga. Provider calls are never retried automatically after dispatch begins.
    - [Validate a payout recipient](/docs/api-reference/payouts/validate-a-payout-recipient): Requires payouts:create. Uses the environment on the API key and Paga Business Validate Deposit to Bank. Simulated sandbox behavior is available only when PAGA_SANDBOX_SIMULATE=true.
  - Public checkout
    - [Read public checkout payment status](/docs/api-reference/public-checkout/read-public-checkout-payment-status): No authentication. Poll this payer-safe endpoint after starting a Pay Link, event, Split Pay, or storefront order payment. It returns current database status immediately after callback or reconciliation settlement and never exposes payer contact details, provider references, or internal IDs.
  - Refunds
    - [Get a refund request](/docs/api-reference/refunds/get-a-refund-request)
    - [List refund requests in the API key environment](/docs/api-reference/refunds/list-refund-requests-in-the-api-key-environment)
    - [Request a full or partial collection refund](/docs/api-reference/refunds/request-a-full-or-partial-collection-refund): Creates a REQUESTED refund for admin review. This call never dispatches funds directly.
  - Subscription plans
    - [Archive a subscription plan](/docs/api-reference/subscription-plans/archive-a-subscription-plan)
    - [Create a subscription plan](/docs/api-reference/subscription-plans/create-a-subscription-plan)
    - [Get a subscription plan](/docs/api-reference/subscription-plans/get-a-subscription-plan)
    - [List subscription plans in the API key environment](/docs/api-reference/subscription-plans/list-subscription-plans-in-the-api-key-environment)
    - [Update a subscription plan](/docs/api-reference/subscription-plans/update-a-subscription-plan)
  - Subscriptions
    - [Activate a draft subscription](/docs/api-reference/subscriptions/activate-a-draft-subscription)
    - [Add a customer to a subscription](/docs/api-reference/subscriptions/add-a-customer-to-a-subscription)
    - [Cancel a subscription](/docs/api-reference/subscriptions/cancel-a-subscription)
    - [Create a subscription](/docs/api-reference/subscriptions/create-a-subscription)
    - [Delete an unused draft subscription](/docs/api-reference/subscriptions/delete-an-unused-draft-subscription)
    - [Get subscription details](/docs/api-reference/subscriptions/get-subscription-details)
    - [List a subscription's subscribers](/docs/api-reference/subscriptions/list-a-subscription-s-subscribers): Filter by email to check one customer. Accepts the subscription ID or code (SUB-001). Up to 100, newest first.
    - [List subscriptions in the API key environment](/docs/api-reference/subscriptions/list-subscriptions-in-the-api-key-environment)
    - [Read one subscriber](/docs/api-reference/subscriptions/read-one-subscriber): active is true while the customer has paid for the current cycle (ACTIVE) or is inside the grace period (OVERDUE).
    - [Update a subscriber status](/docs/api-reference/subscriptions/update-a-subscriber-status)
    - [Update a subscription](/docs/api-reference/subscriptions/update-a-subscription)
  - Transactions
    - [Find a transaction by merchant reference](/docs/api-reference/transactions/find-a-transaction-by-merchant-reference): Requires transactions:read. Scoped to the API key merchant and environment. Use after uncertain responses; never resend with a new key.
    - [List transactions](/docs/api-reference/transactions/list-transactions): Lists transactions in the API key environment with currency, status, type, channel, date, amount, search, sorting, and pagination filters.
    - [Read current transaction status](/docs/api-reference/transactions/read-current-transaction-status): Requires transactions:read. Creation retries replay the original response; this endpoint returns current status.
    - [Read wallet balances](/docs/api-reference/transactions/read-wallet-balances): Requires wallets:read. Pending is unconfirmed collection money; reserved is money held for payouts; only available can be spent.
    - [Simulate a final sandbox collection or payout outcome](/docs/api-reference/transactions/simulate-a-final-sandbox-collection-or-payout-outcome): Requires sandbox:simulate and a sandbox API key. SUCCESS posts the entry; FAILED reverses it and releases payout funds. Repeating an outcome is safe; changing a terminal outcome returns 409. No real money moves.
  - Virtual accounts
    - [List dedicated collection accounts](/docs/api-reference/virtual-accounts/list-dedicated-collection-accounts): Requires virtual-accounts:read. Results are scoped to the API key environment. Provision accounts through the Business owner/admin API.
    - [Simulate an incoming transfer to a sandbox virtual account](/docs/api-reference/virtual-accounts/simulate-an-incoming-transfer-to-a-sandbox-virtual-account): Requires sandbox:simulate and a sandbox API key. Immediately creates and posts a collection ledger entry and credits available balance. This route simulates a verified bank notification; it does not accept or process real transfers.
- [AI tools and MCP](/docs/ai-tools): Connect Claude, Cursor, VS Code and other AI assistants to the Creddot docs.