Purchase Flow

This flow allows a user to choose a payment method in the context of a purchase. It starts with a check for a signed TOS and, if necessary, presents the user with a TOS screen before allowing them to proceed. The user may choose an existing payment method if they have one, or create a new payment method and then select it.

Upon completion, this flow returns the following values:

Value	Description
`id`	The payment method ID, which may be used in creating an invoice.
`psp_reference`	A reference ID for the payment method from the payment service provider (PSP).
`pm_state`	The state of the payment method. One of: `ACTIVE`, `INACTIVE`, or `UNVERIFIED`. Payment methods must have a state of `ACTIVE` to be used in processing transactions.

attention

This flow does not, by itself, complete a purchase. It simply provides a UI for the user to select (or add) payment methods for use in a purchase transaction. Refer to our Developer Guides for information on processing transactions.

Widget flow

Copy

Copied

window.Tilia.execute({
    rootId: < your.element.id > ,
    flow: purchase,
    redirect: < redirect > ,
    onComplete: handleComplete,
    onError: handleError,
});

Restricting Payment Method Types

Payment methods have a maximum value for which they can be used. By default, credit cards can only be used for payments up to $10,000. In the case that a user tries to pay for an invoice larger than the allowable amount, the payment will fail.

For an improved user experience, you can optionally pass us the flowConfig with transactionDetail values (transaction_amount and currency). If the value exceeds the allowable amount for a payment method type, the widget will filter out any saved payments of that type as well as the buttons to add additional payment methods of that type (like the “Add Card” button).

Copy

Copied

window.Tilia.execute({
    rootId: < your.element.id > ,
    flow: purchase,
    flowConfig: {
        "transactionDetails": {
            "transaction_amount": "10000",
            "currency": "USD"
        }
    },
    redirect: < redirect > ,
    onComplete: handleComplete,
    onError: handleError,
});

onComplete

The handleComplete callback will be invoked by the widget with the result of the flow.

If the user cancels anywhere in the flow:

Copy

Copied

{
    source: “tilia”,
    event: “tilia.pm.complete”,
    state: “cancel”,
}

If the user completes the flow:

Copy

Copied

{
    source: “tilia”,
    event: “tilia.pm.complete”,
    id: < payment.method.id > ,
    psp_reference: < psp.reference > ,
    pm_state: < payment.method.state >
}

The appearance of the purchase widget can be customized. Refer to Widget Customization for details.

Redirect flow

Copy

Copied

<a href=”<redirectUrl>?flow=purchase&returnurl=<your.return.url>”>Choose payment method</a>

Upon completion, the user is routed to your redirect URL, which has the following query string parameters added:

If the user cancels anywhere in the flow: state=cancel
If the user completes the flow:
- state=complete
- id=<payment.method.id>
- psp_reference=<psp.reference>
- pm_state=<payment.method.state>