Skip to main content

Integrating Consent Tokens with Stitch-Hosted UI

Consent tokens can be created easily via the Stitch API. The Stitch-Hosted UI simplifies your overall integration process by handling the secure capturing of card details and 3DS verification by the user, once they are redirected to the given URL.

The paymentConsentRequestCreate API call requires a client token with the scope client_recurringpaymentconsentrequest.

The GraphQL API URL https://api.stitch.money/graphql can be used for all consent requests (whether on test or live clients),

Note that a consent request may be initiated together with, or without, an initial charge. Including an initial charge means the user will be charged the given amount together with granting consent for subsequent payments to be made on their card.

Examples of creating a consent with and without an initial charge are shown below:

API Input Fields
  • The nonce field (4096-character limit) is required to be unique per request, and hence, consent request.

After creating a consent request, you will receive the following return values relevant to the consent:

  • id: This is the unique consent token that is used to later initiate transactions on the corresponding card.
  • url: This is the redirection URL that the user should be redirected to, which surfaces the Stitch-Hosted UI to the user.

Handle Interaction URL​

After creation of a consent request, the user must be redirected to the given url, after appending a redirect_uri query parameter. This will guide the user through the required consent granting and 3DS interaction.

As an 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?transactionId=2ce31de7-a30d-4f3b-bfaa-cd06cb30db79&clientId=test-c8cb5f28-ddfa-4f3b-bcff-3213ee30b97f&redirect_uri=https%3A%2F%2Fexample.payment
danger

The URL specified as the redirect_uri must be secure i.e. an HTTPS URL.

Once the user has successfully completed the interaction, they will be redirected back to your specified redirect_uri, together with the consent id as a query parameter. You will also receive a corresponding webhook to confirm the status of the consent request (as well as for the transaction, if an initial charge was included).

The table below describes the different statuses a consent request may have.

StatusDescription
PaymentConsentPendingThe consent request has been created, and is yet to be granted by the user. The user must be directed to the interaction URL to proceed.
PaymentConsentProcessingThe consent request has moved from pending and is currently being processed.
PaymentConsentGrantedThe consent has been granted by the user, and the consent token may now be used to initiate transactions.
PaymentConsentFailedThe consent failed to be granted successfully by the user. An associated reason will be returned with this status.
PaymentConsentCancelledThe consent granting was cancelled. An associated reason will be returned with this status.
PaymentConsentExpiredThe consent request was not granted by the user, by the time of expiry.
PaymentConsentRevokedThe consent was previously granted, but has been revoked for the card. This token can no longer be used to initiate transactions.

Subscribe to Webhooks​

Webhooks for consent requests can be subscribed to by running the clientWebhookAdd mutation, to receive payment-consent-request webhook events.

If the subscription is successfully created, the body returned by the request will look similar to the sample in the Example Response tab in widget above.

For more information on receiving webhook events, listing active webhook subscriptions, unsubscribing from webhooks and validating signed webhook subscriptions, please visit the Webhooks page.

Webhook Statuses​

The payment-consent-request webhook will be dispatched for each of the following status updates:

  • PaymentConsentProcessing
  • PaymentConsentFailed
  • PaymentConsentGranted
  • PaymentConsentCancelled
  • PaymentConsentExpired
  • PaymentConsentRevoked
Example Card Payload
{
  "data": {
    "card": {
      "cardHolderName": "Joe Soap",
      "expiryMonth": 12,
      "expiryYear": 25,
      "first6": "555550",
      "id": "Y2FyZC85YWY4OGE4MS05ZjNhLTRlNDItYWRiYy04ZTA1M2Q1YTM3M2U=",
      "last4": "0331",
      "network": "Mastercard"
    },
    "createdAt": "2023-06-11T11:52:49.230Z",
    "id": "cmVjdXJyaW5nUGF5bWVudENvbnNlbnRSZXF1ZXN0L2NiNmYyYmQ5LTVjODgtNDFmOS04MmE1LWE0NWEyNDYxMGJmNg==",
    "status": "GRANTED",
    "type": "CARD",
    "updatedAt": "2023-06-21T11:52:49.230Z"
  },
  "datetime": "2023-05-10T12:22:42.865Z",
  "id": "consent-request:status:success:cb6f2bd9-5c88-41f9-82a5-a45a24610bf6",
  "type": "consent-request-status"
}

Initial Charges on Consents​

If you create consent requests that include initial charges, corresponding transaction webhooks will be sent as well.

In the case that a consent request is successfully granted, you will receive a GRANTED consent request webhook, and a corresponding SUCCESS transaction webhook.

The consent request webhook will contain the corresponding authorization transaction ID. All transaction aspects (such as object structure, webhooks, status querying, etc.) follow identically to transactions initiated from consent tokens.

Handling Granted Consents​

Once a user has granted consent for you to process recurring transactions on a given card of theirs, the consent request be in a PaymentConsentGranted state. At this point, you may proceed to initiate transactions using the respective consent ID.

In the case that a user chooses to delete their saved card and consent from your platform, you should revoke the consent request, so that it is no longer possible to initiate transactions on the card.

Test Card Numbers​

Our sandbox environment allows simulating success and failure cases when initiating a card transaction, without requiring real debit or credit card details.

You may use the below card numbers on the card input screen to trigger the corresponding scenario.

tip

For all cards numbers, any future date for the expiry date (in the format MM/YY), as well as any 3-digit value for the CVC, will process as expected.

ScenarioCard Number
3DS successful and payment completed4032035421088592
Transaction fails during 3DS verification4018884230103383, 4004462059871392
Transaction fails during payment authorization4009546746099840, 4032033425469975