Topups

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).

Credit card topups are usually credited instantly. For bank account topups, the full amount may not be available right away. A portion of the topups may be credited immediately (reflected in instant_credit_amount), with the remainder settling later (settled_amount and expected_settlement_at). While funds are settling, the status is partially_credited and the TOPUPS.PARTIALLY_CREDITED webhook fires. Once settlement completes, the status changes to fully_credited and TOPUPS.FULLY_CREDITED fires.

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",
		"instant_credit_amount": 200.35,
    "settled_amount": 0,
    "expected_settlement_at": null
  }
}