Charging a Consent

Once a consent has been successfully granted, it can be charged by initiating a transaction 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.

There are a few limitations on charges for a Capitec Variable Once-Off Consent:

• All charges must be made within 24 hours of consent approval.
• All charges must be less than or equal to the total amount, as specified in paymentOptions.variable.max.
• A maximum of 3 successful charges can be made on a variable once-off consent.

Initiating a Transaction

The initiateTransaction API mutation requires a client token with the scope transaction_initiate. A valid consent request ID is required, and this consent request must be in a PaymentConsentGranted state.

Transaction Status

A typical initiateTransaction API request for a Capitec Pay variable once-off 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 user's account has been charged.
TransactionFailure	The transaction failed to be charged on the user'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": {
      "bin": "41111111",
      "cardHolderName": "Joe Soap",
      "expiryMonth": 12,
      "expiryYear": 2024,
      "first6": "41111111",
      "id": "Y2FyZC85YWY4OGE4MS05ZjNhLTRlNDItYWRiYy04ZTA1M2Q1YTM3M2U=",
      "issuer": {
        "name": "capitec",
        "country": "ZA"
      },
      "last4": "1111",
      "maskedPan": "411111******1111",
      "network": "Visa",
      "type": "Credit"
    },
    "createdAt": "2023-05-10T12:22:42.865Z",
    "eci": "05",
    "externalReference": "79261d16-c53b-48eb-9019-dc9cfb6c5126",
    "id": "Y2FyZHRyYW5zYWN0aW9uLzQwNDMxRTY5LTNERjctNEIyQS1CNDY0LURFNTQwNDc0QkMxQw==",
    "nonce": "abb1c3b7-b39b-4a4c-93cb-3bbb363a3171",
    "originalAmount": {
      "currency": "ZAR",
      "quantity": "1"
    },
    "paymentRequestId": "RRFyZHRyYW5zYWN0aW9uLzQwNDMxRTY5LTNERjctNEIyQS1CNDY0LURFNTQwNDc0QkMxQw==",
    "retrievalReferenceNumber": "508714102541",
    "secure3dDecision": "skip",
    "secure3dDecisionReason": "clientSpecified",
    "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
internalServerError	TransactionFailed	internalServerError