Initiating Transactions

Once a consent has been successfully granted, payments may be initiated using the consent token. This will capture funds via the user's authorized Capitec Pay method, assuming initiation is within bounds of the granted consent.

Initiating a Transaction

The initiateTransaction API mutation requires a client token with the scope transaction_initiate. A valid ID is required, and the Payment Consent Request must be in a GRANTED state.

Transaction Status

A typical initiateTransaction API for a Capitec Pay recurring consent will return a TransactionPending status, with the final success or failure status to follow by webhook. However, there are some scenarios in which a transaction initiation could fail immediately.

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

An example 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.

Transaction Statuses

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

Status	Description
TransactionPending	Capitec has accepted and is processing the transaction. This status is returned by the Stitch API after initiating a transaction.
TransactionSuccess	The transaction has been successfully completed, and customer's account has been charged.
TransactionFailure	The transaction failed to be charged on the customer's account. 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.

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=",
      "last4": "1111",
      "network": "Visa"
    },
    "createdAt": "2023-05-10T12:22:42.865Z",
    "externalReference": "79261d16-c53b-48eb-9019-dc9cfb6c5126",
    "id": "Y2FyZHRyYW5zYWN0aW9uLzQwNDMxRTY5LTNERjctNEIyQS1CNDY0LURFNTQwNDc0QkMxQw==",
    "originalAmount": {
      "currency": "ZAR",
      "quantity": "1"
    },
    "originalTransactionId": "GBFyZHRyYW5zYWN0aW9uLzQwNDMxRTY5LTNERjctNEIyQS1CNDY0LURFNTQwNDc0QkMxQw",
    "paymentConsentRequestId": "FRFyZHRyYW5zYWN0aW9uLzQwNDMxRTY5LTNERjctNEIyQS1CNDY0LURFNTQwNDc0QkMxQw==",
    "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"
}

Testing and Simulation

When using a test client, transaction initiation scenarios can be simulated by configuring the beneficiaryReference field when initiating the transaction. The state returned by the Stitch API is TransactionPending, with the final transaction success or failure state sent by webhook. However, there are some scenarios in which a transaction could fail immediately.

Transaction failure reasons can be simulated by modifying the beneficiaryReference field, and setting it to the corresponding reason.

beneficiaryReference input value	Result state.__typename	Result state.reason
capitecClientDeactivated	TransactionFailed	capitecClientDeactivated
capitecClientBlockedMerchant	TransactionFailed	capitecClientBlockedMerchant
capitecTransactionLimitExceeded	TransactionFailed	capitecTransactionLimitExceeded
capitecConsentRevoked	TransactionFailed	capitecConsentRevoked
capitecInvalidAmount	TransactionFailed	capitecInvalidAmount
capitecConsentInvalid	TransactionFailed	capitecConsentInvalid
capitecInsufficientFunds	TransactionFailed	capitecInsufficientFunds
capitecPaymentBeforeFirstPaymentDate	TransactionFailed	capitecPaymentBeforeFirstPaymentDate
capitecPaymentAlreadyPaidForSelectedInterval	TransactionFailed	capitecPaymentAlreadyPaidForSelectedInterval
internalServerError	TransactionFailed	internalServerError