We’re #paymentsgeeks, and we love it. Check out our docs and you’ll see.
Modo API Documentation
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!
/vaultThis 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.
/reportsThis 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.
- 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.
- 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).
- 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,)
- 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.
- 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.