Apruve REST API

This version is in Beta, there may be issues we're still working out.

Getting Started

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 support@apruve.com.

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 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 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.

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 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 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.

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 support@apruve.com.

Accounts and Keys

User Roles

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:

Role Description
Shopper The person shopping for products or services, and clicking the Apruve button during checkout.
Payer The person who will be reviewing and paying for the transaction.
Merchant The person who owns the store.

test.apruve.com

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 you create.

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 sue@example.com, you can create accounts like sue+shopper@example.com, sue+payer@example.com and joe+merchant@example.com. Emails sent to any of these addresses will show up in your inbox.

API Keys

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.

test.apruve.com app.apruve.com
https://test.apruve.com/api_keys https://app.apruve.com/api_keys

Using your API Key

All your API requests to Apruve should include an Apruve-Api-Key header that contains your API key:

Apruve-Api-Key: f5fbe71d68772d1f562ed6f598b995b3

Webhooks

You can receive automated notifications of events in Apruve via webhooks.

How Apruve Uses Webhooks

When a 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:

Field Name Data Type Comments
uuid String A unique ID that can be used to track the messages you've processed.
created_at Date The timestamp of the webhook request.
event String The type of event that prompted the webhook call. An example is "payment_term.accepted".
entity JSON A JSON representation of the subject of the webhook notification (Invoice, Order, or Payment Term).
status String The current status of the item being updated.
links URL 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:

{
    "uuid":"abcdefghi",
    "created_at":"2016-08-18T10:36:54-05:00",
    "event":"payment_term.accepted",
    "entity": 
    {
        "po_number":"abcdefghi",
        "type":"CorporateAccount",
        "status":"approved",
        "escalated_at":null,
        "final_state_at":null,
        "links":
        {
            "order":"https://test.apruve.com/api/v4/orders/jklmnopqr"
        }
    }
}

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.

Digital Signature

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:

  1. The signature itself. This can be found in the X-Apruve-Signature HTTP header included in every Apruve webhook request.
  2. Apruve's public key. You can get this value interactively via Apruve's Public Key API.
  3. 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.

Ruby Example:

apruve_public_key = OpenSSL::PKey.read(Apruve::Client.get('public_key.txt').body)
verified = apruve_public_key.verify(
                  OpenSSL::Digest::SHA256.new,
                  Base64.decode64(webhook.headers['X-Apruve-Signature']),
                  webhook.body)

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.

Webhooks

Webhook - invoice.closed

Overview

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

Overview

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

Overview

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

Overview

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.

Webhook Endpoints

You may configure endpoints that Apruve will send webhooks to one of two ways:

  1. 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.
  2. Through the Apruve API. The WebhookEndpoint resource allows you to manage your webhook endpoints. Refer to the API docs for details.