Skip to main content

Integrating Consent Tokens with Secure Fields

Once-off Card payments may be initiated over the Stitch API, using card detail inputs captured using Stitch Secure Fields. This method allows for you to render card input fields directly on your checkout page, still being able to customize your user experience, without the need for PCI-DSS compliance.

Should 3DS completion be required, you will receive an interaction URL to redirect the user to.

Capturing Secure Fields​

To securely capture card details, the Stitch Secure Fields SDK should be integrated within the checkout page on your client-side. The full integration of the SDK is described in more detail here.

At a high-level, the <StitchSecureForm> contains <StitchSecureField> elements - These are the respective card fields the user will populate. On completion of the form, all card details, including encrypted values (number and cvc) will be returned. These should be passed through to your server-side, to confirm against the consent request (detailed in the next section).

To create a consent token using captured card details from the Secure Fields SDK, two API calls are required:

  1. Create the consent, to initialize the consent token that will be used for subsequent payments.
  2. Confirm the consent using the card details provided from the Secure Fields, in order to have the consent granted. Should 3DS be required, an interaction URL will be included in the response.

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 an id in the response. This is the unique consent token that is used to later initiate transactions on the corresponding card.

The paymentConsentRequestConfirm 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 transaction initiation requests (for both test and live clients).

An example of the consent confirmation query is shown below:

API Input Fields
  • The consentRequestId field should contain the returned id from the consent creation.
  • The nonce field (4096-character limit) is required to be unique per request, and hence, transaction.
  • The externalReference field (4096-character limit) field may be used to associate the transaction to your payment/order's reference.
  • All relevant card details are specified within the card.cardDetails object. The encryptedPan and encryptedSecurityCode are collected from the Secure Fields SDK.
  • The cardUsageType of the card details must be specified as clientReturning.

After confirming a consent request, one of two scenarios typically occur:

  • If 3DS is not required, consent will be granted. The returned status in the response will indicate this, and a corresponding webhook will be sent.
  • Alternatively, if 3DS verification is required by the user, the consent request will still be pending, and you will need to redirect the user to complete this step.

Handle Interaction URL​

You will notice that the response of the consent confirmation API call contains an authorizationTransaction within the consentDetails. If an interactionUrl is returned as part of the authorizationTransaction in the response, the user must visit this URL, after appending a redirect_uri query parameter. This will guide the user through the required 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://3ds.stitch.money/2ce31de7-a30d-4f3b-bfaa-cd06cb30db79?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 and the payment has been processed, they will be redirected back to your specified redirect_uri with the following query parameters.

ParameterDescription
transactionIdThe payment's Stitch ID
flowThe 3DS interaction type i.e. challenge or frictionless
externalReferenceThe payment's external reference
statusThe payment's final status i.e. TransactionSuccess or TransactionFailure
statusReasonThe optional reason for the payment's status

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 confirmation request must be made on the consent, or the user must be directed to the required 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": {
      "bin": "555550",
      "cardHolderName": "Joe Soap",
      "expiryMonth": 12,
      "expiryYear": 25,
      "first6": "555550",
      "id": "Y2FyZC85YWY4OGE4MS05ZjNhLTRlNDItYWRiYy04ZTA1M2Q1YTM3M2U=",
      "issuer": {
        "name": "capitec",
        "country": "ZA
      }
      "last4": "0331",
      "maskedPan": "555550******0331",
      "network": "Mastercard",
      "type": "Credit"
    },
    "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 will 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