Initiating payments

Payments may be initiated at any time, as long as the PaymentConsentRequest is in a GRANTED state. The only required inputs are the ID of the consent request as the token, a nonce to enforce uniqueness and an amount.

Build and surface interaction URL

If an interactionUrl is returned as part of the response, the user must visit this URL, after appending a redirect_uri. This URL will guide the user through the interaction, after which the transaction will resume. On completion, a transaction webhook will be sent.

The building of this redirect_uri parameter follows the same process used when building a consent request URL.

For example, if you choose to redirect your user to the whitelisted URL https://example.com/payment, you'd append the following additional query string to the url returned from the API: &redirect_uri=https%3A%2F%2Fexample.com%2Fpayment. The full URL you would expose to the user should look similar to the following:

https://secure.stitch.money/v2/interaction/card/interaction?transactionId=2ce31de7-a30d-4f3b-bfaa-cd06cb30db79&redirect_uri=https%3A%2F%2Fexample.payment

Handling transaction states

The status of the transaction is available at state.__typename.

PENDING

Transactions wait in a PENDING state if a user interaction is required. More detail about this interaction can be accessed via the reason property. For card payments, this will be 3D-secure interaction. Note that 3D-secure is typically disabled for recurring payments.

In this case, the user must visit the interactionUrl, as described above, before the transaction status may be updated.

FAILURE

There are many ways for a transaction to fail, most commonly relating to the issuer rejecting the authorization. More detail about the failure reason can be accessed via the reason property.

SUCCESS

The transaction has cleared successfully. No additional steps are required.