Initiating Transactions with Consent Tokens

Following the creation of consent tokens, it is seamless to initiate card transactions over the Stitch API. For any transactions that require 3DS to be completed, you will receive an interaction URL to redirect the user to, for this step. Upon successful completion of the transaction initiation, the user's card will have been charged.

info

Transactions can only be initiated using consent tokens that are in the PaymentConsentGranted state. Attempting to initiate a transaction on a consent with any other status will result in an API error being returned.

Initiating a Transaction

The initiateTransaction API call requires a client token with the scope transaction_initiate.

The GraphQL API URL https://api.stitch.money/graphql should be used for this API query (whether on test or live clients). A typical initiateTransaction API call is shown below:

API Input Fields

• The externalReference field (4096-character limit) field may be used to associate the transaction to your payment/order's reference.
• The nonce field (4096-character limit) is required to be unique per request, and hence, transaction.
• The token field should contain the previously granted consent request id value, representing the card that is being charged.

3DS verification can be enabled or disabled on a specific transaction by setting the paymentMethods.card.requireSecure3d field with a boolean value. This specification overrides the dynamic 3DS rule result for the transaction. Use of this field requires client configuration.

After initiating a transaction, one of two scenarios typically occur:

• If 3DS is not required, transaction initiation is immediately successful. 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 transaction status will be pending, and you will need to redirect the user to complete this step.

Handle Interaction URL

If an interactionUrl is returned as part of 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://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 transaction id as a query parameter. You will also receive a corresponding webhook to confirm the status of the transaction.

Transaction Statuses

The table below describes the different statuses a transaction can have:

Status	Description
TransactionPending	The transaction has been initiated, but an interaction is required for the transaction to be successfully completed. An associated reason will be returned with this status.
TransactionSuccess	The transaction has been successfully completed, and user's card has been charged. If 3DS is disabled, or not required for the transaction, this will be returned immediately on successful intiation.
TransactionFailure	The transaction failed to be charged on the user's card. An associated reason will be returned with this status.

Subscribe to Webhooks

Webhooks for transactions can be subscribed to by running the clientWebhookAdd mutation, to receive transaction 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 transaction webhook will be dispatched for each of the following status updates:

• TransactionSuccess
• TransactionFailure

Example Payload

{
  "data": {
    "amount": {
      "currency": "ZAR",
      "quantity": "1"
    },
    "card": {
      "cardHolderName": "Joe Soap",
      "expiryMonth": 12,
      "expiryYear": 2024,
      "first6": "41111111",
      "id": "Y2FyZC85YWY4OGE4MS05ZjNhLTRlNDItYWRiYy04ZTA1M2Q1YTM3M2U=",
      "issuer": {
        "name": "capitec",
        "country": "ZA"
      },
      "last4": "1111",
      "network": "Visa",
      "type": "credit"
    },
    "createdAt": "2023-05-10T12:22:42.865Z",
    "externalReference": "79261d16-c53b-48eb-9019-dc9cfb6c5126",
    "id": "Y2FyZHRyYW5zYWN0aW9uLzQwNDMxRTY5LTNERjctNEIyQS1CNDY0LURFNTQwNDc0QkMxQw==",
    "originalAmount": {
      "currency": "ZAR",
      "quantity": "1"
    },
    "paymentRequestId": "RRFyZHRyYW5zYWN0aW9uLzQwNDMxRTY5LTNERjctNEIyQS1CNDY0LURFNTQwNDc0QkMxQw==",
    "status": "success",
    "statusReason": null,
    "type": "card",
    "updatedAt": "2023-05-10T12:22:42.865Z"
  },
  "datetime": "2023-05-10T12:22:42.865Z",
  "id": "transaction:status:success:40431E69-3DF7-4B2A-B464-DE540474BC1C",
  "type": "transaction"
}

Querying Transaction Status

You can check any transaction's status, as well as other corresponding details, with a query to the GraphQL API. An example query is shown below: