Grant credits (Default mode)

Learn how to grant or top up user balances programmatically using the Deposit API. This is useful for signup bonuses, subscription renewals, refunds/goodwill, migrations, or promotions.

This guide applies to Default mode (you control payments). In Shared mode, users fund a hosted, cross‑app wallet and you don’t deposit credits directly. See Shared Mode.

Prerequisites

Default mode enabled and your Paywalls API key configured.
A stable, pseudonymous user id selected. See User Identity.

Call the Deposit API

Use POST /v1/user/balance/deposit/post. Amount is a string in your configured currency (e.g., “10”).

cURL
Node.js (fetch)
Python (requests)

curl -X POST https://api.paywalls.ai/v1/user/balance/deposit \
-H "Authorization: Bearer $PAYWALLS_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $UNIQUE_EVENT_ID" \
-d '{
	"user": "user_123",
	"amount": "10",
	"metadata": {
		"reason": "signup_bonus",
		"source": "marketing_campaign_2025_09"
	}
}'

const res = await fetch("https://api.paywalls.ai/v1/user/balance/deposit", {
method: "POST",
headers: {
	Authorization: `Bearer ${process.env.PAYWALLS_API_KEY}`,
	"Content-Type": "application/json"
},
body: JSON.stringify({
	user: "user_123",
	amount: "10",
	metadata: { reason: "signup_bonus", campaign: "fall_launch" },
}),
});
const json = await res.json();

import os, requests, json

r = requests.post(
"https://api.paywalls.ai/v1/user/balance/deposit",
headers={
"Authorization": f"Bearer {os.environ['PAYWALLS_API_KEY']}",
"Content-Type": "application/json"
},
data=json.dumps({
"user": "user_123",
"amount": "10",
"metadata": {"reason": "signup_bonus"}
}),
)
data = r.json()

Verify and display balances

The deposit appears in the Ledger immediately.
Optionally fetch the updated balance for display using GET /user/balance.

Include Idempotency-Key so repeated webhooks or retries do not create duplicate credits.

Common scenarios

Grant a one‑time credit when a new account is created.

Amount: small trial amount (e.g., “1.00”)
Metadata: {"reason":"signup_bonus","signup_event":"evt_signup_123"}

// Example: in your user-created handler
await fetch("https://api.paywalls.ai/v1/user/balance/deposit", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PAYWALLS_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": `signup:${userId}`, // stable for this logical event
  },
  body: JSON.stringify({
    user: userId,
    amount: "1.00",
    metadata: { reason: "signup_bonus" },
  }),
});

2. Subscription renewal credits

Credit users monthly after your PSP confirms payment (e.g., Stripe invoice.payment_succeeded).

Amount: your plan’s included usage value (e.g., “10.00”)
Metadata: include invoice id, plan, period_start/end for reconciliation

// Example: in your Stripe webhook handler (invoice.payment_succeeded)
const {
  id: invoiceId,
  payment_intent: pi,
  customer,
  lines,
} = event.data.object;
await fetch("https://api.paywalls.ai/v1/user/balance/deposit", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PAYWALLS_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": invoiceId, // prevents duplicates on retries
  },
  body: JSON.stringify({
    user: mapStripeCustomerToUserId(customer),
    amount: planIncludedCreditsAmount(lines), // e.g., "10.00"
    metadata: {
      reason: "subscription_included_credits",
      invoice_id: invoiceId,
      payment_intent: pi,
    },
  }),
});

See Connect Stripe for Default mode setup.

No‑code (Zapier, n8n)

You can call the Deposit API from no‑code tools to credit balances without custom code.

Method: POST https://api.paywalls.ai/v1/user/balance/deposit
Headers:
- Authorization: Bearer PAYWALLS_API_KEY
- Content-Type: application/json
Body: { "user": "...", "amount": "2.00", "metadata": { ... } }

Prefer injecting a stable user from your CRM/DB. For no‑code patterns, see No-code: Zapier, n8n, and other flows.

Best practices

Idempotency first: reuse the same Idempotency-Key on retries/webhook replays.
Pseudonymous identity: avoid PII in user ids. See User Identity.
Don’t expose keys: keep PAYWALLS_API_KEY server/edge only.
Reconciliation: store invoice/payment ids in metadata. Use the Ledger and Analytics & Reporting.
Testing: use Stripe test mode in Default mode staging. See Test keys & Environments.

Deposit API

Reference for POST /user/balance/deposit.

User balance (GET)

Fetch and display a user’s current balance.

Pricing & Metering

How charges are computed and written to the ledger.

Getting started

Core concepts

How‑to guides

SDKs & Integrations

More

Common scenarios

2. Subscription renewal credits

No‑code (Zapier, n8n)

Best practices

Deposit API

User balance (GET)

Pricing & Metering

​Common scenarios

​1. Signup bonus on registration

​2. Subscription renewal credits

​No‑code (Zapier, n8n)

​Best practices

​Related

Deposit API

User balance (GET)

Pricing & Metering

Common scenarios

1. Signup bonus on registration

2. Subscription renewal credits

No‑code (Zapier, n8n)

Best practices

Related