Retrieving Wallet Balance

Another version of this information is available

If you're new to Tilia services, another version of this information is available in the Tutorials section of these docs, which might be an easier place to start.

Money is transferred to and from wallets through Tilia transactions. Depending on your configuration and the type of currency, money stored in wallets can be used as a payment method, or may be transferred to the user via a payout.

Wallet balance is stored as the smallest denomination of the associated currency. In the samples below, the currency is USD so the wallet balance is in cents.

You can retrieve an account's wallet balance by calling the /payment_methods endpoint. You can also use this endpoint to retrieve the wallet's id, which is required for Requesting Payouts.

attention

In general, you will not use this method to retrieve other payment methods, such as an account's PayPal or credit card information. Instead, you will use the Tilia web UI in the context of a purchase flow.

To retrieve account wallet balance

Retrieving wallet balance requires an API token with the scope read_payment_methods.

To check an account's wallet balance, submit a GET request with the account_id to the /payment_methods endpoint.

Copy
Copied
curl --location --request GET https://payments.tilia-inc.com/v1/{account_id}/payment_methods \
--header 'Authorization: Bearer <Access_Token>' \
--header 'Content-Type: application/json' \

The response JSON returns an array of payment method objects for the specified account. You can obtain the wallet balance by locating the object with a value of wallet in the provider field.

The wallet_balance field tells you the amount available in the wallet, and processing_currency tells you the associated currency.

Two sample responses are included below. The first response is for an account with two stored payment methods: a USD wallet and a credit card. The second response is for an account with only a USD wallet.

Account with USD Wallet and Credit Card

Copy
Copied
{
    "status": "Success",
    "message": [],
    "codes": [],
    "payload": [
        {
			"id": "d3da84e7-a203-4453-a016-f190b9f0dae3",
			"account_id": "ebcbc9c4-7c1b-47df-9ec4-1bcfa48e0344",
			"method_class": "registration",
			"display_string": "USD Wallet",
			"provider": "wallet",
			"psp_reference": "99c63b85-e1c1-4b11-82b1-1cccaad86f60",
			"psp_hash_code": "",
			"processing_currency": "USD",
			"pm_state": "ACTIVE",
			"integrator": "acme",
			"created": "2020-08-14 10:59:59",
			"updated": "2020-08-14 10:59:59",
			"wallet_balance": "2457",
			"payment_method_id": "",
			"provider_data": {
				"wallet_id": "99c63b85-e1c1-4b11-82b1-1cccaad86f60",
				"wallet_balance": "2457"
			}
		},
        {
			"id": "151a109d-c8e6-4202-9424-069dbd6a4397",
			"account_id": "ebcbc9c4-7c1b-47df-9ec4-1bcfa48e0344",
			"method_class": "american-express",
			"display_string": "American Express ending in 0002",
			"provider": "adyen",
			"psp_reference": "8415980438197366",
			"psp_hash_code": "2e141bf3bc640ec70efb88931aaaaaaa",
			"processing_currency": "USD",
			"pm_state": "ACTIVE",
			"integrator": "acme",
			"created": "2020-08-21 09:03:39",
			"updated": "2020-08-21 09:03:39",
			"payment_method_id": "151a109d-c8e6-4202-9424-069dbd6a4397",
			"first_name": "Jessica",
			"last_name": "Pley",
			"full_name": "Jessica Pley",
			"expiration": "03/30",
			"address1": "1 Main Street",
			"city": "San Jose",
			"country_iso": "US",
			"geoip_state": "CA",
			"geoip_country_iso": "US",
			"zip": "95131",
			"bin": "370000",
			"last_four": "0002",
			"avs": "4"
		}
	]
}

Account with USD Wallet Only

Copy
Copied
{
    "status": "Success",
    "message": [],
    "codes": [],
    "payload": [
        {
			"id": "fce464b4-cf9f-49c2-bdb1-2db3275d6284",
			"account_id": "7f938c50-0225-4fbe-b465-81d70934064a",
			"method_class": "registration",
			"display_string": "USD Wallet",
			"provider": "wallet",
			"psp_reference": "a900281d-5d01-4784-a412-f447389929f8",
			"psp_hash_code": "",
			"processing_currency": "USD",
			"pm_state": "ACTIVE",
			"integrator": "acme",
			"created": "2020-08-14 10:59:59",
			"updated": "2020-08-14 10:59:59",
			"wallet_balance": "2457",
			"payment_method_id": "",
			"provider_data": {
				"wallet_id": "a900281d-5d01-4784-a412-f447389929f8",
				"wallet_balance": "35970"
			}
		}
	]
}