Tokens

Vault allows clients to tokenize card funding details and perform token management. The token is a unique reference to the stored credentials that can be used for credential retrieval and payment initiation.

Integration Overview

Vault is protected by a client token. You'll need to follow the steps described in the client token guide to obtain a client token with the client_vault_manage scope.

The Stitch REST API URL https://api.stitch.money/v2/tokens can be used for all tokenization requests.

Token Creation

The initial step involves creating a token in Vault. The returned token serves as a unique reference to the stored card and includes additional metadata such as BIN, last four digits, expiry, and issuer information.

To collect sensitive card details while maintaining PCI compliance, you can use the Secure Fields SDK. Secure Fields offers customizable input components that can be embedded in your UI to securely capture and encrypt card details, without exposing raw data to your systems.

Token Types

Vault currently only supports the creation of card tokens that reference stored PAN data.

Initiate a POST request to create a token with the following request body:

curl -X POST 'https://api.stitch.money/v2/tokens' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
        "type": "card",
        "card": {
          "number": "ev:QkTC:isEzOI93mYXVqlGB:A6SJIP5XrD8t/lLWRA70oTY2HFNHBVV3ZSZ3s1Fm+/cy:oDJ/pltqoXV9J0F6L9nSdjO7/tuIZMlzKoSBrOE9Fnq7qXZfcVZKmfewOHiqBzY:$",
          "securityCode": "ev:QkTC:dS6lP/MgJpKMpWQp:A6SJIP5XrD8t/lLWRA70oTY2HFNHBVV3ZSZ3s1Fm+/cy:8MHtJD9ctDVZWBo85DssJjUTKpTsgZm7YG6zPu8U+uTOlQ:$",
          "expiry": {
              "month": "02",
              "year": "29"
          }
        },
        "metadata": {
          "cardholderName": "Test User",
          "providers": [
            "name": "PSP",
            "token": "psp-token-123"
          ]
        },
        "externalReference": "user-123"
      }'

Field	Type	Description
`card.number`	`string`	The encrypted card number collected using the Secure Fields SDK.
`securityCode`	`string` (optional)	The encrypted security code (CVV/CVC) collected using the Secure Fields SDK. The security code is stored for 1 hour, after which it will be automatically removed and will need to be recollected.
`card.expiry.month`	`string`	The card expiry month in MM format (01-12).
`card.expiry.year`	`string`	The card expiry year in YY format (e.g., 25 for 2025).
`metadata`	`string` (optional)	Arbitrary key-value pairs that can be stored along with the token. Useful for adding custom information.
`externalReference`	`string` (optional)	A custom unique identifier associated with the token (e.g., an identifier used by the client to reference the card).

Stitch tokenizes and securely stores the card details in Vault, and returns metadata associated with the card. The response includes the token id, the card's BIN, the last 4 digits of the PAN, expiry details, and issuer information.

{
  "id": "dG9rZW4vMTQ0NjZlYjAtMjlhMi00ZDM3LWIyYjctNTZkMWFkNWIxZWIw",
  "card": {
      "bin": "42424242",
      "last4": "4242",
      "expiry": {
        "month": "02",
        "year": "29"
      },
      "network": "visa",
      "fundingType": "debit",
      "issuer": {
        "name": "fnb",
        "country": "za"
      }
  },
  "metadata": {
      "cardholderName": "Test User",
      "providers": [
        "name": "PSP",
        "token": "psp-token-123"
      ]
  },
  "externalReference": "user-123"
}

Field	Type	Description
`card.bin`	`string`	The first 8 digits of the card number.
`card.last4`	`string`	The encrypted security code (CVV/CVC) collected using the Secure Fields SDK. The security code is stored for 1 hour, after which it will be automatically removed and will need to be recollected.
`card.expiry.month`	`string`	The card expiry month in MM format (01-12).
`card.expiry.year`	`string`	The card expiry year in YY format (e.g., 25 for 2025).
`card.network`	`string` (optional)	The card network. Possible values: `⁠visa`, `⁠mastercard`, `⁠amex`, or ⁠`diners`. `⁠null` if the network cannot be identified.
`card.fundingType`	`string` (optional)	The funding type of the card which specifies how transactions are financed. Possible values: `⁠credit`, `⁠debit`, or ⁠`prepaid`. ⁠null if the funding type cannot be identified.
`card.issuer.name`	`string` (optional)	The name of the financial institution that issued the card. `⁠null` if the issuer name cannot be identified.
`card.issuer.country`	`string` (optional)	The country code (ISO 3166-1 alpha-2) of the card issuer. `⁠null` if the issuer country cannot be identified.
`metadata`	`string` (optional)	Arbitrary key-value pairs that can be stored along with the token. Useful for adding custom information.
`externalReference`	`string` (optional)	A custom unique identifier associated with the token (e.g., an identifier used by the client to reference the card).

If token creation fails, Stitch returns an error response in the following format:

{
  "title": "Internal Server Error",
  "code": "INTERNAL_SERVER_ERROR",
  "detail": "Token creation failed"
}

Token Retrieval

Initiate a GET request to retrieve a specific stored token by ID:

curl -X GET 'https://api.stitch.money/v2/tokens/Y2FyZC8xNDQ2NmViMC0yOWEyLTRkMzctYjJiNy01NmQxYWQ1YjFlYjA=' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \

The response object is identical in structure to the one returned by the POST request used to create a token.

{
  "id": "dG9rZW4vMTQ0NjZlYjAtMjlhMi00ZDM3LWIyYjctNTZkMWFkNWIxZWIw",
  "card": {
      "bin": "42424242",
      "last4": "4242",
      "expiry": {
        "month": "02",
        "year": "29"
      },
      "network": "visa",
      "fundingType": "debit",
      "issuer": {
        "name": "fnb",
        "country": "za"
      }
  },
  "metadata": {
      "cardholderName": "Test User",
      "providers": [
        "name": "PSP",
        "token": "psp-token-123"
      ]
  },
  "externalReference": "user-123"
}

You can list multiple stored tokens and filter the results using query parameters, such as externalReference:

curl -X GET 'https://api.stitch.money/v2/tokens?externalReference=user-123' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \

The response includes a data field containing an array of token objects that match the specified filters.

{
  "data": [
    {
      "id": "dG9rZW4vMTQ0NjZlYjAtMjlhMi00ZDM3LWIyYjctNTZkMWFkNWIxZWIw",
      "card": {
          "bin": "42424242",
          "last4": "4242",
          "expiry": {
            "month": "02",
            "year": "29"
          },
          "network": "visa",
          "fundingType": "debit",
          "issuer": {
            "name": "fnb",
            "country": "za"
          }
      },
      "metadata": {
          "cardholderName": "Test User",
          "providers": [
            "name": "PSP",
            "token": "psp-token-123"
          ]
      },
      "externalReference": "user-123"
    },
    {
      "id": "dG9rZW4vMWU0OWQ0MmItMmQ2ZS00ZGZmLWFlMjYtYWVjYTc1NTdhNTc0",
      "card": {
          "bin": "41111111",
          "last4": "1111",
          "expiry": {
            "month": "06",
            "year": "27"
          },
          "network": "visa",
          "fundingType": "credit",
          "issuer": {
            "name": "absa",
            "country": "za"
          }
      },
      "metadata": {
          "cardholderName": "Test User",
          "providers": [
            "name": "PSP",
            "token": "psp-token-456"
          ]
      },
      "externalReference": "user-123"
    }
  ]
}

Token retrieval is paginated and supports the offset and limit query parameters to control result size and pagination. The default page size is 2000. A paginated query example is indicated below:

curl -X GET 'https://api.stitch.money/v2/tokens?limit=50?offset=100' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \

Query Parameters

Parameter	Description
`offset`	The number of records to skip before starting to return results. Used for pagination.
`limit`	The maximum number of records to return in the response. Used to control page size.
`externalReference`	A unique identifier provided by the client to reference or filter specific records.

Query Paging

The default page size is 2000. Use the limit field to reduce the number of records returned in a single response.

Token Revocation

Initiate a DELETE request to delete a stored token by ID:

curl -X DELETE 'https://api.stitch.money/v2/tokens/Y2FyZC8xNDQ2NmViMC0yOWEyLTRkMzctYjJiNy01NmQxYWQ1YjFlYjA=' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \

Response Handling

Note that a DELETE request does not return a response body. Use the HTTP status code to determine the result of the operation.

Deletion

Token revocation is irrevocable. If a token is deleted in error, a new token must be created to re-tokenize the card details.

Integration Overview​

Token Creation​

Token Retrieval​

Token Revocation​

Integration Overview

Token Creation

Token Retrieval

Token Revocation