OpenAPI Specification
openapi: 3.1.0
info:
title: Lago API documentation Add_ons Wallets API
description: Lago API allows your application to push customer information and metrics (events) from your application to the billing application.
version: 1.15.0
license:
name: AGPLv3
identifier: AGPLv3
contact:
email: tech@getlago.com
servers:
- url: https://api.getlago.com/api/v1
description: US Lago cluster
- url: https://api.eu.getlago.com/api/v1
description: EU Lagos cluster
security:
- bearerAuth: []
tags:
- name: Wallets
description: Everything about Wallet collection
externalDocs:
description: Find out more
url: https://doc.getlago.com/docs/api/wallets/wallet-object
paths:
/wallets:
post:
tags:
- Wallets
summary: Lago Create a wallet
description: This endpoint is used to create a wallet with prepaid credits.
operationId: createWallet
requestBody:
description: Wallet payload
content:
application/json:
schema:
$ref: '#/components/schemas/WalletCreateInput'
required: true
responses:
'200':
description: Wallet created
content:
application/json:
schema:
$ref: '#/components/schemas/Wallet'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/UnprocessableEntity'
get:
tags:
- Wallets
summary: Lago List all wallets
description: This endpoint is used to list all wallets with prepaid credits.
operationId: findAllWallets
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/per_page'
- name: external_customer_id
in: query
description: The customer external unique identifier (provided by your own application).
required: true
explode: true
schema:
type: string
example: 5eb02857-a71e-4ea2-bcf9-57d3a41bc6ba
responses:
'200':
description: Wallets
content:
application/json:
schema:
$ref: '#/components/schemas/WalletsPaginated'
'401':
$ref: '#/components/responses/Unauthorized'
/wallets/{lago_id}:
parameters:
- name: lago_id
in: path
description: Unique identifier assigned to the wallet within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the wallet's record within the Lago system.
required: true
schema:
type: string
format: uuid
example: 1a901a90-1a90-1a90-1a90-1a901a901a90
put:
tags:
- Wallets
summary: Lago Update a wallet
description: This endpoint is used to update an existing wallet with prepaid credits.
operationId: updateWallet
requestBody:
description: Wallet update payload
content:
application/json:
schema:
$ref: '#/components/schemas/WalletUpdateInput'
required: true
responses:
'200':
description: Wallet updated
content:
application/json:
schema:
$ref: '#/components/schemas/Wallet'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/UnprocessableEntity'
get:
tags:
- Wallets
summary: Lago Retrieve a wallet
description: This endpoint is used to retrieve an existing wallet with prepaid credits.
operationId: findWallet
responses:
'200':
description: Wallet
content:
application/json:
schema:
$ref: '#/components/schemas/Wallet'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
delete:
tags:
- Wallets
summary: Lago Terminate a wallet
description: This endpoint is used to terminate an existing wallet with prepaid credits.
operationId: destroyWallet
responses:
'200':
description: Wallet terminated
content:
application/json:
schema:
$ref: '#/components/schemas/Wallet'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'405':
$ref: '#/components/responses/NotAllowed'
/wallet_transactions:
post:
tags:
- Wallets
summary: Lago Top up a wallet
description: This endpoint is used to top-up an active wallet.
operationId: createWalletTransaction
requestBody:
description: Wallet transaction payload
content:
application/json:
schema:
$ref: '#/components/schemas/WalletTransactionCreateInput'
required: true
responses:
'200':
description: Wallet transaction created
content:
application/json:
schema:
$ref: '#/components/schemas/WalletTransactions'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'422':
$ref: '#/components/responses/UnprocessableEntity'
/wallets/{lago_id}/wallet_transactions:
get:
tags:
- Wallets
summary: Lago List all wallet transactions
description: This endpoint is used to list all wallet transactions.
operationId: findAllWalletTransactions
parameters:
- name: lago_id
in: path
description: Unique identifier assigned to the wallet within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the wallet's record within the Lago system.
required: true
schema:
type: string
format: uuid
example: 1a901a90-1a90-1a90-1a90-1a901a901a90
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/per_page'
- name: status
in: query
description: The status of the wallet transaction. Possible values are `pending` or `settled`.
required: false
explode: true
schema:
type: string
example: pending
- name: transaction_status
in: query
description: The transaction status of the wallet transaction. Possible values are `purchased` (with pending or settled status), `granted` (without invoice_id), `voided` or `invoiced`.
required: false
explode: true
schema:
type: string
example: purchased
- name: transaction_type
in: query
description: The transaction type of the wallet transaction. Possible values are `inbound` (increasing the wallet balance) or `outbound` (decreasing the wallet balance).
required: false
explode: true
schema:
type: string
example: inbound
responses:
'200':
description: Wallet transactions
content:
application/json:
schema:
$ref: '#/components/schemas/WalletTransactionsPaginated'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
components:
schemas:
PaginationMeta:
type: object
required:
- current_page
- total_pages
- total_count
properties:
current_page:
type: integer
description: Current page.
example: 2
next_page:
type: integer
description: Next page.
example: 3
nullable: true
prev_page:
type: integer
description: Previous page.
example: 1
nullable: true
total_pages:
type: integer
description: Total number of pages.
example: 4
total_count:
type: integer
description: Total number of records.
example: 70
WalletTransactionCreateInput:
type: object
required:
- wallet_transaction
properties:
wallet_transaction:
type: object
required:
- wallet_id
properties:
wallet_id:
type: string
format: uuid
description: Unique identifier assigned to the wallet within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the wallet's record within the Lago system.
example: 1a901a90-1a90-1a90-1a90-1a901a901a90
paid_credits:
type: string
pattern: ^[0-9]+.?[0-9]*$
description: The number of paid credits.
example: '20.0'
granted_credits:
type: string
pattern: ^[0-9]+.?[0-9]*$
description: The number of free granted credits.
example: '10.0'
voided_credits:
type: string
pattern: ^[0-9]+.?[0-9]*$
description: The number of voided credits.
example: '5.0'
invoice_requires_successful_payment:
type: boolean
description: A boolean setting that, when set to true, delays issuing an invoice for a wallet top-up until a successful payment is made; if false, the invoice is issued immediately upon wallet top-up, regardless of the payment status. Default value of false.
example: false
metadata:
type: array
description: This optional field allows you to store a list of key-value pairs that hold additional information or custom attributes related to the data.
items:
type: object
properties:
key:
type: string
description: The unique identifier for the attribute.
value:
type: string
description: The value associated with the key.
example:
- key: example key
value: example value
- key: another key
value: another value
WalletCreateInput:
type: object
properties:
wallet:
type: object
required:
- rate_amount
- currency
- external_customer_id
properties:
name:
type: string
description: The name of the wallet.
example: Prepaid
rate_amount:
type: string
pattern: ^[0-9]+.?[0-9]*$
description: The rate of conversion between credits and the amount in the specified currency. It indicates the ratio or factor used to convert credits into the corresponding monetary value in the currency of the transaction.
example: '1.5'
currency:
allOf:
- $ref: '#/components/schemas/Currency'
- description: The currency of the wallet.
example: USD
paid_credits:
type: string
pattern: ^[0-9]+.?[0-9]*$
nullable: true
description: The number of paid credits. Required only if there is no granted credits.
example: '20.0'
granted_credits:
type: string
pattern: ^[0-9]+.?[0-9]*$
nullable: true
description: The number of free granted credits. Required only if there is no paid credits.
example: '10.0'
external_customer_id:
type: string
description: The customer external unique identifier (provided by your own application)
example: hooli_1234
expiration_at:
type: string
format: date-time
nullable: true
description: The date and time that determines when the wallet will expire. It follows the ISO 8601 datetime format and is expressed in Coordinated Universal Time (UTC).
example: '2022-07-07T23:59:59Z'
invoice_requires_successful_payment:
type: boolean
description: A boolean setting that, when set to true, delays issuing an invoice for a wallet top-up until a successful payment is made; if false, the invoice is issued immediately upon wallet top-up, regardless of the payment status. Default value of false.
example: false
transaction_metadata:
type: array
description: This optional field allows you to store a list of key-value pairs that provide additional information or custom attributes. These key-value pairs will be included in the metadata of wallet transactions generated during the wallet creation process.
items:
type: object
properties:
key:
type: string
description: The unique identifier for the attribute.
value:
type: string
description: The corresponding value for the key.
example:
- key: example_key
value: example_value
- key: another_key
value: another_value
recurring_transaction_rules:
type: array
description: List of recurring transaction rules. Currently, we only allow one recurring rule per wallet.
items:
type: object
description: Object that represents rule for wallet recurring transactions.
required:
- trigger
properties:
paid_credits:
type: string
pattern: ^[0-9]+.?[0-9]*$
nullable: true
description: The number of paid credits used for recurring top-up.
example: '20.0'
granted_credits:
type: string
pattern: ^[0-9]+.?[0-9]*$
nullable: true
description: The number of free granted credits used for recurring top-up.
example: '10.0'
method:
type: string
enum:
- fixed
- target
description: The method used for recurring top-up. Possible values are `fixed` or `target`.
example: target
trigger:
type: string
enum:
- interval
- threshold
description: The trigger. Possible values are `interval` or `threshold`.
example: interval
interval:
type: string
enum:
- weekly
- monthly
- quarterly
- yearly
description: 'The interval used for recurring top-up. It represents the frequency at which automatic top-up occurs. The interval can be one of the following values: `weekly`, `monthly`, `quarterly` or `yearly`. Required only when trigger is `interval`.'
example: monthly
started_at:
type: string
format: date-time
example: '2022-08-08T00:00:00Z'
description: The effective start date for recurring top-ups. This date should be provided in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).
threshold_credits:
type: string
pattern: ^[0-9]+.?[0-9]*$
description: The threshold for recurring top-ups is the value at which an automatic top-up is triggered. For example, if this threshold is set at 10 credits, an automatic top-up will occur whenever the wallet balance falls to or below 10 credits. Required only when trigger is set to `threshold`.
example: '20.0'
target_ongoing_balance:
type: string
pattern: ^[0-9]+.?[0-9]*$
description: The target ongoing balance is the value set for the ongoing balance to be reached by the automatic top-up. Required only when trigger is set to `target`.
example: '200.0'
invoice_requires_successful_payment:
type: boolean
description: A boolean setting that, when set to true, delays issuing an invoice for a wallet top-up until a successful payment is made; if false, the invoice is issued immediately upon wallet top-up, regardless of the payment status. Default value of false.
example: false
transaction_metadata:
type: array
description: This optional field allows you to store a list of key-value pairs containing additional information or custom attributes. These key-value pairs will populate the metadata of the wallet transactions triggered by this rule.
items:
type: object
properties:
key:
type: string
description: The unique identifier for the attribute.
value:
type: string
description: The value associated with the key.
example:
- key: example_key
value: example_value
- key: another_key
value: another_value
WalletTransactionsPaginated:
allOf:
- $ref: '#/components/schemas/WalletTransactions'
- type: object
required:
- meta
properties:
meta:
$ref: '#/components/schemas/PaginationMeta'
ApiErrorNotAllowed:
type: object
required:
- status
- error
- code
properties:
status:
type: integer
format: int32
example: 405
error:
type: string
example: Method Not Allowed
code:
type: string
example: not_allowed
WalletsPaginated:
type: object
required:
- wallets
- meta
properties:
wallets:
type: array
items:
$ref: '#/components/schemas/WalletObject'
meta:
$ref: '#/components/schemas/PaginationMeta'
ApiErrorNotFound:
type: object
required:
- status
- error
- code
properties:
status:
type: integer
format: int32
example: 404
error:
type: string
example: Not Found
code:
type: string
example: object_not_found
ApiErrorUnprocessableEntity:
type: object
required:
- status
- error
- code
- error_details
properties:
status:
type: integer
format: int32
example: 422
error:
type: string
example: Unprocessable entity
code:
type: string
example: validation_errors
error_details:
type: object
ApiErrorUnauthorized:
type: object
required:
- status
- error
properties:
status:
type: integer
format: int32
example: 401
error:
type: string
example: Unauthorized
ApiErrorBadRequest:
type: object
required:
- status
- error
properties:
status:
type: integer
format: int32
example: 400
error:
type: string
example: Bad request
WalletTransactions:
type: object
required:
- wallet_transactions
properties:
wallet_transactions:
type: array
items:
$ref: '#/components/schemas/WalletTransactionObject'
Currency:
type: string
example: USD
enum:
- AED
- AFN
- ALL
- AMD
- ANG
- AOA
- ARS
- AUD
- AWG
- AZN
- BAM
- BBD
- BDT
- BGN
- BIF
- BMD
- BND
- BOB
- BRL
- BSD
- BWP
- BYN
- BZD
- CAD
- CDF
- CHF
- CLF
- CLP
- CNY
- COP
- CRC
- CVE
- CZK
- DJF
- DKK
- DOP
- DZD
- EGP
- ETB
- EUR
- FJD
- FKP
- GBP
- GEL
- GIP
- GMD
- GNF
- GTQ
- GYD
- HKD
- HNL
- HRK
- HTG
- HUF
- IDR
- ILS
- INR
- ISK
- JMD
- JPY
- KES
- KGS
- KHR
- KMF
- KRW
- KYD
- KZT
- LAK
- LBP
- LKR
- LRD
- LSL
- MAD
- MDL
- MGA
- MKD
- MMK
- MNT
- MOP
- MRO
- MUR
- MVR
- MWK
- MXN
- MYR
- MZN
- NAD
- NGN
- NIO
- NOK
- NPR
- NZD
- PAB
- PEN
- PGK
- PHP
- PKR
- PLN
- PYG
- QAR
- RON
- RSD
- RUB
- RWF
- SAR
- SBD
- SCR
- SEK
- SGD
- SHP
- SLL
- SOS
- SRD
- STD
- SZL
- THB
- TJS
- TOP
- TRY
- TTD
- TWD
- TZS
- UAH
- UGX
- USD
- UYU
- UZS
- VND
- VUV
- WST
- XAF
- XCD
- XOF
- XPF
- YER
- ZAR
- ZMW
WalletTransactionObject:
type: object
required:
- lago_id
- lago_wallet_id
- status
- transaction_status
- transaction_type
- credit_amount
- amount
- created_at
properties:
lago_id:
type: string
format: uuid
description: Unique identifier assigned to the wallet transaction within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the wallet transaction's record within the Lago system.
example: 1a901a90-1a90-1a90-1a90-1a901a901a90
lago_wallet_id:
type: string
format: uuid
description: Unique identifier assigned to the wallet within the Lago application. This ID is exclusively created by Lago and serves as a unique identifier for the wallet's record within the Lago system.
example: 1a901a90-1a90-1a90-1a90-1a901a901a90
status:
type: string
enum:
- pending
- settled
description: The status of the wallet transaction. Possible values are `pending` or `settled`.
example: settled
source:
type: string
enum:
- manual
- interval
- threshold
description: The source field represents the origin or trigger of the wallet transaction. Possible values are `manual`, `interval`. `threshold`
example: manual
transaction_status:
type: string
enum:
- purchased
- granted
- voided
- invoiced
description: The transaction status of the wallet transaction. Possible values are `purchased` (with pending or settled status), `granted` (without invoice_id), `voided` or `invoiced`.
example: purchased
transaction_type:
type: string
enum:
- inbound
- outbound
description: The type of transaction. Possible values are `inbound` (increasing the balance) or `outbound` (decreasing the balance).
example: inbound
amount:
type: string
pattern: ^[0-9]+.?[0-9]*$
description: The amount of credits based on the rate and the currency.
example: '10.0'
credit_amount:
type: string
pattern: ^[0-9]+.?[0-9]*$
description: The number of credits used in the wallet transaction.
example: '100.0'
invoice_requires_successful_payment:
type: boolean
description: A boolean setting that, when set to true, delays issuing an invoice for a wallet top-up until a successful payment is made; if false, the invoice is issued immediately upon wallet top-up, regardless of the payment status. Default value of false.
example: false
metadata:
type: array
description: This field allows you to store a list of key-value pairs that hold additional information or custom attributes related to the data.
items:
type: object
properties:
key:
type: string
description: The unique identifier for the attribute.
value:
type: string
description: The value associated with the key.
example:
- key: example key
value: example value
- key: another key
value: another value
settled_at:
type: string
format: date-time
description: The date when wallet transaction is settled, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).
example: '2022-04-29T08:59:51Z'
created_at:
type: string
format: date-time
description: The date of the wallet transaction creation, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).
example: '2022-04-29T08:59:51Z'
WalletUpdateInput:
type: object
required:
- wallet
properties:
wallet:
type: object
properties:
name:
type: string
nullable: true
description: The name of the wallet.
example: new_name
expiration_at:
type: string
format: date-time
nullable: true
description: The date and time that determines when the wallet will expire. It follows the ISO 8601 datetime format and is expressed in Coordinated Universal Time (UTC).
example: '2022-07-07T23:59:59Z'
invoice_requires_successful_payment:
type: boolean
description: A boolean setting that, when set to true, delays issuing an invoice for a wallet top-up until a successful payment is made; if false, the invoice is issued immediately upon wallet top-up, regardless of the payment status. Default value of false.
example: false
recurring_transaction_rules:
type: array
description: List of recurring transaction rules. Currently, we only allow one recurring rule per wallet.
required:
- trigger
- paid_credits
- granted_credits
items:
type: object
description: Object that represents rule for wallet recurring transactions.
properties:
lago_id:
type: string
format: uuid
example: 1a901a90-1a90-1a90-1a90-1a901a901a90
description: A unique identifier for the recurring transaction rule in the Lago application. Can be used to update a recurring transaction rule.
trigger:
type: string
enum:
- interval
- threshold
description: The trigger. Possible values are `interval` or `threshold`.
example: interval
method:
type: string
enum:
- fixed
- target
description: The method used for recurring top-up. Possible values are `fixed` or `target`.
example: target
interval:
type: string
enum:
- weekly
- monthly
- quarterly
- yearly
description: 'The interval used for recurring top-up. It represents the frequency at which automatic top-up occurs. The interval can be one of the following values: `weekly`, `monthly`, `quarterly` or `yearly`. Required only when trigger is set to `interval`.'
example: monthly
threshold_credits:
type: string
pattern: ^[0-9]+.?[0-9]*$
description: The threshold for recurring top-ups is the value at which an automatic top-up is triggered. For example, if this threshold is set at 10 credits, an automatic top-up will occur whenever the wallet balance falls to or below 10 credits. Required only when trigger is set to `threshold`.
example: '20.0'
paid_credits:
type: string
pattern: ^[0-9]+.?[0-9]*$
description: The number of paid credits. Required only if there is no granted credits.
example: '20.0'
granted_credits:
type: string
pattern: ^[0-9]+.?[0-9]*$
description: The number of free granted credits. Required only if there is no paid credits.
example: '10.0'
started_at:
type: string
format: date-time
example: '2022-08-08T00:00:00Z'
description: The effective start date for recurring top-ups. This date should be provided in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC).
target_ongoing_balance:
type: string
pattern: ^[0-9]+.?[0-9]*$
description: The target ongoing balance is the value set for the ongoing balance to be reached by the automatic top-up. Required only when trigger is set to `target`.
example: '200.0'
invoice_requires_successful_payment:
type: boolean
description: A boolean setting that, when set to true, delays issuing an invoice for a wallet top-up until a successful payment is made; if false, the invoice is issued immediately upon wallet top-up, regardless of the payment status. Default value of false.
example: false
transaction_metadata:
type: array
description: This optional field allows you to store a list of key-value pairs containing additional information or custom attributes. These key-value pairs will populate the metadata of the wallet transactions triggered by this rule.
items:
type: object
properties:
key:
type: string
description: The unique identifier for the attribute.
value:
type: string
description: The value associated with the key.
example:
- key: example_key
value: example_value
- key: another_key
value: another_value
Wallet:
type: object
required:
- wallet
properties:
wallet:
$ref: '#/components/schemas/WalletObject'
WalletObject:
type: object
required:
- lago_id
- lago_customer_id
- external_customer_id
- status
- currency
- rate_amount
- credits_balance
- balance
- balance
# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lago/refs/heads/main/openapi/lago-wallets-api-openapi.yml