Transactions
A transaction is the accounting record for money that moved. Beam creates one for every successful charge and every successful refund, and it records the amounts: the gross amount, the Beam fee, the VAT, and the net amount.
Transactions are immutable. Once Beam creates one, it never changes. Charges and refunds tell you whether a payment worked; transactions tell you what it was worth.
You can read transactions through the API, or view them in your merchant account in Lighthouse .
Transaction types
transactionType | Created when | transactionId is |
|---|---|---|
PAYMENT | A charge reaches SUCCEEDED. | The chargeId of that charge. |
REFUND | A refund reaches SUCCEEDED. | The refundId of that refund. |
VOID | A refund reaches SUCCEEDED and is processed as a void. | The refundId of that refund. |
A successful refund produces either a REFUND or a VOID transaction. Both mean the refund succeeded, so treat them
the same when you reconcile. The refund object does not tell you which one you will get, so do not branch on it.
A void comes from the refund, not the charge. It does not change the charge, which stays SUCCEEDED.
When Beam creates a transaction
A transaction appears the moment a charge or a refund reaches SUCCEEDED. You never create one yourself.
From a charge. Every successful payment creates a PAYMENT transaction, and its transactionId is the chargeId.
The charge source makes no difference: a payment link, a Bolt device and your own
POST /api/v1/charges call all work the same way here. For the full flow, see the
charge flow or the
payment link flow.
From a refund. When a refund reaches SUCCEEDED, Beam creates a transaction whose
transactionId is the refundId. For the flow, see the refund flow.
In both cases Beam sends transaction.created alongside the resource’s own event (charge.succeeded or
refund.succeeded). The resource event tells you the outcome; the transaction event has the amounts. For which event
to act on, see Track the charge and
Track the refund.
Amounts on a transaction
All amounts are in the smallest currency unit. For THB that is satang, so 10000 means 100.00 THB.
| Field | Meaning |
|---|---|
grossAmount | The amount paid, before fees are deducted. |
feeAmount | Beam’s fee for this transaction. |
vatAmount | The 7% VAT on the fee. |
netAmount | The amount you earn: grossAmount - feeAmount - vatAmount. |
feeStrategy | How the fee was calculated, either RATE or MINIMUM_AMOUNT. |
chargeSource and sourceId tell you where the original payment came from, and referenceId carries your own order
reference, so you can match a transaction back to your records. For every field, see the
Transactions API Specification.
Webhook events for transactions
transaction.created: Beam recorded a transaction, for a successful charge or a successful refund.
Use this event for your accounting, because it is the only one that includes the fees and the net amount. See Event Types for the payload and the Webhook guide for how to set your endpoint up.
Next steps
- Transactions API: how to read one transaction or list many.
- Charges and Refunds: the objects a transaction is created from.