{"metadata":{"image":[],"title":"","description":""},"api":{"url":"","auth":"required","results":{"codes":[]},"params":[],"method":"get"},"next":{"description":"","pages":[]},"title":"Merchant Integration Tutorial","type":"basic","slug":"merchant-integration-tutorial-1","excerpt":"","body":"Apruve.js is a JavaScript library that you can use to embed the Apruve checkout into your online store. With a little bit of server-side code, and a little bit of Javascript, you can be up and running with Apruve in no time. This tutorial will provide an overview, along with links to more detailed information where appropriate.\n\n# Step 0: Prerequisites\n\n* You've read our [Merchant Technical Overview](doc:merchant-technical-overview) to get the big picture.\n* You've created an account on test.apruve.com with a [Merchant account and an API Key](doc:accounts-and-keys).\n\n# Step 1: Server-side prep\n\nApruve relies on information provided by your store to feed our approval and payment workflows. Because of this, it's important that you provide the most accurate and complete order information you can. To do this, create an Apruve Order object in JSON using the contents of your shopping cart. Then sign that data with a secure hash to prevent tampering.\n\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Pro Tip\",\n  \"body\": \"If you are using ruby, we have a [gem](https://github.com/apruve/apruve-ruby/) that will create the order object and secure hash for you.\"\n}\n[/block]\n## 1a: Creating an Order JSON Object\n\nHere's an example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"merchant_id\\\": \\\"4d556524255a8e65385f9da2a2693cf1\\\",\\n    \\\"merchant_order_id\\\": \\\"WidgetCo-001\\\",\\n    \\\"amount_cents\\\": 1150,\\n    \\\"currency\\\": \\\"USD\\\",\\n    \\\"tax_cents\\\": 50,\\n    \\\"shipping_cents\\\": 100,\\n    \\\"expire_at\\\": \\\"2014-07-15T10:12:27-05:00\\\",\\n    \\\"po_number\\\": \\\"PO-1234ABC\\\",\\n    \\\"order_items\\\": [\\n        {\\n            \\\"description\\\": \\\"Description for a widget\\\",\\n            \\\"title\\\": \\\"A Widget\\\",\\n            \\\"sku\\\": \\\"SKU-ABCD\\\",\\n            \\\"price_total_cents\\\": 900,\\n            \\\"price_ea_cents\\\": 900,\\n            \\\"quantity\\\": 1\\n        },\\n        {\\n            \\\"description\\\": \\\"Description for another widget\\\",\\n            \\\"title\\\": \\\"Another Widget\\\",\\n            \\\"sku\\\": \\\"SKU-EFGH\\\",\\n            \\\"price_total_cents\\\": 100,\\n            \\\"price_ea_cents\\\": 100,\\n            \\\"quantity\\\": 1\\n        }\\n    ]\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nRefer to the documentation for the [Order](ref:orders) and [OrderItems](ref:orderitems) objects for details on order and order item fields.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"PO Number\",\n  \"body\": \"PO Number is usually entered by the shopper as part of the checkout process, but if you know this value ahead of time you can specify it in the `po_number` field of your order JSON.  This will pre-populate the field in the Apruve checkout with that PO Number.\"\n}\n[/block]\n## 1b: Creating a Secure Hash \n\nTo create the secure hash, make a string by concatentating your API Key and all the **values** of your order object, then perform a SHA256 hex digest function on it. The ordering of the fields is critical and must be in the order specified below.\n\n>**ProTip:** If an optional field has no value, you may leave it out of the hash...just be sure there is no whitespace in the JSON value, either.\n\n### Ordering of fields in the Order object\n**Note:** Not all order and order item fields are included in the hash.  Only include the fields specified below!\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Ordering\",\n    \"h-1\": \"Field Name\",\n    \"h-2\": \"Required\",\n    \"0-1\": \"merchant_id\",\n    \"1-1\": \"merchant_order_id\",\n    \"2-1\": \"amount_cents\",\n    \"3-1\": \"currency\",\n    \"4-1\": \"tax_cents\",\n    \"5-1\": \"shipping_cents\",\n    \"6-1\": \"expire_at\",\n    \"7-1\": \"accepts_payment_terms\",\n    \"8-1\": \"finalize_on_create\",\n    \"9-1\": \"invoice_on_create\",\n    \"0-0\": \"1\",\n    \"1-0\": \"2\",\n    \"2-0\": \"3\",\n    \"3-0\": \"4\",\n    \"4-0\": \"5\",\n    \"5-0\": \"6\",\n    \"6-0\": \"7\",\n    \"7-0\": \"8\",\n    \"8-0\": \"9\",\n    \"9-0\": \"10\",\n    \"0-2\": \"yes\",\n    \"1-2\": \"no\",\n    \"2-2\": \"yes\",\n    \"3-2\": \"no\",\n    \"4-2\": \"no\",\n    \"5-2\": \"no\",\n    \"6-2\": \"no\",\n    \"7-2\": \"no\",\n    \"8-2\": \"no\",\n    \"9-2\": \"no\"\n  },\n  \"cols\": 3,\n  \"rows\": 10\n}\n[/block]\n**Then for each Order Item, in order:**\n[block:parameters]\n{\n  \"data\": {\n    \"0-1\": \"title\",\n    \"1-1\": \"price_total_cents\",\n    \"2-1\": \"price_ea_cents\",\n    \"3-1\": \"quantity\",\n    \"4-1\": \"merchant_notes\",\n    \"5-1\": \"description\",\n    \"6-1\": \"variant_info\",\n    \"7-1\": \"sku\",\n    \"8-1\": \"vendor\",\n    \"9-1\": \"view_product_url\",\n    \"0-0\": \"1\",\n    \"1-0\": \"2\",\n    \"2-0\": \"3\",\n    \"3-0\": \"4\",\n    \"4-0\": \"5\",\n    \"5-0\": \"6\",\n    \"6-0\": \"7\",\n    \"7-0\": \"8\",\n    \"8-0\": \"9\",\n    \"9-0\": \"10\",\n    \"0-2\": \"yes\",\n    \"1-2\": \"no\",\n    \"2-2\": \"no\",\n    \"3-2\": \"no\",\n    \"4-2\": \"no\",\n    \"5-2\": \"no\",\n    \"6-2\": \"no\",\n    \"7-2\": \"no\",\n    \"8-2\": \"no\",\n    \"9-2\": \"no\"\n  },\n  \"cols\": 3,\n  \"rows\": 10\n}\n[/block]\nNote that even though some fields are optional, if they are in the order object you send in the payload then it **must** be in the hash as well.\n\nAfter you create the order string, we prepend the entire thing with your API Key.\n\n\nFor example, consider the example Order above. The string to sign would be all of the **values** from that object, in the order provided above, concatenated into one long string. Before the API key, we get:\n\n>**Note:** This is one long string, with no line breaks!\n\n``` text\n4d556524255a8e65385f9da2a2693cf1WidgetCo-0011150USD501002014-07-15T10:12:27-05:00A Widget9009001Description for a widgetSKU-ABCDAnother Widget1001001Description for another widgetSKU-EFGH\n```\n\nLet's say your API Key is `945d7e36fed1cd8ebaf4eb472eca4dca`. Then, the entire string we're going to hash becomes:\n\n``` text\n945d7e36fed1cd8ebaf4eb472eca4dca4d556524255a8e65385f9da2a2693cf1WidgetCo-0011150USD501002014-07-15T10:12:27-05:00A Widget9009001Description for a widgetSKU-ABCDAnother Widget1001001Description for another widgetSKU-EFGH\n```\n\nFinally, we use the SHA256 algorithm to create a digital signature. Most languages have it built-in. Here's an example in Ruby:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"require 'digest'\\n\\nsecure_hash = Digest::SHA256.hexdigest('945d7e36fed1cd8ebaf4eb472eca4dca4d556524255a8e65385f9da2a2693cf1WidgetCo-0011150USD501002014-07-15T10:12:27-05:00A Widget9009001Description for a widgetSKU-ABCDAnother Widget1001001Description for another widgetSKU-EFGH')\\n=> \\\"f3a9662162f90e3e8b9c75b674af094f3295ee789e9e80197850649c4bd9fbc5\\\"\",\n      \"language\": \"ruby\"\n    }\n  ]\n}\n[/block]\nOK, so now we have the Order JSON object, and our secure hash. We're ready to load `apruve.js`.\n\n# Step 2: Add `apruve.js` to your checkout view\n\n`apruve.js` is the JavaScript library that manages the Apruve button on your checkout page. First, import the script.\nThen initialize it with your Payment Request, your secure hash, and other variables. Last, register a call-back\nfunction. Then put a special `<DIV>` on the page where we want the button to appear.\n\n> For more information, see the [Apruve.js Reference](doc:apruvejs-reference)\n\n## 2a: Import `apruve.js`\n\nDeclare the `apruve.js` script in your HTML markup.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<script src=\\\"https://test.apruve.com/js/v4/apruve.js\\\" type=\\\"text/javascript\\\"></script>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\n>**Test vs. Production URLs**\n>\n>We recommend that you use environment variables to ensure you get the correct script from `test.apruve.com` or `app.apruve.com`, as appropriate.\n\n## 2b: Initialize `apruve.js`\n\nInitialize `apruve.js` with the order JSON and the secure hash that we created on the server.\n\n>**ProTip:** Keep in mind that we want to give `apruve.js` the value of the JSON object, so do NOT surround it with quotes! The secure hash **is** a string, so it **should** be in quotes.\n\n**Initializing `apruve.js` (example shown is written in Ruby ERB)**\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<script type=\\\"text/javascript\\\">\\n    apruve.setOrder(<%= :::at:::order.to_json %>, '<%= @order.secure_hash %>');\\n</script>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\n## 2c: Register JavaScript Callbacks\n\n`apruve.js` can notify you when events happen during the checkout process. We recommend that you register at least one callback function on the `apruve.APRUVE_COMPLETE_EVENT` that will be fired when there is an Order ID available for you to capture.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Event\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"`apruve.APRUVE_LAUNCHED_EVENT`\",\n    \"2-0\": \"`apruve.APRUVE_CLOSED_EVENT`\",\n    \"1-0\": \"`apruve.APRUVE_COMPLETE_EVENT`\",\n    \"0-1\": \"Fires when the shopper clicks on the Apruve button.\",\n    \"1-1\": \"Fires when the Apruve lightbox has closed, and the shopper has successfully created an Order.\\nWhen this event fires, the Order ID will be passed as a parameter to your callback function.\",\n    \"2-1\": \"Fires when the Apruve lightbox has closed, but the shopper has NOT successfully created an Order. Usually, this is because the shopper has cancelled the process before completing it. Sometimes this happens if there was an error during checkout. It would be good to check and log `apruve.errors`.\"\n  },\n  \"cols\": 2,\n  \"rows\": 3\n}\n[/block]\nHere is an example of our Javascript block, extended from the one above. Note that `apruve.paymentRequest` and the `apruve.secureHash` variables are set via server-side parameters. As above, the example here uses Embedded Ruby. You should use what is appropriate for your server platform. Also, we use JQuery in the callback we registered. Again, this is a convenient example, and you should use whatever means is appropriate to post the `apruve.orderId` to your server.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<script type=\\\"text/javascript\\\">\\n    apruve.setOrder(<%= @order.to_json %>, '<%= @order.secure_hash %>');\\n    apruve.registerApruveCallback(apruve.APRUVE_COMPLETE_EVENT, function (orderId) {\\n        // The order ID is passed into your callback function as a parameter\\n        // Use any mechanism, such as a hidden form field, to post the ID to your server.\\n        $('#orderId').val(orderId)\\n        $('#confirmOrderForm').show()\\n    });\\n</script>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\n## 2d: Place the Apruve &lt;DIV&gt; tag\n\nDetermine where you want the Apruve button to appear on your checkout page, and place a DIV there with `id='apruveDiv'`, like the following:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<div id=\\\"apruveDiv\\\"></div>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\n# Step 3: Post the orderId to your server\n\nYour checkout page is almost complete. If you try it out, it should even work! But we're not quite done. Apruve has created an orderId to represent the transaction, which you will need for all other communication related to this order.\n\nYou need to get the orderId that apruve.js created, attach it to your order, and save it in your database. You are free to do this however you like. Here are some suggestions:\n\n* If you have a \"review and confirm\" page where the shopper must review their order before it is placed, you should put the orderId in a hidden field on that form. Then, when the shopper clicks your \"Place Order!\" button, it gets sent to your server. This is a very common scenario.\n* Use AJAX in the callback you registered to send the ID to your server. As long as you are registering the callback to run on the `APRUVE_COMPLETE_EVENT`, `apruve.orderId` will have been set.\n\nBy default, when checkout completes, Apruve will finalize the Order, generate an Invoice based on the Order's contents, issue that Invoice to the buyer, and charge the buyer's bank account (if applicable for the given payment method).\n\n# Step 4: (Optional) POST an Invoice to Apruve\n\nSome stores might need to exercise a little more control over the lifecycle of the Order. They might not have shipping and tax amounts available at checkout, or they might want to wait to generate an Invoice until products are in stock. Apruve can support virtually any scenario via the Order object's `finalize_on_create` and `invoice_on_create` flags [more information available here](ref:section--_on_create-fields).\n\nIf your use case requires that you create Invoices yourself, you can do so using Apruve's Invoice API.\n\nHere's what a simple Invoice JSON document looks like. There's lots of information about it in the [API docs for Invoices](ref:invoices) . If you haven't read it already, you'll also want to review the [Apruve REST API](ref:getting-started-1) documents for how to use your API Key for authentication, set request headers, etc.\n\n**The request body of a Invoice POST:**\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"amount_cents\\\":1150,\\n    \\\"currency\\\":\\\"USD\\\",\\n    \\\"tax_cents\\\": 50,\\n    \\\"shipping_cents\\\": 100,\\n    \\\"expire_at\\\": \\\"2014-07-15T10:12:27-05:00\\\",\\n    \\\"invoice_items\\\": [\\n        {\\n            \\\"description\\\": \\\"Description for a widget\\\",\\n            \\\"title\\\": \\\"A Widget\\\",\\n            \\\"sku\\\": \\\"SKU-ABCD\\\",\\n            \\\"price_total_cents\\\": 900,\\n            \\\"quantity\\\": 1\\n        },\\n        {\\n            \\\"description\\\": \\\"Description for another widget\\\",\\n            \\\"title\\\": \\\"Another Widget\\\",\\n            \\\"sku\\\": \\\"SKU-EFGH\\\",\\n            \\\"price_total_cents\\\": 100,\\n            \\\"quantity\\\": 1\\n        }\\n    ]\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nWe're going to POST this to Apruve. If we get an HTTP 201 response back, you've created your Invoice! Your response body will include a status. If the status is `closed`, you've been paid. If it is `open`, you are still awaiting payment for the invoice. This could be because the buyer still needs to provide a payment method, etc.\n\n# Step 5: (Optional) Register a Web Hook\n\nIf you want to be notified when Orders are approved or rejected, when invoices are paid, or when payment terms for an order are accepted, you can register a web hook. There's lots more detail about the different webhooks and what they mean in the [Webhooks](doc:webhooks) section of the API documentation. We **strongly** recommend that you set up a web hook handler for your store, as web hooks are the simplest, most reliable way to decide when to fulfill an order. \n\n## 5a: Create a Web Service to Receive The Web Hook Notification\n\nFirst, create a service that will receive the web hook. Apruve will automatically post a small JSON blob to that URL whenever a certain events occur.\n\n**Example Web Hook Notification for an Invoice**\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"uuid\\\":\\\"abcdefghi\\\",\\n    \\\"created_at\\\":\\\"2016-02-01T06:00:00\\\",\\n    \\\"event\\\":\\\"invoice.closed\\\",\\n    \\\"entity\\\": {\\n        \\\"amount_cents\\\":1150,\\n        \\\"currency\\\":\\\"USD\\\",\\n        \\\"tax_cents\\\": 50,\\n        \\\"shipping_cents\\\": 100,\\n        \\\"expire_at\\\": \\\"2014-07-15T10:12:27-05:00\\\",\\n        \\\"invoice_items\\\": [\\n            {\\n                \\\"description\\\": \\\"Description for a widget\\\",\\n                \\\"title\\\": \\\"A Widget\\\",\\n                \\\"sku\\\": \\\"SKU-ABCD\\\",\\n                \\\"price_total_cents\\\": 900,\\n                \\\"quantity\\\": 1\\n            },\\n            {\\n                \\\"description\\\": \\\"Description for another widget\\\",\\n                \\\"title\\\": \\\"Another Widget\\\",\\n                \\\"sku\\\": \\\"SKU-EFGH\\\",\\n                \\\"price_total_cents\\\": 100,\\n                \\\"quantity\\\": 1\\n            }\\n        ]\\n    }\\n}\\n\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n## 5b: Set a Web Hook URL On Your Merchant Account\n\nIf you edit your Merchant Account in Apruve, you'll see this field:\n\n![merchant webhook field](https://s3.amazonaws.com/apruve-documentation-resources/merchant_webhook_field.png)\n\nEnter the URL for your endpoint in the 'Webhook URL' field and click the Save button. That's it! Apruve should now be sending you notifications for changes in your orders and invoices, allowing you to complete processing of the order appropriately.\n\n# Demo application\n\nTo see all of these principles in action, check out our demo store at [https://merchant-demo.herokuapp.com](https://merchant-demo.herokuapp.com). This store is a very simple Ruby/Sinatra app, and the source code can be found at [https://github.com/apruve/apruve-ruby-demo](https://github.com/apruve/apruve-ruby-demo).","updates":[],"order":3,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"59837eda6050430034ef50ad","project":"58b9e955fba7da250056ff86","version":{"version":"4.0","version_clean":"4.0.0","codename":"","is_stable":true,"is_beta":false,"is_hidden":false,"is_deprecated":false,"categories":["58b9e955fba7da250056ff8a","58b9e9e168a4a5190011dcc2","58b9ea1de87271190074c623","58b9f9df4022e60f00ae20af","58bda4f77181082500275455","58bda69b8bcd092f00e52862","58bda751b4e9640f00e4bdaf","58e800fabc0deb0f002801f3","5925bfd9504e5239003807f4","5925c026aef9fd27008525c0","5925c0e7dd71b51b00ccc329","592d872451a3e80f00eb4a1a","592d9539b9b6b91900569ea0","592d990a51a3e80f00eb4c25","592d9bf480832f0f00ddfa46","592d9d5051a3e80f00eb4e02","592dbd5cd97832190073d76a","598360d76050430034ef4e07","598363237c926c0028d2e420","598363755de0a1002049efad","598363c27c926c0028d2e442","59c15f2ebc639a0032f770f0"],"_id":"58b9e955fba7da250056ff89","releaseDate":"2017-03-03T22:08:21.880Z","__v":22,"createdAt":"2017-03-03T22:08:21.880Z","project":"58b9e955fba7da250056ff86"},"category":{"sync":{"isSync":false,"url":""},"pages":[],"title":"Developer Resources","slug":"developer-resources-1","order":2,"from_sync":false,"reference":false,"_id":"598360d76050430034ef4e07","project":"58b9e955fba7da250056ff86","version":"58b9e955fba7da250056ff89","isAPI":false,"createdAt":"2017-08-03T17:43:51.991Z","__v":0},"user":"59232ee4e465c11900921e8a","createdAt":"2017-08-03T19:51:54.659Z","githubsync":"","__v":0,"parentDoc":null,"updatedAt":"2019-10-24T18:26:11.742Z"}

Merchant Integration Tutorial


Apruve.js is a JavaScript library that you can use to embed the Apruve checkout into your online store. With a little bit of server-side code, and a little bit of Javascript, you can be up and running with Apruve in no time. This tutorial will provide an overview, along with links to more detailed information where appropriate. # Step 0: Prerequisites * You've read our [Merchant Technical Overview](doc:merchant-technical-overview) to get the big picture. * You've created an account on test.apruve.com with a [Merchant account and an API Key](doc:accounts-and-keys). # Step 1: Server-side prep Apruve relies on information provided by your store to feed our approval and payment workflows. Because of this, it's important that you provide the most accurate and complete order information you can. To do this, create an Apruve Order object in JSON using the contents of your shopping cart. Then sign that data with a secure hash to prevent tampering. [block:callout] { "type": "info", "title": "Pro Tip", "body": "If you are using ruby, we have a [gem](https://github.com/apruve/apruve-ruby/) that will create the order object and secure hash for you." } [/block] ## 1a: Creating an Order JSON Object Here's an example: [block:code] { "codes": [ { "code": "{\n \"merchant_id\": \"4d556524255a8e65385f9da2a2693cf1\",\n \"merchant_order_id\": \"WidgetCo-001\",\n \"amount_cents\": 1150,\n \"currency\": \"USD\",\n \"tax_cents\": 50,\n \"shipping_cents\": 100,\n \"expire_at\": \"2014-07-15T10:12:27-05:00\",\n \"po_number\": \"PO-1234ABC\",\n \"order_items\": [\n {\n \"description\": \"Description for a widget\",\n \"title\": \"A Widget\",\n \"sku\": \"SKU-ABCD\",\n \"price_total_cents\": 900,\n \"price_ea_cents\": 900,\n \"quantity\": 1\n },\n {\n \"description\": \"Description for another widget\",\n \"title\": \"Another Widget\",\n \"sku\": \"SKU-EFGH\",\n \"price_total_cents\": 100,\n \"price_ea_cents\": 100,\n \"quantity\": 1\n }\n ]\n}", "language": "json" } ] } [/block] Refer to the documentation for the [Order](ref:orders) and [OrderItems](ref:orderitems) objects for details on order and order item fields. [block:callout] { "type": "info", "title": "PO Number", "body": "PO Number is usually entered by the shopper as part of the checkout process, but if you know this value ahead of time you can specify it in the `po_number` field of your order JSON. This will pre-populate the field in the Apruve checkout with that PO Number." } [/block] ## 1b: Creating a Secure Hash To create the secure hash, make a string by concatentating your API Key and all the **values** of your order object, then perform a SHA256 hex digest function on it. The ordering of the fields is critical and must be in the order specified below. >**ProTip:** If an optional field has no value, you may leave it out of the hash...just be sure there is no whitespace in the JSON value, either. ### Ordering of fields in the Order object **Note:** Not all order and order item fields are included in the hash. Only include the fields specified below! [block:parameters] { "data": { "h-0": "Ordering", "h-1": "Field Name", "h-2": "Required", "0-1": "merchant_id", "1-1": "merchant_order_id", "2-1": "amount_cents", "3-1": "currency", "4-1": "tax_cents", "5-1": "shipping_cents", "6-1": "expire_at", "7-1": "accepts_payment_terms", "8-1": "finalize_on_create", "9-1": "invoice_on_create", "0-0": "1", "1-0": "2", "2-0": "3", "3-0": "4", "4-0": "5", "5-0": "6", "6-0": "7", "7-0": "8", "8-0": "9", "9-0": "10", "0-2": "yes", "1-2": "no", "2-2": "yes", "3-2": "no", "4-2": "no", "5-2": "no", "6-2": "no", "7-2": "no", "8-2": "no", "9-2": "no" }, "cols": 3, "rows": 10 } [/block] **Then for each Order Item, in order:** [block:parameters] { "data": { "0-1": "title", "1-1": "price_total_cents", "2-1": "price_ea_cents", "3-1": "quantity", "4-1": "merchant_notes", "5-1": "description", "6-1": "variant_info", "7-1": "sku", "8-1": "vendor", "9-1": "view_product_url", "0-0": "1", "1-0": "2", "2-0": "3", "3-0": "4", "4-0": "5", "5-0": "6", "6-0": "7", "7-0": "8", "8-0": "9", "9-0": "10", "0-2": "yes", "1-2": "no", "2-2": "no", "3-2": "no", "4-2": "no", "5-2": "no", "6-2": "no", "7-2": "no", "8-2": "no", "9-2": "no" }, "cols": 3, "rows": 10 } [/block] Note that even though some fields are optional, if they are in the order object you send in the payload then it **must** be in the hash as well. After you create the order string, we prepend the entire thing with your API Key. For example, consider the example Order above. The string to sign would be all of the **values** from that object, in the order provided above, concatenated into one long string. Before the API key, we get: >**Note:** This is one long string, with no line breaks! ``` text 4d556524255a8e65385f9da2a2693cf1WidgetCo-0011150USD501002014-07-15T10:12:27-05:00A Widget9009001Description for a widgetSKU-ABCDAnother Widget1001001Description for another widgetSKU-EFGH ``` Let's say your API Key is `945d7e36fed1cd8ebaf4eb472eca4dca`. Then, the entire string we're going to hash becomes: ``` text 945d7e36fed1cd8ebaf4eb472eca4dca4d556524255a8e65385f9da2a2693cf1WidgetCo-0011150USD501002014-07-15T10:12:27-05:00A Widget9009001Description for a widgetSKU-ABCDAnother Widget1001001Description for another widgetSKU-EFGH ``` Finally, we use the SHA256 algorithm to create a digital signature. Most languages have it built-in. Here's an example in Ruby: [block:code] { "codes": [ { "code": "require 'digest'\n\nsecure_hash = Digest::SHA256.hexdigest('945d7e36fed1cd8ebaf4eb472eca4dca4d556524255a8e65385f9da2a2693cf1WidgetCo-0011150USD501002014-07-15T10:12:27-05:00A Widget9009001Description for a widgetSKU-ABCDAnother Widget1001001Description for another widgetSKU-EFGH')\n=> \"f3a9662162f90e3e8b9c75b674af094f3295ee789e9e80197850649c4bd9fbc5\"", "language": "ruby" } ] } [/block] OK, so now we have the Order JSON object, and our secure hash. We're ready to load `apruve.js`. # Step 2: Add `apruve.js` to your checkout view `apruve.js` is the JavaScript library that manages the Apruve button on your checkout page. First, import the script. Then initialize it with your Payment Request, your secure hash, and other variables. Last, register a call-back function. Then put a special `<DIV>` on the page where we want the button to appear. > For more information, see the [Apruve.js Reference](doc:apruvejs-reference) ## 2a: Import `apruve.js` Declare the `apruve.js` script in your HTML markup. [block:code] { "codes": [ { "code": "<script src=\"https://test.apruve.com/js/v4/apruve.js\" type=\"text/javascript\"></script>", "language": "html" } ] } [/block] >**Test vs. Production URLs** > >We recommend that you use environment variables to ensure you get the correct script from `test.apruve.com` or `app.apruve.com`, as appropriate. ## 2b: Initialize `apruve.js` Initialize `apruve.js` with the order JSON and the secure hash that we created on the server. >**ProTip:** Keep in mind that we want to give `apruve.js` the value of the JSON object, so do NOT surround it with quotes! The secure hash **is** a string, so it **should** be in quotes. **Initializing `apruve.js` (example shown is written in Ruby ERB)** [block:code] { "codes": [ { "code": "<script type=\"text/javascript\">\n apruve.setOrder(<%= @order.to_json %>, '<%= @order.secure_hash %>');\n</script>", "language": "html" } ] } [/block] ## 2c: Register JavaScript Callbacks `apruve.js` can notify you when events happen during the checkout process. We recommend that you register at least one callback function on the `apruve.APRUVE_COMPLETE_EVENT` that will be fired when there is an Order ID available for you to capture. [block:parameters] { "data": { "h-0": "Event", "h-1": "Description", "0-0": "`apruve.APRUVE_LAUNCHED_EVENT`", "2-0": "`apruve.APRUVE_CLOSED_EVENT`", "1-0": "`apruve.APRUVE_COMPLETE_EVENT`", "0-1": "Fires when the shopper clicks on the Apruve button.", "1-1": "Fires when the Apruve lightbox has closed, and the shopper has successfully created an Order.\nWhen this event fires, the Order ID will be passed as a parameter to your callback function.", "2-1": "Fires when the Apruve lightbox has closed, but the shopper has NOT successfully created an Order. Usually, this is because the shopper has cancelled the process before completing it. Sometimes this happens if there was an error during checkout. It would be good to check and log `apruve.errors`." }, "cols": 2, "rows": 3 } [/block] Here is an example of our Javascript block, extended from the one above. Note that `apruve.paymentRequest` and the `apruve.secureHash` variables are set via server-side parameters. As above, the example here uses Embedded Ruby. You should use what is appropriate for your server platform. Also, we use JQuery in the callback we registered. Again, this is a convenient example, and you should use whatever means is appropriate to post the `apruve.orderId` to your server. [block:code] { "codes": [ { "code": "<script type=\"text/javascript\">\n apruve.setOrder(<%= @order.to_json %>, '<%= @order.secure_hash %>');\n apruve.registerApruveCallback(apruve.APRUVE_COMPLETE_EVENT, function (orderId) {\n // The order ID is passed into your callback function as a parameter\n // Use any mechanism, such as a hidden form field, to post the ID to your server.\n $('#orderId').val(orderId)\n $('#confirmOrderForm').show()\n });\n</script>", "language": "html" } ] } [/block] ## 2d: Place the Apruve &lt;DIV&gt; tag Determine where you want the Apruve button to appear on your checkout page, and place a DIV there with `id='apruveDiv'`, like the following: [block:code] { "codes": [ { "code": "<div id=\"apruveDiv\"></div>", "language": "html" } ] } [/block] # Step 3: Post the orderId to your server Your checkout page is almost complete. If you try it out, it should even work! But we're not quite done. Apruve has created an orderId to represent the transaction, which you will need for all other communication related to this order. You need to get the orderId that apruve.js created, attach it to your order, and save it in your database. You are free to do this however you like. Here are some suggestions: * If you have a "review and confirm" page where the shopper must review their order before it is placed, you should put the orderId in a hidden field on that form. Then, when the shopper clicks your "Place Order!" button, it gets sent to your server. This is a very common scenario. * Use AJAX in the callback you registered to send the ID to your server. As long as you are registering the callback to run on the `APRUVE_COMPLETE_EVENT`, `apruve.orderId` will have been set. By default, when checkout completes, Apruve will finalize the Order, generate an Invoice based on the Order's contents, issue that Invoice to the buyer, and charge the buyer's bank account (if applicable for the given payment method). # Step 4: (Optional) POST an Invoice to Apruve Some stores might need to exercise a little more control over the lifecycle of the Order. They might not have shipping and tax amounts available at checkout, or they might want to wait to generate an Invoice until products are in stock. Apruve can support virtually any scenario via the Order object's `finalize_on_create` and `invoice_on_create` flags [more information available here](ref:section--_on_create-fields). If your use case requires that you create Invoices yourself, you can do so using Apruve's Invoice API. Here's what a simple Invoice JSON document looks like. There's lots of information about it in the [API docs for Invoices](ref:invoices) . If you haven't read it already, you'll also want to review the [Apruve REST API](ref:getting-started-1) documents for how to use your API Key for authentication, set request headers, etc. **The request body of a Invoice POST:** [block:code] { "codes": [ { "code": "{\n \"amount_cents\":1150,\n \"currency\":\"USD\",\n \"tax_cents\": 50,\n \"shipping_cents\": 100,\n \"expire_at\": \"2014-07-15T10:12:27-05:00\",\n \"invoice_items\": [\n {\n \"description\": \"Description for a widget\",\n \"title\": \"A Widget\",\n \"sku\": \"SKU-ABCD\",\n \"price_total_cents\": 900,\n \"quantity\": 1\n },\n {\n \"description\": \"Description for another widget\",\n \"title\": \"Another Widget\",\n \"sku\": \"SKU-EFGH\",\n \"price_total_cents\": 100,\n \"quantity\": 1\n }\n ]\n}", "language": "json" } ] } [/block] We're going to POST this to Apruve. If we get an HTTP 201 response back, you've created your Invoice! Your response body will include a status. If the status is `closed`, you've been paid. If it is `open`, you are still awaiting payment for the invoice. This could be because the buyer still needs to provide a payment method, etc. # Step 5: (Optional) Register a Web Hook If you want to be notified when Orders are approved or rejected, when invoices are paid, or when payment terms for an order are accepted, you can register a web hook. There's lots more detail about the different webhooks and what they mean in the [Webhooks](doc:webhooks) section of the API documentation. We **strongly** recommend that you set up a web hook handler for your store, as web hooks are the simplest, most reliable way to decide when to fulfill an order. ## 5a: Create a Web Service to Receive The Web Hook Notification First, create a service that will receive the web hook. Apruve will automatically post a small JSON blob to that URL whenever a certain events occur. **Example Web Hook Notification for an Invoice** [block:code] { "codes": [ { "code": "{\n \"uuid\":\"abcdefghi\",\n \"created_at\":\"2016-02-01T06:00:00\",\n \"event\":\"invoice.closed\",\n \"entity\": {\n \"amount_cents\":1150,\n \"currency\":\"USD\",\n \"tax_cents\": 50,\n \"shipping_cents\": 100,\n \"expire_at\": \"2014-07-15T10:12:27-05:00\",\n \"invoice_items\": [\n {\n \"description\": \"Description for a widget\",\n \"title\": \"A Widget\",\n \"sku\": \"SKU-ABCD\",\n \"price_total_cents\": 900,\n \"quantity\": 1\n },\n {\n \"description\": \"Description for another widget\",\n \"title\": \"Another Widget\",\n \"sku\": \"SKU-EFGH\",\n \"price_total_cents\": 100,\n \"quantity\": 1\n }\n ]\n }\n}\n", "language": "text" } ] } [/block] ## 5b: Set a Web Hook URL On Your Merchant Account If you edit your Merchant Account in Apruve, you'll see this field: ![merchant webhook field](https://s3.amazonaws.com/apruve-documentation-resources/merchant_webhook_field.png) Enter the URL for your endpoint in the 'Webhook URL' field and click the Save button. That's it! Apruve should now be sending you notifications for changes in your orders and invoices, allowing you to complete processing of the order appropriately. # Demo application To see all of these principles in action, check out our demo store at [https://merchant-demo.herokuapp.com](https://merchant-demo.herokuapp.com). This store is a very simple Ruby/Sinatra app, and the source code can be found at [https://github.com/apruve/apruve-ruby-demo](https://github.com/apruve/apruve-ruby-demo).