Skip to main content

Wallets and Topups

Credyt's unique architecture unifies multiple billing models under a core primitive, the customer wallet. Every customer has one wallet, and that wallet can hold multiple accounts, each dedicated to a specific asset. Accounts are created automatically when a customer is subscribed to a product and can represent both fiat currencies or any custom assets you define.

Keeping wallets funded is critical for continuous product use. Credyt gives you two complementary ways to accept top-up payments, powered by Stripe.

Hybrid Billing

If you have a hybrid billing setup that leverages an external provider, be sure to read our Adjustments guide.

Option 1: Customer Billing Portal​

The easiest way for your customers to add funds is through the hosted Billing Portal, a self-service billing centre where they can check their balances, manage auto top-ups (recharge), and monitor their product usage:

  • Customers initiate top-ups directly in the portal
  • The only integration step is generating a session link and redirecting the customer
  • No sign-up is required on the customer side
  • The customer is responsible for defining the top-up amount
  • For custom assets, the default exchange rate is used

Read more about the billing portal here.

Create a Billing Portal Session​

API Reference

POST https://api.credyt.ai/billing-portal/sessions
{
  "customer_id": "{{customerId}}",
  "return_url": "https://glitch.ai/account",
  "failure_url": "https://glitch.ai/callbacks/credyt/failure"
}

Response

{
  "redirect_url": "https://billing.credyt.ai/api/sign-in?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
  "expires_at": "2025-10-18T07:23:43Z"
}

Redirect the customer to the redirect_url, where the customer can view their balance and initiate a top-up.

Option 2: Top-up API​

Use the Top-up API when you want more control over the top-up flow, for example, if you choose to embed a top-up CTA directly within your product.

  • You collect or define the amount to top up in your own product
  • Your backend calls the Top-up API to create a checkout session
  • Credyt returns a redirect_url that navigates directly to the top-up payment page
  • After payment, the customer is returned to the customer billing portal
  • When topping up custom assets you have the option to override the default exchange rate
    • Use this to implement tiering or incentives

Initiate a top-up​

API Reference

POST https://api.credyt.ai/top-ups
{
  "customer_id": "cust_473cr1y0ghbyc3m1yfbwvn3nxx",
  "amount": 25.0,
  "currency": "USD",
  "description": "Video Promotion Credits",
  "return_url": "https://glitch.ai/account",
  "failure_url": "https://glitch.ai/callbacks/credyt-failure"
}

Response

{
  "id": "top_473cr1y0ghbyc3m1yfbwvn3nxx",
  "status": "initiated",
  "redirect_url": "https://billing.credyt.ai/api/sign-in?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
  "created_at": "2024-07-29T15:51:28.071Z",
  "expires_at": "2024-07-29T15:51:28.071Z"
}

Redirects the customer to the redirect_url to complete the top-up payment.

Check the Wallet Balance​

API Reference

After we receive confirmation that payment has succeeded the customer's wallet account balance will be updated. Typically this happens before the customer is redirected back to the billing portal.

You can query a customer's wallet balances at any time, via the Customer Wallet API.

curl -L 'https://api.credyt.ai/customers/:customerId/wallet' \
-H 'Accept: application/json' \
-H 'X-CREDYT-API-KEY: <CREDYT-API-KEY>'

Response

{
  "accounts": [
    {
      "id": "default:USD",
      "name": "default",
      "asset": "USD",
      "available": 14.566678
    },
    {
      "id": "default:TOK",
      "name": "default",
      "asset": "TOK",
      "available": 993450234
    }
  ]
}

Testing​

To make testing easier, all payments in test mode are processed through Credyt's default test Stripe account. We'll be adding the ability to use your own Stripe account for testing in the near future.

When testing payments interactively with Stripe, you can use their standard test cards, for example:

  • Number: 4242 4242 4242 4242
  • Expiry: Any future month/year (e.g. 12/34)
  • CVC: any three‑digit CVC e.g. 123
  • Any values for the other fields

For the full list of test card numbers and scenarios, see Stripe’s docs.