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.
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",
"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" }'
The metadata object can be used to associate arbitrary data with the token. The metadata field is optional in the request body.
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"
}
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. |
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" \
Note that a DELETE request does not return a response body. Use the HTTP status code to determine the result of the operation.
Token revocation is irrevocable. If a token is deleted in error, a new token must be created to re-tokenize the card details.
Sandbox Testing
Simulated responses for each token management operation can be generated by initiating requests to the API using a Test Client. To retrieve simulated tokens, use an externalReference value of Stitch. Any other reference will return an empty array.