Authentication and card data

Part of the Certification guide. Mark your scope on that page before you run these cases. Base payloads and test cards are on the Reference page.

1. Connectivity and authentication

Two authentication methods exist. The bearer-token flow in 1.1 is the default and applies to every integration. Basic Authentication in 1.2 is an alternative that FlexFactor must enable on your account.

1.1 Bearer token

Applies to: CORE. Tokens live for 10 minutes. Cache the token and request a new one only after a 401. One token request for many API calls is the expected pattern; the Solutions engineer can see the token-request rate on the sandbox side.

Reference: Authentication, /health, Workflows §1.

ID	Scenario	Setup / action	Expected result	Evidence
AUTH-01	Health check	`GET /v1/health` with no authentication	HTTP 200 with an empty body	HTTP status
AUTH-02	Token issued	`POST /v1/oauth2/token` with valid `appKey` and `appSecret`	HTTP 200; `accessToken` and `expires` present; `expires` is a Unix-epoch timestamp in milliseconds 10 minutes after issue	Response without the token value
AUTH-03	Invalid credentials	`POST /v1/oauth2/token` with a wrong `appSecret`	HTTP 401; no token issued	HTTP status, `traceId`
AUTH-04	Invalid bearer, then refresh and retry	`POST /v1/evaluate` with the base CIT payload and a malformed bearer token. Request a new token and resend the same request one time	The first response is HTTP 401. The resend returns HTTP 200 with `status` `APPROVED`	Both HTTP statuses, `orderId`

1.2 Basic Authentication

Applies to: BASIC-AUTH. The credential is the API Key and API Secret joined by a single period, Base64-encoded, and sent as Authorization: Basic {credential} on every request. No call to /oauth2/token is made. The credential does not expire, so a 401 is a credential defect; log it and raise an alert rather than retrying. Build the header on the server. The encoding is not encryption, so the header must travel over HTTPS only.

Reference: Basic Authentication.

ID	Scenario	Setup / action	Expected result	Evidence
BASIC-AUTH-01	Request authenticated with the Basic header	`POST /v1/evaluate` with the base CIT payload and `Authorization: Basic base64({API Key}.{API Secret})`	HTTP 200; `status` `APPROVED`; `orderId` present	`orderId`
BASIC-AUTH-02	Wrong secret	Repeat BASIC-AUTH-01 with an incorrect API Secret	HTTP 401; no order created	HTTP status, `traceId`
BASIC-AUTH-03	Malformed credential	Repeat BASIC-AUTH-01 twice: once with the API Key and API Secret joined by a colon, once with the plain `{API Key}.{API Secret}` string after `Basic` with no Base64 encoding	HTTP 401 both times; no order created	HTTP statuses, `traceId`
BASIC-AUTH-04	Basic header on every endpoint	Run the in-scope cases in Sections 8 to 11 with the Basic header on `/capture`, `/cancel`, `/refund`, and `GET /v1/orders/{id}`	Each call returns the same result as it does with a bearer token	HTTP statuses

2. Tokenization and card data

2.1 Tokenized path

Applies to: TOKENIZE. /tokenize is authenticated by the mid and environment query parameters, not by a bearer token. Store the token with the BIN, last 4 digits, expiry month and year, and holder name, because the /evaluate payload requires those fields alongside the token.

Reference: /tokenize, Sandbox Test Cards, Appendix B.

ID	Scenario	Setup / action	Expected result	Evidence
TOKENIZE-01	Tokenize a card	`POST /v1/tokenize?mid={mid}&environment={tokenizationKey}` with card `4000002760003184`, any future expiry, first and last name	HTTP 200; `transaction.payment_method.token` is a GUID; `last_four_digits` is `3184`; `first_six_digits` is `400000`	Token GUID
TOKENIZE-02	Token used in evaluate	Base CIT payload with `paymentMethod.cardNumber` = token from TOKENIZE-01 and `token: true`	HTTP 200; `status` is `APPROVED`	`orderId`
TOKENIZE-03	Invalid card number	`/tokenize` with `number` = `4000000000000000`	HTTP 400 with an `errors` object	`traceId`
TOKENIZE-04	Wrong tokenization key	`/tokenize` with an incorrect `environment` value	HTTP 401 or 403; no token issued	HTTP status

2.2 Direct card data path

Applies to: DIRECT-CARD. Requires a PCI AOC on file and enablement by FlexFactor.

Reference: Workflows §4, Appendix A.1.

ID	Scenario	Setup / action	Expected result	Evidence
DIRECT-CARD-01	Raw PAN accepted	Base CIT payload with `paymentMethod.cardNumber` = `4000002760003184`, `token: false`, `verificationValue` omitted	HTTP 200; `status` is `APPROVED`	`orderId`
DIRECT-CARD-02	CVV sent on CIT	Base CIT payload with card `4111111111111111`, `token: false`, `verificationValue` = `999`, any name other than `Cure Tester`	HTTP 200; `status` is `APPROVED`	`orderId`