> ## Documentation Index
> Fetch the complete documentation index at: https://docs.enfuce.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Initiate card data retrieval
> Endpoint to initiate retrieval of card data. This will enable the end user make e-commerce transactions without
needing access to a plastic card. This means that the end user will get access to card number (PAN), expiry
date and CVC2/CVV2. This operation will generate an access token used to view the card data, enabling end users
to access their card data through their own devices, via app or web interface.
Supporting the possibility to copy the card data to the devices clipboard should be examined with caution.
The data lifespan and the access to the device clipboards varies between operating systems which introduces
risk. So while recognising that the possibility to copy the card data can improve end-user experience,
the potential increased risk of such a feature should be considered.
### Process description
1. End user request to see the card data (Pan number, exp. date and CVV) through its own devices, via app or
web interface.
2. The end user request triggers a request to Enfuce Card API (/v4/card/{cardId}/controlToken)
* The request will fail if cardId is not valid.
* Besides cardId, no additional validation is done. This means that Enfuce will not validate open-to-buy,
card status or usage limiters of the card when responding to request. In order to validate if a purchase
can be done with card data in question, separate API calls should be done to retrieve real time status
of card and it´s balance.
3. The successful response from this endpoint returns a token and two URLs
* Note the token is valid for 30 seconds which is the deadline for the end user device to make
the POST call to retrieve the HTML snapshot
4. The end users device is instructed to access the returned URL to view the card data
* Mobile app retrieves the HTML snapshot with card data by executing a POST call to the cardDataUrl
with the content of the token in a form field named token.
* Desktop browser opens iframe to cardDataFrameUrl with query parameter _key_. Key needs to agreed with
Enfuce beforehand. After that is loaded, parent page makes window.postMessage() call to the iframe.
Posted message object contains field _operation_ with value _view-pan_ and field _token_. Example:
```javascript
iframe.addEventListener('load', () => {
iframe.contentWindow.postMessage({operation: 'view-pan', token}, cardDataFrameUrl);
})
```
5. Enfuce responds with a HTML snapshot containing the card data.
* The request will fail if the token is not valid.
6. End user sees card data on device and can utilise it to make a purchase.
### PCI and security considerations
The service is designed to avoid exposure of sensitive, PCI categorised data to the web/app back-end,
therefore the card data is sent directly from the service endpoint to the end users device. The functionality
is developed, assessed, and certified for PCI DSS. PCI DSS regulations are detailed, but highlighting
a few that have impact on the this functionality:
* Card data remains encrypted in transport.
* No card data is stored in the process.
* The software is code reviewed.
* The publicly exposed endpoint is protected by a web application firewall.
The end user device will not fall within PCI scope, as it will not have access, be connected to or be able
to impact Enfuce system where the card data resides. In other words, the device displaying the card data does
not access the data itself, rather the content is rendered inside browser widget (Webview or Iframe).
Enfuce recommendations for end user app development:
* The app and the related back-end should ensure that the user is strongly authenticated (SCA) before being
able to view the card data. It is recommended, that each view is preceded by an SCA event, and this should be
done for every view event.
* The app must show the card data for only the time needed for the user to use this data and it is recommended
that there is a timeout of 1 minute until the card holder data view is automatically closed for the user.
* The app developers need to take necessary precautions to stop other apps or processes to access or interact
with the card data view.
* The app developers need to ensure that the communication between the app and the related back-end is done
in an authenticated and encrypted session.
## OpenAPI
````yaml card post /v4/card/{cardId}/controlToken
openapi: 3.0.3
info:
description: >
Card API have different endpoints for creating, editing and updating a card
via different methods.
Below in the picture is the basic flow of a card lifecycle. Note we don't
restrict changes,
so it is possible although not advisable e.g. to change card status from
Card Lost to Card OK.
Below is a short summary of each status:
| Status name |
Description |
Authorisations rejected |
Clearing transactions posting blocked |
| Card OK |
Card is open and in normal status. Card has to be in this status in order for it to be renewed. |
No |
No |
| Card Blocked |
Temporary block on the card that will prevent approval of authorisations. Can be used instead of account level temporary block if target is to block only a specific card. |
Yes |
No |
| Suspected Fraud |
Temporary block on the card that will prevent approval of authorisations. Functionality the same as for "Card blocked", the different code allows to differentiate between the blocks. |
Yes |
No |
| Card No Renewal |
Status set to prevent following card renewal. Does not affect card functionality in any way, only renewal. |
No |
No |
| Card Closed Due To Fraud |
Used to close a card due to known fraud. |
Yes |
No |
| Card Lost |
Used to close a card because it is lost. |
Yes |
No |
| Card Stolen |
Used to close a card because it is stolen. |
Yes |
No |
| Card Closed |
Used to close card by request from customer or bank, reason for closure is set with status update reason. Allows still clearing transaction posting. |
Yes |
No |
### Encrypted payload for _Create card_ or _Get card_ with a full card
number
The payload field _encryptedData_ in create card requests is encrypted with
JWE (JSON Web Encryption).
The field value must be presented using compact serialization scheme, i.e.
Base64URL-encoded elements
separated by a ".".
JWE should use RSA-OAEP-256 algorithm for encrypting the random symmetric
key and A256GCM algorithm for
encrypting the payload. Public keys used for encryption are provided in
certificates below.
JWE header must also contain parameter "x5t#S256" with SHA256 fingerprint of
the certificate used.
See RFC7516 section 4.1.10.
The payload to be encrypted must be in JSON-format and contain field
"cardNumber". For example:
{ "cardNumber": "5555555555554444" }
Certificate for test environments (jwe-test-20260422.pem):
-----BEGIN CERTIFICATE-----
MIIDsTCCApmgAwIBAgIUNbIeMweA9gtL+71Uoctyok+LP5owDQYJKoZIhvcNAQEL
BQAwaDELMAkGA1UEBhMCRkkxDjAMBgNVBAcMBUVzcG9vMQ8wDQYDVQQKDAZFbmZ1
Y2UxETAPBgNVBAsMCENhcmQgQVBJMSUwIwYDVQQDDBxqd2UtdGVzdC0yMDI2MDQy
Mi5lbmZ1Y2UuY29tMB4XDTI2MDQyMjA4MTQ1MVoXDTI4MDQxMTA4MTQ1MVowaDEL
MAkGA1UEBhMCRkkxDjAMBgNVBAcMBUVzcG9vMQ8wDQYDVQQKDAZFbmZ1Y2UxETAP
BgNVBAsMCENhcmQgQVBJMSUwIwYDVQQDDBxqd2UtdGVzdC0yMDI2MDQyMi5lbmZ1
Y2UuY29tMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAl9nrCsMtzGy2
r/tfZugYW8vX/+GoZv9FUK2XfsEqgaTBWVQZvkbRKAijtdymHXwe72rZuVBotaUm
ES/5Eqqhy5Mb6pYZ9H3VwV0tq6RSiq6A9nEevfPHe2UXl66K6XC8WWXtLyHu1sdk
t9Gf4zLMspL7C+8m1OfJMZzBAEXcuoNcUPbWHzupyWpKvCZqbV1kwXDaYhCYR0cQ
BLNUTxQS+fIYZrlrzIiwGng/3IDBsaVuJdFfa3OqRcNPt6rbcvtrQ3pN6zSvOPB6
MVUKNPp7PeSBYomnPa+CI68XG9GfxK3fhos/uUlrQv4rnDP/qTtUvrK9VutDrg4r
y/GXroEr8wIDAQABo1MwUTAdBgNVHQ4EFgQUnZQPK6mB0zIKBmPXjSkFWGJR4zMw
HwYDVR0jBBgwFoAUnZQPK6mB0zIKBmPXjSkFWGJR4zMwDwYDVR0TAQH/BAUwAwEB
/zANBgkqhkiG9w0BAQsFAAOCAQEAV7yknM6xyWA2lZlDKaQdg7Jug6pKvW6733IQ
ois3/1VJPa1piDiNWfQcvvinxvTyczCjnh/HOdtbFfLJHezcj1R/YsrSE45VIc9Z
d3gwK1MpLUNdb9ifmpxT9gfGy7mPNZC0FtzWHqWwcogzyScoLWT11usqHR64aZiZ
/shfQPy6iK5gDF6yrwUB+Tv3TZl934GvYhFw/P3uk7ZSJ27/XhUrbnooagqRYZlN
+/+2hvyGDZ4YVfdt7rhWfmm3xHNCVVyRjuLaaWOebWM+y705KN57DXyXxDPkmmud
M2aru88ojhKc73QIQy8izAOTFKtyuOxtQR7PbDBpXcJhHGO/UQ==
-----END CERTIFICATE-----
Certificate for production environments (jwe-20260422.pem):
-----BEGIN CERTIFICATE-----
MIIDpzCCAo+gAwIBAgIUP+Z0k9p29DQZLP62py6KuG8XbRQwDQYJKoZIhvcNAQEL
BQAwYzELMAkGA1UEBhMCRkkxDjAMBgNVBAcMBUVzcG9vMQ8wDQYDVQQKDAZFbmZ1
Y2UxETAPBgNVBAsMCENhcmQgQVBJMSAwHgYDVQQDDBdqd2UtMjAyNjA0MjIuZW5m
dWNlLmNvbTAeFw0yNjA0MjIwODE3NDZaFw0yODA0MTEwODE3NDZaMGMxCzAJBgNV
BAYTAkZJMQ4wDAYDVQQHDAVFc3BvbzEPMA0GA1UECgwGRW5mdWNlMREwDwYDVQQL
DAhDYXJkIEFQSTEgMB4GA1UEAwwXandlLTIwMjYwNDIyLmVuZnVjZS5jb20wggEi
MA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCCmlTBos5Q32mEL3XU0UjrPN22
27YpyqCE234kwJ8BIBnzkQdrfkB27cucYnzj7HHg+1tn7CJBtprwkwzAEMW2CY5G
/3kOD9hw9amFKtw1C/pMW4ZJh0W8pbbN1+9Y0Ti85hWQN7+UVyRybZqSr8aCXKV9
5qyVU/00rdDT+mXdSjppzn3HU4jmWABIwJkT5wyxeIMonr+O+WHW08yd1LYd5ID6
tfyC8o48pXI2uugyNGIPKdwiaK/C/qojiJYJRRZEaXatAk2OFFvq+ryeICO88TK9
eB7ngEPpfa04nebkH8Scj4rbyYPmSyFpGfvVeXvzODixdI1Qxz/KK9j96PiNAgMB
AAGjUzBRMB0GA1UdDgQWBBSFbT/MlsLoAOdcGNVwCbJWnEFVyTAfBgNVHSMEGDAW
gBSFbT/MlsLoAOdcGNVwCbJWnEFVyTAPBgNVHRMBAf8EBTADAQH/MA0GCSqGSIb3
DQEBCwUAA4IBAQAHGOulvkVGjntcH9fJMRgOh32fjddc3+UDx5DKGluvDoqEgZdw
ow1PFSRMNNHfMlOLCpNsiwuLJhA5weWUZnrMrizVkTGf2M39FkltlozY/mWwkJ97
3sSfy6AN1lw/IbWJqOaYYU5wAWPgVP7lkiyDhJ21QtgHKeRQeTAtwuV3vv5cj/Cx
ns/vYrXsoEJTboimlNm9eLUq61B+BFsZqJsvu8S3nT0icM4d4ZXwD0Ci/cs76wQN
iLe3+O3GM1rQu+upvZJd9LqylXGa/mi5y0TwlunCG9ppIOotZQZpS3JlS8gKPTwS
iUuAvpt0bTTTqMDpE+4i9pjqiU6hyGguFkaB
-----END CERTIFICATE-----
version: '1'
title: Card details API
contact:
name: Enfuce Financial Services
url: https://enfuce.com
email: info@enfuce.com
x-logo:
url: https://developer.enfuce.com/images/enfuce.svg
altText: Enfuce logo
servers:
- url: >-
https://integration-api-cat2.{{environment}}.ext.{{realm}}.cia.enfuce.com/card
- url: https://integration-api-cat2.live.ext.prod.cia.enfuce.com/card
description: Live environment
security: []
tags:
- name: Create card
description: Endpoints for creating a card
- name: Update card
description: Endpoints for updating a card
- name: Get card
description: Endpoints for fetching a card
- name: Get plastic
description: Endpoints for fetching a plastic
- name: Update plastic
description: Endpoints for updating a plastic
- name: Get application
description: Endpoints for fetching an application
- name: Update application
description: Endpoints for updating an application
paths:
/v4/card/{cardId}/controlToken:
post:
tags:
- Get card
summary: Initiate card data retrieval
description: >
Endpoint to initiate retrieval of card data. This will enable the end
user make e-commerce transactions without
needing access to a plastic card. This means that the end user will get
access to card number (PAN), expiry
date and CVC2/CVV2. This operation will generate an access token used to
view the card data, enabling end users
to access their card data through their own devices, via app or web
interface.
Supporting the possibility to copy the card data to the devices
clipboard should be examined with caution.
The data lifespan and the access to the device clipboards varies between
operating systems which introduces
risk. So while recognising that the possibility to copy the card data
can improve end-user experience,
the potential increased risk of such a feature should be considered.
### Process description
1. End user request to see the card data (Pan number, exp. date and CVV)
through its own devices, via app or
web interface.
2. The end user request triggers a request to Enfuce Card API
(/v4/card/{cardId}/controlToken)
* The request will fail if cardId is not valid.
* Besides cardId, no additional validation is done. This means that Enfuce will not validate open-to-buy,
card status or usage limiters of the card when responding to request. In order to validate if a purchase
can be done with card data in question, separate API calls should be done to retrieve real time status
of card and it´s balance.
3. The successful response from this endpoint returns a token and two
URLs
* Note the token is valid for 30 seconds which is the deadline for the end user device to make
the POST call to retrieve the HTML snapshot
4. The end users device is instructed to access the returned URL to view
the card data
* Mobile app retrieves the HTML snapshot with card data by executing a POST call to the cardDataUrl
with the content of the token in a form field named token.
* Desktop browser opens iframe to cardDataFrameUrl with query parameter _key_. Key needs to agreed with
Enfuce beforehand. After that is loaded, parent page makes window.postMessage() call to the iframe.
Posted message object contains field _operation_ with value _view-pan_ and field _token_. Example:
```javascript
iframe.addEventListener('load', () => {
iframe.contentWindow.postMessage({operation: 'view-pan', token}, cardDataFrameUrl);
})
```
5. Enfuce responds with a HTML snapshot containing the card data.
* The request will fail if the token is not valid.
6. End user sees card data on device and can utilise it to make a
purchase.
### PCI and security considerations
The service is designed to avoid exposure of sensitive, PCI categorised
data to the web/app back-end,
therefore the card data is sent directly from the service endpoint to
the end users device. The functionality
is developed, assessed, and certified for PCI DSS. PCI DSS regulations
are detailed, but highlighting
a few that have impact on the this functionality:
* Card data remains encrypted in transport.
* No card data is stored in the process.
* The software is code reviewed.
* The publicly exposed endpoint is protected by a web application
firewall.
The end user device will not fall within PCI scope, as it will not have
access, be connected to or be able
to impact Enfuce system where the card data resides. In other words, the
device displaying the card data does
not access the data itself, rather the content is rendered inside
browser widget (Webview or Iframe).
Enfuce recommendations for end user app development:
* The app and the related back-end should ensure that the user is
strongly authenticated (SCA) before being
able to view the card data. It is recommended, that each view is preceded by an SCA event, and this should be
done for every view event.
* The app must show the card data for only the time needed for the user
to use this data and it is recommended
that there is a timeout of 1 minute until the card holder data view is automatically closed for the user.
* The app developers need to take necessary precautions to stop other
apps or processes to access or interact
with the card data view.
* The app developers need to ensure that the communication between the
app and the related back-end is done
in an authenticated and encrypted session.
operationId: createCardDataControlTokenByCardIdV4UsingPOST
parameters:
- name: cardId
in: path
description: The id of the card's data requested
required: true
schema:
type: string
format: biginteger
- name: auditUser
in: query
description: The audit user to log the request
required: true
schema:
type: string
responses:
'201':
description: Successful creation of the control token
content:
application/json:
schema:
$ref: '#/components/schemas/CardDataControlTokenResponseBody'
'401':
$ref: '#/components/responses/error401'
'403':
$ref: '#/components/responses/error403'
'404':
description: Card Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
'500':
$ref: '#/components/responses/error500'
deprecated: false
components:
schemas:
CardDataControlTokenResponseBody:
type: object
properties:
token:
type: string
description: The control token.
cardDataUrl:
type: string
description: The URL to call on mobile devices for accessing the card's data.
cardDataFrameUrl:
type: string
description: The URL to open in iframe to access the card's data.
required:
- token
title: CardDataControlTokenResponseBody
errorResponse:
type: object
properties:
code:
type: string
description: An error code indicating what kind of error. I.e. HTTP error code
message:
type: string
description: Error message in human-readable format
id:
type: string
format: uuid
description: Unique error identifier
errorCode:
type: string
description: Enfuce code for a specific error type
errorType:
type: string
description: Error type
enum:
- STATIC_VALIDATION_ERROR
- DYNAMIC_VALIDATION_ERROR
- INTEGRATION_ERROR
- SECURITY_ERROR
- UNEXPECTED_ERROR
errorReason:
type: string
description: Free-form text explaining the error reason
timestamp:
type: string
format: date-time
description: Datetime when error occurred
responses:
error401:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
error403:
description: Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
error500:
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/errorResponse'
````