We’re #paymentsgeeks, and we love it. Check out our docs and you’ll see.

Modo API Documentation

Modo is a payments orchestration platform for enterprises. We believe marrying money flows and data flows removes complexity throughout the payment lifecycle and allows for better customer experiences, reduced payment cost, and lower operational overhead.

Marrying the data flows and money flows is the fundamental value Modo’s payments orchestration brings. The Modo API is designed to be a predictable and intuitive interface for interacting with payments. We offer secure REST APIs for checkout, vault, and report resources and endpoints. See below for more details on each API.

/checkout

Creating a /checkout is as easy as 1) starting an order 2) accepting a payment 3) providing session information. Do you need to have ALL your order, payment, or session information to create a /checkout? Heck no! Because of our ingenious design those elements can be updated or modified as you gather information from your customers. Each element of /checkout is described below:

What is an order?

The order contains all the information specific to a customer’s purchase, including customer details for the person placing the order (name, address, email etc), what the customer is buying and how much each item costs (could have multiple items in an order), as well as any internal references you the merchant may have for the order. Don’t worry if you don’t have any, Modo will assign each order an unique id that will be associated with all the order details. Certain details, like order amount, can be updated throughout the lifecycle of the order. See below for more information on what actions are available for your checkout.

What is a session?

The session contains all the details around how the order is being placed and even physically where the order is occuring. So if you are an online merchant, the session information will be web-based and may contain information on where the request is coming from (like an ip address, browser type etc). Our API offers many different types of sessions such as mobile, point-of-sale terminals, even fuel dispensers to name a few. See the specification for the full list of session types and details that are supported.

What is a payment?

A ‘payment’ contains information not only about the account holder’s payment method (aka a credit card, a bank account, their paypal wallet etc) but specifies which payment service provider will be used to process the payment (a specific one or “any”). The customer who is making / receiving the order MAY be different from the account holder or payer who is paying for the order so that information is provided separately. Our API offers a number of different payment methods so see our specification for the full list of support methods.

What is a payment service?

A payment service is the provider who is processing the payment(s) on your behalf. During implementation, which payment service(s) you will be configured for your use case. Not sure which one you will be using? You can select ANY as your payment service and that will work for all your payment methods!

The validation_mode determines how much order, payment and session information will be required to complete the /checkout. See below for more details on how to use ACTIONS to step through the lifecycle of your checkout.

/vault

This resource allows you to securely store and tokenize checkout information related to payment details , person information for payer, customer information for an order, and session information.

/reports

This resource returns an array of /checkout objects based on search criteria (data range, checkout_id etc).

/Checkout keeps track of order amounts and ensures those balance (or match) with the payment amounts you receive. We do this by dividing the lifecycle of each payment into 5 states: Validate, Fund, Complete, Settle, and Reconcile. All ledgers and the systems that managed them are required to be in sync in order for the payment to move to the next state.

When using /checkout money flows from a payment account like a card or bank account and eventually lands in either an order (merchant bank account) or fee account. These values are monitored and constantly balanced through settlement and reconciliation. All payments pass through the superset of states below. All accounts including payment, order, and fee accounts move in lock step so they can remain balanced throughout the lifecycle of the /checkout. For example, all accounts must reach validate before any can proceed to Fund. A state may or may not be supported by any given payment type which will allow it to pass through to the next state uninterrupted.

Validate

Evaluate whether /checkout information, including /order, /payment and session information, are valid and sufficient for this validation_mode.
Validation modes include Minimum, Recommended, Maximum depending on the amount of order, session, and payment information required.
Any checkout, order, and payment values provided will be reflected in the accounts and will indicate that no money has moved.
For resources this means:
Payment rules have been met. This includes any required fraud, 3DS1, 3DS2, PIN, AVS, and CVV checks.
Order rules have been met. Order total has been verified against Client order systems if applicable.
This is different from basic data validation, which is performed at the API level.

Fund

Reserves funds against the payment source.
Holds value (when possible) on the /payment for all or part of the order_total or if not provided, the checkout_total, but doesn’t charge payment_method(s) provided.
This step will be skipped when not supported by a given payment type. For example card payments support this as an authorization where as bank transfers have no such concept.
Virtual Accounts are used to track orders, fees and other items that may not be tracked by the payment processor.
For each resources this means:
Payment (hold, authorization, balance inquiry, …).
Order (pickable order, that is accepted).

Complete

Collects funds from the payment source.
“Complete” means that funds have been captured by the processor but have not yet landed in the processor’s bank account.
Goods have been shipped and payments are considered collected or captured.
For each resources this means:
Payment (hold, authorization, balance inquiry, …)
Order (order shipped,)

Settle

Guarantees that funds have been deposited to the Client’s account by the payment processor.
Funds have been deposited to the Client’s account net or gross of fees.
Adjustments to order, payment and fee accounts have been completed.

Reconcile

The window for making accounting adjustments is now past. The Client’s finance division has performed any remaining adjustments and the checkout is frozen for all of eternity.
Any disputes and refunds have been balanced and resolved.
Final adjustments to order, payment and fee accounts have been completed.
No additional account activity will occur.
Client’s offering lifetime returns may choose not to support reconcile.