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@example.com.
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 ether 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
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.
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.
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
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.
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.
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
If you need to create an invoice against and 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.
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
*_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
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
3. Invoicing Separately
Perhaps your industry requires that you invoice after an order is fulfilled. If that's the case, you would set
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
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.
Be sure and contact us if you have questions, suggestions, or just want to chat! We're always available at firstname.lastname@example.org.
Accounts and Keys
There is only one kind of user in the Apruve system. Your role is determined simply by how you
participate in a particular transaction. For any given transaction, there are three different roles:
||The person shopping for products or services, and clicking the Apruve button during checkout.
||The person who will be reviewing and paying for the transaction.
||The person who owns the store.
https://test.apruve.com is a complete clone of https://app.apruve.com. All data and user accounts are separate.
The only difference is that no money will ever change hands on test.apruve.com. It exists only as a test
environment that can be used for exploring how Apruve works, or by software developers who are integrating stores or
developing applications that connect to Apruve. We even provide the ability to create test credit cards and bank accounts.
It is possible to set up both merchant and buyer profiles on the same account. The only requirement is that you must have a unique email address for each account
ProTip: If you use GMail (or a Google Apps account), you can easily make multiple Apruve accounts by adding "+something" to your address.
If your address is email@example.com, you can create accounts like firstname.lastname@example.org, email@example.com and
firstname.lastname@example.org. Emails sent to any of these addresses will show up in your inbox.
Apruve uses API Keys for authentication against our web services. An API Key is a substitute for your username/password
and can be used to provide automated access on your behalf (such as your store, if you are a merchant). Because
they provide access to your Apruve data, API Keys should be treated like any other password and kept secret.
Because it allows a system to access your data on your behalf, an API Key is associated with your user profile. We
recommend creating a unique API Key for each system/store that you integrate with Apruve.
Using your API Key
All your API requests to Apruve should include an
Apruve-Api-Key header that contains your API key:
You can receive automated notifications of events in Apruve via webhooks.
How Apruve Uses Webhooks
webhook_url is specified on a Merchant's profile, Apruve will POST a JSON document to that URL when the status
of an item changes. Apruve expects a 200 response from this POST. If a 200 is not received, we
will keep trying (with exponentially increasing delay) for 24 hours.
The status changes that will trigger a Webhook call are:
- Invoice Closed
- Order Accepted
- Order Canceled
- Payment Term Accepted
The JSON payload will contain the following information:
||A unique ID that can be used to track the messages you've processed.
||The timestamp of the webhook request.
||The type of event that prompted the webhook call. An example is "payment_term.accepted".
||A JSON representation of the subject of the webhook notification (Invoice, Order, or Payment Term).
||The current status of the item being updated.
||The URL for the item from the Apruve API. This URL may be used as a unique identifier for the resource, and/or to fetch the item from the API.
Example Webhook Payload:
Each Webhook has a unique UUID that identifies it. If you have trouble with a Webhook, this would be helpful information to include in a support request.
Every Apruve webhook contains a SHA256/RSA digital signature of the webhook's contents. If the signature can be verified
using Apruve's public key, you can be certain that the webhook contents were generated by Apruve and have not been
tampered with. To verify a webhook, you need the following three pieces of information:
- The signature itself. This can be found in the
X-Apruve-Signature HTTP header included in every Apruve webhook request.
- Apruve's public key. You can get this value interactively via Apruve's Public Key API.
- The raw, unparsed body of the webhook.
The specific procedure for verifying the signature will vary based on your platform's underlying technology. If your platform
does not provide libraries that provide signature verification services, OpenSSL provides command line tools that can.
apruve_public_key = OpenSSL::PKey.read(Apruve::Client.get('public_key.txt').body)
verified = apruve_public_key.verify(
Apruve Webhook Best Practices
To promote the best security in your Apruve webhook notification service, we recommend following these best practices:
- Use SSL/HTTPS in the URL you provide for your webhook service.
- Verify the request signature.
- Create a mechanism to guarantee that only Apruve will know the correct URL. Perhaps the best way to do this would be
to generate a long, random token (sometimes referred to as an API-key, GUID, or UUID) that is specified as part of the
callback URL you provide to Apruve. When you receive the webhook POST, you should authenticate this token and verify
that it is valid.
- You can also query Apruve using the api_url and verify that the status is correct, rather than trusting the data
you receive on the webhook call. For the absolute highest level of security, use the api_url that you received in
the HTTP response when you created the original payment.
Taking these steps will ensure that only Apruve is authenticated and authorized to trigger a status update in your system.
Webhook - invoice.closed
This webhook event is sent to your webhook endpoint when an invoice is closed. The entire invoice is sent as the payload in this webhook.
Once an invoice is closed, it has been paid. If you have been waiting for payment before you deliver, now would be the time to trigger that.
See the example webhook payload above.
Webhook - order.accepted
This webhook event is sent to your webhook endpoint when an order is accepted. The entire order is sent as the payload in this webhook.
For many situations, order Acceptance is the event to be used to decide when to ship a product or deliver a service.
See the example webhook payload above.
Webhook - order.canceled
This webhook event is sent to your webhook endpoint when an order is canceled. The entire order is sent as the payload in this webhook.
If an order is canceled, it should not be delivered as no payment will be possible.
See the example webhook payload above.
Webhook - payment_term.accepted
This webhook event is sent to your webhook endpoint when a payment_term is accepted. The entire payment_term is sent as the payload in this webhook.
Once a payment_term is accepted, that means that a contract for payment is established, in most industries this would trigger fulfillment of your product.
See the example webhook payload above.
You may configure endpoints that Apruve will send webhooks to one of two ways:
- Through your merchant's settings page on your Apruve dashboard. Log into Apruve as the merchant administrator and click the 'Settings' link found on the upper right of the screen. (Make sure you're acting as the merchant--use the drop-down next to the Settings link to switch contexts if necessary). The Technical tab of the Store Profile has a form that will allow you set a URL to receive webhooks.
- Through the Apruve API. The WebhookEndpoint resource allows you to manage your webhook endpoints. Refer to the API docs for details.