Explore

Migrating Merchants to Shuttle

This document is designed for platforms already processing payments on behalf of their merchants, it outlines the migration process and is not a technical specification. There are three things you might typically want to migrate to Shuttle:

Merchants and their connected gateways (ie which processor they are connected to and their gateway credentials)

Saved cards / payment methods

Recurring schedules managed by the gateway

Some of the APIs herein are not listed on the public API as they are intended for use when working with Shuttle support.

Merchants and their connected Gateways

You can migrate these via API, per merchant call:

POST /c/api/instances

{instance: {instance_key: "", name: "", ... optional merchant details...}}

POST /c/api/instances/{instance_key}/gateway

{gateway: {processor "":, values: {...connection credentials...}}}

Please note:

There is a different format of values for each gateway

You cannot migrate OAUTH clients this way, as our client_id will not have permission on the merchant. For OAUTH, the merchant will need to manually complete the OAUTH journey.

Docs:

Create Instance API:

https://api.shuttleglobal.com/#cf558889-cb20-4375-819e-def485b6d58a⁠

⁠

Create Gateway API:

https://api.shuttleglobal.com/#b8722eda-6508-442f-ae1c-10442d5b1304⁠

⁠

Saved Cards / Payment Methods

You can migrate these via API, either up front or at the time of a payment. These are called payment_methods and must associated to an account (customer) object, the account.crm_key should match your account identifier, that you pass during payment. When creating a payment_method you can nest the account if it doesn’t yet exist in Shuttle:

For upfront migration (per payment method):

POST /c/api/instances/{instance_key}/payment_methods

{payment_method: {account: {...account...}, ... payment_method details...}}

Docs:

Create Payment Method API:

https://api.shuttleglobal.com/#b1e15211-a069-476c-9a9d-8bcea47a26c9⁠

⁠

(optional) Create Account API:

https://api.shuttleglobal.com/#2f87085b-67cc-44b0-94d1-b9ca4a49fac4⁠

⁠

Or, if you prefer you can simply pass the account/token at the time of payment in the payment instruction:

POST /c/api/instances/{instance_key}/payments

{

payment: {

... instruction ...,

account: {...account details...},

payment_method: {save_card: true, ... token details...}

}

Where you pass the account details and payment_method inline in the payment instruction, if the do not exist in Shuttle they will be added, or if they exist, they will be updated. If you pass save_card: true in the payment_method, the token will be retained for future use, otherwise it must be passed each request.

The token format for each gateway is:

Stripe: `${customer}:${payment_method}`: eg `cus_QbdDumamHKPObQ;pm_1PkPxKGSt1QJUqqwM77UrDdu`

To be completed

Docs:

Create Payment API:

https://api.shuttleglobal.com/#fe184f65-c12c-41c0-84cc-34e6b611a13b⁠

⁠

Recurring Schedules

When processing a recurring schedule (eg subscription, or pay in 12 instalments) either your platform will be responsible for initiating each payment against a a card token, or you will instruct a third party’s (eg Stripe’s) scheduling system to run initiate payments.

In the case your platform is running the schedule and instructing payments on a saved token, no migration is required and you can simply pass the card tokens to Shuttle as per the previous section with the payment instruction.

When you are relying on a third party scheduler for recurring payments, you cannot use Shuttle to manage the schedule for you - as Shuttle runs its own scheduler so that schedules on any gateway will operate in a consistent fashion. To use Shuttle, you will need to cancel recurring schedules in whatever platform you use to run them and set them up in Shuttle via the payment API.

Alternatively you could run NEW schedules through Shuttle and let the existing schedules continue to run through your existing platform, however please note, in this case payments run by the third party system wont reflect in Shuttle.

Want to print your doc?
This is not the way.

Try clicking the ⋯ next to your doc name or using a keyboard shortcut (

CtrlP

) instead.