Integrating Once-off Card 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.

For any transactions that require 3DS to be completed, you will receive an interaction URL to redirect the user to. Upon successful completion of the transaction initiation, the user's card will have been charged.

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 invoke the transaction initiation call (detailed in the next section).

Initiating a Transaction

On receiving the corresponding card details from the SDK, these should be passed back to Stitch within the initiateTransaction API call. This requires a client token with the scope transaction_initiate.

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 query 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.
All relevant card details are specified within the paymentMethods.card.cardDetails object. The encryptedPan and encryptedSecurityCode are collected from the Secure Fields SDK.
The cardUsageType of the card details must be specified as onceOff.

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://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.

Parameter	Description
`transactionId`	The payment's Stitch ID
`flow`	The 3DS interaction type i.e. `challenge` or `frictionless`
`externalReference`	The payment's external reference
`status`	The payment's final status i.e. `TransactionSuccess` or `TransactionFailure`
`statusReason`	The optional reason for the payment's status

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.

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": {
      "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==",
    "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"
}

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:

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.

Scenario	Card Number
3DS successful and payment completed	`4032035421088592`
Transaction fails during 3DS verification	`4018884230103383`, `4004462059871392`
Transaction fails during payment authorization	`4009546746099840`, `4032033425469975`

Capturing Secure Fields​

Initiating a Transaction​

Handle Interaction URL​

Transaction Statuses​

Subscribe to Webhooks​

Webhook Statuses​

Querying Transaction Status​

Test Card Numbers​