Skip to main content
POST
/
api
/
credits
/
sessions
cURL
curl --request POST \
  --url https://api.recoupable.com/api/credits/sessions \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "credits": 250,
  "successUrl": "https://chat.recoupable.com?credits=success",
  "accountId": "123e4567-e89b-12d3-a456-426614174000"
}
'
{
  "paymentIntentId": "pi_3O1a2b3c4d5e6f7g_h8i9j0kL",
  "creditsPurchased": 250,
  "totalCents": 289,
  "id": "cs_test_a1b2c3d4e5f6g7h8i9j0",
  "url": "https://checkout.stripe.com/pay/cs_test_a1b2c3d4e5f6g7h8i9j0"
}

Authorizations

​
x-api-key
string
header
required

Your Recoup API key. Learn more.

Body

application/json

Top-up parameters

​
credits
integer
required

The number of credits to purchase. One credit equals one US cent ($0.01), so the value of the credits in USD is credits / 100. Example: 250 is $2.50 worth of credits (the customer is also charged a Stripe processing fee on top).

Required range: x >= 1
Example:

250

​
successUrl
string<uri>

The URL to redirect the customer to after a successful Stripe Checkout payment. Only used when the response is a Checkout fallback (no card on file or 3-D Secure required) — ignored when the card on file is charged directly. Defaults to a generic Recoup success page if omitted.

Example:

"https://chat.recoupable.com?credits=success"

​
accountId
string<uuid>

UUID of the account to create the session for. Only applicable when the authenticated account has admin access to multiple accounts. If not provided, creates a session for the API key's own account.

Example:

"123e4567-e89b-12d3-a456-426614174000"

Response

Top-up initiated successfully. Some fields are conditional on which path was taken — see each field's description.

Top-up response. Two paths share this shape — clients can discriminate on the presence of url (Checkout fallback) vs paymentIntentId (auto-charged).

​
paymentIntentId
string

Auto-charge path only. The Stripe PaymentIntent ID for the off-session charge. Useful for reconciliation and support. Omitted on the Checkout fallback path.

Example:

"pi_3O1a2b3c4d5e6f7g_h8i9j0kL"

​
creditsPurchased
integer

Auto-charge path only. The number of credits purchased, matching the credits request field. These credits are added to the account's balance asynchronously via Stripe webhook (typically within seconds). Omitted on the Checkout fallback path.

Required range: x >= 1
Example:

250

​
totalCents
integer

Auto-charge path only. Total amount in cents charged to the saved card, equal to creditsPurchased plus the Stripe processing fee. Omitted on the Checkout fallback path.

Required range: x >= 1
Example:

289

​
id
string

Checkout fallback only. The Stripe Checkout Session ID. Omitted on the auto-charge path.

Example:

"cs_test_a1b2c3d4e5f6g7h8i9j0"

​
url
string<uri>

Checkout fallback only. The hosted Stripe Checkout URL — redirect the customer here to enter card details and complete payment. Omitted on the auto-charge path.

Example:

"https://checkout.stripe.com/pay/cs_test_a1b2c3d4e5f6g7h8i9j0"