First Time and Returning User FlowsDeprecated

caution

This section includes information around Stitch products and features that are now deprecated. Deprecated aspects of Stitch's plaform are no longer being supported or improved upon.

If you are currently using a deprecated Stitch product, please consider upgrading to one of our newer and equivalent offerings.

First time and returning LinkPay users need to go through different flows in order to complete a payment request. For first time users, they'll need to link and authorize their account, which gives back a user and refresh token pair to the client. The user token can then be used to initiate subsequent payments by the same user from that account, while the refresh token can be used to get a new user token once the current token expires.

note

Each token is linked to the specific bank account the user authorized. This means the user can link multiple bank accounts, so the client needs to store each of these tokens (just the refresh token and token ID) and link them to the user and bank details on your end.

First Time User Flow

For first time users, they'll need to authorize and set up payments to a specific beneficiary. This process is initiated via a payment authorization request.

Once the authorization request has been completed, you can use the authorization code to obtain a user token by following the user authentication guide. This token can be used to initiate payments at any time, using the userInitiatePayment mutation on the Stitch API. If no user interaction is required, the payment will complete instantly.

However, if an interaction such as multifactor authentication is necessary, then the user may be presented with a web interface within your application, allowing them to complete the payment after supplying the required input.

caution

• We advise that you securely store only the refresh token and token ID from the user token response.
• The refresh token will only be returned if the offline_access scope is added to the list of scopes when requesting for the authorization code.

The basic flow for a first time user is as illustrated below. To edit the diagram for your illustration purposes, you can use this Mermaid Live Editor link to start off.

sequenceDiagram participant Client participant secure.stitch.money participant api.stitch.money/graphql Client->>secure.stitch.money: Request client token activate secure.stitch.money secure.stitch.money-->>Client: Client token deactivate secure.stitch.money Client->>api.stitch.money/graphql: Create authorization request for user activate api.stitch.money/graphql api.stitch.money/graphql-->>Client: Authorization request URL deactivate api.stitch.money/graphql Client->>secure.stitch.money: Redirect user to /connect/authorization/{requestId}?{authorizaton_code_flow_parameters} secure.stitch.money->>secure.stitch.money: User bank login secure.stitch.money->>secure.stitch.money: User add beneficiary secure.stitch.money-->> Client: Redirect with authorization code Client->>secure.stitch.money: Fetch user token using authorization code secure.stitch.money-->> Client: User token response Client->> Client: Store Refresh Token and Token ID <br />against the bank details and <br />the user's identifier on the client Client->>api.stitch.money/graphql: Use user token to verify KYC against linked account details api.stitch.money/graphql-->> Client: Linked account details alt Client-side KYC matches linked account's account holder details Client->>api.stitch.money/graphql: Initiate Payment with User Token opt User interaction required api.stitch.money/graphql-->>Client: User interaction response end opt Payment failure api.stitch.money/graphql-->>Client: Payment failure response end opt Payment success response api.stitch.money/graphql-->>Client: Payment success response end opt Query payment request status Client->>api.stitch.money/graphql: Use client token and payment request ID to query for payment request status api.stitch.money/graphql-->>Client: Payment request details end api.stitch.money/graphql->>Client: Incoming webhook event from payment request Client-->>api.stitch.money/graphql: Acknowledge receiving webhook event Client->>Client: Process webhook else Client->> Client: Display KYC mismatch end

Returning User Flow

Once they have one or more accounts linked, and the refresh token securely stored, returning users can easily initiate payment. The refresh token can also be used to automate user-not-present payments e.g. for recurring billing scenarios.

However, just like in the first time linking flow, sometimes user interaction will be required, such as multifactor authentication. Please refer to the user interaction required guide to learn more about the possible user interaction scenarios.

The basic flow for a returning user is as illustrated below. To edit the diagram for your illustration purposes, you can use this Mermaid Live Editor link to start off.

sequenceDiagram participant Client participant secure.stitch.money participant api.stitch.money/graphql Client->> Client: Check if user had <br /> previously linked an account alt User has no linked accounts Note over Client,api.stitch.money/graphql: Go through account linking flow and get a user token else Client->>Client: Fetch all user's linked accounts <br /> and allow the user to select <br /> an account to use in the transaction alt User wants to use an already linked account Client->>Client: Fetch refresh token linked to the <br /> selected account from DB Client->>secure.stitch.money: Use refresh token to get a user token secure.stitch.money-->> Client: User token response Client->> Client: Store new Refresh Token and Token ID else Note over Client,api.stitch.money/graphql: Go through first-time account linking flow and get a user token end end Client->>api.stitch.money/graphql: Initiate Payment with User Token opt User interaction required api.stitch.money/graphql-->>Client: User interaction response end opt Payment failure api.stitch.money/graphql-->>Client: Payment failure response end opt Payment success response api.stitch.money/graphql-->>Client: Payment success response end opt Query payment request status Client->>api.stitch.money/graphql: Use client token and payment request ID to query for payment request status api.stitch.money/graphql-->>Client: Payment request details end api.stitch.money/graphql->>Client: Incoming webhook event from payment request Client-->>api.stitch.money/graphql: Acknowledge receiving webhook event Client->>Client: Process webhook