Skip to main content

addPaymentTransaction

Record a payment transaction (an authorization, a capture or a refund) for an order. It is a plain INSERT into the payment_transaction table.

Use it to save the first transaction of an order from your own return page, webhook or order-creation hook. Core does not create that row for you, and captureOrder and refundOrder need it. For a refund, call recordRefund instead, and for a capture call captureOrder: they record the transaction, set the status and emit the events.

Import​

import { addPaymentTransaction } from "@evershop/evershop/oms/services";

Syntax​

addPaymentTransaction(
  connection: Pool | PoolClient,
  orderId: number,
  amount: number,
  transactionId: string | number,
  transactionType: string,
  paymentAction: string,
  additionalInformation?: string,
  parentTransactionId?: string | number
): Promise<PaymentTransactionRow>

Parameters​

ParameterTypeDescription
connectionPool | PoolClientDatabase connection
orderIdnumberOrder database ID (order_id, not the uuid)
amountnumberTransaction amount, in major currency units
transactionIdstring | numberThe provider's transaction ID. Together with the order it must be unique.
transactionTypestring'online' when a payment provider was involved, 'offline' when it was not (Cash On Delivery)
paymentActionstring'authorize', 'capture' or 'refund'. Core matches these exact lowercase values when it looks for the authorization, the capture and the refunds of an order.
additionalInformationstring (optional)Extra details (JSON string)
parentTransactionIdstring | number (optional)The transactionId of the transaction this one follows, for example the authorization a capture settles

Return Value​

Returns Promise<PaymentTransactionRow>, the inserted row.

Notes​

  • Not idempotent. The table has a unique constraint on the order and the transaction id, so inserting the same transaction twice throws. When a webhook can deliver the same event twice, use insertOnUpdate on transaction_id and payment_transaction_order_id instead, as the Stripe and PayPal modules do.
  • It does not change the payment status and emits no event. Call updatePaymentStatus for that.
  • It is not wrapped in hookable.

Examples​

Record the amount to collect when a Cash On Delivery order is created. The Cash On Delivery module does this inside order creation:

import { addPaymentTransaction } from "@evershop/evershop/oms/services";

await addPaymentTransaction(
  connection,
  order.insertId,
  Number(order.grand_total),
  `cod-authorize-${order.uuid}`,
  "offline",
  "authorize"
);

Record a capture that settles an authorization, with the provider's response attached:

await addPaymentTransaction(
  connection,
  orderId,
  99.99,
  "cap_1234567890",
  "online",
  "capture",
  JSON.stringify({ provider: "my-gateway" }),
  "auth_1234567890" // parent transaction: the authorization
);

See Also​