{ "openapi": "3.0.1", "info": { "title": "Wallets", "description": "The Wallets API enables you to determine the amount of a given currency belonging to an account. Each account\nmay have multiple wallets, but a wallet belongs to only one account. For example, Alice may have a Wallet in USD, a Wallet in LindenDollars, and a Wallet in SandDollars.", "contact": { "name": "Tilia, Inc.", "url": "https://lindenlab.com", "email": "tilia@lindenlab.com" }, "license": { "name": "Tilia, Inc.", "url": "https://www.tilia-inc.com/contact/" }, "version": "1.0.0" }, "servers": [ { "url": "https://wallets.staging.tilia-inc.com", "description": "Staging" }, { "url": "https://wallets.tilia-inc.com", "description": "Production" } ], "paths": { "/balances/{account_id}": { "get": { "summary": "Get wallet balances", "description": "Get wallet balances for the specified account.", "operationId": "GetBalancesByAccountID", "parameters": [ { "name": "account_id", "in": "path", "description": "The account ID.", "required": true, "schema": { "$ref": "#/components/schemas/AccountId" } }, { "name": "currency", "in": "query", "description": "The currency to filter by (e.g. USD).", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Balances response", "content": { "application/json": { "schema": { "type": "object", "properties": { "payload": { "$ref": "#/components/schemas/BalancesResponse" }, "codes": { "type": "array", "description": "Array of codes if failure", "items": { "type": "string" }, "x-go-name": "Codes", "example": null }, "message": { "type": "array", "description": "Array of error messages if failure", "items": { "type": "string" }, "x-go-name": "Message", "example": null }, "status": { "type": "string", "description": "Success or Failure", "x-go-name": "Status", "example": "Success" } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicResponse" }, "example": { "status": "Failure", "message": [ "input is invalid" ], "codes": [ "INPUT_ERROR" ], "payload": { "errors": { "account_id": [ "INVALID_VALUE" ] } } } } } }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "$ref": "#/components/responses/notFound" }, "500": { "$ref": "#/components/responses/serverError" } }, "security": [ { "tilia_auth": [ "read_wallets" ] } ] } }, "/v2/wallet/{wallet_id}": { "get": { "summary": "Get wallet by ID", "description": "Get wallet for the specified wallet id. For Wallet Payment Methods (i.e. payment methods with `provider='wallet'`), the `payment_method.psp_reference=wallet.wallet_id`.", "operationId": "GetWalletByID", "parameters": [ { "name": "wallet_id", "in": "path", "description": "The wallet ID.", "required": true, "schema": { "$ref": "#/components/schemas/WalletId" } } ], "responses": { "200": { "description": "Wallet by id response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Success or Failure", "x-go-name": "Status", "example": "Success" }, "message": { "type": "array", "description": "Array of error messages if failure", "items": { "type": "string" }, "x-go-name": "Message", "example": null }, "codes": { "type": "array", "description": "Array of codes if failure", "items": { "type": "string" }, "x-go-name": "Codes", "example": null }, "payload": { "$ref": "#/components/schemas/Wallet" } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicResponse" }, "example": { "status": "Failure", "message": [ "input is invalid" ], "codes": [ "INPUT_ERROR" ], "payload": { "errors": { "account_id": [ "INVALID_VALUE" ] } } } } } }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "$ref": "#/components/responses/notFound" }, "500": { "$ref": "#/components/responses/serverError" } }, "security": [ { "tilia_auth": [ "read_wallets" ] } ] } }, "/v2/account/{account_id}/wallets": { "get": { "summary": "Get wallets by account", "description": "Get list of wallets for the specified account.", "operationId": "GetWalletsByAccountID", "parameters": [ { "name": "account_id", "in": "path", "description": "The account ID.", "required": true, "schema": { "$ref": "#/components/schemas/AccountId" } } ], "responses": { "200": { "description": "Wallets by account response", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Success or Failure", "x-go-name": "Status", "example": "Success" }, "message": { "type": "array", "description": "Array of error messages if failure", "items": { "type": "string" }, "x-go-name": "Message", "example": null }, "codes": { "type": "array", "description": "Array of codes if failure", "items": { "type": "string" }, "x-go-name": "Codes", "example": null }, "payload": { "$ref": "#/components/schemas/GetWalletsByAccountIDResponse" } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicResponse" }, "example": { "status": "Failure", "message": [ "input is invalid" ], "codes": [ "INPUT_ERROR" ], "payload": { "errors": { "account_id": [ "INVALID_VALUE" ] } } } } } }, "401": { "$ref": "#/components/responses/unauthorized" }, "404": { "$ref": "#/components/responses/notFound" }, "500": { "$ref": "#/components/responses/serverError" } }, "security": [ { "tilia_auth": [ "read_wallets" ] } ] } }, "/v2/wallet/custom": { "post": { "summary": "Create a custom wallet type", "description": "Enables you to create a custom Tilia Wallet to use for nonstandard transaction flows. Reach out to Tilia to define the new wallet type.\n >-\nNOTE: A wallet created from this endpoint will not have an associated payment method. Hence, the wallet would not be usable for purchase in the Checkout Widget. To enable purchase using this custom wallet, create an associated wallet payment method (as described in the Create a Custom Wallet payment method document in the Payments API reference section).", "operationId": "CreateCustomWallet", "requestBody": { "description": "Request for creating a custom wallet for an account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCustomWalletPostBody" } } }, "required": true }, "responses": { "200": { "description": "Response for the create a custom Wallet request", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Success or Failure", "x-go-name": "Status", "example": "Success" }, "message": { "type": "array", "description": "Array of error messages if failure", "items": { "type": "string" }, "x-go-name": "Message", "example": null }, "codes": { "type": "array", "description": "Array of codes if failure", "items": { "type": "string" }, "x-go-name": "Codes", "example": null }, "payload": { "$ref": "#/components/schemas/CreateCustomWalletResponse" } } } } } }, "400": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicResponse" }, "example": { "status": "Failure", "message": [ "input is invalid" ], "codes": [ "INPUT_ERROR" ], "payload": { "errors": { "account_id": [ "INVALID_VALUE" ] } } } } } }, "401": { "$ref": "#/components/responses/unauthorized" }, "500": { "$ref": "#/components/responses/serverError" } }, "security": [ { "tilia_auth": [ "read_wallets" ] } ] } } }, "x-webhooks": { "wallet-balance-alert": { "post": { "summary": "Wallet balance alert", "description": "Webhook event notification request.\n\n\n**`event_name` value:** `wallet-balance-alert`\n\n\n| This request is sent to registered webhook event handlers after |\n| :--- |\n| A publisher's wallet balance drops below their preset thresholds |\n\n\nThe Request body described below is the `message` property in the event notification request data. For more information about event notification requests, visit [Webhooks](/webhooks/#develop-a-webhook-event-handler).", "operationId": "walletBalanceAlert", "requestBody": { "$ref": "#/components/requestBodies/walletBalanceAlertWebhook" }, "responses": { "2XX": { "description": "Return a 2XX status to indicate that the data was received successfully" } }, "security": [ { "tilia_auth": [] } ] } } }, "components": { "securitySchemes": { "tilia_auth": { "type": "oauth2", "flows": { "clientCredentials": { "tokenUrl": "https://auth.staging.tilia-inc.com/token", "scopes": {} } } } }, "schemas": { "AccountId": { "type": "string", "maxLength": 36, "example": "acct_2TiDFXHVFMlAuyy7ovvz3YPKv9b" }, "BalancesResponse": { "type": "object", "properties": { "account_id": { "allOf": [ { "description": "Account ID associated with these wallets.", "x-go-name": "AccountID" }, { "$ref": "#/components/schemas/AccountId" } ] }, "balances": { "type": "object", "description": "An object containing the wallet balances, organized by currency.", "x-go-name": "BalanceInfo", "additionalProperties": { "type": "object", "description": "Key is currency name (e.g. USD).", "properties": { "spendable_balance": { "type": "object", "properties": { "balance": { "type": "integer", "format": "int64", "description": "The sum of the standard and convertible wallet balances, expressed in the lowest denomination of the currency.", "example": "50000" }, "display": { "type": "string", "description": "The sum of the standard and convertible wallet balances, formatted as a string for display purposes.", "example": "$500.00" } } }, "spendable": { "type": "object", "properties": { "balance": { "type": "integer", "format": "int64", "description": "The sum of the standard wallet balances, expressed in the lowest denomination of the currency.", "example": "20000" }, "display": { "type": "string", "description": "The sum of the standard wallet balances, formatted as a string for display purposes.", "example": "$200.00" } } }, "convertible": { "type": "object", "properties": { "balance": { "type": "integer", "format": "int64", "description": "The sum of the convertible wallet balances, expressed in the lowest denomination of the currency.", "example": "10000" }, "display": { "type": "string", "description": "The sum of the convertible wallet balances, formatted as a string for display purposes.", "example": "$100.00" } } } } } } }, "description": "BalancesResponse used to show state of all wallets", "x-go-package": "github.com/lindenlab/extraction-wallets/client/models" }, "BasicResponse": { "type": "object", "properties": { "status": { "type": "string", "description": "The status of the request, either `Success` or `Failure`.", "example": "Success", "x-go-name": "Status" }, "message": { "type": "array", "description": "An array of short, human-readable messages describing the failure. If the request was successful, this array will be empty.", "items": { "type": "string" }, "example": [], "x-go-name": "Message" }, "codes": { "type": "array", "description": "An array of failure reason codes. If the request was successful, this array will be empty.", "items": { "type": "string" }, "example": [], "x-go-name": "Codes" }, "payload": { "type": "object", "properties": {}, "description": "The response payload.", "x-go-name": "Payload" } } }, "WalletId": { "type": "string", "maxLength": 36, "example": "wal_2V2cKKqYoaj018K0EXBauwcurbd" }, "Wallet": { "type": "object", "properties": { "wallet_id": { "allOf": [ { "description": "ID of the wallet", "x-go-name": "ID" }, { "$ref": "#/components/schemas/WalletId" } ] }, "account_id": { "allOf": [ { "description": "Account ID this wallet is associated with", "x-go-name": "AccountID" }, { "$ref": "#/components/schemas/AccountId" } ] }, "description": { "type": "string", "description": "Description of this wallet", "example": "USD Wallet", "x-go-name": "Description" }, "currency": { "type": "string", "description": "Currency identifier for this wallet (e.g. USD)", "example": "USD", "x-go-name": "Currency" }, "current_balance": { "type": "integer", "description": "Current balance of the wallet.", "example": 100, "format": "int64", "x-go-name": "CurrentBalance" }, "active": { "type": "integer", "description": "Indicates whether or not the wallet is active and can be used for transactions. True if the wallet is active. False if the wallet is not active.", "example": 1, "x-go-name": "Active" }, "tags": { "type": "array", "description": "Tags attached to the wallet.", "example": [ "registration" ], "x-go-name": "Tags" } }, "description": "Wallet model return used to represent state of wallet", "x-go-package": "github.com/lindenlab/extraction-wallets/client/models" }, "GetWalletsByAccountIDResponse": { "type": "object", "properties": { "count": { "type": "number", "description": "Number of wallets returned", "example": 1, "x-go-name": "count" }, "wallets": { "type": "array", "description": "An array of Tilia Wallets.", "items": { "type": "object", "$ref": "#/components/schemas/Wallet" } } }, "description": "BalancesResponse used to show state of all wallets", "x-go-package": "github.com/lindenlab/extraction-wallets/client/models" }, "CreateCustomWalletPostBody": { "type": "object", "required": [ "account_id", "wallet_type" ], "properties": { "account_id": { "allOf": [ { "description": "Account ID for the wallet.", "x-go-name": "AccountID" }, { "$ref": "#/components/schemas/AccountId" } ] }, "wallet_type": { "type": "string", "description": "The name of the wallet type. This value must match the value configured by Tilia in your account's settings.", "example": "publisher_hosted", "x-go-name": "WalletType" }, "tags": { "type": "array", "description": "List of tags to attach to the wallet.", "example": [ "coin:TOK" ], "x-go-name": "Tags" } }, "description": "Create a Custom Wallet Post Body", "x-go-package": "github.com/lindenlab/extraction-wallets/internal/handlers" }, "CreateCustomWalletResponse": { "type": "object", "properties": { "wallet_id": { "allOf": [ { "description": "ID of the wallet", "x-go-name": "ID" }, { "$ref": "#/components/schemas/WalletId" } ] }, "account_id": { "allOf": [ { "description": "Account ID this wallet is associated with", "x-go-name": "AccountID" }, { "$ref": "#/components/schemas/AccountId" } ] }, "description": { "type": "string", "description": "Description of this wallet", "example": "USD Wallet", "x-go-name": "Description" }, "currency": { "type": "string", "description": "Currency identifier for this wallet (e.g. USD)", "example": "USD", "x-go-name": "Currency" }, "current_balance": { "type": "integer", "description": "Current balance of the wallet.", "example": 100, "format": "int64", "x-go-name": "CurrentBalance" }, "active": { "type": "integer", "description": "Indicates whether or not the wallet is active and can be used for transactions. True if the wallet is active. False if the wallet is not active.", "example": 1, "x-go-name": "Active" }, "tags": { "type": "array", "description": "Tags attached to the wallet.", "example": [ "coin:TOK" ], "x-go-name": "Tags" } }, "description": "Response payload with a created custom wallet ID.", "x-go-package": "github.com/lindenlab/extraction-wallets/client/models" } }, "responses": { "unauthorized": { "description": "Unauthorized access." }, "notFound": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BasicResponse" }, "example": { "status": "Failure", "message": [ "failed to get account" ], "codes": [ "ACCOUNT_GET_ERROR" ], "payload": null } } } }, "serverError": { "description": "Service unavailable or server error." } }, "requestBodies": { "walletBalanceAlertWebhook": { "content": { "application/json": { "schema": { "type": "object", "properties": { "balance": { "type": "integer", "description": "The current wallet balance.", "example": 1000 }, "critical": { "type": "boolean", "description": "Was this alert triggered by passing the critical threshold?", "example": true }, "description": { "type": "string", "description": "A description of the wallet.", "example": "Registration USD wallet." }, "wallet_id": { "allOf": [ { "description": "Wallet ID that triggered the alert." }, { "$ref": "#/components/schemas/WalletId" } ] }, "warning": { "type": "boolean", "description": "Was this alert triggered by passing the warning threshold?", "example": false } } } } } } } } }