Skip to main content

Payment Lifecycle

A payment in Yeti represents a customer's attempt to pay you — for example, when they enter their card details online or tap a card on a terminal. Behind the scenes, Yeti talks to one or more payment service providers (PSPs) and uses a couple of key identifiers to track everything that happens.

This page explains how a transaction flows through Yeti and two important concepts you’ll see in APIs and webhooks: pspReference and pspModificationReference.

Payment lifecycle​

At a high level, a card transaction in Yeti typically goes through some or all of these stages. In this model, Yeti is your issuer/PSP — it’s the system that approves, captures, settles, and refunds payments on behalf of your customers.

  1. Authorisation — The customer presents their card and Yeti asks the issuer if the payment can be approved. If successful, you get an authorised amount and a pspReference.
  2. Capture — The authorised funds are actually taken from the customer's account. This usually happens immediately (auto-capture) or later (delayed/partial capture). Each capture is a separate operation and doesn't require any additional actions from the you (with the exception of pre-auth payments).
  3. Settlement — The captured funds are batched and paid out to you according to your settlement schedule.
  4. Refunds — You send money back to the customer, either partially or in full, usually as one or more separate refund operations.
  5. Reversals / Expiry — If an authorisation is never captured, it may be reversed or expire, releasing the hold on the customer's account.

Each of these operations is represented and tracked with the identifiers described below.

pspReference​

A pspReference is the unique identifier for a payment operation handled by Yeti’s payment service provider layer. You can think of it as the transaction ID for anything that happens at the PSP level.

Every authorisation, capture, refund, cancellation, and other payment operation processed through Yeti gets its own pspReference. It is generated and managed by Yeti, and is globally unique within Yeti’s PSP layer.

Why pspReference matters​

  • End-to-end tracking. Lets you trace a payment or refund across Yeti and the underlying providers.
  • Follow-up actions. Used to reference the original operation when you capture, refund, or reverse a payment.
  • Reconciliation. Helps you match provider reports and Yeti webhooks/events to your own internal orders or payment records.
  • Support and debugging. A stable reference you can share with Yeti Support when investigating issues.

How to use it in your integration​

Always store the pspReference returned by Yeti for every payment and follow-up action in your own system. This makes it easy to:

  • Correlate incoming webhooks and reports with your internal entities (orders, invoices, subscriptions, etc.).
  • Investigate disputed or failed payments with precise references.
  • Build accurate operational and financial reporting on top of Yeti transactions.

pspModificationReference​

While pspReference identifies a specific payment operation, a pspModificationReference identifies a follow-up change to an existing payment — such as a capture, refund, or reversal that is applied after the original authorisation.

Each modification operation related to an existing payment gets its own pspModificationReference, separate from the original pspReference. This allows Yeti (and you) to distinguish:

  • The original payment operation (identified by pspReference).
  • The subsequent modifications to that payment (each identified by its own pspModificationReference).

Why pspModificationReference matters​

  • Detailed audit trail. Lets you see exactly which modifications have been applied to a payment over time.
  • Multiple actions on a single payment. Supports flows like multiple partial captures or multiple partial refunds against the same original payment.
  • Provider alignment. Mirrors how underlying PSPs track and reconcile follow-up operations.

How to use it in your integration​

You should store both the original pspReference and any pspModificationReference values you receive for a payment. In practice, this lets you:

  • Attach each capture or refund to the right internal object (e.g. shipments, line items, credit notes).
  • Reconcile provider reports that list both original transactions and later modifications.
  • Troubleshoot issues where a specific capture or refund behaves differently from the original authorisation.