Managing PCI Compliance

To process payments, your users need to validate compliance with PCI DSS annually. Users validate compliance by completing a Self-Assessment Questionnaire (SAQ).

Users include any entity that stores, processes, or transmits credit card data. For more information about PCI compliance, see PCI DSS Compliance.

Creating Compliance Forms

When a user gets successfully onboarded, Finix’s API will generate the necessary PCI compliance_form pre-filled with the user’s information. Each compliance_form is uniquely associated with the user.

  • If your users are processing Card Not Present transactions, Finix will generate a pre-filled SAQ Questionnaire with type pci_saq_a . For an example see this sample SAQ A form from the PCI Council.

Finix users must validate PCI compliance within 90 days of being onboarded by completing the necessary compliance_form.

  • The specific date the compliance_form needs to be completed by can be found in due_at .
  • Users must complete and attest to a new compliance_form annually.

Viewing Compliance Forms

A webhook notifies you when Finix creates a compliance_form.

Use the id in the webhook to fetch the compliance_form resource from the /compliance_forms/:COMPLIANCE_FORM_ID: endpoint.

Copy
Copied
curl https://finix.sandbox-payments-api.com/compliance_forms/cf_fEojUGLjwUiqNTBp68JWq8 \
    -H "Content-Type: application/vnd.json+api" \
    -H 'Finix-Version:2022-02-01' \
    -u  USj46WbwgnjapmdYFnEDP3Ec:b9b4042c-9621-438d-a84b-8557d4bda84d

Example Response

Copy
Copied
{
  "id" : "cf_fEojUGLjwUiqNTBp68JWq8",
  "created_at" : "2022-06-22T01:20:12.439149Z",
  "updated_at" : "2022-07-06T17:32:00.328699Z",
  "linked_to" : "MUfnskvHiiDgP7x3TVL2LkG3",
  "linked_type" : "MERCHANT",
  "type" : "PCI_SAQ_A",
  "version" : "2018.5",
  "valid_from" : "2022-06-22T01:20:12.978825Z",
  "valid_until" : "2023-06-22T01:20:12.97883Z",
  "tags" : { },
  "pci_saq_a" : {
    "name" : null,
    "signed_at" : null,
    "user_agent" : null,
    "ip_address" : null,
    "is_accepted" : false,
    "title" : null
  },
  "due_at" : "2022-09-20T01:20:12.430835Z",
  "compliance_form_template" : "cft_wua8ua1yLAcHRK9mx2mF9K",
  "files" : {
    "unsigned_file" : "FILE_fFGMCY4sxGYTqpjnXh54kC",
    "signed_file" : null
  },
  "state" : "INCOMPLETE"
}

HTTP Request

GET https://finix.sandbox-payments-api.com/compliance_forms/:COMPLIANCE_FORM_ID:

Completing Compliance Forms

As part of onboarding your users, you'll need to build a UI experience that allows users to complete the PCI compliance_form and download the form as a PDF if requested.

To complete PCI compliance forms:

  1. Get the compliance_form generated for the merchant using the id from the webhook and present the form to your users when requested.
  2. Show your users the required text to obtain consent.
  3. Submit a PUT API request with the necessary attestation information.

Obtaining Compliance Consent

You need to present your users a link so they can view the compliance form. Users must explicitly consent to the form before you can submit the attestation PUT request to Finix.

To obtain your users' consent, you must present the following text alongside the link to the compliance form:

By submitting this Self-Assessment Questionnaire, I certify that I am an authorized representative of the company and that all the information submitted is true and correct.

Completing the Questionnaire

To complete and submit the questionnaire, update compliance_form with the required pci_saq_a information. Updating the compliance_form with this information will update state from INCOMPLETE to COMPLETED.

Copy
Copied
curl https://finix.sandbox-payments-api.com/compliance_forms/cf_bcu8rBtpCFJVuRpgCxt4HS \
    -H "Content-Type: application/vnd.json+api" \
    -H 'Finix-Version:2022-02-01' \
    -u  USdCBTiL4BwY9jJ6Mq12ymrW:d294d534-b1f7-473b-bc56-7f76ccb011e7 \
    -X PUT \
    -d '
    {
        "pci_saq_a": {
         "name": "John Smith",
         "signed_at": "2022-03-18T16:42:55Z",
         "user_agent": "Mozilla 5.0(Macintosh; IntelMac OS X 10 _14_6)",
         "ip_address":"42.1.1.113",
         "title": "CTO"
       }
    }'

Example Response

Copy
Copied
{
       "id": "cf_bcu8rBtpCFJVuRpgCxt4HS",
       "type": "PCI_SAQ_A",
       "state": "COMPLETED",
       "created_at": "2021-08-15T18:26:56.15Z",
       "updated_at": "2021-07-T15:26:56.15Z",
       "due_at": "2021-11-13T15:26:56.15Z",
       "linked_to": "MUas8jhZf3bWsqyp8neX3UwN",
       "linked_type": "MERCHANT", 
       "pci_saq_a": {
         "name": "John Smith",
         "signed_at": "2022-03-18T16:42:55Z",
         "user_agent": "Mozilla 5.0(Macintosh; IntelMac OS X 10 _14_6)",
         "ip_address":"42.1.1.113",
         "is_accepted": true,
         "title": "CTO" 
       },
       "files": {
         "unsigned_file": "FILE_qf952xmeuiF179wdMiPXrW",
         "signed_file": "FILE_mmRiDs7YaSsqjP727gWD84"
       },
      },
       "valid_from": "2022-03-18T18:26:56.15Z",
       "valid_until": "2023-03-18T18:26:56.15Z",
       "compliance_form_template": "cft_u56ZGx3Xb6U9gAqKfgNisd",
       "tags": {} 
     }

HTTP Request

PUT https://finix.sandbox-payments-api.com/compliance_forms/:COMPLIANCE_FORM_ID:

Response

Field Type Description
id string ID of the compliance_form
type string Type of compliance_form. There is one available value: PCI_SAQ_A
state string The state of the compliance_form. There are three available values: PENDING, COMPLETED, or INVALID.
created_at string Timestamp of when the compliance_form was created.
updated_at string Timestamp of when the compliance_form was last updated.
due_at string Timestamp of when the compliance_form must be completed by.
linked_to string The ID of the merchant linked to the compliance_form.
linked_type string The type of resource this compliance_form is linked to.
pci_saq_a string See pci_saq_a.
files object See files.
valid_from string Timestamp of when the compliance_form becomes active and valid.
valid_until string Timestamp of when the compliance_form is no longer active and valid.
compliance_form_template string Template linked to this compliance_form.
pci_saq_a
Field Type Description
name string Name of the person completing (aka attesting to) the compliance_form
signed_at string Timestamp of the person attesting to this compliance_form
user_agent string User agent of the person attesting to this compliance_form
ip_address string IP address of the person attesting to this compliance_form
is_accepted boolean If all pci_saq_a fields are all submitted, is_accepted updates to true.
files
Field Type Description
unsigned_file string ID of the File resource that has the compliance_form.
signed_file string
  • Auto-fills to null.
  • When a complianceform is attested, `signedfilewill contain aFile` corresponding to the signed version of the form.

Downloading Compliance Forms

Every compliance_form resource has a file object. The file object has a File ID available in:

  • unsigned if the user hasn't completed the form
  • signed if the user has completed the form.

Use the File ID to download the file for your user or fetch it to display the PDF in their browser.

Renewing Compliance

To stay PCI compliant, you and your users need to validate compliance annually by completing the SAQ questionnaire. When the valid_to date passes (i.e. the valid_to date is greater than today’s date), Finix will generate a new compliance_form with new valid_from and valid_to timestamps.