Learn payments once

Payments are at the center of the Primer universe. A payment is a first-class object that has:

  • a payment status that conforms to a unified payment lifecycle
  • payment method information such as card details
  • order details such as amount, line items and tax
  • customer details such as contact information, shipping and billing address
  • a Timeline of events created throughout the lifecycle of the payment


Payments are linked directly to Workflows, which determine what steps a payment follows based on the conditions that occur as it progresses throughout its lifecycle. You can think of a Workflow as a pathfinder for payments.


You may be familiar with the transaction concept used by many payment processors. Because a single Primer payment can go through multiple processors via fallbacks, retries or split routing, it can contain multiple transactions, all of which are clearly displayed on the payment's Timeline.

Payment creation

Payments are created automatically by Universal Checkout, or manually by sending a request to the Payments API.

In both cases, the following data is required to create a payment:

  • A payment method token:
    A string representing the sensitive payment method credentials and customer data. Payment method tokens are generated by Universal Checkout.
    Some payment method tokens can be saved using our Centralized Vault, enabling you to securely create merchant-initiated payments and recurring payments in a unified way.

  • An amount (or a list of line items), and a currency code :
    They describe the total amount and the currency that will be sent to the processor to authorize the payment.

  • An order ID:
    A custom ID for the payment that you can use to quickly retrieve a payment.

Payment lifecycle

All Primer payments conform to a unified payment lifecycle, which makes them work the same way regardless of the payment services you need.

A payment always has a payment status. Each payment will progress through some combination of the statuses listed below on their way through your Workflow.


The payment is awaiting a subsequent action or callback. This usually occurs with asynchronous processors. Prepare for this contingency by setting up Webhooks.

The processor has authorized the payment and no further status-altering actions have been defined in your Workflow.

The processor has settled funds in your account. If the entirety of the payment amount has been settled, the payment will have the status SETTLED.

Some processors allow for the capture of only a part of the authorized amount. If you leverage this capability, the payment status will be set to PARTIALLY_SETTLED.

The processor has declined the payment and no further status-altering actions have been defined in your Workflow. You may want to consider retrying certain declined payments.

This usually occurs when there is a processor gateway issue, such as a service disruption. Set up retries and fallbacks in Workflows to mitigate failures.

The payment was cancelled prior to it being settled.

The payment has been submitted for settlement and funds will be settled later. This usually occurs with asynchronous processors. Prepare for this contingency by setting up Webhooks.


A payment may go through multiple processors in the event of retries and fallbacks. Workflows streamline all processor responses to make sure you only see a single instance of each relevant payment status. Individual processor responses can be inspected in the Timeline.


Available for every payment in the Dashboard, the Timeline is the best representation of a payment on Primer. It displays all attributes of the payment, as well as the entire series of events that have taken place throughout its lifecycle.

Here, you can see all the Connections the payment went through as it progressed through your Workflow, and the various stages at which its status has been updated.



Primer is not a black box. It's your payments infrastructure, we're just hosting it.
You can inspect any event on the Timeline to see all of our requests and responses to your Connections. (But, we do hide sensitive customer data for security and compliance reasons.)