This document is intended for app developers using our developer portal.
\nBefore using this API, you will need a developer portal account, if you do not have one of these, please contact us via online chat or support@shuttleglobal.com. Please login, and add an application. You will be provided a set of sandbox credentials including a shared_key and secret_key.
An integration consists of:
\nUX Components: Shuttle provides a number of ready made \"widgets\" you can use to accelerate development:
\nOnboarding: Allow a merchant to select and connect a payment processor.
\nCheckout: Capture payment details.
\nAuthenticate: Checkout using a payment wallet, where the wallet is also providing authentication and shipping address capture.
\nMerchant View: Allow your staff or merchants browse payment related data and perform common tasks like refunds.
\nREST API: Shuttle provides a full-featured REST API
\nWebhooks: Stay up to date with real time webhooks
\nA message SETUP_STATUS will indicate a change in whether Shuttle is ready to process payments for this merchant. This will also be raised on load for convenience.
Where:
\nFor example:
\nevent = {\n ...\n data: {\n message: \"SETUP_STATUS\",\n payment_ready: true\n }\n ...\n}\nA message EXTEND_SESSION will be raised when a server request is made, so that you can extend the session of the user in your app (if you so wish). The intent is to prevent your session expiring if they are configuring payment processors for some time. This will generally only be raised at most once per minute.
Where:
\nExample:
\nevent = {\n ...\n data: {\n message: \"EXTEND_SESSION\"\n }\n ...\n}\nA message SETUP_DISPLAY will indicate the frame height has changed, eg after a re-render. Shuttle.js will use this to resize the frame. This message also contains a boolean indicating if we are displaying a modal dialog if you decide to dim / block any other controls on the page.
Where:
\nFor example:
\nevent = {\n ...\n data: {\n message: \"SETUP_DISPLAY\",\n height: 137,\n modal: false\n }\n ...\n}\nA message SETUP_ERROR will indicate an error has occurred in the setup component. The typical use case is the session has expired however errors may occur for other reasons.
Where:
\nFor example:
\nevent = {\n ...\n data: {\n message: \"SETUP_ERROR\",\n type: \"SESSION_EXPIRED\",\n error: \"Session expired\"\n }\n ...\n}\nThe onboarding component allows a merchant (business), connect their payment processor(s) through which they wish to collect payment.
\n![\"embed_multi\"](\"https://cdn.shuttleglobal.com/api/onboarding/multi.png\")
\n\nBefore using the onboarding component, you must first create a Shuttle \"instance\" for the merchant via POST /instances
You can check if you have done this via GET /instances/:instance_key/capabilities
Everything in Shuttle is organised under the instance_key, which should generally be you primary key for your merchant.
See:
\nThere are 4 steps to merchant onboarding:
\nSee if an instance for the merchant exists in Shuttle
\nIf required, create an instance for the merchant on Shuttle (see pre-requisites)
\nCreate a deep_link to the onboarding component for the merchant
Embed the onboarding component on your site via shuttle.js
// Server Side\n// Check if the merchant is ready to process payments\ninstance = GET [api]/instances/:instance_key/capabilities\n// If they don't have a Shuttle instance, create one\nif (HTTP 404) {\n POST [api]/instances {...options}\n}\n// Create a deep_link embed onboarding\ndeep_link = POST [api]/instances/:instance_key/deep_links {...options}\n\nThen when rendering your page:
\n// Rendering Engine\n// Include shuttle.js\n<script src=\"https://app.shuttleglobal.com/shuttle-1.4.X.js\">\n{{if !instance.payments_ready}}\n // Show call to action to configure payments\n{{/if}}\n// Include a container div for the onboarding component\n<div class='preserveHtml' class='preserveHtml' data-shuttle-embed=\"${deep_link.id}\"></div>\n// If the <div class='preserveHtml' class='preserveHtml' class='preserveHtml'> is added to the DOM AFTER page load, call\nShuttle.bind();\n\nTry it now: JSFiddle
\nSee also:
\n\nThe onboarding component component is designed to be presented inline within your app as such.
\n![\"embed_inline\"](\"https://cdn.shuttleglobal.com/api/onboarding/embed_inline.png\")
\n\nYou can adjust key CSS elements such as font, text-size and colors to make it feel more natural within your app.
\nWhile we've tried to make the UX feel natural in any environment, if its too different, we suggest presenting it in a modal dialog, such as:
\n![\"embed_popup\"](\"https://cdn.shuttleglobal.com/api/onboarding/embed_popup.png\")
\n\nA Javascript message of type SETUP_DISPLAY will be raised every page render with the vertical height of the component so you can adjust your page if required, this also includes a modal flag to indicate if a modal dialog is being presented should you want to obscure your page.
As merchants have a contract with you (the software vendor) and not Shuttle, they must agree to Shuttle's terms and conditions before using Shuttle. You can let us handle this, and we will prompt the user to agree to them on first use, or you can reflect Shuttle's terms and conditions in your terms and conditions with the user, and disable Shuttle's prompt. You can do this in the Developer section of the portal.
\n![\"embed_activate\"](\"https://cdn.shuttleglobal.com/api/onboarding/activate.png\")
\n\nA new merchant is prompted to \"Add Payment Processor\". When adding a payment processor, if you have multiple payment processors enabled they will be taken to a selection screen, if you only have one available then they will skip this step.
\n![\"new\"](\"https://cdn.shuttleglobal.com/api/onboarding/new.png\")
\n\nWhen multiple payment processors are enable, the user will be prompted to select one, a country selector helps the merchant select one that onboards merchants in their country. The country selector will only display countries supported via the enabled processors.
\n![\"add\"](\"https://cdn.shuttleglobal.com/api/onboarding/add.png\")
\n\nSome processors require an OAUTH (login) process, whereas other require API keys. For those requiring an OAUTH login process, the login will be opened in a popup as such:
\n![\"oauth\"](\"https://cdn.shuttleglobal.com/api/onboarding/oauth.png\")
\n\n![\"oauth_ext\"](\"https://cdn.shuttleglobal.com/api/onboarding/oauth_ext.png\")
\n\n![\"connecting\"](\"https://cdn.shuttleglobal.com/api/onboarding/connecting.png\")
\n\nOnce you've connected a payment processor the user will see the edit page, here they can control any configuration as well as disconnect the payment processor. Different payment processors have different options:
\n![\"edit_stripe\"](\"https://cdn.shuttleglobal.com/api/onboarding/edit_stripe.png\")
\n\n![\"edit_paypal\"](\"https://cdn.shuttleglobal.com/api/onboarding/edit_paypal.png\")
\n\nThis screen is also used for connecting a payment processor via API keys, for example checkout.com.
\n![\"edit_checkout\"](\"https://cdn.shuttleglobal.com/api/onboarding/edit_checkout.png\")
\n\n\n\nTIP!
\n
We try to make configuration as simple as possible and automatically reflect the configuration of the payment processor, however this is not always possible and it is ultimately the merchant's responsibility to ensure the Shuttle and payment processor are configured inline. For example, if they have configured \"billing address\" as mandatory on the gateway's fraud rules, they should ensure \"Require address (AVS)\" is selected Shuttle, so that it is always prompted during checkout.
A merchant can connect multiple payment processors to cater for the following scenarios:
\nWhen switching payment processors, they can connect a new payment processor, and direct new transactions to that, while retaining the old connection for saved cards and for refunding old transactions.
\nTo run different payment methods into different payment processors, eg Stripe + Paypal
\nWhen the merchant connects multiple processors, the screen will display the list of supported payment methods and which processor will be used for it. A payment processor with no payment methods directed to it can still be used if a card has been saved to it.
\n\n\n![\"multi\"](\"https://cdn.shuttleglobal.com/api/onboarding/routing.png\")
\n\nBy design, you can only route payments based on high level type (cards / wallets / direct debit), and you cannot route for example AMEX to one processor and VISA to another, or local cards to one processor and international cards to another.
\nWhen the onboarding component is opened a Javascript message SETUP_STATUS will be raised with a boolean payment_ready to indicate if a valid configuration exists to process a payment, as the user connects / disconnects payment processors, if payment_ready changes, SETUP_STATUS will be raised again.
This is to allow you adjust your call to action from \"configure payments\", to whatever you want once they have been configured.
\nYou can access further details around the connected processors via the REST API.
\nSee:
\nCapabilities API, for the current payment capabilities of the merchant
\nGateways API, for a list of current and historical processor connections
\nLegal Entity Routes API, for a list of current and historical payment method routing rules
\nTo embed a deep_link onto a page:
\nCreate the deep_link server-side via POST /deep_links
\nOn the client side, include shuttle.js
Mark up the
\n where you want to place the deep link with a data-shuttle-embed attribute
If you added the
\n AFTER page load, you will need to run Shuttle.bind();
// Include shuttle.js on the page\n<script src=\"https://app.shuttleglobal.com/shuttle-1.4.X.min.js\"></script>\n// Include a container div, with data attribute \"data-shuttle-embed\"\n<div class='preserveHtml' class='preserveHtml' data-shuttle-embed=\"${deep_link.id}\"></div>\n// If the <div class='preserveHtml' class='preserveHtml' class='preserveHtml'> is added to the page after page load, call\nShuttle.bind();\n\nTry it now: JSFiddle
\n","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"id":"b82a0121-b417-4727-9d0e-5ff1e92af948","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"d63bafbb-5462-40e3-9b0b-27754c770fa9","type":"text/javascript","exec":[""]}}],"_postman_id":"d95bf841-c0b5-4fa3-bbff-0c5dd7dcd1be"},{"name":"Payment","item":[],"id":"9dd09218-5f9c-4e04-a19f-105607a75c8a","description":"The payment popover works the same way as setup by constructing your options and signature. Note you can pass a success_url which will redirect the browser to a new URL on successful payment, or catch the javascript window message.
Try it now: JSFiddle
\nvar options = {\n instance_key: \"10000\",\n amount: \"100\",\n currency: \"USD\"\n};\n\nWhere options support all parameters from the REST API (except payment_method):
In addition, the following options are available that only affect the UX:
To use button DOM attributes, you will need to populate:
\n* data-shuttle-payment: With the serialised options\n* data-shuttle-signature: With the signature
eg
\nfor Javascript, call:
\nvar options = {...};\nvar signature = generateSignature(options);\n// Note: signature generation should be server side,\n// never pass your secret-key to the client browser \nShuttle.doPayment(options, signature);\n\nYou only need to use the success_url (for multi-page apps) or catch the PAYMENT_CLOSE window event (for single-page apps) to transition the user to the next state in your user flow. A number of additional messages are however available.
A message PAYMENT_CLOSE will be raised when the payment dialogue is closed. Only one of success or cancelled will be returned, if cancelled you should check for error, which describes any reasons outside of the user's control why this could not be completed (eg an integration error). If success is returned, so will some or all of payment, contract, transaction and status (see below).
Where:
\nExample:
\n// Cancellation\nevent = {\n ...\n data: {\n message: \"PAYMENT_CLOSE\",\n cancelled: true,\n error: \"Invalid account\"\n }\n ...\n}\n// Successful recurring payment\nevent = {\n ...\n data: {\n message: \"PAYMENT_CLOSE\",\n success: true,\n contract: {\n \"id\": \"co_5139_36612\",\n \"alt_key\": \"00036612\",\n \"account\": \"acc_5139_10163\",\n \"payment_method\": \"pm_5139_10123\",\n \"parent\": \"co_5139_1234\",\n \"currency\": \"AUD\",\n \"amount\": \"100\",\n \"frequency\": \"WEEKLY\",\n \"next_charge\": \"2019-11-01T16:25:02.000Z\",\n \"status\": \"ACTIVE\",\n \"description\": \"UK Compassion\",\n \"created\": \"2019-10-01T16:25:02.000Z\",\n \"updated\": \"2019-10-01T16:25:04.000Z\",\n \"initiated\": \"2019-10-01T16:25:02.000Z\"\n },\n transaction: {\n \"id\": \"tr_5139_10150\",\n \"action\": \"PAYMENT\",\n \"source\": \"RECURRING\",\n \"status\": \"SUCCESS\",\n \"gateway_status\": \"APPROVED\",\n \"gateway_reference\": \"ch_1FOo9r28aBTFOTZXpwpY2cZY\",\n \"authorisation_code\": \"pi_1FOo9r28aBTFOTZXZvU6o8eC (TEST)\",\n \"reference\": \"REF-00010150\",\n \"amount\": \"100\",\n \"balance\": \"0\",\n \"currency\": \"AUD\",\n \"channel\": \"ch_5139_10000\",\n \"initiative\": \"in_5139_10000\",\n \"designation\": \"des_5139_10000\",\n \"legal_entity\": \"le_5139_10000\",\n \"gateway\": \"gw_5139_10020\",\n \"account\": \"acc_5139_10163\",\n \"payment_method\": \"pm_5139_10123\",\n \"contract\": \"co_5139_10186\",\n \"created\": \"2019-10-01T16:25:02.000Z\",\n \"processed\": \"2019-10-01T16:25:04.000Z\"\n },\n status\": \"SUCCESS\"\n }\n ...\n}\n\nA message PAYMENT_SUCCESS will be raised as soon as a payment is successfully performed in ADVANCE of PAYMENT_CLOSE. This will be raised while the popover is still visible once the decision to progress to the receipt screen is made. As client-side messaging is inherently insecure (ie a user could fake a message in the browser \"inspector\"), it is advised you validate the transaction via server request before performing any important business logic (like dispatching goods). As this message will arrive earlier than the PAYMENT_CLOSE message (which isn't until the dialogue is closed) it provides a way to start loading content so you can be more responsive when the popover is closed.
Where:
\nFor example:
\nevent = {\n ...\n data: {\n message: \"PAYMENT_SUCCESS\",\n contract: {\n id: \"co_5139_36612\",\n alt_key: \"00036612\",\n account: \"acc_5139_10163\",\n payment_method: \"pm_5139_10123\",\n parent: \"co_5139_1234\",\n currency: \"AUD\",\n amount: \"100\",\n frequency: \"WEEKLY\",\n next_charge: \"2019-11-01T16:25:02.000Z\",\n status: \"ACTIVE\",\n description: \"UK Compassion\",\n created: \"2019-10-01T16:25:02.000Z\",\n updated: \"2019-10-01T16:25:04.000Z\",\n initiated: \"2019-10-01T16:25:02.000Z\"\n },\n transaction: {\n id: \"tr_5139_10150\",\n action: \"PAYMENT\",\n source: \"RECURRING\",\n status: \"SUCCESS\",\n gateway_status: \"APPROVED\",\n gateway_reference: \"ch_1FOo9r28aBTFOTZXpwpY2cZY\",\n authorisation_code: \"pi_1FOo9r28aBTFOTZXZvU6o8eC (TEST)\",\n reference: \"REF-00010150\",\n amount: \"100\",\n balance: \"0\",\n currency: \"AUD\",\n channel: \"ch_5139_10000\",\n initiative: \"in_5139_10000\",\n designation: \"des_5139_10000\",\n legal_entity: \"le_5139_10000\",\n gateway: \"gw_5139_10020\",\n account: \"acc_5139_10163\",\n payment_method: \"pm_5139_10123\",\n contract: \"co_5139_10186\",\n created: \"2019-10-01T16:25:02.000Z\",\n processed: \"2019-10-01T16:25:04.000Z\"\n },\n status\": \"SUCCESS\"\n }\n ...\n}\n\nA message PAYMENT_FAILURE will be raised each time a payment is attempted unsuccessfully - in practice this should only be when a card is declined by a payment processor - unless for example a saved payment method is selected that is concurrently archived in another window by the user. Please note, the user is advised of the failure and prompted to try again, there is no intended business case where you should need to catch this message. When receiving this message, keep in mind the dialogue has not yet been closed, and the user may subsequently successfully process payment prior to closing the dialogue. For example:
Where:
\nevent = {\n ...\n data: {\n message: \"PAYMENT_FAILURE\",\n transaction: {\n id: \"tr_1000_31745\",\n action: \"PAYMENT\",\n status: \"DECLINED\",\n gateway_status: \"DECLINED_ERROR\",\n gateway_message: \"INVALID: 4020 : Information received from an Invalid IP address.\",\n reference: \"BOLT-00031745\",\n amount: \"1\",\n balance: \"0\",\n currency: \"AUD\",\n initiative: \"in_1000_1101\",\n gateway: \"gw_1000_1340\",\n account: \"acc_1000_4940\",\n payment_method: \"pm_1000_22901\",\n created: \"2019-01-10T10:47:58.000Z\",\n processed: \"2019-01-10T10:47:58.000Z\"\n }\n } \n}\n\nThe select token popover allows you to tokenise a card for use on a later payment, and update the payment method of one or more recurring contracts. This process allows selection of an existing saved payment method, or tokenisation of a new payment method.
\nTo use, construct your options and signature then invoke the popup via Javascript or HTML DOM element (recommended). Note you can pass a success_url which will redirect the browser to a new URL on successful selection, or catch the javascript window message.
Try it now: JSFiddle
\nA typical example set of options, to update the payment method on failing contract co_1234_5678 would be:
var options = {\n instance_key: \"10000\",\n account: \"1234_1023\",\n contracts: [\"co_1234_5678\"],\n title: \"Update Payment Details\"\n};\nWhere options supports:
In addition, the following options are available that only affect the UX:
To use button DOM attributes, for accessibility its recommended you do this for a <a> or <button> tag, you will need to populate:
data-shuttle-token: With the serialised optionsdata-shuttle-signature: With the signatureeg <button data-shuttle-token=\"options\" data-shuttle-signature=\"signature\"></button>
for Javascript, call:
\nvar options = {...};\nvar signature = generateSignature(options);\n// Note: signature generation must be done server side,\n// never pass your secret-key to the client browser \n\nShuttle.selectToken(options, signature);\nYou only need to use the success_url (for multi-page apps) or catch the SELECT_TOKEN_CLOSE window event (for single-page apps) to transition the user to the next state in your user flow. A number of additional messages are however available.
A message SELECT_TOKEN_CLOSE will be raised when the card selection is closed. Only one of success, cancelled will be returned, if cancelled you should check for error, which describes any reasons outside of the user's control why this could not be completed (eg an integration error). If success is returned, a payment_method will be returned also.
Where:
\nFor example:
\nevent = {\n ...\n data: {\n message: \"SELECT_TOKEN_CLOSE\",\n cancelled: true,\n error: \"Invalid account\"\n }\n ...\n}\n...\nevent = {\n ...\n data: {\n message: \"SELECT_TOKEN_CLOSE\",\n success: true,\n payment_method: {\n \"id\": \"pm_5139_10120\",\n \"account\": \"acc_5139_10160\",\n \"code\": \"00010120\",\n \"created\": \"2019-10-01T16:12:17.000Z\",\n \"gateway\": \"gw_5139_10020\",\n \"last_used\": \"2019-10-01T16:12:17.000Z\",\n \"name\": \"Visa ending 4242, exp 12/22\",\n \"status\": \"ACTIVE\",\n \"type\": \"VISA\",\n \"last4\": \"4242\",\n \"expiry\": \"12/2022\"\n },\n contracts: [{...}]\n }\n ...\n}\nA message SELECT_TOKEN_SUCCESS will be raised as soon as a token is successfully selected in ADVANCE of SELECT_TOKEN_CLOSE. This will be raised while the popover is still visible once the decision to progress to the receipt screen is made. As client-side messaging is inherently insecure (ie a user could fake a message in the browser \"inspector\"), it is advised you validate any important information via server request before performing any important business logic (like dispatching goods). As this message will arrive earlier than the SELECT_TOKEN_CLOSE message when the dialogue is closed it provides a way to start loading content so you can be more responsive when the popover is closed.
Where:
\nFor example:
\nevent = {\n ...\n data: {\n message: \"SELECT_TOKEN_SUCCESS\"\n payment_method: {\n \"id\": \"pm_5139_10120\",\n \"account\": \"acc_5139_10160\",\n \"code\": \"00010120\",\n \"created\": \"2019-10-01T16:12:17.000Z\",\n \"gateway\": \"gw_5139_10020\",\n \"last_used\": \"2019-10-01T16:12:17.000Z\",\n \"name\": \"Visa ending 4242, exp 12/22\",\n \"status\": \"ACTIVE\",\n \"type\": \"VISA\",\n \"last4\": \"4242\",\n \"expiry\": \"12/2022\"\n },\n contracts: [{...}]\n }\n ...\n}\nA message SELECT_TOKEN_FAILED will be raised each time a card selection is attempted unsuccessfully - in practice this will only be when adding a new payment method that fails validation - unless for example a saved payment method is selected that is concurrently archived in another window by the user. Please note, the user is advised of the failure and prompted to try again, there is no intended business case where you should need to catch this message. When receiving this message, keep in mind the dialogue has not yet been closed, and the user may subsequently successfully select a token prior to closing the dialogue. For example:
Where:
\nFor example:
\nevent = {\n ...\n data: {\n message: \"SELECT_TOKEN_FAILED\"\n payment_method: {\n \"id\": \"pm_5139_10120\",\n \"account\": \"acc_5139_10160\",\n \"code\": \"00010120\",\n \"created\": \"2019-10-01T16:12:17.000Z\",\n \"gateway\": \"gw_5139_10020\",\n \"name\": \"Visa ending 4242, exp 12/22\",\n \"status\": \"INACTIVE\",\n \"gateway_message\": \"Invalid card number\"\n \"type\": \"VISA\",\n \"last4\": \"4242\",\n \"expiry\": \"12/2022\"\n }\n }\n ...\n}\nAuthenticate has 3 main use cases:
\nThere are a number of additional options available:
\n{\n \"element\": \"shuttle-auth\", \n \"on_start\": function (options) {},\n \"on_success\": function (options) {},\n \"on_error\": function (error) {},\n \"options\":\n {\n \"capture_shipping\": false,\n \"payment_token\": false,\n \"action\": \"AUTHORISE\",\n \"currency\": \"USD\",\n \"amount\": \"10000\",\n \"shipping\": {},\n \"line_items\": [] \n }\n}\n\nWhere:
\nWhere options:
Where line_items is an array of:
Note: SUM(line_items.total_amount) should equal the payment amount. If it is less, a \"Miscellaneous\" line item will be added to make up the difference. If the sum exceeds the payment amount, the difference will be flagged as a \"Discount\".
PRE-VALIDATION
\nYou can optionally check to see if \"authenticate\" is supported by the merchant, we'd recommend just doing this after the config is changed and storing the result, to avoid needing to do it for every basket.
\nUse the \"gateways\" API (See API > Setup > Gateways) to fetch the connected gateways for the merchant and check the features. Shuttle supports 3 relevant features:
\nAUTHENTICATE: User can login via this gateway (account details will be returned)
AUTHENTICATE_CAPTURE_SHIPPING: User can select / enter shipping details via this gateway (shipping address will be returned)
AUTHENTICATE_PAYMENT_TOKEN: User can select or enter a payment method via this gateway (a single use payment token will be returned)
Note: PayPal supports all three features.
\nINSTRUCTIONS
\nTo implement the authenticate widget:
\nEnsure you are using Shuttle.js version 1.3 or later, and embedding shared_key / instance_key in the URL
Add the component in your page
\nUse the on_success() function to call the POST payment API, or POST payment_method API
You must load shuttle.js via a new URL scheme which allows us to pre-load config.
\nIf upgrading from shuttle-1.2 or earlier, Please replace:
\nOLD:\n<script src=\"https://app.shuttleglobal.com/shuttle-1.2.X.js\" type=\"text/javascript\"></script>\nNEW:\n<script src=\"https://app.shuttleglobal.com/${shared_key}/${instance_key}/shuttle-1.4.X.js\" type=\"text/javascript\"></script>\nEXAMPLE - do not use without correct \"shared_key\" / \"instance_key\": \n<script src=\"https://app.shuttleglobal.com/1186_122806/SBSBKEY/shuttle-1.4.X.js\" type=\"text/javascript\"></script>\n\nInjecting express is performed via either:
\nJavascript variable - FASTEST
\nJavascript function
\nJavascript variable
\nInclude the options in the page before the shuttle.js as a global variable shuttle_authenticate_options as such:
<script>window.shuttle_authenticate_options=${options}</script>`\n<script src=\"https://app.shuttleglobal.com/${shared_key}/${instance_key}/shuttle-1.4.X.js\" type=\"text/javascript\"></script>\nAlso include the element where you want to inject the checkout:\n<div class='preserveHtml' class='preserveHtml' class='preserveHtml' id=\"shuttle-auth\"></div>\n\nNoting to replace:
\n${options} with the JSON options
\n${shared_key} with your shared key eg \"1186_122806\"
\n${instance_key} with the instance key of the current merchant eg \"MERCHANT100\"
\n\n\nTip! Add the
\nscripttags at the bottom of your page, so to not impact page load time.
Javascript function
\nIf you are dynamically rendering the page, rather than setting the global variable when you want to render the buttons, call:
\nShuttle.authenticate(options)
Setting the global variable will start loading dependancies ASAP, whereas the Javascript function dependancies will not be loaded until the function called.
\non_start on_success on_errorCalled when a user interacts with the widget. Paypal will block out your page with an overlay, however you may have additional UX changes you want to make.
\nThe data passed to on_start is:
{\n modal: true\n}\n\nWhere:
\nmodal: if the screen should be blocked, if this is true you may want to block user inputs / disable timers etc.Called on successful completion of the express checkout. At this stage no money will have been processed, nor any data in Shuttle changed, you need to POST the data returned in the options to a payment or payment_method API.
\nThe data passed to on_success is:
{\n account: {\n gateway_key: \"paypal's id\",\n first_name: \"John\",\n last_name: \"Smith\",\n email: \"john@gmail.com\",\n phone: \"(102)555-1232\"\n },\n gateway_data: {...},\n shipping: {\n line1: \"Street 1\",\n line2: \"Street 2\",\n line3: \"Street 3\",\n line4: \"City\",\n line5: \"Postcode / Zip\",\n line6: \"State\",\n country: \"US\"\n }\n}\n\nWhere:
\naccount: Contains details about the authenticated user
gateway_key: The ID of the user by the gateway (eg Paypal) you can use this to identify a returning customer if you retain this data
first_name: The customer's first name (where available)
last_name: The customer's last name (where available)
email: The customer's email (where available)
phone: The customer's phone (where available) - you may want to sanitise the formatting as it will be as returned by Paypal etc
gateway_data: Contains some JSON that will be used by the gateway for payment / tokenisation. You should not use this or change this data, other than passing it into Shuttle's API.
shipping: if you requested capture_shipping this is the shipping address returned by the gateway
Some examples of how to use this data (see payment and payment_method API for more options):
\nAuthorise $100:
\nPOST /c/api/instances/SBSBKEY/payments\n{\n \"payment\": {\n \"action\": \"AUTHORISE\",\n \"amount\": \"100\",\n \"currency\": \"USD\",\n \"account\": {\n \"first_name\": \"Jack\",\n \"last_name\": \"Smith\",\n \"phone\": \"(202)555-2448\",\n \"email\": \"jack@email.com\"\n },\n \"gateway_data\": {\n \"gateway\": \"20344_10002\",\n \"card_token\": \"cd9bb44914583d696d03e5b6\",\n \"card_type\": \"VISA\"\n }\n }\n}\n\nPayment of $100, with a shipping address, and save the card for future use:
\nPOST /c/api/instances/SBSBKEY/payments\n{\n \"payment\": {\n \"action\": \"AUTHORISE\",\n \"amount\": \"100\",\n \"currency\": \"USD\",\n \"save_card\": true,\n \"account\": {\n \"first_name\": \"Jack\",\n \"last_name\": \"Smith\",\n \"phone\": \"(202)555-2448\",\n \"email\": \"jack@email.com\"\n },\n \"gateway_data\": {\n \"gateway\": \"20344_10002\",\n \"card_token\": \"cd9bb44914583d696d03e5b6\",\n \"card_type\": \"VISA\"\n },\n shipping: {\n line1: \"Street 1\",\n line2: \"Street 2\",\n line3: \"Street 3\",\n line4: \"City\",\n line5: \"Postcode / Zip\",\n line6: \"State\",\n country: \"US\"\n }\n }\n}\n\nSave payment details for future use:
\nPOST /c/api/instances/SBSBKEY/payment_methods\n{\n \"payment_method\": {\n \"account\": {\n \"crm_key\": \"928495\", // include your customer id! \n \"first_name\": \"Jack\",\n \"last_name\": \"Smith\",\n \"phone\": \"(202)555-2448\",\n \"email\": \"jack@email.com\"\n },\n \"gateway_data\": {\n \"gateway\": \"20344_10002\",\n \"card_token\": \"9f01f87d7d55d2b1e32e8c59\",\n \"card_type\": \"VISA\"\n }\n }\n}\n\nCalled when the user cancels the process, or encounters an error. It is recommended you present errors to the user.
\nThe data passed to on_error is:
{\n cancel: false,\n error: \"An error occurred\"\n}\n\nWhere:
\ncancel: if this was cause by the user cancelling
\nerror: if it was not caused by the user cancelled, an error message that caused this
\nREQUIRES SHUTTLE-1.3.0.JS OR LATER
\nSome gateways, such as PayPal have the ability to perform an \"express checkout\", by authenticating the user and return a shipping address and payment method - this is intended as a quick way for GUESTS to checkout, and is not intended for logged in users. You can access this functionality via the \"authenticate\" component which will embed these checkout buttons into your page.
\nThe widget will loop through the merchants enabled gateways, and for those that support \"authenticate\" injected their \"checkout\" buttons onto the page. If no gateways support this feature, nothing will be rendered.
\nInitially only the Sandbox and PayPal gateways support this feature.
\n","_postman_id":"d91856f8-7ee1-4e84-b551-e4d1c903bf36"},{"name":"Credit Message","item":[{"name":"Use Cases","item":[],"id":"237f44b5-4d93-4ce0-ac3b-13e21f91460d","description":"Credit Message has 3 main use cases:
\nThere are a number of options available:
\n{\n \"element\": \"shuttle-cm\", \n \"currency\": \"GBP\",\n \"amount\": \"100\"\n}\n\nWhere:
\n","_postman_id":"237f44b5-4d93-4ce0-ac3b-13e21f91460d"},{"name":"Integration","item":[],"id":"8c87902b-a4c6-4d46-81f1-60ac3e80b29c","description":"PRE-VALIDATION
\nYou can optionally check to see if \"credit messages\" are supported by the merchant, we'd recommend just doing this after the config is changed and storing the result, to avoid needing to do it every use.
\nUse the \"gateways\" API (See API > Setup > Gateways) to fetch the connected gateways for the merchant and check for the feature:
\nCREDIT_MESSAGE: This gateway supports credit messages. Note, it's possible for a gateway to support credit messages (ie return the feature), but for it not to be available, in this scenario you can include the component, but no message will be displayed.INSTRUCTIONS
\nTo implement the credit message widget:
\nshared_key / instance_key in the URLYou must load shuttle.js via a new URL scheme which allows us to pre-load config.
\nIf upgrading from shuttle-1.2 or earlier, Please replace:
\nOLD:\n<script src=\"https://app.shuttleglobal.com/shuttle-1.2.X.js\" type=\"text/javascript\"></script>\n\nNEW:\n<script src=\"https://app.shuttleglobal.com/${shared_key}/${instance_key}/shuttle-1.3.X.js\" type=\"text/javascript\"></script>\n\nEXAMPLE - do not use without correct \"shared_key\" / \"instance_key\": \n<script src=\"https://app.shuttleglobal.com/1186_122806/SBSBKEY/shuttle-1.3.X.js\" type=\"text/javascript\"></script>\nInjecting express is performed via a Javascript function, when you want to render the buttons, call:
\n Shuttle.credit_message(options)
for example:
\nShuttle.credit_message({\n \"element\": \"product_1_messages\",\n \"currency\": \"USD\",\n \"amount\": \"100\"\n});\n\nShuttle.credit_message({\n \"element\": \"product_2_messages\",\n \"currency\": \"USD\",\n \"amount\": \"149.99\"\n});\nREQUIRES SHUTTLE-1.3.0.JS OR LATER
\nBuy-now pay-later providers, such as Klarna, Affirm and PayPal Credit have the ability to split payments over multiple instalments. Most of these providers allow you to inject marketing text on the product / checkout pages, to encourage customers to take up this option.
\nUse this component on your product / checkout pages, and if the merchant has any connected providers that support this, their respective messages will be displayed in a vertical stack.
\n","_postman_id":"90dd8a2a-ef5d-4d8f-bec7-dcb4161e2c75"},{"name":"Checkout Monitor","item":[],"id":"1d90d6b7-23e4-4f3c-9bed-af7372387488","description":"REQUIRES SHUTTLE-1.3.3.JS OR LATER
\nFor scenarios where a customer is filling in checkout, you can now monitor customer progress to aid them through checkout. Note, all checkout data is redacted and no personal information exposed.
\nExamples where checkout monitor may be useful:
\nTo use the checkout monitor, you need to include a nonce GUID when opening checkout - a nonce is a long unique string, that is also used to prevent duplicate payments.
To monitor a checkout, call the Shuttle.js function:
\nShuttle.checkout_monitor(nonce, callback_function)
For example, to log all updates to console:
\nShuttle.checkout_monitor(nonce, (e) => console.log(JSON.stringify(e)))
Example messages:
\n{\n \"type\": \"connection\",\n \"level\": \"MEDIUM\",\n \"message\": \"Connected\",\n \"state\":\n {\n \"id\": \"1f485fa61f163253c0976bce4d7331af\",\n \"online\": true\n }\n}\n\n{\n \"type\": \"checkout\",\n \"level\": \"LOW\",\n \"message\": \"Payment entry\",\n \"state\":\n {\n \"id\": \"1f485fa61f163253c0976bce4d7331af\",\n \"created\": \"2022-09-06T11:55:56.206Z\",\n \"ip_address\": \"212.161.80.4\",\n \"ip_address_country\": \"GB\",\n \"browser\": \"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/104.0.0.0 Safari/537.36\",\n \"browser_size\": \"509,704\",\n \"source\": \"ECOMMERCE\",\n \"action\": \"PAYMENT\",\n \"channel\": \"24636_10002\",\n \"initiative\": \"24636_10002\",\n \"account\": \"24636_10345\",\n \"currency\": \"USD\",\n \"amount\": \"100.00\",\n \"step\": \"PAYMENT\",\n \"payment_methods\": [],\n \"payment_method_types\": [\n {\n \"type\": \"UNIONPAY\",\n \"gateway\": \"24636_10003\",\n \"features\": [\n \"REQUIRE_AVS\",\n \"PAYMENT\",\n \"FULL_REFUND\",\n \"PARTIAL_REFUND\",\n \"AUTHORISE_AND_SAVE_TOKEN\",\n \"AUTHORISE_ON_SAVED_TOKEN\",\n \"PAYMENT_AND_SAVE_TOKEN\",\n \"PAYMENT_ON_SAVED_TOKEN\",\n \"AUTHORISE\",\n \"VOID\",\n \"CAPTURE\",\n \"MULTI_REFUND\",\n \"SAVE_CARD\"\n ],\n \"hosted_payment_card_type\": \"UNIONPAY\"\n },\n {\n \"type\": \"AMEX\",\n \"gateway\": \"24636_10003\",\n \"features\": [\n \"REQUIRE_AVS\",\n \"PAYMENT\",\n \"FULL_REFUND\",\n \"PARTIAL_REFUND\",\n \"AUTHORISE_AND_SAVE_TOKEN\",\n \"AUTHORISE_ON_SAVED_TOKEN\",\n \"PAYMENT_AND_SAVE_TOKEN\",\n \"PAYMENT_ON_SAVED_TOKEN\",\n \"AUTHORISE\",\n \"VOID\",\n \"CAPTURE\",\n \"MULTI_REFUND\",\n \"SAVE_CARD\"\n ],\n \"hosted_payment_card_type\": \"AMEX\"\n },\n {\n \"type\": \"ACH\",\n \"gateway\": \"24636_10003\",\n \"features\": [\n \"REQUIRE_AVS\",\n \"PAYMENT\",\n \"PAYMENT_AND_SAVE_TOKEN\",\n \"PAYMENT_ON_SAVED_TOKEN\",\n \"FULL_REFUND\",\n \"PARTIAL_REFUND\",\n \"MULTI_REFUND\",\n \"SAVE_CARD\"\n ],\n \"hosted_payment_card_type\": \"ACH\",\n \"ach_options\": [\n {\n \"name\": \"Checking\",\n \"key\": \"checking\"\n },\n {\n \"name\": \"Savings\",\n \"key\": \"savings\"\n },\n {\n \"name\": \"Business Checking\",\n \"key\": \"businessChecking\"\n }\n ]\n },\n {\n \"type\": \"MASTERCARD\",\n \"gateway\": \"24636_10003\",\n \"features\": [\n \"REQUIRE_AVS\",\n \"PAYMENT\",\n \"FULL_REFUND\",\n \"PARTIAL_REFUND\",\n \"AUTHORISE_AND_SAVE_TOKEN\",\n \"AUTHORISE_ON_SAVED_TOKEN\",\n \"PAYMENT_AND_SAVE_TOKEN\",\n \"PAYMENT_ON_SAVED_TOKEN\",\n \"AUTHORISE\",\n \"VOID\",\n \"CAPTURE\",\n \"MULTI_REFUND\",\n \"SAVE_CARD\"\n ],\n \"hosted_payment_card_type\": \"MASTERCARD\"\n },\n {\n \"type\": \"DISCOVER\",\n \"gateway\": \"24636_10003\",\n \"features\": [\n \"REQUIRE_AVS\",\n \"PAYMENT\",\n \"FULL_REFUND\",\n \"PARTIAL_REFUND\",\n \"AUTHORISE_AND_SAVE_TOKEN\",\n \"AUTHORISE_ON_SAVED_TOKEN\",\n \"PAYMENT_AND_SAVE_TOKEN\",\n \"PAYMENT_ON_SAVED_TOKEN\",\n \"AUTHORISE\",\n \"VOID\",\n \"CAPTURE\",\n \"MULTI_REFUND\",\n \"SAVE_CARD\"\n ],\n \"hosted_payment_card_type\": \"DISCOVER\"\n },\n {\n \"type\": \"JCB\",\n \"gateway\": \"24636_10003\",\n \"features\": [\n \"REQUIRE_AVS\",\n \"PAYMENT\",\n \"FULL_REFUND\",\n \"PARTIAL_REFUND\",\n \"AUTHORISE_AND_SAVE_TOKEN\",\n \"AUTHORISE_ON_SAVED_TOKEN\",\n \"PAYMENT_AND_SAVE_TOKEN\",\n \"PAYMENT_ON_SAVED_TOKEN\",\n \"AUTHORISE\",\n \"VOID\",\n \"CAPTURE\",\n \"MULTI_REFUND\",\n \"SAVE_CARD\"\n ],\n \"hosted_payment_card_type\": \"JCB\"\n },\n {\n \"type\": \"VISA\",\n \"gateway\": \"24636_10003\",\n \"features\": [\n \"REQUIRE_AVS\",\n \"PAYMENT\",\n \"FULL_REFUND\",\n \"PARTIAL_REFUND\",\n \"AUTHORISE_AND_SAVE_TOKEN\",\n \"AUTHORISE_ON_SAVED_TOKEN\",\n \"PAYMENT_AND_SAVE_TOKEN\",\n \"PAYMENT_ON_SAVED_TOKEN\",\n \"AUTHORISE\",\n \"VOID\",\n \"CAPTURE\",\n \"MULTI_REFUND\",\n \"SAVE_CARD\"\n ],\n \"hosted_payment_card_type\": \"VISA\"\n },\n {\n \"type\": \"DINERS\",\n \"gateway\": \"24636_10003\",\n \"features\": [\n \"REQUIRE_AVS\",\n \"PAYMENT\",\n \"FULL_REFUND\",\n \"PARTIAL_REFUND\",\n \"AUTHORISE_AND_SAVE_TOKEN\",\n \"AUTHORISE_ON_SAVED_TOKEN\",\n \"PAYMENT_AND_SAVE_TOKEN\",\n \"PAYMENT_ON_SAVED_TOKEN\",\n \"AUTHORISE\",\n \"VOID\",\n \"CAPTURE\",\n \"MULTI_REFUND\",\n \"SAVE_CARD\"\n ],\n \"hosted_payment_card_type\": \"DINERS\"\n }\n ],\n \"payment_method_type_entry\": \"CARDS\",\n \"card_brand\": \"VISA\",\n \"card_number\": \"****\",\n \"card_cvc\": \"***\",\n \"card_expiry\": \"12/23\",\n \"card_number_valid\": true,\n \"card_expiry_valid\": true,\n \"card_cvc_valid\": true,\n \"card_billing_line1\": \"**\",\n \"card_billing_line2\": \"***\",\n \"card_billing_line4\": \"London\",\n \"card_billing_line5\": \"****\",\n \"card_billing_country\": \"GB\",\n \"form_valid\": true,\n \"updated\": \"2022-09-06T11:56:16.309Z\",\n \"v\": 1662465376309\n }\n}\n\nEach message consists of:
\n\"checkout\" publishes a significant amount of data in state. While the state contains all kinds of information which can be useful, please only rely on the following data at this stage:
\n","_postman_id":"1d90d6b7-23e4-4f3c-9bed-af7372387488"},{"name":"Release Notes","item":[],"id":"232ac3f1-8d9f-4bcf-9dea-c37d812d5da7","description":"This section lists the available versions of shuttle.js and notable changes. if you are not using Authenticate / Credit Message modules, you can reference shuttle.js without your public key / instance key, in which case we recommend you reference a specific version and include SRI integrity checksum. If you are using these modules, you will need to include public key / instance key in the URL and NOT use the integrity checksum.
\nshuttle-1.4.6.js alias shuttle-1.4.X.js
SRI: sha384-2Hp+tsbQtUOCC9ksHfP3jAoYjKqJlufMiYG8f1qMGMaCBqzA+FbfLfD2peWoDH9R
<script src=\"https://app.shuttleglobal.com/shuttle-1.4.6.js\" integrity=\"sha384-2Hp+tsbQtUOCC9ksHfP3jAoYjKqJlufMiYG8f1qMGMaCBqzA+FbfLfD2peWoDH9R\" crossorigin=\"anonymous\"></script>\n\nBug Fixes
\nshuttle-1.4.4.js
SRI: sha384-i/xUsM9lYTA45zKVcp7VBKWiGj9H0i/DoZJP0EhVrfTAhRZnTxMTE701ueltm4JS
<script src=\"https://app.shuttleglobal.com/shuttle-1.4.4.js\" integrity=\"sha384-i/xUsM9lYTA45zKVcp7VBKWiGj9H0i/DoZJP0EhVrfTAhRZnTxMTE701ueltm4JS\" crossorigin=\"anonymous\"></script>\n\nBug Fixes
\nshuttle-1.4.3.js
SRI: sha384-1sQj8veCQ/ii3HrET278lGljNlzfSEucMTnxLlU/S2/0dL+V7wsO+VLN0dDGPu/f
<script src=\"https://app.shuttleglobal.com/shuttle-1.4.3.js\" integrity=\"sha384-1sQj8veCQ/ii3HrET278lGljNlzfSEucMTnxLlU/S2/0dL+V7wsO+VLN0dDGPu/f\" crossorigin=\"anonymous\"></script>\n\nImprovements
\nDeeplinks without an ID now dont inject an missing link
\nCleaned up the render of multiple express checkout options
\nCleaned up express checkout error handling
\nshuttle-1.4.1.js
SRI: sha384-FE/L3JelbhG/+PaUmylbo2D7p86vcnIXWx5mEOOSINInLpy79ZucODPmAySiQqsf
<script src=\"https://app.shuttleglobal.com/shuttle-1.4.1.js\" integrity=\"sha384-FE/L3JelbhG/+PaUmylbo2D7p86vcnIXWx5mEOOSINInLpy79ZucODPmAySiQqsf\" crossorigin=\"anonymous\"></script>\n\nSecurity Update
\nshuttle-1.4.0.js
SRI: sha384-1qGaKVAMjRQi7/fb6xuV4b0++Ifce1PAnlhQB0GpsDCH56CTmBBEFYPI0HOAnXya
<script src=\"https://app.shuttleglobal.com/shuttle-1.4.0.js\" integrity=\"sha384-1qGaKVAMjRQi7/fb6xuV4b0++Ifce1PAnlhQB0GpsDCH56CTmBBEFYPI0HOAnXya\" crossorigin=\"anonymous\"></script>\n\nImprovements
\n1.3.X Please note, 1.3.X has been superceded with 1.4.X. It will receive minor patches until 30 June 2025, and security patches until 30 November 2026. Please upgrade before this date.
\nshuttle-1.3.17.js alias shuttle-1.3.X.js
SRI: sha384-+Sh/mBBu6OfWF4j+e77c1zGwyXXgkkTz21DIf6vsLi9r13HH6RajphdInLDB3dE5
<script src=\"https://app.shuttleglobal.com/shuttle-1.3.17.js\" integrity=\"sha384-+Sh/mBBu6OfWF4j+e77c1zGwyXXgkkTz21DIf6vsLi9r13HH6RajphdInLDB3dE5\" crossorigin=\"anonymous\"></script>\n\nImprovements
\nDeeplinks without an ID now dont inject an missing link
\nCleaned up the render of multiple express checkout options
\nCleaned up express checkout error handling
\nshuttle-1.3.15.js
SRI: sha384-PHNi7doFSWSN8LkLGhRWURH7dt87RRpwT1lNyYj8jbFrcpTRd1AXIyW/2GNDrA3L
<script src=\"https://app.shuttleglobal.com/shuttle-1.3.15.js\" integrity=\"sha384-PHNi7doFSWSN8LkLGhRWURH7dt87RRpwT1lNyYj8jbFrcpTRd1AXIyW/2GNDrA3L\" crossorigin=\"anonymous\"></script>\n\nNew Features
\nImprovements
\nBug Fixes
\nFixed an issue with PAYMENT_CLOSE someones returning cancel: true, even on successful payment
\nRemoved the reference to socket.io map which displays an 404 not found when debugging
\nFixed an issue with a display resize event arriving after the checkout iframe removed from the page.
\n09 Aug 2023: 1.3.11
\nshuttle-1.3.11.js alias shuttle-1.3.X.js
New Features
\nSupport for option \"height: fixed\" to disable Shuttle auto resizing iFrame
\nExpress Checkout (Authenticate) now returns is_available if some options were rendered, so allow you alternate your UX flow if express checkout ifs available or not.
Added Shuttle.cancel(guid (default all)) to cancel a checkout
\nImprovements
\nBetter support for multiple / changing checkouts on a page
\nUpdated inline style checkout to start with 0 height and then grow during rendering rather than an random initial height
\nRemoved external dependancy on socket.io
\nRemoved deprecated \"allowpaymentrequest\" iFrame attribute
\n\n\nPlease note, 1.3.X has been superceded with 1.4.X. It will receive minor patches until 30 June 2025, and critical security patches until 30 November 2026. Please upgrade before this date.
\n
shuttle-1.3.7.js
New Features
\n\n\nPlease note, 1.3.X has been superceded with 1.4.X. It will receive minor patches until 30 June 2025, and security patches until 30 November 2026. Please upgrade before this date.
\n
shuttle-1.3.6.js
Bug Fixes and Improvements
\nRemoved console logging
\nFixed an issue displaying Google Pay
\n\n\nPlease note, 1.3.X has been superceded with 1.4.X. It will receive minor patches until 30 June 2025, and security patches until 30 November 2026. Please upgrade before this date.
\n
shuttle-1.3.4.js
New Features
\nInstant render marketing messages (buy now pay later messaging)
\nCheckout monitor - real time updates for whats happening at checkout
\nBug Fixes and Improvements
\nStreamlined the render process to reduce element movement on page
\nFixed an issue with an iFrame loading more often than it should
\n\n\nPlease note, 1.3.X has been superceded with 1.4.X. It will receive minor patches until 30 June 2025, and security patches until 30 November 2026. Please upgrade before this date.
\n
shuttle-1.3.0.js
New Features
\nUPGRADING NOTE - The URL structure has changed to include shared_key and instance_key in the URL:
\n<script src=\"https://app.shuttleglobal.com/${shared_key}/${instance_key}/shuttle-1.3.X.js\" type=\"text/javascript\"></script>\n\n\n\nPlease note, 1.2.X and earlier are now deprecated and not recieving maintenance or security patches.
\n
Please note, prior to 1.3.0, shuttle.js uses the following URL structure:
\nhttps://app.shuttleglobal.com/${version}\neg:\nhttps://app.shuttleglobal.com/shuttle-1.2.x.js\n\nshuttle-1.2.7.js alias shuttle-1.2.X.js
New Features
\nExpress checkout flow (authenticate)
\nMerchant view auto height resizing
\nPrivate beta for INLINE checkout rendering
\nPrivate beta for Apple Pay
\nshuttle-1.2.0.js
New Features
\nSimplified URL structure and naming of shuttle.js (previously payments.js)
Support for the new onboarding flow
\nEmbed the content of deep links in a
\n , by including data-shuttle-embed attribute
Deprecations
The following methods have been deprecated. They will continue to be supported in 1.2 but will be removed in version 1.3, as such, we recommend moving away from them.
Shuttle.doSetup: This UX blends the concepts of account creation / management and gateway configuration, which while faster to build around by a platform doesn't deliver a premium merchant experience. At the expense of an extra API call, the new onboarding flow provides a far more streamlined experience. As this split in functionality is not backward compatible, we decided to deprecate doSetup.
Shuttle.bindButtons(): This has been replaced by Shuttle.bind() as it also supports inline embeds
payments-1.1.4.min.js alias payments-1.1.X.min.js, payments-1.X.min.js
Bug fixes
\npayments-1.1.3.min.js
Bug fixes
\ndisable_new_window in some scenarios the overlay text for a new window was still displaying over the payment dialoguepayments-1.1.2.min.js
Bug fixes
\npayments-1.1.1.min.js
Bug fixes
\noptions object passed into it, causing issues for repeated opening using the same Javascript variable.payments-1.1.0.min.js
New Features
\nIntroduced selectToken, the ability to capture a card details without a transaction, or to update a payment method on an existing contract
\nAdded disable_new_window to prevent the dialog launching as a separate browser window when inside an iFrame.
Added force_new_window to force the dialog to launch as a separate browser window.
Improvements / Updates
\nUpdated Javascript namespace to \"Shuttle\"
\nUpdated html tags to \"data-shuttle-*\"
\nRenamed skip_receipt => disable_receipt, no_redirect to disable_redirect
Improved Javascript messaging, please review all window messages.
\npayments-1.0.11.min.js alias payments-1.0.X.min.js
New Features
\nThis client-side library simplifies embedding onboarding, checkout, tokenisation and deep links into your site. By using our UX components, you are segmenting the card handling part of PCI DSS compliance responsibility away from your platform.
\nTo use these popovers:
\n1. Include the Javascript Library
\nInclude the following file on all you need to use it:
\n<script src=\"https://app.shuttleglobal.com/${shared_key}/${instance_key}/shuttle-1.4.X.js\" type=\"text/javascript\"></script>\n\nWhere:
\nshared_key: is your application's shared key
instance_key: is the current instance_key
This will take the latest version of the file in the 1.4 branch, to use a specific version (so as not to make minor fixes), you should referencde a specific version eg 1.4.0. Please note, the configuration for the merchant will be embedded in the file, which will prevent you using SRI (resource integrity checksums).
\nIf you need to use SRI (integrity checksums), you must reference a specific version of the file eg 1.4.0, and reference the js file without /${shared_key}/${instance_key} so as not to get dynamic content. Due to this, you will not be able to use \"Authenticate\" (express checkout) or \"Credit Messages\" components. You can see the direct links and integrity checksum under UX Components / Shuttle.js / Release Notes.
2a. Onboarding / Deep Links
\nGenerate a \"deep link\" server side, with the parameters for what you want to embed. Add a
\nto your page with the deep link id, for example. If
\nis added to the page AFTER page load, you must then run Shuttle.bind().
2b. Payment / Tokenisation: Decide if integrating via DOM Attributes or Javascript
\nUsing button DOM attributes will bind the popup to the onClick event of the element, for example, the below button will trigger the popup when clicked, this is the recommended approach:
\nNote: Button attributes are detected on page load, if you render the button on the page AFTER page load, call Shuttle.bind(); after your render cycle.
Using the Javascript method will launch the popup immediately, however as it is not pre-loaded, will take longer to open, for example, Shuttle.doSetup(options, signature);
3. Payment / Tokenisation: Construct the options for the popup
options is a Javascript object containing allowed parameters for the method.
When using as button attributes, you will need to stringify JSON.stringify(options);. Take care to escape the string, or alternatively you can base64 encode it btoa(JSON.stringify(options));.
4. Payment / Tokenisation: \"Sign\" the request with a signature
To manually create a signature, follow the below:
\nCreate a timestamp in ms from 1970 eg new Date().getTime() (it will be a 13 digit number eg 1571677967213)
Stringify your options, omitting host, and nonce eg var signatureBody = JSON.stringify(_.omit(options, \"host\", \"nonce\")); ** see tip below
MD5 the concatenation of timestamp + methodName + signatureBody + secret_key, where methodName is doSetup or doPayment, and secret_key is your app's secret key from the developer portal
Your signature is: shared_key + \"-\" + timestamp + \"-\" + md5, where shared_key is your app's shared key from the developer portal
TIP: JSON does NOT require unicode characters to be escaped and the signature will NOT validate if you escape unicode. When you stringify your options, makes sure for example ø remains ø, and is not converted into \\u00f8. If you are having trouble with this, we also support you stripping out non-alphanumeric from the string when generating a signature, ie for step 2 var signatureBody = JSON.stringify(_.omit(options, \"host\", \"nonce\").replace(/[^a-zA-Z0-9]/g, \"\"));
5. Handle success/cancellation
\nIf you have a multipage application, use the success_url / cancel_url options when opening popovers and we will direct the browser accordingly, passing key variables in the query params. If you have a single page application or wish to take greater control of navigation, implement event listeners (see \"Window Events\").
To note, in some cases, the popover may:
\nRedirect the browser away from the current URL, we will return the user to either success_url, cancel_url, or, if these have not been provided with the current URL (and raise the appropriate dialogue close event). This is done to provide a better UX experience on mobile devices. You can disable this by passing the disable_redirect parameter.
Open the popup in a separate browser window rather than integrated into the current window, for example when you run shuttle.js in an iFrame. This is due to security and aesthetics. When your page is iFramed there is a security risk another party can intercept user input, and from UX perspective the popover will be centred in the iFrame rather than the entire browser window. You can disable this passing the disable_new_window parameter, however in doing so, you MUST implement an x-frame-options header of deny or sameorigin on your webpage (see here) to meet PCI DSS for your customers.
Open a further popup in a separate window, where the user is required to navigate to a third-party website that has a x-frame-options header on it preventing its iFraming if the popover is not the top window (for example some OAUTH processes during setup, or Paypal / GoCardless during payment). You cannot disable this at this stage.
If you are a single page app, the popovers will communicate back to you via client-side Javascript window.postMessage notifications, for instructions on how to catch these, see here.
window.addEventListener(\"message\", function(e) {\n console.log(\"Event Type: \" + (e.data || {}).message);\n console.log(\"Event Payload: \" + JSON.stringify(e.data));\n});\n\nEach JSFiddle includes an example of catching events.
\n","event":[{"listen":"prerequest","script":{"id":"c53b81fd-c048-4828-8db9-7b6ce4dfc7f2","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"e116dada-e953-434c-8d01-5a26d6c81669","type":"text/javascript","exec":[""]}}],"_postman_id":"b5f50016-d9ac-4765-960e-f73daceef096"},{"name":"Apple Pay","item":[],"id":"7d642930-cef7-4865-9828-7fe19e968ea0","description":"Apple Pay is available for Safari and IOS users on various payment processors.
\nTo use Apple Pay your implementation must be using shuttle-1.3.3.js or later.
\nTo use Apple Pay, Apple require the HTTP domain hosting the checkout to be verified, this process involves uploading a file to the location:
\nhttps://yourdomain/.well-known/apple-developer-merchantid-domain-association
Shuttle helps you manage this process, however you will need to implement the endpoint /.well-known/apple-developer-merchantid-domain-association and use it to return the contents of the following API call:
https://app.shuttleglobal.com/c/api/instances/:instance_key/apple_pay_verification_file/:domain
Please note, your endpoint must be publically accessible and return the content of this file in mimetype plain/text.
This request performs a simple search against account objects:
criteria: The search criteria (URL encoded).
order: The sort you would like to apply
expand: The fields to expand into full objects (see GET object)
limit: The maximum records to return
offset: The offset from the first records to start returning records
Available fields for criteria and order:
id
\nchannel
\ncompany
\ncreated
\ncrm
\ncrm_key
\ndivision
\nfirst_name
\nlast_name
\nphone
\ntag
\nupdated
\nExpand:
\nGETResponse:
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{session_key}}"},{"key":"password","value":"Request:
\naccount_id can be one of:
id: the id assigned by us
crm_key: the id assigned by you
Where you can expand:
created_session last_transaction updated_sessionResponse:
\nWhere address contains:
Update an existing account.
\n{{account_id}} can be either ID, or crm_key (take care to escape appropriately if it contains non URL safe characters)Request:
\nWhere account:
Where address contains:
Response:
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{session_key}}"},{"key":"password","value":"Create a new account.
\nRequest:
\nWhere account:
Where address contains:
Response:
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{session_key}}"},{"key":"password","value":"This request performs a simple search against charge objects:
criteria: The search criteria (URL encoded).order: The sort you would like to applyexpand: The fields to expand into full objects (see GET object) limit: The maximum records to return offset: The offset from the first records to start returning recordsAvailable fields for criteria and order:
Expand:
\nGETResponse:
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{session_key}}"},{"key":"password","value":"Request:
\nYou can expand the following fields:
contractcreated_session updated_sessionResponse:
\nWhere status is:
When updating a charge, only several properties can be changed. They can be updated individually or altogether.
\nRequest:
\nResponse:
\nUpdated charge object
A charge is an invoice on a contract. A monthly recurring contract for example would have a new charge each month.
\n","event":[{"listen":"prerequest","script":{"id":"00ab9ff3-5e4a-4ca4-874c-17a5e41d64ce","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"96aec599-7184-4c35-b4d2-e16c9b8fbee6","type":"text/javascript","exec":[""]}}],"_postman_id":"8ba4f586-3afd-462e-a2fe-dfd32539bd1a","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{session_key}}"},{"key":"password","value":"The \"checkout\" endpoint allows you to generate a hosted checkout that can be embedded via iFrame in a page via \"shuttle.js\", it accepts the same parameters as create a hosted URL.
\nThe following fields from the payment API are not available or have an altered meaning during a hosted process:
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{session_key}}"},{"key":"password","value":"A checkout is a payment experience you want to display to a user.
\nYou should:
\nFrom your server call POST .../checkouts with your payment options (docs)
\nOn your checkout page, embed shuttle-1-4.X.js (docs)
Add a DIV to your checkout page with the following
\nFor example:
\n< div data-shuttle-checkout=\"4fgjk4zrxgp6vt0s5xpy1h6eeg6g7r2g\" id=\"checkout\" data-shuttle-style=\"INLINE\" data-shuttle-disable-new-window=\"true\"></div>\n<script src=\"https://app.shuttleglobal.com/1186_144767/P_31.221.4.210-2024-12-17T13:28:43.104Z/shuttle-1.4.X.js\" type=\"text/javascript\">\n\nTip! If you are using dynamic rendering (eg React), call Shuttle.bind() after adding the
to the screen to trigger checkout render.
\n","_postman_id":"b1f47bf6-80c8-4ac9-8817-009ea3ac8858","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{session_key}}"},{"key":"password","value":"Request body:
\nnonce is the \"nonce\" you passed in the options for checkout.Response:
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{session_key}}"},{"key":"password","value":"The checkout monitor allows you to receive real time updates for how checkout is being completed.
\nUse cases include:
\nTo use the checkout_monitor, you need to:
\nShuttle.checkout_monitor({sessionid}) (available in shuttle-1.3.3.js or later) See: https://api.shuttleglobal.com/#1d90d6b7-23e4-4f3c-9bed-af7372387488Please note: You must have loaded shuttle-1-3.X.js using the /shared_key/instance_key/ structure, using the same instance you created the session for ie:
\nhttps://app.shuttleglobal.com/{shared_key}/{instance_key}/shuttle-1.3.X.js
\n","event":[{"listen":"prerequest","script":{"id":"6bba06f4-6ef1-40d7-8065-31d4e15e8515","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"46cc108b-628c-49b7-9e14-d099f15df3b0","type":"text/javascript","exec":[""]}}],"_postman_id":"ccc892a1-2f53-4202-a183-60df4ed39c1d","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{session_key}}"},{"key":"password","value":"This request performs a simple search against contract objects:
criteria: The search criteria (URL encoded).order: The sort you would like to applyexpand: The fields to expand into full objects (see GET object) limit: The maximum records to return offset: The offset from the first records to start returning recordsAvailable fields for criteria and order:
Expand:
\nGETResponse:
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{session_key}}"},{"key":"password","value":"Request:
\ncontract_id can be one of:
id: the id assigned by us
alt_key: the id assigned by you (eg order id), if not unique the most recently updated contract will be matched
You can expand the following fields:
account
created_session
payment_method
last_transaction
last_charge
updated_session
Response:
\nWhere status is:
Where legal_entities is:
This API returns a list of charges that will be created for an in-progress recurring contract. For contracts with no completion date, the list will be restricted to the shorter of 3 years or 100 charges.
\nRequest:
\ncontract_id can be one of:
id: the id assigned by usalt_key: the id assigned by you (eg order id), if not unique the most recently updated contract will be matchedResponse:
\nWhere future_charges is an array of:
Note, in the following scenarios a HTTP 400 will be returned, code: INVALID_REQUEST, message as as follows:
When updating a contract, only several properties can be changed. They can be updated individually or altogether.
\nNote: Updating the amount of the contract will cancel the contract and create a NEW contract, with a parent reference to the now cancelled contract. You cannot update the amount of a contract while a payment is processing (including when its processing asynchronously ie in a PENDING / UNRESOLVED status).
Request:
\nResponse:
\nUpdated contract object. In some cases a new contract will be created, with a parent of the contract edited.
Cancelling a contract will prevent future charges being created on a contract and stop all automated payments. A contract may still have an outstanding balance at time of cancellation.
\nRequest:
\nRequest:
\nResponse:
\nUpdated contract object
For recurring payments which have an amount overdue you can instruct us to attempt payment of the outstanding balance on either the default payment method or an alternative one.
\nRequest:
\nResponse:
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{session_key}}"},{"key":"password","value":"The \"Update Payment Method URL\" endpoint allows you to generate an encoded URL to direct a browser to, to allow a user to modify their method of payment on a recurring contract. It does not accept any parameters.
\nRequest:
\nResponse:
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{session_key}}"},{"key":"password","value":"A contract represents an action by the user to perform a one time or recurring payment, its essentially the agreement between the user and the entity to perform one or a series of transactions.
\nIf a recurring payment has a significant change made (eg amount, frequency or initiative), a new contract will be created with a reference back to the previous contract as parent. Changing the paymnent method or next payment date will however not create a new contract.
Automated payments (ie payments from a scheduled payment or recurring contracts) will be automatically retried if they encountered an ERROR or a DECLINE. The schedule for retries are as follows:
\nWhen an error encountered (eg gateway offline):
\nWhen a decline encountered (eg insufficient funds):
\nThe retry date be scheduled in the next_payment field (which you can modify with a PUT). After a unsuccessful retry the retry_count will be incremented and next_payment recalculated, retry_count determines which delay amount to use.
If the retry falls AFTER the next instalment is due, it wont be scheduled as the next instalment will occur first. If the next instalment fails it will INCREASE the retry_count.
Once the retry attempts count exceeds the times scheduled, the retry_complete flag will be set and no further automated retries will be tried. New installments WILL however still have a payment attempt.
A successful payment will reset retry_count to 0 and retry_complete to false.
To create an onboarding deep link, set:
\ntype: gateway-setupcontext: Is a map that allows you to pass various options to the widgetWhere context supports:
processor: Use the onboarding component in the context of a single processor only. This is designed to be used when processor selection has already been performed outside of Shuttle. You are able to connect the gateway, customise checkout (but only with options from the one gateway). You can disconnect and reconnect the gateway, but can not maintain multiple connections to the same gateway in the same instance. You currently cannot also connect a fraud tool in this mode. For example \"processor\": \"STRIPE\".processor_filter: (coming soon) allows you only offer the merchant a sub-selection of the processors your application supports for a new connection. This wont affect any already connected processors. For example \"processor_filter\": [\"STRIPE\", \"SQUARE\"]. Unlike the processor field, processor_filter does not affect the behaviour of the onboarding component other than displaying a filtered list of service providers when \"Add\" selected.theme: allows you to customise some elements of the CSS to make the UX feel more natural within your app. See below.Theme\nThe elements you can customise are listed below. For colors, you can either set color{Name}Base, and we will calculate Active / Hover / Disabled etc states or you can override each individually via the respective variable.
\"baseFontSize\": \"16px\",\n\"baseFontFamily\": \"Arial\",\n\"backgroundColor\": \"#FFF\",\n\"headerBackground\": \"#FFF\",\n\"headerBorderBottom\": \"none\",\n\"baseBorderRadius\": \"0.4rem\",\n\"rowHeight\": \"3.0rem\",\n\"modalOverlay\": \"#000\",\n\"textColor\": \"#000\",\n\"textColorInverse\": \"#FFF\",\n\"linkColor\": \"blue\",\n\"borderColor\": \"#000\",\n\"colorPrimaryBase\": \"#007bff\",\n\"colorPrimaryText\": \"#000\", // default calculated from Base\n\"colorPrimaryActive\": \"#0062cc\", // default calculated from Base\n\"colorPrimaryHover\": \"#0062cc\", // default calculated from Base\n\"colorPrimaryDisabled\": \"#007bff\", // default calculated from Base\n\"colorPrimaryForeground\": \"#004085\", // default calculated from Base\n\"colorPrimaryBackground\": \"#cce5ff\", // default calculated from Base\n\"colorPrimaryBorder\": \"#b8daff\", // default calculated from Base\n\"colorPrimaryLink\": \"#002752\", // default calculated from Base\n\"colorSecondaryBase\": \"#6c757d\",\n\"colorSecondaryText\": \"#000\", // default calculated from Base\n\"colorSecondaryActive\": \"#545b62\", // default calculated from Base\n\"colorSecondaryHover\": \"#545b62\", // default calculated from Base\n\"colorSecondaryDisabled\": \"#6c757d\", // default calculated from Base\n\"colorSecondaryForeground\": \"#383d41\", // default calculated from Base\n\"colorSecondaryBackground\": \"#e2e3e5\", // default calculated from Base\n\"colorSecondaryBorder\": \"#d6d8db\", // default calculated from Base\n\"colorSecondaryLink\": \"#202326\", // default calculated from Base\n\"colorSuccessBase\": \"#28a745\",\n\"colorSuccessText\": \"#000\", // default calculated from Base\n\"colorSuccessActive\": \"#1e7e34\", // default calculated from Base\n\"colorSuccessHover\": \"#1e7e34\", // default calculated from Base\n\"colorSuccessDisabled\": \"#28a745\", // default calculated from Base\n\"colorSuccessForeground\": \"#155724\", // default calculated from Base\n\"colorSuccessBackground\": \"#d4edda\", // default calculated from Base\n\"colorSuccessBorder\": \"#c3e6cb\", // default calculated from Base\n\"colorSuccessLink\": \"#0b2e13\", // default calculated from Base\n\"colorDangerBase\": \"#dc3545\",\n\"colorDangerText\": \"#000\", // default calculated from Base\n\"colorDangerActive\": \"#bd2130\", // default calculated from Base\n\"colorDangerHover\": \"#bd2130\", // default calculated from Base\n\"colorDangerDisabled\": \"#dc3545\", // default calculated from Base\n\"colorDangerForeground\": \"#721c24\", // default calculated from Base\n\"colorDangerBackground\": \"#f8d7da\", // default calculated from Base\n\"colorDangerBorder\": \"#f5c6cb\", // default calculated from Base\n\"colorDangerLink\": \"#491217\", // default calculated from Base\n\"colorWarningBase\": \"#ffc107\",\n\"colorWarningText\": \"var(-Text-color)\", // default calculated from Base\n\"colorWarningActive\": \"#d39e00\", // default calculated from Base\n\"colorWarningHover\": \"#d39e00\", // default calculated from Base\n\"colorWarningDisabled\": \"#ffc107\", // default calculated from Base\n\"colorWarningForeground\": \"#856404\", // default calculated from Base\n\"colorWarningBackground\": \"#fff3cd\", // default calculated from Base\n\"colorWarningBorder\": \"#ffeeba\", // default calculated from Base\n\"colorWarningLink\": \"#533f03\", // default calculated from Base\n\"colorInfoBase\": \"#17a2b8\",\n\"colorInfoText\": \"#000\", // default calculated from Base\n\"colorInfoActive\": \"#117a8b\", // default calculated from Base\n\"colorInfoHover\": \"#117a8b\", // default calculated from Base\n\"colorInfoDisabled\": \"#17a2b8\", // default calculated from Base\n\"colorInfoForeground\": \"#0c5460\", // default calculated from Base\n\"colorInfoBackground\": \"#d1ecf1\", // default calculated from Base\n\"colorInfoBorder\": \"#bee5eb\", // default calculated from Base\n\"colorInfoLink\": \"#062c33\", // default calculated from Base\n\"colorLightBase\": \"#f8f9fa\",\n\"colorLightText\": \"#000\", // default calculated from Base\n\"colorLightActive\": \"#dae0e5\", // default calculated from Base\n\"colorLightHover\": \"#dae0e5\", // default calculated from Base\n\"colorLightDisabled\": \"#f8f9fa\", // default calculated from Base\n\"colorLightForeground\": \"#818182\", // default calculated from Base\n\"colorLightBackground\": \"#fefefe\", // default calculated from Base\n\"colorLightBorder\": \"#fdfdfe\", // default calculated from Base\n\"colorLightLink\": \"#686868\", // default calculated from Base\n\"colorDarkBase\": \"#343a40\",\n\"colorDarkText\": \"#000\", // default calculated from Base\n\"colorDarkActive\": \"#1d2124\", // default calculated from Base\n\"colorDarkHover\": \"#1d2124\", // default calculated from Base\n\"colorDarkDisabled\": \"#343a40\", // default calculated from Base\n\"colorDarkForeground\": \"#1b1e21\", // default calculated from Base\n\"colorDarkBackground\": \"#d6d8d9\", // default calculated from Base\n\"colorDarkBorder\": \"#c6c8ca\", // default calculated from Base\n\"colorDarkLink\": \"#040505\" // default calculated from Base\nFor example, if \"John Doe\" (user 1234) was logged in to instance \"9999\", and you wanted to drop in an onboarding UX with a customised header bar, create the following deep link:
\nPOST /instances/9999/deep_links\n{\n \"deep_link\": {\n \"type\": \"gateway-setup\",\n \"context\": {\n \"theme\": {\n \"headerBackground\": \"transparent\",\n \"headerBorderBottom\": \"none\"\n }\n },\n \"user\": {\n \"alt_key\": \"1234\",\n \"name\": \"John Doe\"\n }\n }\n}\nA message EXTEND_SESSION will be raised when a server request is made, so that you can extend the session of the user in your app (if you so wish). The intent is to prevent your session expiring if they are configuring payment processors for some time. This will generally only be raised at most once per minute.
Where:
\nExample:
\nevent = {\n ...\n data: {\n message: \"EXTEND_SESSION\"\n }\n ...\n}\nA message DASHBOARD_DISPLAY will indicate the frame height has changed, eg after a re-render. Shuttle.js will use this to resize the frame. This message also contains a boolean indicating if we are displaying a modal dialog if you decide to dim / block any other controls on the page.
Where:
\nFor example:
\nevent = {\n ...\n data: {\n message: \"DASHBOARD_DISPLAY\",\n height: 137,\n modal: false\n }\n ...\n}\nA message DASHBOARD_ERROR will indicate an error has occurred in the dashboard component. The typical use case is the session has expired however errors may occur for other reasons.
Where:
\nFor example:
\nevent = {\n ...\n data: {\n message: \"DASHBOARD_ERROR\",\n type: \"SESSION_EXPIRED\",\n error: \"Session expired\"\n }\n ...\n}\nThe merchant view allows you to search and view people, transactions and recurring schedules. You can embed it allowing the user to search through data - for example in the developer portal, or link directly to a person, transaction or recurring schedule.
\nTo create a merchant view deep link, set:
\ntype: merchantcontext: (optional) see belowWhere context:
For example, if \"John Doe\" (user 1234) was logged in to instance \"9999\", and you wanted to drop in a UX for the payment activity on subscription \"ABC123\", create the following deep link:
\nPOST /instances/9999/deep_links\n{\n \"deep_link\": {\n \"type\": \"merchant\",\n \"context\": {\n \"module\": \"enquiry\",\n \"action\": \"view_contract\",\n \"alt_key\": \"ABC123\"\n },\n \"user\": {\n \"alt_key\": \"1234\",\n \"name\": \"John Doe\"\n }\n }\n}\nThis sections lists the types of deep links you can create and the parameters they accept.
\n","_postman_id":"f6acd9d4-a13e-4c50-bdd3-bb706b2bbdf4","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{session_key}}"},{"key":"password","value":"When creating a deeplink, all fields are nested under the deep_link field. See the deep links section for a list of available deep links.
Request:
\nWhere user:
Response:
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{session_key}}"},{"key":"password","value":"This will return a HTTP 302 to the desired page.
\nDuring the redirection process, Shuttle will execute the deep link, creating a Shuttle user and session. Sessions typically expire after 15 minutes of inactivity.
A deep-link allows you to create a URL that links to various pages in the system.
\nWhen creating a deeplink you pass a:
\ntype: the UX you want to embed (eg gateway-setup for onboarding)user: details of the user currently logged into your appexpiry_seconds: (optional, default 900) how long the deeplink is valid forcontext: type specific options, for example, you can set a theme for gateway-setupCreating a deep link returns a GUID, which you can use shuttle.js to embed in your page, or use to load a browser window or iFrame.
Example:
\nshuttle.js to render on your pageThis request performs a simple search against gateway objects:
criteria: The search criteria (URL encoded).order: The sort you would like to applyexpand: The fields to expand into full objects (see GET object) limit: The maximum records to return offset: The offset from the first records to start returning recordsAvailable fields for criteria and order:
Expand:
\nGETResponse:
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{session_key}}"},{"key":"password","value":"Request:
\ngateway_id is our ID or your ID for the gateway (id or code)You can expand the following fields:
authenticate_jscheckout_js created_session credit_message_js processorupdated_sessionResponse:
\nWhere status is one of:
Where payment_method_types and payment_method_types_moto:
Where each payment_method contains a list of features that are available. Please note, we do our best to automatically reflect what is supported by the gateway, but in some circumstances, we :
Creating a gateway will establish a new connection to a payment processor. In general this API can be used for:
\nDuplicating a gateway (eg moving it to another instance)
\nA bespoke onboarding process / UX
\nClient migration to Shuttle
\nProcessors and valid values change regularly, as such, other than using it to duplicate a gateway connection, this API is intended to be used in conjunction with Shuttle support.
\nRequest:
\nResponse:
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{session_key}}"},{"key":"password","value":"Updating a gateway is intended to be used in conjunction with Shuttle support.
\n{{gateway_id}} can be either ID, or codeRequest:
\nResponse:
\nWhere status:
ACTIVE: Supports new payments and new payment methodsRUNDOWN: Only support payments on existing payment_methodsARCHIVE: Does not support new payments or payment_methods, nor will any API requests be made to the gateway in this statusThis endpoint will attempt to reach the gateway using the credentials configured on the gateway.
\nRequest:
\ngateway_id is our ID or your ID for the gateway (id or code)Response:
\nWhere connection_status is one of:
COMING SOON
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{session_key}}"},{"key":"password","value":"Request:
\ngateway_id is our ID or your ID for the gateway (id or code)This method will return the approximate number of saved payment methods on a gateway. Please note, the number is accurate as of the \"updated\" date, however a cached value will be returned if more than 100 in total. The duration of the cache scales with the number of saved payment methods, values over 10k will only be updated monthly
\nResponse:
\nWhere by_status:
This request performs a simple search against instance objects:
criteria: The search criteria (URL encoded).order: The sort you would like to applyexpand: The fields to expand into full objects (see GET object) limit: The maximum records to return offset: The offset from the first records to start returning recordsAvailable fields for criteria and order:
Expand:
\nGETResponse:
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{session_key}}"},{"key":"password","value":"Request:
\ninstance_id is our ID or your ID for the instance (id or instance_key)You can expand the following fields:
applicationsecret_keyResponse:
\nWhere status is one of:
You can create an instance via API or payments.js.
\nRequest:
\nWhere instance contains:
Where legal_entities is (enterprise only):
Request:
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{session_key}}"},{"key":"password","value":"You can update several fields on an instance. Only the passed fields will be updated, fields not passed will not be updated. To blank a field, pass the field with an empty string.
\nRequest:
\nWhere instance contains:
Where legal_entities is (enterprise only):
Request:
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{session_key}}"},{"key":"password","value":"Request:
\ninstance_id is our ID or your ID for the instance (id or instance_key)Response:
\nHTTP 204 - no body
This endpoint will, with immediate affect mark an instance as INACTIVE. While the instance may exist in the instance list as INACTIVE for up to one year, it will be inaccesssible. No further instructions will be issued by the instance (including any instructions to cancel previously issued instructions, or invalidate previously generated third party credentials). Any instructions mid way through completion will lapse (eg an authorised payment not yet captured).
\nPLEASE USE WITH EXTREME CAUTION - THIS CANNOT BE REVERSED
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{session_key}}"},{"key":"password","value":"The capabilities API allows you to determine the payment capabilities of the instance, and determine if the instance is able to process a specific type of payment. Behind the scenes the merchant may have configured multiple payment processors to achieve this set of capabilities..
\n\n\nTIP! This API does a good job at indicating if the merchant is ready to process a specific payment, however its designed as a simple representation of the
\ngatewaysAPI and it is possible that at checkout no payment options are available. For example, if you are performing an \"AUTH\" in a currency that doesn't have the ability to do \"AUTH\"s (eg if the merchant has configured to only support ACH for USD payments).
Query Parameters:
\ncurrency (optional): The ISO code of the currency of the transactionResponse:
\nWhere a capability:
Where a payment_method_type:
NOTE: If the instance has not been created it will return a HTTP 404 with a body {\"code\":\"NOT_FOUND\",\"message\":\"Instance not found\"}.
This request performs a simple search against legal_entity objects:
criteria: The search criteria (URL encoded).order The sort you would like to applyexpand: The fields to expand into full objects (see GET object) limit: The maximum records to return offset: The offset from the first records to start returning recordsAvailable fields for criteria and order:
Expand:
\nGETResponse:
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{session_key}}"},{"key":"password","value":"Request:
\nlegal_entity_id is our ID or your ID for the legal_entity (id or code)Expand:
\ncreated_session updated_sessionResponse:
\nWhere legal_entity is:
Where status is one of:
This is an enterprise feature.
\nA legal_entity represents a real world company, which is incorporated in a country with a registered name, company type and company number. Additional information such as registered address, and contact details may be included for reference, or if you need to include these in receipting.
In a typical environment you will only have a single legal_entity per instance (by default, this is named ORG), it is however possible to set up multiple entities with different gateways that sit behind each entity. Unless you configure multiple entities, the legal_entity for a payment will not be displayed in the merchant portal.
\nYou can then control how payments are routed to each entity:
\nThis request performs a simple search against legal_entity_route objects:
criteria: The search criteria (URL encoded).order The sort you would like to applyexpand: The fields to expand into full objects (see GET object) limit: The maximum records to return offset: The offset from the first records to start returning recordsAvailable fields for criteria and order:
Expand:
\nGETResponse:
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{session_key}}"},{"key":"password","value":"Available to expand:
\ncreated_session gateway legal_entityupdated_sessionResponse:
\nWhere status is one of the below:
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{session_key}}"},{"key":"password","value":"This is an enterprise feature.
\nA legal_entity_route is a mapping between legal_entity and gateway. A contract is drawn up between an account (payer) and legal entity (payee), the legal entity routes are use to determine which gateway will be used to process the transaction.
Where you can expand:
contract transactionpartspayment_methodResponse:
\nWhere status is:
Where gateway_status is:
The \"Create Payment URL\" endpoint allows you to generate a URL to a hosted payment process.The options for the URL are the same as payment API, with the following additional fields:
\nThe following fields from the payment API are not available or have an altered meaning during a hosted process:
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{session_key}}"},{"key":"password","value":"If you POST a payment, a new payment will be attempted. Unless the payment is rejected prior to processing the API request will succeed and return a payment object in a SUCCESS or DECLINE status. If however the payment is rejected due to a validation rule (eg no card data), no payment will be created.
\nWhere payment_method:
Where account:
Where account.address, payment_method.billing and shipping:
Where line_items is an array of:
Note: SUM(line_items.total_amount) should equal the payment amount. If it is less, a \"Miscellaneous\" line item will be added to make up the difference. If the sum exceeds the payment amount, the difference will be flagged as a \"Discount\".
If 3D secure (3DS) is required for a transaction, the transaction will be returned in a status of REQAUTH, with a redirect_url field. You will need to iFrame this URL (or redirect to it) for the user to complete the 3D secure process. If the gateway has the feature REQUIRES_3DS_WINDOW the gateway does not support an iFramed process and the redirect_url must be launched in a new window (or redirect the browser to it).
There are two possible outcomes of a 3DS process:
\n* Approved: The user passed 3D secure, and the transaction has been process successfully. They will be redirected to the success_url included in the original payment instruction. The success url will have the following query parameters added ?payment=pay_123_123&contract=co_123_123&transaction=tr_123_123&payment_method=pm_123_123&status=SUCCESS (note status could be any transaction.status, its recommended SUCCESS and UNATTRIBUTED present a receipt, PENDING and UNRESOLVED present an “In progress” message, see transaction statuses for further info). The transaction has been processed by the time the user reaches this URL, you can fetch the transaction via API for full details. Transaction and status may be missing if the contract has a start date in the future.
* Declined / Cancelled: 3D secure or the subsequent payment instruction is declined. The user will be redirected to the cancel_url included in the original payment instruction. The cancel_url will have the following query parameters added ?payment=pay_123_123&contract=co_123_123&transaction=tr_123_123&payment_method=pm_123_123&status=DECLINED&error=Gateway+message (note status could be any transaction.status, see transaction statuses for further info). The transaction will have been processed (unsuccessfully) by the time the user reaches this URL, so you can fetch the transaction via API for full details.
You can capture an authorisation in part of full.
\nNote, support for multi-refund (eg I authorise $100 and capture $20 followed by a second capture of $80) is not available on all gateways.
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{session_key}}"},{"key":"password","value":"You can void an authorisation, which will unblocked the authorised amount.
\nThere are no parameters to void.
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{session_key}}"},{"key":"password","value":"The payments end point allows you to create and retrieve once off payments. If you attempt to fetch a scheduled or recurring payment you will receive an error advising: \"Payments API is not available for scheduled or recurring payments, please use the contract and transaction API\"
Note: When a payment is performed behind the scenes a contract and transaction is created, a payment is a simplified view of these 2 objects.
\nYou can not search payments, please search transactions instead
\n","event":[{"listen":"prerequest","script":{"id":"d13f189d-b079-47bc-9d10-c7eec5c36ac5","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"2c900731-51f9-45cf-ad8c-477f333d2b36","type":"text/javascript","exec":[""]}}],"_postman_id":"faebf5e6-c780-436f-b97b-6bc46a89e16a","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{session_key}}"},{"key":"password","value":"This request performs a simple search against payment_method objects:
criteria: The search criteria (URL encoded).order: The sort you would like to applyexpand: The fields to expand into full objects (see GET object) limit: The maximum records to return offset: The offset from the first records to start returning recordsAvailable fields for criteria and order:
Expand:
\nGETResponse:
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{session_key}}"},{"key":"password","value":"Request:
\nAvailable fields to expand:
account
created_session
gateway
updated_session
Response:
\nWhere address:
Where status:
Update an existing payment_method.
\n{{payment_method_id}} can be either ID, or codeRequest:
\nWhere payment_method:
Where address:
Response:
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{session_key}}"},{"key":"password","value":"This API is for advanced use cases and designed to be used in hand
\nCreate a new payment_method. In general this API can be used for:
\nUnless you're duplicating a payment_method between environments, this API is intended to be used in conjunction with Shuttle support as:
\nRequest:
\nWhere payment_method is (data import / data copy - ie token import) :
Where payment_method (for third party UX - ie payment details capture and pass to gateway for tokenisation) :
Where address:
Response:
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{session_key}}"},{"key":"password","value":"Request:
\npayment_method_id is the id assigned when created.Response:
\nHTTP 204 and an empty body
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{session_key}}"},{"key":"password","value":"This request returns a list of payment processors. Please note, not all payment processors will be available to your application, and you should filter the list for visible: true. Invisible payment processors are returned so you can render information for all processors used by your instances, even when the processor is not generally available. For example gateways disabled in the application configuration, legacy integrations, pre-release integrations, custom integrations, and integrations that are not generally available due to commercial, compatibility or other reasons.
Response:
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{session_key}}"},{"key":"password","value":"Request:
\nprocessor_id is our ID for the processorexpand is not currently supported for instancesResponse:
\nNote: settings and values are a proprietary format, and not for general use.
Where you can expand:
accountcreated_session parts source_transactionupdated_sessionWhere status is:
Where gateway_status is:
You can refund a payment in part of full, or simply mark a payment as refunded (if refunded offline). You can refund \"PAYMENT\" and \"CAPTURE\" type transactions, but not \"AUTH\" (you must void an AUTH that has not been captured).
\nNote, support for multi-refund (eg I pay $100 and refund $20 followed by a second refund of $80) is not available on all gateways.
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{session_key}}"},{"key":"password","value":"You can refund a capture in part of full, or simply mark a payment as refunded (if refunded offline).
\nNote, support for multi-refund (eg I pay $100 and refund $20 followed by a second refund of $80) is not available on all gateways.
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{session_key}}"},{"key":"password","value":"You can refund a contract, which allows you to refund multiple transactions at once for recurring payments / subscriptions.
\nWhere legal_entities is an array of:
The following error codes may be returned by this call:
\nThe instruction returns the following fields (if validate_only not set):
If validate_only is set, the following will be returned:
Where refund_candidates is an array containing:
You can refund a contract, which allows you to refund multiple transactions at once for recurring payments / subscriptions. This will create a list of refunds from a single instruction.
\n","event":[{"listen":"prerequest","script":{"id":"c72b3852-e2d4-4263-a4a8-c3a789124c32","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"29471f56-6315-4b69-915a-863e970e3b7e","type":"text/javascript","exec":[""]}}],"_postman_id":"ac6f9eab-64b8-4a19-8561-94909ac47e81","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{session_key}}"},{"key":"password","value":"This request performs a simple search against transaction objects:
criteria: The search criteria (URL encoded).order: The sort you would like to applyexpand: The fields to expand into full objects (see GET object) limit: The maximum records to return offset: The offset from the first records to start returning recordsAvailable fields for criteria and order:
Expand:
\nGETResponse:
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{session_key}}"},{"key":"password","value":"Where you can expand:
accountcapturescontractcreated_session gatewaypartspayment_methodrefundssource_transactionupdated_sessionResponse:
\nWhere status is:
Where gateway_status is:
Where workflows contains the id's of any workflows executed, each containing the type of workflow hook:
Where parts is an array of part:
Where workflow hook_type contains:
A transaction is created for each attempt to instruct a payment gateway to do a payment, authorisation, capture, void or refund. Please note, each of these activities have their own API, and the transaction list is a way to see the overall ledger.
\n","event":[{"listen":"prerequest","script":{"id":"c9d489fe-3777-4ef0-8cd2-bb4a9f88f496","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"f96d2cd8-cf5a-4258-91b6-92a6fae6a6d4","type":"text/javascript","exec":[""]}}],"_postman_id":"ecfe6b5b-8b05-40f5-b502-a06f5d4bb6c9","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{session_key}}"},{"key":"password","value":"This request performs a simple search against workflow objects:
criteria: The search criteria (URL encoded).order: The sort you would like to applyexpand: The fields to expand into full objects (see GET object) limit: The maximum records to return offset: The offset from the first records to start returning recordsAvailable fields for criteria and order:
Expand:
\nGETResponse:
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{session_key}}"},{"key":"password","value":"Request:
\nworkflow_id is our ID or your ID for the workflow (id or code)You can expand the following fields:
Response:
\nWhere status is one of:
Where each features contains a list of features that are available in the integration. This is for users building a bespoke checkout:
This endpoint will attempt to reach the processor using the credentials configured on the workflow.
\nRequest: \nworkflow_id is our ID or your ID for the workflow (id or code)
Response:
\nWhere connection_status is one of:
COMING SOON
\n","auth":{"type":"basic","basic":{"basicConfig":[{"key":"username","value":"{{session_key}}"},{"key":"password","value":"The below table lists the various error codes you may receive from the API:
\n","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"id":"31e97960-4c8c-4aa9-8fce-473b880c2d10","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"3abd2142-0bab-4414-9c7c-e1dd1d6b7a8f","type":"text/javascript","exec":[""]}}],"_postman_id":"4fb80953-b426-47b4-85b7-0a4bb601b86d"}],"id":"a258cf7f-84d5-416c-b434-a8aeafb5c32b","description":"The base URL for all endpoints, is:
\nhttps://app.shuttleglobal.com/c/api/instances/{{instance_id}}\n\nWhere {{instance_id}} is the unique identifier you used for the client / account during onboarding.
Note: This API only accepts secure requests under https__.
\nThere are two types of authentication,
\nsecret_key which will be passed on all requests in the authorisation header, as such:Authorization: Basic ${base64(secret_key + \":\")}\n\ninstance on which you can create an instance specific instance.secret_key. You can then pass that on the API with the application's shared_key. Using this mechanism you will only be able to access APIs under /api/instances/:instance/\\\\*Authorization: Basic ${base64(application.shared_key + \":\" + instance.secret_key)}\n\nList APIs allow you to pass a search criteria and order clause.
\nWhere criteria:
Supports operators:
\n!=, >=, >, <, <=
=: exact match, separate multiple values with ; for IN
~=: partial match
<>: between, separate values with ; ie <>min;max
!: is null
!!: is not null
Separate multiple criteria with ,
Strings are case insensitive (some exceptions apply)
\nBooleans are Y/N (TIP: we recommend checking for =Y or !=Y as some objects treat false as null)
Example:
\nstatus=ACTIVE;FAILING
status=ACTIVE;FAILING,email=dave@gmail.com
scheduler=Y
URL escape the criteria:
\ncriteria=status=ACTIVE;FAILING,email=dave@gmail.comWhere order:
Supports any field criteria supports
\nDefaults to created:desc
Will order asc unless you specify desc
Separate order field with ,
Example:
\norder=updated
order=updated;desc
order=status,updated;desc
Many objects allow you to \"expand\" a referenced object on GET and LIST apis. The list of fields that can be expanded are on the docs GET object API and can be expanded passing expand and a csv list of field names eg:?expand=field1,field2
You can also expand nested fields, using a dot syntax nest
\n?expand=field1.subfield1
For example:
\nGET .../payment_gateways/pg_123_456\n{\n payment_gateway: {\n id: \"pg_123_456\", \n ...\n updated_session: \"ses_123_78634\"\n }\n}\nGET .../payment_gateways/pg_123_456?expand=updated_session\n{\n payment_gateway: {\n id: \"pg_123_456\", \n ...\n updated_session: {\n id: \"ses_123_78634\",\n ...\n \"user\": \"user_123_567\"\n }\n }\n}\nGET .../payment_gateways/pg_123_456?expand=updated_session.user\n{\n payment_gateway: {\n id: \"pg_123_456\", \n ...\n updated_session: {\n id: \"ses_123_78634\",\n ...\n \"user\": { \n id: \"user_123_567\",\n ...\n }\n }\n }\n}\n\nAll webhooks will come from one of the following IP addresses:
\n52.51.86.26\n54.229.12.118\n54.76.31.104\n34.252.246.134\nWebhooks must be to a HTTPS target on port 443.
\nWebhooks do not contain any sensitive information, if you wish to see the objects being referred to you must fetch them via the API using your API credentials.
\n","event":[{"listen":"prerequest","script":{"id":"f4f98e62-3cdf-4a4d-8440-2c52e81143b4","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"fe3514ed-ce32-4475-9b84-c29f53bc599c","type":"text/javascript","exec":[""]}}],"_postman_id":"b9f69de0-7097-44a7-ae4b-4e3949f673c6"},{"name":"Retry Policy ","item":[],"id":"11b62c0e-e5ed-4b20-8891-1f784750a5d0","description":"A webhook that returns HTTP 200 will be considered successful.
\nYou can activate a webhook retry policy using the following syntax when defining your webhook URL in the developer portal. All retries / failovers are after 1 minute delay.
\n|: sets the number of attempts, eg target|3 (attempt 3 times)>: failover to a second URL, eg targetA>targetB (attempt targetA, then attempt targetB),: send a webhook to multiple destinations eg targetA,targetB (sent to targetA AND targetB)Examples (where targetA=https://postb.in/b/aaa, and targetB=https://postb.in/b/bbb):
\n\n","event":[{"listen":"prerequest","script":{"id":"2d8d8c2a-5c07-476d-9966-63f0644a4f43","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"2aa41476-4980-42c3-8320-35bbdb1fe3d1","type":"text/javascript","exec":[""]}}],"_postman_id":"11b62c0e-e5ed-4b20-8891-1f784750a5d0"},{"name":"Deprecations","item":[],"id":"2d08c2d0-f195-4d62-8c2a-ff07a45a03cf","description":"Note: Retries are DISABLED in the sandbox environment.
\n
You should handle webhook deprecations. Some webhooks may be replaced over time, these will be marked as deprecated with a date. You should ignore all deprecated webhooks with a date prior to your integration date, and also log all deprecation notifications for your developers. In general deprecations will be maintained for a period of 12 months.
For example:
\n{\n \"key\": \"11842_1586343957346_5258502bcde56ad8\",\n \"client\": \"11842\",\n \"action\": \"PAYMENT.SUCCESS\",\n \"transaction\": \"tr_11842_10009\",\n \"contract\": \"co_11842_10004\",\n \"payment\": \"pay_11842_10009\",\n \"created\": \"2020-04-08T11:05:56\",\n \"deprecated\": \"2020-04-01T00:00:00.000Z\",\n \"deprecated_comment\": \"This is for a capture and has been replaced by CAPTURE.SUCCESS\"\n}\nSent when a new account is created, please note all payments are against an account, so will may receive this per payment instruction if you are not passing an account identifier through on the API (as will will create a unique account object per payment)
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when an existing account is updated.
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when an authorisation was captured successfully. This only applies to AUTH / CAPTURE scenarios, not where the AUTH and CAPTURE are at the same time.
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when a authorisation failed capture.
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when an authorisation was instructed for capture but is still in progress, you will receive a CAPTURE.SUCCESS or CAPTURE.FAILED once the status of the capture is known.
We will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when a capture is unresolved, this means it was sent to the gateway but its not clear if the capture was processed or not. Please note, Shuttle will try to automatically reconcile the transaction with the gateway immediately, then after 1 minute, and again after 15 minutes. In some cases however it will require the merchant to log into their gateway to see if the funds were received.
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when a recurring payment contract has a new charge raised.
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when a recurring payment contract has a charge updated, eg the amount or due date.
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent for a recurring payment contract, when the unpaid amount of a charge is voided. If this is sent you will not receive a CHARGE.COMPLETE, as the charge will never be fully paid.
We will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent for a recurring payment contract, when a charge is fully paid. This will not be sent if the charge is voided, you will receive a CHARGE.WRITTENOFF.
We will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when a recurring payment contract is activated successfully (by default, a contract with an initial payment will not start unless the initial payment successful)
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when a recurring payment contract is update (eg next_charge, payment_method, status, last_transaction). Its worth noting we may fire two of these for each recurring payment, once to indicate a new charge is present (updating next_charge), and a second time when the new charge is paid (updating last_transaction).
We will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when a recurring payment contract status transitions to COMPLETED, CANCELLED or FAILED.
We will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when a recurring payment has a note (ie comment) added or updated.
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when payment was completed successfully. This may be an AUTH or AUTH/CAPTURE.
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when a payment was declined.
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when a payment has started processing, but the success status is not available yet (eg: for Direct Debit). You will receive a PAYMENT.SUCCESS or PAYMENT.FAILED webhook once completed.
We will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when a payment is unresolved, this means it was sent to the gateway but its not clear if the transaction was processed or not. Please note, Shuttle will try to automatically reconcile the transaction with the gateway immediately, then after 1 minute, and again after 15 minutes. In some cases however it will require the merchant to log into their gateway to see if the funds were received.
\nOnce the transaction is resolved (automatically by Shuttle or manually by the user) you would then get a PAYMENT.SUCCESS or PAYMENT.FAILED webhook.
We will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when a payment is updated, for exampled refunded.
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when payment method is created for SINGLEUSE.\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when payment method created (and saved for reuse) or transitions from PENDING to ACTIVE (saved for reuse).\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when payment method transitions from PENDING to FAILED, or failed tokenisation.
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when payment method was created in a PENDING status (eg it is still being authorised).
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when payment method is updated. This will trigger each time the payment method is used, or updated with new details.
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when tokenised payment method is \"deleted\". This is the transition from an ACTIVE to an INACTIVE status.
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when a refund was completed successfully.
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when a refund was declined. Examples include if the initial transaction was too long ago (varies gateway by gateway), or the refund has already been refunded via the gateway.
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when a refund has started processing, but the success status is not available yet. You will receive a REFUND.SUCCESS or REFUND.FAILED webhook once completed.
We will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when a refund is unresolved, this means it was sent to the gateway but its not clear if the refund was processed or not. Please note, Shuttle will try to automatically reconcile the transaction with the gateway immediately, then after 1 minute, and again after 15 minutes. In some cases however it will require the merchant to log into their gateway to see if the funds were sent.
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when an authorisation was voided successfully.
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when an authorisation failed voiding.
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when a new channel is created.
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when an channel is updated.
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when an channel is archived. No further payments will be processed via an channel once archived.
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when an designation is updated.
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when an designation is archived. No further payments will be processed via an designation once archived.
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when a new designation is created.
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when a new designation route is created.
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when an designation is updated.
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when an designation is archived. No further payments will be processed via an designation once archived.
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when a new processor connection is made.
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when a new processor connection is updated.
\nNote: This currently will also fire every time an OAUTH access token is updated, which may be quite regularly.
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when a processor is disconnected. No further payments will be processed via a gateway once disconnected.
\nNote: Not routing any payments to the GATEWAY is different from disconnecting it.
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when a new initiative is created.
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when an initiative is updated.
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when an initiative is archived. No further payments will be processed via an initiative once archived.
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when a new instance is created.
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when an instance is updated.
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when an instance is terminated.
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when a legal entity is created.
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when a legal entity is created.
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when a legal entity is archived.
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when a payment routing rule is created.
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when a payment routing rule is replaced.
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when a payment routing rule is created.
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when a payment routing rule is created.
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when a team is updated.
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Sent when a team is archived.
\nWe will POST webhooks to your configured URL using the attached format, where:
\nYou endpoint should return HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Webhooks are generated for many different events.
\nWe will POST webhooks to the URL configured in the developer portal. Your endpoint should return a HTTP Status of 200 if the webhook has been received. A non 200 status code we be deemed as undelivered.
Additional webhooks will be added over time, so take care to only filter for the events your care about.
\nUpon receipt of a webhook, you should decide if you want to consume the webhook, and if so, fetch the associated object eg payment, transaction or contract via API and process accordingly. No sensitive data is passed in the webhook, just references to the data.
\n","event":[{"listen":"prerequest","script":{"id":"70429353-ea02-43d1-9669-caa634f53768","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"0ab26cd5-311d-4cba-91ca-16c6884844c0","type":"text/javascript","exec":[""]}}],"_postman_id":"f0ac8b59-e151-4b0c-928c-d1eb0358657b"},{"name":"Testing","item":[{"name":"Sandbox Gateway","item":[],"id":"38b4af18-cfc3-41d0-8423-96fdddd13cf1","description":"When developing or testing, unless you are testing how a specific gateway behaves, we recommend you use our \"Sandbox Gateway\". This is the first gateway listed when connecting a gateway in SANDBOX, and requires no credentials.
\nDeveloper Mode options:
\nIf you are using our supplied checkout, most developer options are handled for you, however you should ensure that you handle a PENDING response from checkout, and catch the subsequent approval / decline webhook.
\nSandbox - Test Cards
\nEach of the below tests a unique scenario, it is recommended you test at least every single non Approved card in this list, or if building your own checkout, every single card in this list.
\nSandbox - 3D Secure Test Cards
\nSandbox - Test ACH Accounts
\nSandbox - Test SEPA Accounts
\n","event":[{"listen":"prerequest","script":{"id":"9467bc29-1808-4336-8425-da6a171b6dcb","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"b54a124e-6ef9-471f-ae63-6d60cb7d636e","type":"text/javascript","exec":[""]}}],"_postman_id":"38b4af18-cfc3-41d0-8423-96fdddd13cf1","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"97c33494-30ff-4a6a-8c96-fe1e47c21b1e","id":"97c33494-30ff-4a6a-8c96-fe1e47c21b1e","name":"Testing","type":"folder"}}},{"name":"PayPal","item":[],"id":"0bfcbfbe-7d8d-44d0-82ae-e5c27d8bf15c","description":"The PayPal sandbox works a little differently from other gateways - to test failure scenarios, a HTTP header needs to be passed to PayPal. This only applied to SANDBOX payments.
\nYou can do this by setting the customer name:
\nfirst_name: PayPal-Mock-Responselast_name: PAYER_CANNOT_PAY Where last name is the response you want to emulate.
\nPlease refer to the following documentation:
\nWhen testing payments, the test cards will depending on the gateway you're connected to. Test cards will only work in your application's sandbox, where you've also connected to a gateway's sandbox environment.
\n","event":[{"listen":"prerequest","script":{"id":"c86f4dea-01e2-4baa-9c6a-70f615363267","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"effc8443-2631-4992-a2f9-ec728530b1c7","type":"text/javascript","exec":[""]}}],"_postman_id":"00ae793b-e5e4-4a9a-b1d4-b592ef9df261","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"97c33494-30ff-4a6a-8c96-fe1e47c21b1e","id":"97c33494-30ff-4a6a-8c96-fe1e47c21b1e","name":"Testing","type":"folder"}}}],"id":"97c33494-30ff-4a6a-8c96-fe1e47c21b1e","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"id":"c7e49777-0e68-48d1-9f95-e61455e4a164","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"ead418c5-c6d8-4aa3-a11f-28757cc459c9","type":"text/javascript","exec":[""]}}],"_postman_id":"97c33494-30ff-4a6a-8c96-fe1e47c21b1e","description":""},{"name":"Release Notes","item":[{"name":"20260417","item":[],"id":"bb18d997-e507-48b7-98c2-2f9b0ed68261","description":"New Features
\nXendit — new gateway integration available for merchants in supported regions
\nFatZebra — new gateway integration
\nAndDone — new integration
\nScheduled Charges — schedule customised multi-instalment payments with configurable amounts and dates per instalment
\nPayment Links API — new POST /payment_links endpoint for programmatic creation of links
\nImprovements
\nCybersource — automatic resolution of pending transactions; AVS mode selector and expanded metadata field mapping
\nStripe — SEPA now supports target date scheduling and pending-until-settled status, keeping transactions in pending until the bank settles (matching the ACH behaviour)
\nAuthorize.Net — CCD now available as a configurable ACH eCheck type (alongside PPD and WEB)
\nInterprose — payment plans now supported via schedule metadata
\nApple Pay / Google Pay — temporary cards now work in sandbox gateway for end-to-end wallet testing
\nshuttle.js — 1.4.6 - embedded checkout now propagates allow=payment permission to sub-iframes via wildcard, unblocking nested embed scenarios
\nPassword reset — session now remains authenticated immediately after reset
\nBug Fixes
\nGateways:
\nStripe — ACH delayed failures now process correctly; transactions no longer remain locked in SUCCESS
\nPayPal — onboarding endpoint restored
\nQuickBooks Payments — ValidationFault resolved; delete-card error fixed; ACH now supported on CAD-only accounts; raw card details used in place of cardOnFile where available to improve
authorization rates; fixed boltUtilsContext error in processPaymentMade
GoCardless — gateway message no longer cleared after an automatic retry; fixed IBP payments being routed to Stripe when multiple gateways are configured
\nAuthorize.Net — ACH nameOnAccount no longer incorrectly populated with the account number
\nAuthorize.Net — token expiry no longer causes a 20-second outage on the payment processor
\nCheckout.com — refunds outside the 1-year window now return a clear, user-friendly error instead of a generic failure
\nTrustPayments — fixed null-dereference in capture() when the transaction is not yet indexed
\nSandbox gateway — pending tokenise handling fixed
\nRecurring token payments — now correctly respect the gateway ARCHIVE status and are blocked on archived gateways
\nupdate_transaction webhook — now correctly includes gateway_status in the payload
\nGeneric — fixed token-delete error affecting multiple gateways
\nPlatform & reliability:
\nReporting — format-csv formatter now tolerates ipstack 500s during IP country lookup
\nCustomised branding logo — Save button no longer disabled on some domain names
\nGift Aid — claim items now include account data when created without an active claim
\nApple Pay — well-known verification now checks both with and without the .txt extension for broader server compatibility
\nNew Features
\nImprovements
\nGoCardless - Enhanced decline event tracking with detailed reason codes for better reconciliation
\nGoCardless - Improved refund metadata for clearer transaction history
\nGoCardless - Fixed language parameter handling for international customers
\nStripe - Added support for extended card authorization (7 → 30 days)
\nStripe - Improved settlement tracking for auth+capture transactions with currency and fee data
\nAuthorize.net - Added connect via API Keys (rather than login)
\nNMI - Now supports passing cardholder name
\nCheckout - Updated security headers and CSP context for new / updated gateways
\nBug Fixes
\nImprovements
\nAuth.NET - You can now refund ACH payments (where supported by Auth.NET)
\nAuth.NET - You can now determine the payment type for scheduled payments (PPD or WEB)
\nAuth.NET - Now supports API Key connectivity (contact support if you need this)
\nCustomer portal change payment method now supports all payment methods checkout supports
\nStripe - account issues preventing payment are now presented in gateway-setup
\nPayTomorrow - improved rendering or credit messages
\nImproved web security at checkout
\nImproved express checkout rendering, speed and page build
\nBug Fixes
\nVarious bug fixes
\nRecurring payments retry_count now reset to 0 on pending transactions
Fixed an issue causing incomplete translation files appearing on some new instances
\nFixed an issue in report generation when report names contain a comma
\nImprovements
\nGoCardless - Added Canada support for PAD
\napi - you can now fetch an archived instance and see its been archived
\nimproved security measures around MFA tokens
\nimproved security measures passwords - password age, preventing reuse
\npositioning change for native ApplePay / GooglePay / Click to Pay
\nPAYMENT.AUDIT webhooks now contain payment, transaction references
\nStripe - changed idempotency to better support multiple Shuttle accounts connected to the same Stripe account
\nStripe - cleaned up some text around ACH
\nImprovements
\nPayPal - simplified some language
\nPayPal - expose more connectivity errors on the config tool
\nBraintree - redact credentials on edit
\nGeneral - updated various depenancies with security updates
\nGeneral - standardise the technology of file uploads
\nStats - added tracking of tokenisation requests
\nCheckout - updated recaptcha to enterprise
\napi - added webhooks attach / detach endpoints for an instance
\napi - added the abiliuty to upload all file types as notes
\nBug Fixes
\nAuth.NET - added support for renewing access tokens in scheduled jobs
\nAdyen - added support for authorisation only
\n(Enterprise) Fixed initiative ordering
\n(Enterprise) Added ability for amending giftaid claim dates
\nImprovements
\nWorldpay: Error 91 (upstream connectivity error) now maps to DECLINE_RETRY
\nGoCardless - Support for Success+
\nBug Fixes
\nSandbox gateway - fixed \"require CVC\" being applied to ACH
\nFixed resending a team invite displaying an error
\nNew Features
\nSingle use payment links - ability to create single use payment links that can be shared with customers, via parameters or natural language (private release)
\nOAUTH server - ability to allow merchants connect to a Shuttle account via OAUTH2 (private release)
\nImprovements
\nMany merchant portal improvements including
\nLogin & MFA improvements
\nSimpler UX components are easier to use
\nSimpler menuing system
\nImprovements
\nBug Fixes
\nFixed an issue bringing a contract out of unresolved
\nFixed an issue with GET charge returning a 500 error if requested while the transaction was still being processed
\nImprovements
\nStripe: ACH now support manual verification process for banks that dont support open banking
\nGoCardless: Improved rate limit handling, new transactions will not be submitted to Gocardless when GoCardless srate limiter is above 80% utilisation
\nImprovements
\nBugs
\nFreedomPay: Now passing cardPresent N
\nCybersource: Trim long orderReferences
\nSandbox: Fixed an issue with tokenisation and 3DS
\nCheckout fixed an infrequent issue resulting in a max call stack exceeded
\nImprovements
\nBugs
\nSquare: Fixed an issue affecting checkout presenting on some acounts
\nGMO: Updated memberId to now be account_key
\nCybersource: Fixed a display issue when configuring single currency accounts
\nFreedomPay: Fixed a display issue when configuring single currency accounts
\nNew features
\nImprovements
\nShuttle.js: v1.4.1 security update to protect against possible XSS in browser messaging
\nCheckout: Added better support for connectivity issues during payment submission, payment will be automatically retried, and handle if both instructions reach the server .
\nGoCardlesss: now submits payments to GoCardless asynchronously when close to being rate limited. Specifically, if less than 100 requests remaining (of 1000/min request limit) payments will not be submitted immediately.
\nBugs
\nOpayo: fixed an issue with some users getting the error \"Merchant session key or card identifier invalid\" using a tokenised card
\nFixed an issue with 4dp currencies being rounded to 2dp when making a settlement payment on an overdue contract
\nFixed an issues where an instruction for card tokenise + scheduled payment not passing currency to the gateway during tokenise step, which affected some processors with a multi-mid configuration
\nFixed and issue where the authorisation url would not be passed to a gateway on a 3DS retry
\nImprovements
\nAdyen - Added finer granularity in connection error reasons
\nAPI - Improved the performance of the payment_method API when requestion a large number of payment_methods
\nImprovements
\nReleased shuttle-1.4.0.js which supports large baskets. Previously basket size was limited by the URL (~ 2kb)
\nYou can now expand created_session, and updated_session in objects for details on who made a change
Updating a contact amount now creates an audit record
\nRemoved county field for US addresses
\nUpdated internal routing logic to allow passing a gateway_id in a payment instruction to override the available routes when using a saved card.
\nYou can now expand nested fields, eg ?expand=updated_session.user to expand the updated_session, and the user within it
Bug Fixes
\nImprovements
\nAuthorize.net - better handling of response code 4 (pending)
\nAuthorize.net - optimised handling of when Auth.net is unavailable
\nAuthorize.net - added a clearer explanation when trying to capture an expired Auth
\nAuthorize.net - request metadata is now stored for payment declines
\nAuthorize.net - request metadata has been extended for payments, to include customer profile creation
\nAuthorize.net - added invoiceNumber to refund, to enable refunds for customers that have configured it as a mandatory field
\nQuickbooks Payments - request metadata has been extended for payments, to include charges and cards
\nQuickbooks Payments - \"A temporary issue prevented this request from being processed.\" now maps to DECLINE_RETRY, rather than UNRESOLVED
\nImprovements
\nStripe - Declined transactions now have gateway_metadata containing the API calls used
\nStripe - ACH & Multibanco now use the Payment Intents API due to Stripe deprecating payment sources API
\nDev Portal - Improved the ability to privately deploy gateways on an application by application and instance by instance basis
\nAuth.NET - Now has a more informative error message for refunds after the permitted 180 days
\nAuth.NET - Updated the webhook validation process due to it not working on some accounts
\nNMI - Updated the webhook validation process due to it not working on some accounts
\nFreedomPay - Various improvements
\nImprovements
\nBug Fixes
\nImprovements
\nBug Fixes
\nImprovements
\nBug Fixes
\nImprovements
\nBug Fixes
\nImprovements
\nBug Fixes
\nImprovements
\nBug Fixes
\nImprovements
\nImprovements
\nBug Fixes
\nImprovements
\nBug Fixes
\nBug Fixes
\nBug Fixes
\nNew Features
\ncreated_session and updated_session, ie who created them and updated them, this was not previously tracked and will only be populated from 9 May 2024 onwards. The API docs will be updated in due course.Improvements
\nBug Fixes
\nImprovements
\nBug Fixes
\nNew Features
\nImprovements
\nBug Fixes
\nImprovements
\nBug Fixes
\nBug Fixes
\nNew Features
\nfuture_charges API which returns future occurrences of a recurring contractImprovements
\nBug Fixes
\nImprovements
\nBug Fixes
\nrequiresCVC flag on a UNRESOLVED transactionImprovements
\nImprovements
\nBug Fixes
\nNew Features
\nImprovements
\n{is_available: BOOL} if content was rendered to allow you to adjust your page layoutBug Fixes
\nNew Features
\nImprovements
\ninstance now supports metadata, features, report_users, receipt_usersapplication now supports featureslegal_entity now supports website, support_url, privacy_policy, tcsaccount now supports timezone, companyBug Fixes
\nNew Features
\nImprovements
\nBug Fixes
\nNew Features
\nImprovements
\n/c/api/instances/{id}/* now supports the use of client (eg cl_1234) as well as instance_keycompany fieldalt_key to field CUSTOMBug Fixes
\nNew Features
\nImprovements
\nBugs
\nImprovements
\nBug Fixes
\nThis section lists recent platform changes - please note, not all changes are relevent to all users
\n","auth":{"type":"noauth","isInherited":false},"event":[{"listen":"prerequest","script":{"id":"892e850d-8dd8-4548-907c-5619dcb17cc7","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"17b0e941-b43b-4bbb-b041-eb2b06975685","type":"text/javascript","exec":[""]}}],"_postman_id":"2d04c433-d737-49fe-b505-817ef4bd1f38"}],"event":[{"listen":"prerequest","script":{"id":"0523a6bd-cbb1-4c3c-a9ab-40fe99484872","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"1f71278b-4a51-4a48-8131-f151ea79f30c","type":"text/javascript","exec":[""]}}]}