Payment

This document outlines a streamlined payment process enabling customers to transfer funds to merchants. The payment can be initiated through messaging platforms or web interfaces, as required. By integrating with an extensive array of payment providers and methods, along with a comprehensive suite of customer experience enhancements, this solution achieves a best-in-class standard.

Key features of the payment action include:

Partial Payments: Allows customers to make multiple payments with different payment methods for the amount due. Note that context.resolutionMode should not be set as on-successful-transaction when enabling partial payments.
Adjustments: Enables additional modifications against the amount. Example: [{"type":"late-fee","amount":10}].
Resolution modes: The payment action will depend on the resolution-mode defined in the context.
- If resolution-mode is set to on-successful-transaction, the action is resolved when the transaction status is APPROVED.
- If resolution-mode is set to on-amount-due, the action is resolved when the total of all APPROVED transactions meets or exceeds the amount specified in the context.

In order to use this action the merchant account must have a product of the following type enabled.

payments

This action pairs well with the following actions.

State

The complete payment action will contain the total amount paid, along with each transaction ID that made up the sum. Each transaction may not just be a CHARGE but could also be a REVERSAL so in complex situations you may need to do a layer of investigation to determine the total sum paid.

Union

When this action is unioned you can no longer use partial payments. There will no longer be a pay button. Instead, the successful resolution of the unioned action will then trigger a payment to take place.

Macro level details for how union attribute behaves can be found within the Union documentation.

Features

Name	Type	Description	Rules
amountToBePaid	number	Amount in cents to be paid. Examples: 100.
description	string	(required) A short description for what is being paid for. Used within messages so keep it simple and direct. Examples: "12-12-2030 Service Appointment", "12 Dozen Roses", "May 2024 Water Bill", "Tacos".	MaxLength: 50 MinLength: 3
reference	string	Reference value for this transaction. Generally this is used for reconciliation of payments with invoices in down stream systems/processes. If specified in features, cannot be specified in context. When placed here we will show the user what this value is. Examples: "ref-123".	MaxLength: 128
currency	string	Currency code. Examples: "USD".	MaxLength: 3 Pattern: ^([A-Z]*)$
noDisplay	boolean	Turns off the display of amount totals and math. This should be disabled in preference of the line-items action. Examples: true.
action	string	Changes the name in messaging and web experiences from 'pay'. Examples: "donate", "subscribe".	MaxLength: 20 Pattern: ^[A-Za-z]+$
partial	object	Enables the customer to make multiple payjments with different payment methods for the amount due. context.resolutionMode should not be on-successful-transaction when enabling partial payments.	See partial
maximumPayableAmount	number	Maximum amount in cents allowed per transaction. Examples: 100.

partial

Name	Type	Description	Rules
min	number	Minimum amount in cents allowed. Examples: 1.	Minimum: 1
max	number	Maximum amount in cents allowed. Examples: 100.	Minimum: 1

Context (required)

Name	Type	Description	Rules
amount	number	Deprecated use features.amountToBePaid. Amount in cents to be paid. Examples: 100.
adjustments	array	Additional modifications to make against the amount. These will be calculated in order. You will see adjustments show up here from other actions, such as convenience-fee. Examples: `[{"type":"discount","amount":10}]`.	See adjustments
reference	string	Reference value for this transaction. Generally this is used for reconciliation of payments with invoices in down stream systems/processes. If specified in context, cannot be specified in features. When placed within context it will not be shown to the user. Examples: "ref-123".	MaxLength: 128
resolutionMode	string	How this action will determine it has 'completed' its task. If on-successful-transaction is chosen then any successful payment, of any amount, will resolve this action. Otherwise, the full amount must be captured across multiple transactions. Examples: "amount-due".	Possible values: `amount-due`, `on-successful-transaction`.
expirationMode	string	If a payment has been made, but this business process fails, what should we do with any transactions made during that time. Examples: "none".	Possible values: `reversal`, `none`.
metadata	object	Key value pairs to attach to the transaction, or broadcast in webhooks. Examples: `{"key":"value"}`.

adjustments

Name	Type	Description	Rules
type	string	(required) The type of adjustment being made. Examples: "discount".	MaxLength: 32
amount	number	(required) Amount in cents for the adjustment. Examples: -10, 10.
description	string	A friendly description of the adjustment being made. Examples: "Discount applied for being a good customer.".	MaxLength: 256 MinLength: 3

Example

Below is an example payload for adding an action to a business process or blueprint.

{
    "type": "payment",
    "union": 0,
    "context": {
        "amount": 100,
        "adjustments": [
            {
                "type": "discount",
                "amount": 10
            }
        ],
        "reference": "ref-123",
        "resolutionMode": "amount-due",
        "expirationMode": "none",
        "metadata": {
            "key": "value"
        }
    },
    "features": {
        "amountToBePaid": 100,
        "description": "Tacos",
        "reference": "ref-123",
        "currency": "USD",
        "noDisplay": true,
        "action": "subscribe",
        "partial": {
            "min": 1,
            "max": 100
        },
        "maximumPayableAmount": 100
    }
}