Process flow

Shuttle provides four actions for managing payment links:

• Create a new payment link
• Get a payment link
• Update an existing payment link
• Delete a payment link

And generates the following notifications:

• PAYMENT_LINK.CREATED - Payment link has been created
• PAYMENT_LINK.UPDATE - Payment link details have been updated
• PAYMENT_LINK.PENDING - Payment submitted, however awaiting authorisation
• PAYMENT_LINK.FAILED - Payment was declined, after previously being pending
• PAYMENT_LINK.COMPLETE - Payment successful
• PAYMENT_LINK.EXPIRED - Payment link expired
• PAYMENT_LINK.ARCHIVE - Payment link archived (ie deleted)

Typical process flow

Typically you will want to implement the following:

1. On your desired trigger, “Create a payment link”, putting an id for your workflow in a state field

2. If you care about payment events, handle the following webhooks, filtering on state for your workflow id, where action equals:

   • PAYMENT_LINK.COMPLETE: to recognise the payment has been completed, eg place order
   • PAYMENT_LINK.PENDING: to recognise the payment is underway, eg reserve stock
   • PAYMENT_LINK.FAILED: to recognise the payment has been declined AFTER the customer has left the payment page (ie after a payment was previously pending), eg release stock, or send them a new payment link
   • PAYMENT_LINK.EXPIRED: to recognise the payment link has expired, eg send them a new payment link

   On receiving a webhook, and filtering by state and action, retrieve the payment link using “Get a payment link”.

Tip! Shuttle’s workflow automation integrations present state as nine separate values, as below. If you use both the API and workflow automation, use the same format for compatibility:

payment_link = {
    "id": "pl_1234_567890",
    "url": "https://app.shuttleglobal.com/cp/links/pl_1234_567890",
    "options": {},
    "state": {
        "state1": "INVOICE_PAYMENT",
        "state2": "",
        "state3": "",
        "state4": "",
        "state5": "",
        "state6": "",
        "state7": "",
        "state8": "",
        "state9": ""
    }
}

webhook = {
    "action": "PAYMENT_LINK.COMPLETE",
    "payment_link": "pl_1234_567890",
    "contract": "co_1234_10151",
    "transaction": "tr_1234_10150",
    "payment_method": "pm_1234_10141",
    "state": {
        "state1": "INVOICE_PAYMENT",
        "state2": "",
        "state3": "",
        "state4": "",
        "state5": "",
        "state6": "",
        "state7": "",
        "state8": "",
        "state9": ""
    },
    ...
}