Documentação

English

Português
Español

English

Português
Español

Appearance

Payment Queues ​

Access Prerequisites

  • Permission (module): processPaymentQueue (controls buttons in the UI) + manageToken (required by the backend for queue routes)
  • License/Feature: None specific.
  • Menu container: GENERAL → group Charges (route /manage-payment-queues)

What it is / when to use ​

Payment Queues model structures for NFT redemption/buyback by priority — typical of debts with a payment order, such as court-ordered payments (precatórios), public debts (TCU/União), debentures, or tokenized corporate obligations. Each queue is a rule: it selects which NFTs are included (by collection + attribute + attribute value), defines the payment priority, and the type (lump-sum or installment).

This screen handles queue configuration. The item-by-item execution (each NFT to be paid, in priority order) takes place on the Payment queue orders screen, where the operator approves the payment for each NFT: the system pays the holder the price_paid of the NFT from the platform wallet and returns the NFT to TKN_OWNER.

Prerequisites ​

  • Permission: processPaymentQueue registered to enable buttons in the UI (dual permission — CPM enum + dynamic module in DB). The creation/editing/deletion routes are validated at the API-Gateway with manageToken; without this enum the operation returns an error even when the button is visible.
  • License/Feature: None specific.
  • Dependencies on other screens: the collection and the attribute/value referenced must exist in the issued NFTs — that is how the system knows which NFTs belong to the queue.

Step by step ​

  1. Go to Charges → Payment Queues (route /manage-payment-queues).
  2. The list shows queues with Name and Priority.
  3. Click Create new to open the configuration modal.
  4. Fill in Name, Collection, Priority, Attribute, Attribute value, and the Payment type.
  5. If the type is Installment, provide Percentage and Months.
  6. Confirm with Save. To edit, use the pencil icon; to remove, the trash icon.

Fields (queue modal) ​

FieldWhat it isRequired?System/backend effect
NameQueue identifierYesSaves name in payment_queue (TokenController). Locked on edit (cannot be changed after creation).
CollectionID of the NFT collection served by the queueYesSaves collectionId. Together with attribute/value, delimits the universe of eligible NFTs.
PriorityPrecedence order of the queue in paymentYesSaves priority (numeric). Defines which queue/NFT is paid first when ordering the queue orders. Accepts numbers only.
AttributeName of the characteristic that marks an NFT as part of the queueYesSaves attribute. Matched with Attribute value to select the NFTs.
Attribute valueExpected value of the attribute aboveYesSaves value. E.g.: attribute tipo with value precatorio.
Payment typeLump-sum (Upfront / A) or Installment / PYesSaves payment_type (A or P). Switching to A clears percentage and months. Defines whether the NFT value is paid all at once or in portions.
Percentage(Installment) % of the value paid per installmentConditional (type P)Saves percentage. Defines the size of each installment relative to the NFT value.
Months(Installment) number/interval of installmentsConditional (type P)Saves months. Defines how many months the value is distributed over.

The Save button is only enabled when name, priority, attribute value, attribute, and collection are filled in.

Actions and modals ​

  • Create new: opens PaymentQueueModalComponent in creation mode → POST /v1/assets/createPaymentQueues.
  • Edit (pencil): opens the same modal with the queue loaded (edit mode) → POST /v1/assets/updatePaymentQueues. The Name field is locked.
  • Delete (trash): calls POST /v1/assets/deletePaymentQueues. On success the page reloads.

Business rules / considerations ​

Attention

  • NFT selection is done by collection + attribute + value: if the attribute/value does not match exactly what is in the NFTs, the queue will be empty.
  • The Name is immutable after creation.
  • Priority is what orders the payment — queues with conflicting priorities can produce an unexpected payment order. Plan the numbering carefully.
  • Configuring as Installment without providing Percentage/Months leaves the installment rule incomplete.
  • Financial values: the values actually paid come from the price_paid of each NFT (during execution) and are handled as BigNumber — without rounding.
  • Idempotency: the execution of each order is protected (an NFT already paid is not paid again) and transactions follow FinLib idempotency (E00021 = already processed = success).