Overview
Getting Started
Apruve is an automated way to handle payments from your business customers, and to manage payments for your purchases. Every transaction on Apruve starts life as an Order that is submitted to Apruve through a checkout on your shopper's browser. From there, Apruve and the merchant interact over this API to finalize the details of the order.
Beta API and Documentation
This is a BETA copy of our documentation, and our v4 API is still considered BETA as well. This means that things might change without notice, and that the documentation might be wrong too. Please let us know how we can help get you unstuck, or if we can provide clarification, or if we need to update the documentation to make something clearer. Just open an email editor and send us a note at [email protected].
Order Lifecycle
Apruve looks to your eCommerce system as a Payment Gateway. So your customer creates an Order in Apruve as a way to interact with a matching order in your system. Integrating with your eCommerce system is handled either by writing code to interact with apruve.js, or by installing one of our integration plugins.
At the end of Apruve's checkout process, apruve.js will send an Order UUID to your eCommerce system through Javascript. Once your system receives this ID, you may start interacting over this REST API to Apruve.
Depending on your specific business requirements, you may end up having different workflows to get an order approved. But in every case, your order needs to be finalized, and an invoice needs to be issued against that order.
Orders can have the following states:
- new: The Order has been created, but not yet escalated for approval
- pending: The Order is waiting for credit and/or account holder approval
- accepted: The account has sufficient credit available and the account holder has approved the Order
- canceled: The Order has been rejected by the account holder, the purchaser has insufficient credit, or has been canceled by the seller
Finalizing an Order
Finalizing an order signals to Apruve that the eCommerce system is not going to make any further changes to the order before it's presented to the customer. Finalizing an order only signals that the order is ready to be approved by the decision maker. Note that an order does not have to have an invoice on it to be approved, and an approved order does not represent real money movement from the buyer to the seller. It only indicates that the order has been accepted as presented.
Issuing an Invoice
Once the eCommerce system knows what should be charged for the order, it may issue an invoice. The amount of the invoice may differ from the Order, but providing as much data as possible about why an invoice may differ in cost is an important aspect of communicating with your customer.
Once an invoice is issued, it becomes Open and may be paid at any point after that. If the order was approved with a payment method, the invoice may be paid automatically.
Invoices can have the following states:
- pending: The Invoice has been created, but has not yet been issued to the payer
- open: The Invoice has been issued to the payer and is awaiting payment and/or funding
- funded: You have been paid for this Invoice by the bank, but it is still awaiting payment by the purchaser
- closed: The Invoice has been fully paid for by the purchaser
- canceled: The Invoice has been withdrawn, and no goods will be provided or payments will be received
Webhooks and Fulfillment
Invoices and Orders produce Webhook notifications that can be captured by your eCommerce system to indicate to it when to fulfill an order. In most situations, the order going to Approved will be enough to trigger shipment of goods. But in some cases, a more sophisticated system may be required to lower loss risk, or to work within an industries unique constraints.
*_on_create Fields
Getting started with Apruve is easy. Apruve has a number of default flags that make getting started much easier. By default all these flags are true, and must be set to false to disable their behavior.
Order finalize_on_create
For an order to be presented to your customer, it must first be 'Finalized'. This signals to Apruve that the order is not going to have any more changes and that the customer can act upon it. By default Apruve will automatically finalize any order that is submitted, this indicates that the fields of the order are already set and will not change.
Order invoice_on_create
For you to receive money, an invoice must be created and issued to notify a customer that they owe money to a merchant. By default apruve will automatically create an invoice based on the Order information. The amount on the order will become the invoice amount, and the order's order_items will be copied to the invoice. The invoice will automatically be issued.
Invoice issue_on_create
If you need to create an invoice against an order, Apruve will assume that whatever invoice you create should be automatically issued. If you'd like to create an invoice to be opened later, you can set issue_on_create to false so that the invoice does not automatically issue. If you set the invoice this way, you must issue the Invoice manually using the Invoice action.
Use Cases
We want Apruve to be easy to use, even in the API. To borrow a page from Python, we want easy things to be easy and hard things to be possible. We think we've hit that balance with our *_on_create flags, the defaults are easy, but if you need to do something more complicated, they may be turned off.
1. Simple Uses
If you don't need to modify the order or the invoice before the customer is asked for payment, leave all the flags on. Apruve will automatically finalize the order and issue the first invoice and attempt to pay it. You may wish to fetch the order from Apruve after you receive the order_id, to store the order's status, or to inspect if you should fulfill. In this case the only integration points for your system will be this order, and a Webhook handler.
2. Shipping Costs Calculation
If you have to modify the order with shipping cost, tax or some other change, you may turn off finalize_on_create by setting your order's finalize_on_create to false. Once the shipping and tax has been calculated, update the order and finalize it. Since invoice_on_create is still set to true, an invoice will be created and issued when you call finalize.
3. Invoicing Separately
Perhaps your industry requires that you invoice after an order is fulfilled. If that's the case, you would set invoice_on_create to false on the order to ensure that it does not attempt to get paid prematurely. In this case the order would be approved, and at some later time, perhaps after a tracking number for shipment has been assigned, an invoice would be created against the order for payment.
4. Completely Manual
If you require total control over the Apruve process, be sure to set both finalize_on_create and invoice_on_create to false on the order as it's constructed. Once the invoice is created, and updated the way that it is required, you must Finalize the order by POSTing to the Order's Finalize action.
Either before or after you've finalized the order, you will need to create an invoice against the order. If you create the invoice before you finalize, it will remain pending until the order is finalized. If you create the invoice after the order has been finalized, the invoice will be issued automatically as soon as the order is approved.
Stuck?
Be sure and contact us if you have questions, suggestions, or just want to chat! We're always available at [email protected].