Aviate Wallet

The Aviate Wallet feature provides several endpoints that allow you to manage the wallets associated with user acounts. This section documents the APIs exposed by the Aviate Wallet feature.

Before You Begin

Authentication

The Aviate Plugin uses a JWT based authentication mechanism. Thus, all the APIs listed in this document require a valid token. This can be obtained via the Auth API.

Resources

This section lists the models used by the Aviate Wallet APIs.

WalletInput

Represents a wallet input used to create a new wallet.

Name	Type	Generated by	Description
`kbAccountId`	`string` (UUID)	user	Kill Bill Account ID associated with the wallet
`currency`	`string`	user	Currency of the wallet (must match the account's default currency)
`initCredit`	`InitCredit`	user	Configuration initial wallet credits.
`topOff`	`TopOff`	user	Configuration for automatic wallet replenishment

Wallet

Represents a wallet associated with a customer account. It maintains the available and pending credit balances, top-off configuration, and credit history records.

Name	Type	Generated by	Description
`walletId`	`string` (UUID)	system	Unique identifier for the wallet
`kbAccountId`	`string` (UUID)	user	Kill Bill Account ID associated with the wallet
`currency`	`string`	user	Currency of the wallet (must match the account's default currency)
`balance`	`string`	system	Current available credit balance
`liveBalance`	`string`	system	Balance including credits reserved for the next invoice
`topOff`	`TopOff`	user	Configuration for automatic wallet replenishment
`records`	`WalletRecord[]`	system	Ledger entries for credit additions and consumptions

WalletRecord

Represents a credit transaction in the wallet ledger, including original and remaining amounts, optional expiration, and linkage to invoice/payment.

Name	Type	Generated by	Description
`recordId`	`integer`	system	Unique identifier for the ledger entry
`creditType`	`string`	user	Type of credit (`CREDIT_PAID`, `CREDIT_FREE`, `CREDIT_USED`)
`originAmount`	`string`	system	Original credited amount
`remainAmount`	`string`	system	Remaining unused portion of the credit
`description`	`string`	user	Optional description or memo
`expDate`	`string` (ISO datetime)	user	Optional expiration timestamp
`parentRecordId`	`integer`	system	Reference to the original credit record (for partial consumption)
`kbInvoiceId`	`string` (UUID)	system	Associated Kill Bill invoice ID
`kbPaymentId`	`string` (UUID)	system	Associated Kill Bill payment ID (if invoice was paid)

CreditInput

Payload used to add credits to a wallet, either manually or via automated top-off.

Name	Type	Generated by	Description
`creditType`	`string`	user	Type of credit (`CREDIT_PAID`, `CREDIT_FREE`)
`expDate`	`string` (ISO datetime)	user	Optional expiration date for the credit

TopOff

Configuration model for automatically replenishing wallet credits when they fall below a threshold.

Name	Type	Generated by	Description
`topOffType`	`string`	user	Mode of top-off (`TOP_OFF_FIXED` or `TOP_OFF_TARGET`)
`lowWatermark`	`string`	user	Threshold below which top-off is triggered
`amount`	`string`	user	Amount of credit to add when top-off is triggered
`expDurationUnit`	`string`	user	Unit for credit expiration (`DAYS`, `WEEKS`, `MONTHS` or `YEARS`)
`expDurationLength`	`integer`	user	Duration length for credit expiration from the time of issuance

Wallet APIs

Create a Wallet

Create a new Wallet for a particular user Account. At this stage, we only support one wallet per-account and the currency needs to match the user Account's currency.

HTTP Request

POST /plugins/aviate-plugin/v1/wallet

Example Request:

curl -X POST \
     -H "Authorization: Bearer ${ID_TOKEN}" \
     -H 'X-Killbill-ApiKey: bob' \
     -H 'X-Killbill-ApiSecret: lazar' \
     -H 'Content-Type: application/json' \
     -d '{
           "kbAccountId": "85661371-7587-4d1a-8ece-d566ea77dbcb",
           "currency": "USD",
           "initCredit": {
             "creditType": "CREDIT_PAID",
             "amount": "100.00",
             "expDate": "2025-12-31T00:00:00Z"
           },
           "topOff": {
             "topOffType": "TOP_OFF_TARGET",
             "lowWatermark": "20.00",
             "amount": "40.00",
             "expDurationUnit": "MONTHS",
             "expDurationLength": 3
           }
         }' \
     http://127.0.0.1:8080/plugins/aviate-plugin/v1/wallet

Example Response:

In the following response, the wallet was created but the payment associated with initial paid credits failed so the error is returned to the user. Retrying the payment against the invoice with a valid payment method would activate the credits.

{
  "wallet": {
    "walletId": "cba7aef9-085a-47de-abb5-0888da8e9761",
    "kbAccountId": "85661371-7587-4d1a-8ece-d566ea77dbcb",
    "currency": "USD",
    "balance": "0",
    "liveBalance": "-1.000000000",
    "topOff": {
      "topOffType": "TOP_OFF_TARGET",
      "lowWatermark": "20.000000000",
      "amount": "40.000000000",
      "expDurationUnit": "MONTHS",
      "expDurationLength": 3
    },
    "records": [
      {
        "recordId": 123,
        "creditType": "CREDIT_PAID",
        "originAmount": "100.000000000",
        "remainAmount": "100.000000000",
        "description": "Initial amount",
        "expDate": "2025-12-31T00:00",
        "parentRecordId": 0,
        "kbInvoiceId": "5b31513e-5d2a-4d47-80a1-fa5dea355882",
        "kbPaymentId": ""
      }
    ]
  },
  "status": "WALLET_PAYMENT_FAILED",
  "errorMessage": "Payment failed for invoiceId=5b31513e-5d2a-4d47-80a1-fa5dea355882"
}

Request Body

A WalletInput data.

Query Parameters

None

Response

If successful, returns a Wallet object.

Add credits to a Wallet

Add credits to a previously created wallet.

HTTP Request

PUT /plugins/aviate-plugin/v1/wallet/{walletId}/credit

Example Request:

curl -X PUT \
     -H "Authorization: Bearer ${ID_TOKEN}" \
     -H 'X-Killbill-ApiKey: bob' \
     -H 'X-Killbill-ApiSecret: lazar' \
     -H 'Content-Type: application/json' \
     -d '{
           "creditType": "CREDIT_FREE",
           "amount": "25.00",
           "expDate": "2025-09-01T00:00:00Z"
         }' \
     http://127.0.0.1:8080/plugins/aviate-plugin/v1/wallet/cba7aef9-085a-47de-abb5-0888da8e9761/credit

Example Response:

{"status":"WALLET_SUCCESS","errorMessage":""}

Modify topOff Wallet configuration

Modify or add a topOff configuration for a previously created wallet.

HTTP Request

PUT /plugins/aviate-plugin/v1/wallet/{walletId}/topOffConfig

Example Request:

curl -X PUT \
     -H "Authorization: Bearer ${ID_TOKEN}" \
     -H 'X-Killbill-ApiKey: bob' \
     -H 'X-Killbill-ApiSecret: lazar' \
     -H 'Content-Type: application/json' \
     -d '{
           "topOffType": "TOP_OFF_TARGET",
           "lowWatermark": "10.00",
           "amount": "50.00",
           "expDurationUnit": "MONTHS",
           "expDurationLength": 6
         }' \
     http://127.0.0.1:8080/plugins/aviate-plugin/v1/wallet/cba7aef9-085a-47de-abb5-0888da8e9761/topOffConfig

Example Response:

Returns 200 OK if successful.

Retrieve Wallets for user Account

Retrieve all the wallets for a particular Account.

HTTP Request

GET /plugins/aviate-plugin/v1/wallet/{accountId}

Example Request:

curl -X GET \
     -H "Authorization: Bearer ${ID_TOKEN}" \
     -H 'X-Killbill-ApiKey: bob' \
     -H 'X-Killbill-ApiSecret: lazar' \
     http://127.0.0.1:8080/plugins/aviate-plugin/v1/wallet/85661371-7587-4d1a-8ece-d566ea77dbcb

Example Response:

[
  {
    "walletId": "cba7aef9-085a-47de-abb5-0888da8e9761",
    "kbAccountId": "85661371-7587-4d1a-8ece-d566ea77dbcb",
    "currency": "USD",
    "balance": "25.000000000",
    "liveBalance": "-1.000000000",
    "topOff": {
      "topOffType": "TOP_OFF_TARGET",
      "lowWatermark": "10.000000000",
      "amount": "50.000000000",
      "expDurationUnit": "MONTHS",
      "expDurationLength": 6
    },
    "records": [
      {
        "recordId": 123,
        "creditType": "CREDIT_PAID",
        "originAmount": "100.000000000",
        "remainAmount": "100.000000000",
        "description": "Initial amount",
        "expDate": "2025-12-31T00:00",
        "parentRecordId": 0,
        "kbInvoiceId": "5b31513e-5d2a-4d47-80a1-fa5dea355882",
        "kbPaymentId": ""
      },
      {
        "recordId": 124,
        "creditType": "CREDIT_FREE",
        "originAmount": "25.000000000",
        "remainAmount": "25.000000000",
        "description": "Add credits",
        "expDate": "2025-09-01T00:00",
        "parentRecordId": 0,
        "kbInvoiceId": "",
        "kbPaymentId": ""
      }
    ]
  }
]

Example Response:

Returns 200 OK if successful.