Key Concepts

Tenant

In the Ping Payments™ ecosystem, a tenant represents a platform, marketplace, or organization that has integrated with our suite of products. Tenants act as the top-level entities within the Ping Payments API hierarchy.

Each tenant has its own unique <<glossary:tenant_id>> and enables payment services for its merchants and their end customers, operating as an isolated environment with its own data and configuration.

Merchant

In the Ping Payments™ ecosystem, a Merchant represents an organization selling goods or services through a Tenant. They may also simply represent a recipient of funds, in cases where there is no clear point of sale.

Each tenant has their own set of merchants, and while multiple tenants can include the same person or organization in their set of merchants, there is a watertight separation between them for operational purposes. Any information shared between these entities are kept strictly for compliance and oversight under the auhtority of Finansinspektionen (Financial Supervisory Authority of Sweden).

Each merchant has their own merchant_id.

Payment Order

A payment order is a container that groups one or more payments related to a single purchase or transaction flow. It represents the intent to collect funds from a customer, and may involve multiple payment attempts or methods (e.g., retries or split payments).

Each payment order has its own payment_order_id.

Lifecycle and status

A Payment order's lifecycle is controlled entirely by the tenant, but is partially dependent on its associated payments.

A payment order can be set as:

• OPEN (default):

  All Payment orders start as open, and remains in this state until closed. Payments may only be initialized and associated with the payment order in this state.

• CLOSED:

  A closed payment order is closed for adding additional Payments.

• SPLIT:

  When all payments have been terminated (set to either COMPLETED, DENIED, ABORTED or STOPPED), the payment order can be split. When split, allocations will have been calculated according to the Split Tree.

• SETTLED:

  All calculated allocations are ready for disbursement.

Split Tree

A Split Tree is a set of rules defining how funds acquired through a Payment Order should be distributed among various parties. It should reflect the commercial agreement between Ping Payments, the tenant, and its merchants. The Split Tree system is extremely flexible and can accommodate even the most complex of business cases.

The Split Tree is designed and constructed by Ping Payments in collaboration with the tenant, is set when creating the Payment Order, and is evaluated when the Payment Order is split.

It is of utmost importance that the split tree is verified in its correctness by both Ping Payments and the Tenant so as to ensure that funds end up according to all parties expectations.

Payments

In the Ping Payments™ API, a Payment represents a single purchase attempt made by an end user. It is the core transactional unit used to capture funds in exchange for goods or services.

Structure

A Payment typically

• One or more items of purchase (also called items or order items)
• A specified payment method (e.g., card, swish, deposit, invoice)

Every Payment is associated with a Payment Order, which acts as a container for one or more payments related to the same purchase or checkout flow.

Items

Each Payment consists of one or more items, which typically represent individual products or services included in a purchase. These items are conceptually similar to order lines in a traditional checkout flow.

Each item defines:

• A name of the product or service
• The amount to be charged for that item
• VAT rate for that item
• The recipient merchant or liquidity account that should receive the funds for the item
• Optional tags that can be used in future selection filters for operations or statistics

Items enable fine-grained control over how a payment is distributed — allowing a single payment to be split across multiple merchants/liquidity accounts based on the composition of the purchase.

Payment Methods

The Ping Payments API supports a number of different payment methods. See Payment Methods for more information.