Topups represent transactions that add funds to your Tremendous account balance from a saved bank account or credit card. These transactions are initiated with an API request.
To use topups, first add a bank account or credit card to your Tremendous account in the dashboard.
Ensure that your chosen funding source has balance_funding in the usage_permissions field. This means it can be used to create topups:
{
"id": "NNCO40HLYN87",
"method": "credit_card",
"usage_permissions": [
"balance_funding"
],
"status": "active",
"meta": {
"accountholder_name": "Jane Doe",
"network": "Visa",
"last4": "1111",
"year": "2028",
"month": "12",
"expired": false,
"last_payment_failed_at": null
}
}
You must include an idempotency key when calling POST /topups; you can retry with the same key, and we guarantee at most one successful topup per key. If a previous request with that key was accepted (topup created), subsequent requests return 409 Conflict referencing the existing topup, but if the previous attempt failed (e.g., 4xx validation error), you can reuse the same key to resubmit corrected parameters.
When a topup is created, it will first show a status of created , meaning the topup request was successful and the transaction is underway. Once the funds have been added to the account balance, the topup status will change to fully_credited and the TOPUPS.FULLY_CREDITED webhook event will trigger (if your account has webhooks enabled).
Example Topup
{
"topup": {
"id": "XC82V7YJI4CC",
"amount": 200.35,
"processing_fee": 6.01,
"funding_source_id": "FUNDING-SOURCE-ID",
"status": "fully_credited",
"created_at": "2025-08-14T22:22:30.783Z",
"fully_credited_at": null,
"rejected_at": null,
"reversed_at": null,
"reversed_reason": null,
"idempotency_key": "abc1234"
}
}