Skip to main content

Consent via Secure API


Because this model requires sensitive details to be passed to Stitch via API, the calling client will need to be PCI-compliant.


  1. Initiate a consent request.
  2. Grant the consent request by providing the full card details via API. This may involve a 3DS interaction.
  3. Receive a consent webhook.

The ID of this consent request is the card token. At this point in the flow the consent request will be in a PENDING state. The token may only be used for payments once the consent request is in a GRANTED state.

While the Hosted UI flow provides an interface for the user to input their card details to Stitch, this flow allows the client to securely provide card details to Stitch, via the API.


Calling this API will initiate a R1 authorization transaction on the user's card. This will subsequently be voided, and users will not be charged for these payments.

If the user is required to complete 3D-secure as part of the authorization for consent, this is done within this step.

The response to this call will contain 2 important pieces of information:

  1. Consent request status: If this is GRANTED, this flow is complete, and the consent request ID may be used to initiate payments.
  2. Authorization transaction: This includes details of the underlying authorization transaction, as well as its status, which may be PENDING, SUCCESS or FAILURE.

The status of the consent request is available at status.__typename.

If the consent state is GRANTED, this flow is complete, and the consent request ID may be used to initiate a payment.

If the consent state is PENDING, the token is not yet ready for use and more interactions may be required. Please see the underlying transaction state (consentDetails.authorizationTransaction.state.__typename) for more information.

Transaction state is 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. Most commonly, this reason will be waitingFor3dSecure.

In this case, the user must visit the interactionUrl found on the authorizationTransaction response. This URL will guide the user through the 3D-secure flow, and a consent webhook will be sent on completion. Please see the webhooks documention for subscribing to these events.


This interaction flow will not collect any card details. This page is minimal, and will only complete the required interaction.

Transaction state is 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.