--- title: "Top up a wallet" method: POST path: "/wallet_transactions" tags: ["wallets"] --- # Top up a wallet `POST /wallet_transactions` This endpoint is used to top-up an active wallet. ## Request body - WalletTransactionCreateInput - `wallet_transaction` object, required - `wallet_id` string, uuid, required — 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. - `name` string, nullable — The name of the wallet transaction. It will appear on the invoice as the label for the fee. If not set, the label on the invoice will fallback to either `Prepaid credits - {{wallet_name}}` if the wallet name is set, or `Prepaid credits`. Note that this name will apply to all transactions (`paid_credits`, `granted_credits` and `voided_credits`) created by this action. - `paid_credits` string, nullable — The number of paid credits. - `granted_credits` string, nullable — The number of free granted credits. - `voided_credits` string, nullable — The number of voided credits. - `invoice_requires_successful_payment` boolean — 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. - `ignore_paid_top_up_limits` boolean — When true, allows topping up the wallet with transactions that exceed the paid top-up limits. Defaults to false. - `invoice_custom_section` InvoiceCustomSectionInput — Configuration for invoice custom sections to apply to invoices generated by this resource. - `skip_invoice_custom_sections` boolean — Set to `true` to exclude all invoice custom sections from PDF generation for invoices related to this resource. When `true`, `invoice_custom_section_codes` is ignored. - `invoice_custom_section_codes` string[] — List of unique codes identifying the invoice custom sections to apply. These override the default invoice custom sections configured at the customer or billing entity level. - `payment_method` PaymentMethodReference — Reference to a specific payment method for processing the payment. - `payment_method_type` 'provider' | 'manual' — The type of payment method to use. - `payment_method_id` string, uuid — The unique identifier of the payment method (required when using a specific provider payment method). - `metadata` object[], nullable — This optional field allows you to store a list of key-value pairs that hold additional information or custom attributes related to the data. - `key` string — The unique identifier for the attribute. - `value` string — The value associated with the key. ## Response `200` Wallet transaction created - WalletTransactions - `wallet_transactions` WalletTransactionObject[], required - `lago_id` string, uuid, required — 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. - `lago_wallet_id` string, uuid, required — 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. - `lago_invoice_id` string, uuid, nullable, required — Unique identifier assigned to the invoice associated with this wallet transaction. This ID is exclusively created by Lago and serves as a unique identifier for the invoice's record within the Lago system. - `lago_credit_note_id` string, uuid, nullable, required — Unique identifier of the credit note associated with this wallet transaction. This ID is exclusively created by Lago and serves as a unique identifier for the invoice's record within the Lago system. - `lago_voided_invoice_id` string, uuid, nullable, required — Unique identifier of the invoice that was voided and triggered the creation of this inbound wallet transaction. Only present for inbound transactions on traceable wallets that were created as a result of an invoice void. - `status` 'pending' | 'settled' | 'failed', required — The status of the wallet transaction. Possible values are `pending`, `settled` or `failed`. - `source` 'manual' | 'interval' | 'threshold', required — The source field represents the origin or trigger of the wallet transaction. Possible values are `manual`, `interval`, `threshold` - `transaction_status` 'purchased' | 'granted' | 'voided' | 'invoiced', required — The transaction status of the wallet transaction. Possible values are `purchased` (with pending or settled status), `granted` (without invoice_id), `voided` or `invoiced`. - `transaction_type` 'inbound' | 'outbound', required — The type of transaction. Possible values are `inbound` (increasing the balance) or `outbound` (decreasing the balance). - `amount` string, required — The amount of credits based on the rate and the currency. - `credit_amount` string, required — The number of credits used in the wallet transaction. - `invoice_requires_successful_payment` boolean, required — 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. - `metadata` object[], required — This field allows you to store a list of key-value pairs that hold additional information or custom attributes related to the data. - `key` string — The unique identifier for the attribute. - `value` string — The value associated with the key. - `remaining_amount_cents` integer, nullable, required — The remaining unconsumed amount of an inbound wallet transaction, expressed in cents. Only present for inbound transactions on traceable wallets. Tracks how much of the original credited amount has not yet been consumed by outbound transactions. - `remaining_credit_amount` string, nullable, required — The remaining unconsumed amount of an inbound wallet transaction, expressed in credits. Only present for inbound transactions on traceable wallets. - `priority` integer, required — The priority of the wallet transaction, used to determine the order in which inbound transactions are consumed. Lower values are consumed first. - `settled_at` string, date-time, nullable, required — The date when wallet transaction is settled, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). - `failed_at` string, date-time, nullable, required — The date when the wallet transaction failed, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). - `created_at` string, date-time, required — The date of the wallet transaction creation, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). - `name` string, nullable, required — The name of the wallet transaction. It will appear on the invoice as the label for the fee. If not set, the label on the invoice will fallback to either `Prepaid credits - {{wallet_name}}` if the wallet name is set, or `Prepaid credits`. - `applied_invoice_custom_sections` AppliedInvoiceCustomSectionObject[] — The invoice custom sections applied to invoices generated by this wallet transaction. - `lago_id` string, uuid, required — Unique identifier of the applied invoice custom section in the Lago application. - `created_at` string, date-time, required — The date of the applied invoice custom section creation, represented in ISO 8601 datetime format and expressed in Coordinated Universal Time (UTC). - `invoice_custom_section_id` string, uuid — **Deprecated.** Unique identifier of the invoice custom section that was applied. - `invoice_custom_section` InvoiceCustomSectionObject, required - `lago_id` string, uuid, required — Unique identifier for the invoice custom section in the Lago application, generated by Lago to ensure record uniqueness within the system. - `name` string, required — Name of the invoice custom section. - `code` string, required — Unique code identifying the invoice custom section for the API request. - `description` string — Internal description of the invoice custom section. - `details` string — The value shown on the invoice PDF. - `display_name` string — The name of the invoice custom section displayed on the invoice. - `applied_to_organization` boolean — **Deprecated.** This field will be removed in a future version. When set to true, it applies the invoice custom section to the organization's default billing entity. To apply or remove an invoice custom section from any billing entity (including the default one), please use the `PUT /billing_entities/:code` endpoint instead. - `organization_id` string, uuid — Unique identifier for the organization associated with the invoice custom section. - `created_at` string, date-time — Creation date of the tax. - `payment_method` PaymentMethodReference, required — Reference to a specific payment method for processing the payment. - `payment_method_type` 'provider' | 'manual' — The type of payment method to use. - `payment_method_id` string, uuid — The unique identifier of the payment method (required when using a specific provider payment method). ## Other responses - `400` — Bad Request error - `401` — Unauthorized error - `403` — Forbidden - `422` — Unprocessable entity error --- [API](https://skmtc.dev/getlago/apis/lago-api-documentation.md) · [All operations](https://skmtc.dev/getlago/apis/lago-api-documentation/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/getlago/lago-api-documentation/revisions/6e969ef3bb45/schema)