Certification guide

This guide lists the test cases a payment processor, gateway, or orchestrator runs in the FlexFactor sandbox before the integration is certified for production. It follows the order of a full payment cycle: authentication, tokenization, the evaluate call for each flow, capture, cancel, refund, recovery after errors, and webhooks. Every case cites the page that defines the behavior. Those pages remain the authoritative reference for request and response shapes.

Certification is required one time, at first go-live. Re-certification is required only when you add a flow, add an integration path, or rework the integration. Boarding a new merchant onto a certified integration does not require re-certification.

How to use this guide

Download the test-case workbook

Every case in this guide is also available as an Excel workbook: one tab per page, the same columns as the tables here, a column for each piece of evidence, and the result sheet with the totals calculated for you.

Download the certification test-case workbook (xlsx)

The workbook is generated from these pages. When the two differ, these pages are authoritative.

Select your scope

Mark each profile as In or Out before you start. The profile codes appear as an Applies to tag on every section and on individual cases where a section is mixed.

Code	Profile	What it covers	Enablement needed	In / Out
CORE	Core	Bearer-token authentication, error handling, idempotency, order inquiry	None	In (always)
BASIC-AUTH	Basic Authentication	`Authorization: Basic` header on every request instead of a bearer token	Enabled by FlexFactor on request
TOKENIZE	Tokenized card data	`POST /v1/tokenize` before `/evaluate`; `paymentMethod.token: true`	Tokenization Key
DIRECT-CARD	Direct card data	Raw PAN in `/evaluate`; `paymentMethod.token: false`	PCI AOC on file; enabled by FlexFactor
CIT-PURCHASE	CIT Purchase	Synchronous sale; approve or decline in one call	None
CIT-AUTHORIZE	CIT Authorize	Synchronous authorization plus an explicit `/capture`	`authorize` capability enabled by FlexFactor
MIT-ASYNC-PURCHASE	MIT Async Purchase	Asynchronous rescue resolved by webhook	Webhook endpoint
MIT-ASYNC-AUTHORIZE	MIT Async Authorize	Asynchronous authorization resolved by webhook plus `/capture`	`authorize` capability; webhook endpoint
SYNC-MIT	Sync MIT	Retry-driven synchronous MIT; FlexFactor is the only retry mechanism	Back-end configuration by FlexFactor
WEBHOOKS	Webhooks	Handler behavior and post-approval events	Webhook endpoint registered in the sandbox portal

Exactly one of TOKENIZE or DIRECT-CARD must be In. WEBHOOKS must be In when MIT-ASYNC-PURCHASE or MIT-ASYNC-AUTHORIZE is In, and we recommend it for SYNC-MIT because the order.capturerequired event is the backstop that prevents an uncaptured rescue.

Pages

The cases are split across eight pages in payment-cycle order. Each page carries one or more numbered sections; the section numbers are the row keys in the result sheet.

Page	Sections	Cases
Authentication and card data	1, 2	14
Customer-initiated flows	3, 4	8
Merchant-initiated flows	5, 6, 7	15
Capture, cancel, and refund	8, 9, 10	22
Idempotency and error handling	11, 12	20
Webhooks	13	6
Payload review and production cutover	14, 15	27
Certification reference	Appendices A, B, C	None

Section map

Section	Applies to	Skip when
1 Connectivity and authentication	CORE	Never
1.2 Basic Authentication	BASIC-AUTH	BASIC-AUTH is Out
2 Tokenization and card data	TOKENIZE, DIRECT-CARD	Never; run the sub-section for your path
3 CIT Purchase	CIT-PURCHASE	CIT-PURCHASE is Out
4 CIT Authorize	CIT-AUTHORIZE	CIT-AUTHORIZE is Out
5 MIT Async Purchase	MIT-ASYNC-PURCHASE	MIT-ASYNC-PURCHASE is Out
6 MIT Async Authorize	MIT-ASYNC-AUTHORIZE	MIT-ASYNC-AUTHORIZE is Out
7 Sync MIT	SYNC-MIT	SYNC-MIT is Out
8 Capture	CIT-AUTHORIZE, MIT-ASYNC-AUTHORIZE, SYNC-MIT	All three are Out
9 Cancel	CIT-AUTHORIZE, MIT-ASYNC-PURCHASE, MIT-ASYNC-AUTHORIZE, SYNC-MIT	All four are Out
10 Refund	CORE	Never
11 Idempotency, timeouts, and order recovery	CORE	Never
12 Error handling	CORE	Never
13 Webhooks	WEBHOOKS	WEBHOOKS is Out
14 Payload quality review	CORE	Never
15 Production cutover checks	CORE	Never

Case format

Every table has the same columns.

Column	Content
ID	Stable identifier; cite it in results and support requests
Scenario	What the case proves
Setup / action	Only the fields that differ from the base payloads in Appendix A. No prefix means you drive the case through the sandbox API; Support: means FlexFactor triggers it on request
Expected result	The checkable outcome. HTTP status, response fields, order status from `GET /v1/orders/{id}`, and webhook events
Evidence	What to record for the result sheet. HTTP statuses, response bodies, `orderId` values, and webhook `IdempotencyKey` values; no application logs or code are requested

Record for every case: the case ID, the UTC timestamp, the HTTP status, the FlexFactor orderId when one is returned, and the traceId from any error response. Record the webhook IdempotencyKey for every event you cite. Three tables are not runnable cases: the response handling rules in Section 12.2 and the routing rules in Section 14.2 are confirmed in writing, one sentence per rule, and Section 15 is a checklist.

📘
HTTP 200 is not a transaction outcome
HTTP 200 means the request reached FlexFactor. The outcome is in the status field, and its vocabulary differs by endpoint: APPROVED, DECLINED, CHALLENGE, CAPTUREREQUIRED, or SUBMITTED on /evaluate; SUCCESS or FAILED on /capture and /refund; no status field on /cancel. Appendix C.4 summarizes the envelope, and Workflows §3.5 defines it.

Submitting results

Send the completed result sheet and the evidence to your FlexFactor Solutions engineer at [email protected]. The Solutions engineer reviews the results, reviews the requests received by the sandbox (Section 14), and certifies the integration or returns a list of cases to re-run.

Prerequisites

Item	Detail
Sandbox credentials	MID, API Key (`appKey`), API Secret (`appSecret`), Site ID. Tokenization Key when TOKENIZE is In. All values are sandbox-specific; see Credentials
Base URL	`https://api-sandbox.flexfactor.io/v1/`
Enablement	Confirm with your Solutions engineer before testing: `authorize` capability (CIT-AUTHORIZE, MIT-ASYNC-AUTHORIZE), Sync MIT configuration (SYNC-MIT), direct card data (DIRECT-CARD), Basic Authentication (BASIC-AUTH)
Webhook endpoint	HTTPS endpoint registered in the sandbox portal and subscribed to all events; see Webhooks. Allow the sandbox source IPs `35.172.5.145` and `3.211.16.180` if your ingress is restricted
Test cards	See Appendix B and the Sandbox Test Cards page. Real card data is rejected in the sandbox
Base payloads	Appendix A. Each case states only the fields it changes
Records	Keep the request and response for every case you cite, so you can supply the evidence column. Section 14 is reviewed from the requests received by the sandbox; you do not need to send request logs

Result sheet

Copy the table, keep only the sections in scope, and record one row per case. Attach evidence by case ID. The workbook holds the same table and fills in the counts from the case tabs.

Section	Cases run	Passed	Failed	Not applicable	Tester	Date (YYYY-MM-DD)
1 Connectivity and authentication
2 Tokenization and card data
3 CIT Purchase
4 CIT Authorize
5 MIT Async Purchase
6 MIT Async Authorize
7 Sync MIT
8 Capture
9 Cancel
10 Refund
11 Idempotency, timeouts, and order recovery
12 Error handling
13 Webhooks
14 Payload quality review
15 Production cutover checks

Sign-off	Name	Date (YYYY-MM-DD)
Integrator test lead
FlexFactor Solutions engineer

Certification outcome (completed by the Solutions engineer): Certified, Certified with documented gaps, or Remediation required. List every gap or remediation item by case ID.

Support

Technical questions and result submissions: [email protected]