What is a Payment?
A Payment is a first-class object that unifies the representation of a user payment across all your processors or payment methods.
A Primer payment is made of:
- a payment status that conforms to a unified payment lifecycle
- payment method information such as card details
- order details such as line items and currency
- customer details such as contact information, shipping, and billing address
- a timeline of events created throughout the lifecycle of the payment
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 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.
A newly-created payment is assigned the status .
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 to mitigate failures.
The payment was canceled 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.
Enforcing the payments lifecycle
The Payments API enforces our payments lifecycle state machine and returns a validation error if an API call is attempted where the payment status doesn't support that action.
The error status code returned is 400 with errorId = InvalidPaymentStatus
See below for the breakdown of the API requests and what's supported for each payment status (table scrolls horizontally):
| API Request | PENDING | AUTHORIZED | SETTLING | SETTLED | PARTIALLY_SETTLED | CANCELLED | DECLINED | FAILED |
|---|---|---|---|---|---|---|---|---|
POST /authorize | Allow | Block | Block | Block | Block | Block | Allow | Allow |
POST /cancel | Allow | Allow | Allow | Block | Block | Block | Block | Block |
POST /capture | Block | Allow | Allow | Block | Allow | Block | Block | Block |
POST /decline | Allow | Block | Block | Block | Block | Block | Block | Block |
POST /refund | Block | Block | Block | Allow | Allow | Block | Block | Block |
Processors may not support all the actions for each payment status outlined in the above table e.g. some processors may support cancelling a SETTLING payment, whilst others may not.
Payment creation
Payments are created automatically by Universal Checkout - our unified client-side SDK - or manually by sending a request to the Payments API.
In both cases, the following data is required to create a payment:
- An order ID
- An amount (or a list of line items), and a currency code
- A payment method token
Order ID
The Order ID offers a simple way for you to tie one or multiple payments to an order in your system.
You can reuse the same order ID for multiple payments. This is handy to link multiple payments together.
Line items and currency
They describe the total amount and the currency that will be sent to the processor to authorize and capture the payment.
Payment method token
A payment method token is a string representing sensitive payment method credentials and customer data.
Primer provides Universal Checkout, our all-in-one Checkout SDK, to securely capture payment method data while fully embedded on your site or in your app.
By communicating directly with Primer's PCI-L1 tokenization service, Universal Checkout transforms sensitive customer data into a secure uniform string called a payment method token.
Universal Checkout generates a payment method token regardless of the customer's chosen payment method. This enables you to reason about your checkout flow in a unified way.
Our agnostic tokenization service and centralized vault enable you to handle recurring payments, fallbacks, and retries across processors without compromising UX.
No more PSP-specific tokens — now you own your payment data.
Payment timeline
Available for every payment in the Dashboard, the payment 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.
Navigate, search and filter your payments with an easy-to-use interface in the Payments section of the Primer Dashboard.
Select a payment to see its detailed timeline of events.
Primer is not a black box, but rather your payments infrastructure. Select a specific event to see the requests and responses, providing full transparency into everything that’s happened to your payment throughout its journey.
