Overview of Payments in Fluent

Essential knowledge

Author:

Fluent Commerce staff

Changed on:

25 Oct 2023

Overview

Fluent Order Management enables the management of payments throughout the lifecycle of an Order.
Build custom payment logic into the Order workflow using the OMX Workflow Framework and provided entities.
This document provides an overview of the Payment Data Model and GraphQL API capabilities and does not include any reference Rules, Workflows, or UX Components.

Key points

Pre-requistes
Data Model
Entities
Explanation of the Entity Relationships through an Example
Relationship details
GraphQL queries required for Payments

Pre-requisites

You must have knowledge of how the Workflow Framework works.

Data Model

The following data model is the global entity data model which shows where the Payments solution sits in the Fluent platform.

The following data model outlines the entities available to manage payments.

Entities

These are the entities involved in the Payment orchestration domain.

*Entity*	*Description*
`Order` ¹	Represents the sales order for a customer
`FinancialTransaction` ⁴	A pool of funds available in order to pay for an order
`Fulfilment` ³	A plan to move items in order to deliver on a promise made to a customer
`Payment` ⁵	Represents the process of capturing or refunding part or all of a financial transaction
`PaymentTransaction` ⁶	A log of activities that have occurred whilst processing a payment through its lifecycle
`BillingAccount` ⁸	The source of record for a group of financial operations relating to a customer
`Invoice` ¹²	The document representing the itemised charge to a customer for the supply of goods
`CreditMemo` ⁷	A memorandum issued to indicate a change in an orders sale price

Note

The number on the entities indicates the entities in the data model above.

Explanation of the Entity Relationships through an Example

The following use case explains the relationship between different entities in the Payments domain.

High-level example

This example serves as a practical walkthrough of how the entities related to payments are intended to be used within the lifecycle of an order.

A customer ordered 3 items from an electronic store. The items are a Laptop for $1500, a TV for $1000 and a Speaker for $500. A total of $3000.
The order was paid for with 2 transactions. $500 via gift voucher and the remaining $2500 with a credit card.
The order was then split and fulfilled at 2 separate locations which means 2 shipments were sent to the customer's delivery address.

Entity relationships for the above example

When an
```
`Order`
```
is created using the
```
`createOrder`
```
query, 2
```
`FinancialTransactions`
```
are created with the status
```
`CREATED`
```
. 1 with the
```
`paymentMethod`
```
"CREDITCARD" and another with "GIFTVOUCHER".
Given the order needs to be split, two
```
`Fulfilments`
```
should then be created by the
```
`createFulfilment`
```
query.
Fulfillments are processed which includes picking and packing of fulfillment items.
Payments are captured once corresponding fulfillments are shipped.
```
`Fulfilment 1`
```
contains a TV that is $1000 and is paid through a CREDITCARD (Payment 1) using the
```
`createPayment`
```
query.
- The status of the
```
`FinancialTransaction`
```
  with the
```
`paymentMethod`
```
  CREDITCARD changes to
```
`PARTIALLY_CAPTURED`
```
  by
```
`updateFinacialTransaction`
```
  query to reflect the fact the remaining funds have not been captured yet.
```
`Fulfilment 2`
```
contains a Laptop and a Speaker for $2000 and is partially paid with the remaining authorised funds on the
```
`FinancialTransaction`
```
with
```
`paymentMethod`
```
CREDITCARD (Payment 2) and the remaining outstanding amount via the other
```
`FinancialTransaction`
```
where the
```
`paymentMethod`
```
is GIFTVOUCHER (Payment 3) using
```
`createPayment`
```
query.
- The status of both FinancialTransaction becomes
```
`CAPTURED`
```
  at this point using the updateFinancialTransaction query.
Multiple
```
`PaymentTransactions`
```
will be created for each
```
`payment`
```
using the
```
`createPaymentTransaction`
```
query containing the
```
`status`
```
log for each payment. For example, credit card
```
`PENDING`
```
, or credit card
```
`CAPTURED`
```
.
Once all the payments are captured, 1 invoice is generated using the
```
`createInvoice`
```
query for each
```
`fulfilment`
```
and is sent to the customer.

Relationship details

Entity relationships related to payments are documented below.

*Name*	*Relationship Type*	*Comment*
Customer_Order	Zero-Many	A customer can place many orders at different times, so one `Customer` can have many orders.
Customer_BillingAccount	Zero-Many	A customer can create many accounts each having its own account details so, one `Customer` can have many billing accounts. If the `Customer` is newly created, the customer will not have a `BillingAccount` until it is created.
Order_Fulfilment	Zero-Many	An Order can be split into many fulfillments due to different fulfilments being fulfilled from different locations or at different times, so 1 `Order` can have many `Fulfilment` .
Order_BillingAddress	Zero-One	A customer can optionally add a billing address while ordering items from a store, so an `Order` can store one `BillingAddress` as an attribute.
Order_Invoice	Zero-Many	An Order can have many invoices through the relationship of a fulfillment. An order can have multiple fulfillments and each fulfillment will have an invoice, so one `Order` can have many invoices.
BillingAccount_BillingAddress	Zero-One	A customer can have one address per account so, a `BillingAccount` can have 0 or 1 `BillingAddress` .
FinancialTransaction_Payment	Zero-Many	A financial transaction can have multiple payment methods such as a Credit Card and a Gift Card, so a `FinancialTransaction` can have multiple payments. If the payment is being captured before the order is sent to Fluent Order Management, the `FinancialTransaction` will have 0 `Payment` with the status `CAPTURED` .
Fulfilment_Payment	Zero-Many	A customer can pay for fulfillment through multiple payment methods such as a gift card and a credit card, so a `Fulfilment` can have 0 (no payment made) or many (for example, using a credit card only or using a credit card and a gift card) payments associated with it.
Payment_PaymentTransaction	One-Many	A payment will go through different stages such as authorised, captured, failure etc. Each stage is recorded as a payment transaction so, 1 `Payment` can have many payment transactions.
Order_ReturnOrder	Zero-Many	A customer may want to return different items of order at different times hence creating multiple return orders for each item, so 1 `Order` can have many return orders.
ReturnOrder_CreditMemo	One-One	When an order is returned, or exchange happens, a credit memo is generated for the return order, so 1 `ReturnOrder` can have 1 `CreditMemo` .
BillingAcount_CreditMemo	Zero-Many	There can be multiple transactions, adjustments or refunds involved with a customer’s billing account. Each transaction or adjustment generates a new credit memo so, 1 `BillingAccount` can have many `CreditMemos` .
CreditMemo_Payment	Zero-Many	If the initial payment was made by a credit card and PayPal account by a customer, the respective amount will be paid back to each of the payment methods so, one `CreditMemo` can have many payments. In case of a return or refund, any transaction made between a customer and the business will generate a new `CreditMemo`

GraphQL queries required for Payments

The following queries are required to build a Payment solution:

Query

Description

`createPaymentServiceProvider`

Creates a new

`PaymentServiceProvider`

that enables businesses to accept various payment methods including, credit-card, debit-card, bank transfers, digital wallets and other alternative payment options

`createCustomer`

Creates a new

`Customer`

with a unique

`ID`

to store customer information so that businesses can have a holistic view of their customer including, their contact information, order history and other details.

`createBillingAccount`

Creates a new

`BillingAccount`

for a customer to track their purchase history, their account information and other details.

`createOrder`

Creates a new

`Order`

for a customer so that businesses can process and track orders from various sales channels in a unified system.

(Financial Transactions can also be created here using

`FinancialTransaction`

as a field)

`createFulfilment`

Creates a

`Fulfilment`

for an order so that businesses can provide streamlined order fulfillment to their customers by efficiently processing fulfillments, generating picking/packing slips and triggering shipping processes.

`createFinancialTransaction`

Creates a

`FinancialTransaction`

for an order so that businesses can hold a record of all the financial activities related to an order.

`updateFinancialTransaction`

Updates the status of the

`FinancialTransaction`

of an order so that businesses can modify the

`status`

of the financial activities related to an order.

`createPayment`

Creates a new

`Payment`

for fulfillment so that businesses can keep a record of all payment transactions related to fulfillment.

`updatePayment`

Updates a

`Payment`

for fulfillment so that businesses can modify details such as the status of a payment for fulfillment.

`createPaymentTransaction`

Creates a

`PaymentTransaction`

for a payment which includes the process of transferring funds. It plays a crucial role in exchanging funds securely and efficiently.

`createInvoice`

Creates a new

`Invoice`

for an order or fulfilment so that businesses can dynamically generate invoices based on transaction data for an order or fulfilment and customer information.

`createReturnOrder`

Creates a new

`ReturnOrder`

for a customer so that businesses can create and manage return orders, ensuring that the return for a customer is handled efficiently and consistently.

`createCreditMemo`

Creates a new

`CreditMemo`

for return orders, revised orders or exchange orders so that the businesses can facilitate the creation, approval, and processing of credit memos and also ensure credit memos are accurately associated with corresponding orders, products or billing accounts.

You can find all the GraphQL queries related to Payments here(deprecated).

Note

The given example is one of the use cases. The Payments solution is flexible and can be used in any business according to region-specific or business scenarios. For Example:

Take the Payment before the fulfillments are shipped
Take the Payment before order creation
Might not create a BillingAddress and take BillingAddress as ShippingAddress
Generate and send an Invoice as the order is placed.

Overview of Payments in Fluent

Overview

Key points

Pre-requisites

Data Model

Entities

Explanation of the Entity Relationships through an Example

High-level example

Entity relationships for the above example

Relationship details

GraphQL queries required for Payments

Fluent Commerce staff

Building Blocks

By Type

Legal Resources