Skip to main content

Integrating Once-off Card via Secure API

Once-off Card payments are easily initiated with the Stitch Secure API. This method allows for raw card details to be submitted securely to Stitch. 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.

Initiating a Transaction​

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

If card details are collected via the Secure Fields SDK, the GraphQL API URL must be set to https://api.stitch.money/graphql (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, 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:

StatusDescription
TransactionPendingThe 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.
TransactionSuccessThe 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.
TransactionFailureThe 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:

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