Transaction Templates

Transaction templates are models that simplify the use of our DSL, standardizing transaction flows in the Ledger. These templates ensure consistency and reduce the need to manually map transaction flows each time. For instance, a card transaction template can standardize the breakdown of values into settlement amounts, fees, and taxes.

Examples of transaction templates include bill payment, bill recharge, and PIX-in for Brazil, as well as ACH and wire transfers for the United States. Other examples might be "sale" and "stock inclusion" for specific items, like the "dipirona" instrument in a pharmacy.

Example of a PIX-out Transaction Template

A PIX-out transaction template might look like this:

(transaction v1
   (chart-of-accounts-group-name PIX_OUT)
   (metadata
       (anyKey anyValue)
       (anotherKey anotherValue)
   )
   (code PIX_OUT)
   (description "description for the transaction not for the operation")
   (send BRL $amount+$fee|2
     (source
       (from $sourceAccount :amount BRL $amount|2
         (description "PIX shipping")
         (chart-of-accounts pix_out_debit_82891231)
       )
       (from $sourceAccount :amount BRL $fee|2
         (description "PIX shipping rate")
         (chart-of-accounts pix_out_fee_debit)
       )
     )
   )
   (distribute
     (to @fees/PIX_OUT :amount BRL $fee|2
       (chart-of-accounts pix_out_fee_credit)
     )
     (distribute :remaining
       (to @external/BRL :remaining
         (chart-of-accounts pix_out_external)
         (description "internalTransactionId 99839218")
       )
     )
   )
)

Where:

• $amount: transaction amount

• $sourceAccount: the identifier of the source account

• @external/BRL: the settlement account for external transactions

• @fees/PIX_OUT: the account for saving PIX fees

• $fee: the value of the PIX fee to charge the account holder

Using Transaction Templates

Instead of manually writing the DSL, a user can initiate a PIX-out transaction by sending the following:

{
  "transactionType": id, // ID generated in a previous step
  "transactionTypeCode": "PIX_OUT",
  "variables": {
    "amount": 100,
    "source": "@johndoe",
    "fee": 1
  }
}

This JSON input populates the DSL template like this:

(transaction v1
   (chart-of-accounts-group-name PIX_OUT)
   (metadata
       (anyKey anyValue)
       (anotherKey anotherValue)
   )
   (code PIX_OUT)
   (description "description for the transaction not for the operation")
   (send BRL 101|2
     (source
       (from @gabriel :amount BRL 100|2
         (description "PIX shipping")
         (chart-of-accounts pix_out_debit_82891231)
       )
       (from @gabriel :amount BRL 1|2
         (description "PIX shipping rate")
         (chart-of-accounts pix_out_fee_debit)
       )
     )
   )
   (distribute
     (to @fees/PIX_OUT :amount BRL 1|2
       (chart-of-accounts pix_out_fee_credit)
     )
     (distribute :remaining
       (to @external/BRL :remaining
         (chart-of-accounts pix_out_external)
       )
     )
   )
)

This method ensures consistent patterns in the Ledger. For example, if all transaction templates must use values in base 100 for BRL, the template uses BRL 2 $amount, preventing errors from incorrect base values.

Managing Transaction Templates

To manage transaction templates, we will use the same DSL that was used for manual transactions, making it easier to manipulate using the Transaction templates API.

• To create a transaction template, use the Create a transaction template endpoint.

• To retrieve all transaction templates, use the Retrieve all transaction templates endpoint.

• To retrieve a specific transaction template, use the Retrieve a transaction templates endpoint.

• To update a transaction template, use the Update a transaction template endpoint.

• To remove a transaction template, use the Delete a transaction template endpoint.