curl --request POST \
--url https://api.tirdad.ai/v1/wallets/{id}/top-up \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"amount": "<string>",
"bonus_credits_expiry_date_utc": "<string>",
"bonus_credits_to_add": "<string>",
"coupons": [
{
"coupon_code": "<string>"
}
],
"credits_to_add": "<string>",
"description": "<string>",
"effective_date": "2023-11-07T05:31:56Z",
"expiry_date_utc": "<string>",
"force_sync_invoice": true,
"idempotency_key": "<string>",
"metadata": {},
"priority": 123
}
'from tirdad_sdk import Tirdad
with Tirdad(
api_key_auth="<YOUR_API_KEY_HERE>",
) as f_client:
res = f_client.wallets.top_up_wallet(id="<id>", transaction_reason="INVOICE_VOID_REFUND")
# Handle response
print(res)import { Tirdad } from "@tirdad/sdk";
const tirdad = new Tirdad({
apiKeyAuth: "<YOUR_API_KEY_HERE>",
});
async function run() {
const result = await tirdad.wallets.topUpWallet("<id>", {
transactionReason: "INVOICE_VOID_REFUND",
});
console.log(result);
}
run();package main
import(
"context"
tirdad "github.com/tirdad-billing/go-sdk/v2"
"github.com/tirdad-billing/go-sdk/v2/models/types"
"log"
)
func main() {
ctx := context.Background()
s := tirdad.New(
tirdad.WithSecurity("<YOUR_API_KEY_HERE>"),
)
res, err := s.Wallets.TopUpWallet(ctx, "<id>", types.TopUpWalletRequest{
TransactionReason: types.TransactionReasonInvoiceVoidRefund,
})
if err != nil {
log.Fatal(err)
}
if res.TopUpWalletResponse != nil {
// handle response
}
}{
"checkout_session": {
"action": "create_subscription",
"cancel_url": "<string>",
"cancelled_at": "2023-11-07T05:31:56Z",
"checkout_invoice_id": "<string>",
"checkout_payment_id": "<string>",
"checkout_status": "initiated",
"completed_at": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z",
"customer_id": "<string>",
"entity_creation_result": {
"entity_id": "<string>",
"status": "created"
},
"expires_at": "2023-11-07T05:31:56Z",
"failure_reason": "<string>",
"failure_url": "<string>",
"id": "<string>",
"idempotency_key": "<string>",
"metadata": {},
"next_poll_after_ms": 123,
"payment": {
"gateway": "<string>",
"id": "<string>",
"status": "INITIATED"
},
"payment_action": {
"type": "checkout_url",
"url": "<string>"
},
"payment_provider": "razorpay",
"stale": true,
"success_url": "<string>",
"terminal": true,
"updated_at": "2023-11-07T05:31:56Z"
},
"invoice_id": "<string>",
"wallet": {
"alert_settings": {
"alert_enabled": true,
"alert_threshold_type": "absolute",
"critical": {
"condition": "above",
"threshold": "<string>"
},
"info": {
"condition": "above",
"threshold": "<string>"
},
"warning": {
"condition": "above",
"threshold": "<string>"
}
},
"alert_state": "ok",
"auto_topup": {
"amount": 123,
"cooldown": "3600000000000",
"enabled": true,
"invoicing": true,
"threshold": 123
},
"balance": "<string>",
"config": {
"allowed_price_types": [
"ALL"
]
},
"conversion_rate": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"created_by": "<string>",
"credit_balance": "<string>",
"credits_available_breakdown": {
"free": "<string>",
"purchased": "<string>"
},
"currency": "<string>",
"customer_id": "<string>",
"description": "<string>",
"environment_id": "<string>",
"id": "<string>",
"metadata": {},
"name": "<string>",
"real_time_balance": "<string>",
"real_time_credit_balance": "<string>",
"status": "published",
"tenant_id": "<string>",
"topup_conversion_rate": "<string>",
"updated_at": "2023-11-07T05:31:56Z",
"updated_by": "<string>",
"wallet_status": "active",
"wallet_type": "PRE_PAID"
},
"wallet_transaction": {
"amount": "<string>",
"consumption_breakdown": [
{
"credit_transaction_id": "<string>",
"credits": "<string>"
}
],
"conversion_rate": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"created_by": "<string>",
"created_by_user": {
"email": "<string>",
"id": "<string>",
"metadata": {},
"name": "<string>",
"roles": [
"<string>"
],
"tenant": {
"billing_details": {
"address": {
"address_city": "<string>",
"address_country": "<string>",
"address_line1": "<string>",
"address_line2": "<string>",
"address_postal_code": "<string>",
"address_state": "<string>"
},
"email": "<string>",
"help_email": "<string>",
"phone": "<string>"
},
"created_at": "2023-11-07T05:31:56Z",
"id": "<string>",
"metadata": {},
"name": "<string>",
"status": "<string>",
"updated_at": "2023-11-07T05:31:56Z"
},
"type": "user"
},
"credit_amount": "<string>",
"credit_balance_after": "<string>",
"credit_balance_before": "<string>",
"credits_available": "<string>",
"currency": "<string>",
"customer": {
"address_city": "<string>",
"address_country": "<string>",
"address_line1": "<string>",
"address_line2": "<string>",
"address_postal_code": "<string>",
"address_state": "<string>",
"billing_currency": "<string>",
"contact": "<string>",
"contact_persons": [
{
"first_name": "<string>",
"department": "<string>",
"designation": "<string>",
"email": "<string>",
"id": "<string>",
"is_primary": true,
"last_name": "<string>",
"mobile": "<string>",
"salutation": "<string>"
}
],
"created_at": "2023-11-07T05:31:56Z",
"created_by": "<string>",
"email": "<string>",
"environment_id": "<string>",
"external_id": "<string>",
"id": "<string>",
"integrations": [
{
"created_at": "2023-11-07T05:31:56Z",
"created_by": "<string>",
"entity_id": "<string>",
"entity_type": "customer",
"environment_id": "<string>",
"id": "<string>",
"metadata": {},
"provider_entity_id": "<string>",
"provider_type": "<string>",
"status": "published",
"tenant_id": "<string>",
"updated_at": "2023-11-07T05:31:56Z",
"updated_by": "<string>"
}
],
"metadata": {},
"name": "<string>",
"status": "published",
"tax_treatment": "taxable",
"tenant_id": "<string>",
"timezone": "<string>",
"updated_at": "2023-11-07T05:31:56Z",
"updated_by": "<string>"
},
"customer_id": "<string>",
"description": "<string>",
"environment_id": "<string>",
"expiry_date": "2023-11-07T05:31:56Z",
"id": "<string>",
"idempotency_key": "<string>",
"metadata": {},
"parent_transaction_id": "<string>",
"priority": 123,
"reference_id": "<string>",
"reference_type": "PAYMENT",
"source_id": "<string>",
"source_type": "INVOICE",
"status": "published",
"tenant_id": "<string>",
"topup_conversion_rate": "<string>",
"transaction_reason": "INVOICE_PAYMENT",
"transaction_status": "pending",
"type": "credit",
"updated_at": "2023-11-07T05:31:56Z",
"updated_by": "<string>",
"wallet": {
"alert_settings": {
"alert_enabled": true,
"alert_threshold_type": "absolute",
"critical": {
"condition": "above",
"threshold": "<string>"
},
"info": {
"condition": "above",
"threshold": "<string>"
},
"warning": {
"condition": "above",
"threshold": "<string>"
}
},
"alert_state": "ok",
"auto_topup": {
"amount": 123,
"cooldown": "3600000000000",
"enabled": true,
"invoicing": true,
"threshold": 123
},
"balance": "<string>",
"config": {
"allowed_price_types": [
"ALL"
]
},
"conversion_rate": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"created_by": "<string>",
"credit_balance": "<string>",
"credits_available_breakdown": {
"free": "<string>",
"purchased": "<string>"
},
"currency": "<string>",
"customer_id": "<string>",
"description": "<string>",
"environment_id": "<string>",
"id": "<string>",
"metadata": {},
"name": "<string>",
"real_time_balance": "<string>",
"real_time_credit_balance": "<string>",
"status": "published",
"tenant_id": "<string>",
"topup_conversion_rate": "<string>",
"updated_at": "2023-11-07T05:31:56Z",
"updated_by": "<string>",
"wallet_status": "active",
"wallet_type": "PRE_PAID"
},
"wallet_id": "<string>"
}
}{
"code": "http_client_error",
"http_status_code": 123,
"message": "<string>"
}{
"code": "http_client_error",
"http_status_code": 123,
"message": "<string>"
}{
"code": "http_client_error",
"http_status_code": 123,
"message": "<string>"
}Top up wallet
Use when adding funds to a wallet (e.g. top-up, refund, or manual credit). Supports optional idempotency via reference.
curl --request POST \
--url https://api.tirdad.ai/v1/wallets/{id}/top-up \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"amount": "<string>",
"bonus_credits_expiry_date_utc": "<string>",
"bonus_credits_to_add": "<string>",
"coupons": [
{
"coupon_code": "<string>"
}
],
"credits_to_add": "<string>",
"description": "<string>",
"effective_date": "2023-11-07T05:31:56Z",
"expiry_date_utc": "<string>",
"force_sync_invoice": true,
"idempotency_key": "<string>",
"metadata": {},
"priority": 123
}
'from tirdad_sdk import Tirdad
with Tirdad(
api_key_auth="<YOUR_API_KEY_HERE>",
) as f_client:
res = f_client.wallets.top_up_wallet(id="<id>", transaction_reason="INVOICE_VOID_REFUND")
# Handle response
print(res)import { Tirdad } from "@tirdad/sdk";
const tirdad = new Tirdad({
apiKeyAuth: "<YOUR_API_KEY_HERE>",
});
async function run() {
const result = await tirdad.wallets.topUpWallet("<id>", {
transactionReason: "INVOICE_VOID_REFUND",
});
console.log(result);
}
run();package main
import(
"context"
tirdad "github.com/tirdad-billing/go-sdk/v2"
"github.com/tirdad-billing/go-sdk/v2/models/types"
"log"
)
func main() {
ctx := context.Background()
s := tirdad.New(
tirdad.WithSecurity("<YOUR_API_KEY_HERE>"),
)
res, err := s.Wallets.TopUpWallet(ctx, "<id>", types.TopUpWalletRequest{
TransactionReason: types.TransactionReasonInvoiceVoidRefund,
})
if err != nil {
log.Fatal(err)
}
if res.TopUpWalletResponse != nil {
// handle response
}
}{
"checkout_session": {
"action": "create_subscription",
"cancel_url": "<string>",
"cancelled_at": "2023-11-07T05:31:56Z",
"checkout_invoice_id": "<string>",
"checkout_payment_id": "<string>",
"checkout_status": "initiated",
"completed_at": "2023-11-07T05:31:56Z",
"created_at": "2023-11-07T05:31:56Z",
"customer_id": "<string>",
"entity_creation_result": {
"entity_id": "<string>",
"status": "created"
},
"expires_at": "2023-11-07T05:31:56Z",
"failure_reason": "<string>",
"failure_url": "<string>",
"id": "<string>",
"idempotency_key": "<string>",
"metadata": {},
"next_poll_after_ms": 123,
"payment": {
"gateway": "<string>",
"id": "<string>",
"status": "INITIATED"
},
"payment_action": {
"type": "checkout_url",
"url": "<string>"
},
"payment_provider": "razorpay",
"stale": true,
"success_url": "<string>",
"terminal": true,
"updated_at": "2023-11-07T05:31:56Z"
},
"invoice_id": "<string>",
"wallet": {
"alert_settings": {
"alert_enabled": true,
"alert_threshold_type": "absolute",
"critical": {
"condition": "above",
"threshold": "<string>"
},
"info": {
"condition": "above",
"threshold": "<string>"
},
"warning": {
"condition": "above",
"threshold": "<string>"
}
},
"alert_state": "ok",
"auto_topup": {
"amount": 123,
"cooldown": "3600000000000",
"enabled": true,
"invoicing": true,
"threshold": 123
},
"balance": "<string>",
"config": {
"allowed_price_types": [
"ALL"
]
},
"conversion_rate": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"created_by": "<string>",
"credit_balance": "<string>",
"credits_available_breakdown": {
"free": "<string>",
"purchased": "<string>"
},
"currency": "<string>",
"customer_id": "<string>",
"description": "<string>",
"environment_id": "<string>",
"id": "<string>",
"metadata": {},
"name": "<string>",
"real_time_balance": "<string>",
"real_time_credit_balance": "<string>",
"status": "published",
"tenant_id": "<string>",
"topup_conversion_rate": "<string>",
"updated_at": "2023-11-07T05:31:56Z",
"updated_by": "<string>",
"wallet_status": "active",
"wallet_type": "PRE_PAID"
},
"wallet_transaction": {
"amount": "<string>",
"consumption_breakdown": [
{
"credit_transaction_id": "<string>",
"credits": "<string>"
}
],
"conversion_rate": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"created_by": "<string>",
"created_by_user": {
"email": "<string>",
"id": "<string>",
"metadata": {},
"name": "<string>",
"roles": [
"<string>"
],
"tenant": {
"billing_details": {
"address": {
"address_city": "<string>",
"address_country": "<string>",
"address_line1": "<string>",
"address_line2": "<string>",
"address_postal_code": "<string>",
"address_state": "<string>"
},
"email": "<string>",
"help_email": "<string>",
"phone": "<string>"
},
"created_at": "2023-11-07T05:31:56Z",
"id": "<string>",
"metadata": {},
"name": "<string>",
"status": "<string>",
"updated_at": "2023-11-07T05:31:56Z"
},
"type": "user"
},
"credit_amount": "<string>",
"credit_balance_after": "<string>",
"credit_balance_before": "<string>",
"credits_available": "<string>",
"currency": "<string>",
"customer": {
"address_city": "<string>",
"address_country": "<string>",
"address_line1": "<string>",
"address_line2": "<string>",
"address_postal_code": "<string>",
"address_state": "<string>",
"billing_currency": "<string>",
"contact": "<string>",
"contact_persons": [
{
"first_name": "<string>",
"department": "<string>",
"designation": "<string>",
"email": "<string>",
"id": "<string>",
"is_primary": true,
"last_name": "<string>",
"mobile": "<string>",
"salutation": "<string>"
}
],
"created_at": "2023-11-07T05:31:56Z",
"created_by": "<string>",
"email": "<string>",
"environment_id": "<string>",
"external_id": "<string>",
"id": "<string>",
"integrations": [
{
"created_at": "2023-11-07T05:31:56Z",
"created_by": "<string>",
"entity_id": "<string>",
"entity_type": "customer",
"environment_id": "<string>",
"id": "<string>",
"metadata": {},
"provider_entity_id": "<string>",
"provider_type": "<string>",
"status": "published",
"tenant_id": "<string>",
"updated_at": "2023-11-07T05:31:56Z",
"updated_by": "<string>"
}
],
"metadata": {},
"name": "<string>",
"status": "published",
"tax_treatment": "taxable",
"tenant_id": "<string>",
"timezone": "<string>",
"updated_at": "2023-11-07T05:31:56Z",
"updated_by": "<string>"
},
"customer_id": "<string>",
"description": "<string>",
"environment_id": "<string>",
"expiry_date": "2023-11-07T05:31:56Z",
"id": "<string>",
"idempotency_key": "<string>",
"metadata": {},
"parent_transaction_id": "<string>",
"priority": 123,
"reference_id": "<string>",
"reference_type": "PAYMENT",
"source_id": "<string>",
"source_type": "INVOICE",
"status": "published",
"tenant_id": "<string>",
"topup_conversion_rate": "<string>",
"transaction_reason": "INVOICE_PAYMENT",
"transaction_status": "pending",
"type": "credit",
"updated_at": "2023-11-07T05:31:56Z",
"updated_by": "<string>",
"wallet": {
"alert_settings": {
"alert_enabled": true,
"alert_threshold_type": "absolute",
"critical": {
"condition": "above",
"threshold": "<string>"
},
"info": {
"condition": "above",
"threshold": "<string>"
},
"warning": {
"condition": "above",
"threshold": "<string>"
}
},
"alert_state": "ok",
"auto_topup": {
"amount": 123,
"cooldown": "3600000000000",
"enabled": true,
"invoicing": true,
"threshold": 123
},
"balance": "<string>",
"config": {
"allowed_price_types": [
"ALL"
]
},
"conversion_rate": "<string>",
"created_at": "2023-11-07T05:31:56Z",
"created_by": "<string>",
"credit_balance": "<string>",
"credits_available_breakdown": {
"free": "<string>",
"purchased": "<string>"
},
"currency": "<string>",
"customer_id": "<string>",
"description": "<string>",
"environment_id": "<string>",
"id": "<string>",
"metadata": {},
"name": "<string>",
"real_time_balance": "<string>",
"real_time_credit_balance": "<string>",
"status": "published",
"tenant_id": "<string>",
"topup_conversion_rate": "<string>",
"updated_at": "2023-11-07T05:31:56Z",
"updated_by": "<string>",
"wallet_status": "active",
"wallet_type": "PRE_PAID"
},
"wallet_id": "<string>"
}
}{
"code": "http_client_error",
"http_status_code": 123,
"message": "<string>"
}{
"code": "http_client_error",
"http_status_code": 123,
"message": "<string>"
}{
"code": "http_client_error",
"http_status_code": 123,
"message": "<string>"
}Body
Top up request
INVOICE_PAYMENT, FREE_CREDIT_GRANT, SUBSCRIPTION_CREDIT_GRANT, PURCHASED_CREDIT_INVOICED, PURCHASED_CREDIT_DIRECT, CREDIT_NOTE, CREDIT_EXPIRED, WALLET_TERMINATION, MANUAL_BALANCE_DEBIT, CREDIT_ADJUSTMENT, INVOICE_VOID_REFUND, PURCHASED_CREDIT_BONUS amount is the amount in the currency of the wallet to be added NOTE: this is not the number of credits to add, but the amount in the currency amount = credits_to_add * conversion_rate if both amount and credits_to_add are provided, amount will be ignored ex if the wallet has a conversion_rate of 2 then adding an amount of 10 USD in the wallet wil add 5 credits in the wallet
bonus_credits_expiry_date_utc is the expiry (UTC, full precision) applied to the bonus credits transaction. Independent of expiry_date_utc, which governs the purchase credits. Only honored when bonus credits are actually granted (explicit BonusCreditsToAdd or slab).
bonus_credits_to_add is an explicit override for the bonus credits granted alongside this purchase. When nil/omitted, the bonus is resolved from the tenant's bonus_credits_topup_config slabs (if enabled). When set, it must be greater than 0 and is used as-is, skipping slab resolution. To grant no bonus, omit this field entirely.