Transaction

When you submit a query to the Anti-Fraud services, you create a Transaction. A transaction may contain the execution of one or more services configured in the query model or informed in the request body. These services may be internal analyses or external queries that are performed on the processing conveyor. After that, based on validation rules, the status is set for the transaction.

Services and validation rules can be configured only in the query template.

A transaction is characterized by an endpoint where the required services can be informed and a set of rules validated.

Related documentation:

If you use Certta SDKs and need to link mobile tokens with transactions, access Transaction linking
To understand the structure and services available in transaction responses, access Transactions

Transaction webhooks: Transactions created directly through POST /transactions do not emit TRANSACTIONPROCESSSTARTEDEVENT. Use the transaction id returned by the creation request to correlate subsequent TRANSACTIONSTATUSUPDATEDEVENT and related events. See Webhook Events.

For details on authentication, access Authenticating.

Authentication Requirements:

Regular endpoints use OAuth2 authentication with base URL: https://api.us.prd.caf.io
For enhanced security, some endpoints may also support mTLS authentication with base URL: https://mtls.us.prd.caf.io
For information on implementing mTLS, access Using mTLS

Supported endpoints

Create transaction

post

Submission of the necessary person or company data and the template model against which the verification services shall be executed, as well as the set of rules to be validated.

Required Permission: Create Transaction

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

originstringRequired

Parameter that defines the onboarding origin. Must be set to TRUST.

Header parameters

AuthorizationstringRequired

Access token.

Example: Bearer your_token_here

Body

templateIdstringRequired

Unique ID of the Query Template (configured in Trust).

metadataobjectOptional

Free to add any kind of attribute, ideal for linking IDs or other information in the transaction.

referenceTokenstringOptional

Mobile Token (Session Token).

_callbackUrlstring · uriOptional

Callback URL (webhook).

Responses

200

Success

application/json

requestIdstringOptional

Unique identifier of request.

Example: 6cb8093c-14ef-4fd1-810b-ee9fa5f9aae9

idstringOptional

Unique identifier of created transaction.

Example: 6021a21b3811c35ecb8dea20

400

Bad request

application/json

401

Unauthorized

application/json

500

Internal Server Error

application/json

post/

POST /v1/transactions/?origin=text HTTP/1.1
Host: api.us.prd.caf.io
Authorization: text
Content-Type: application/json
Accept: */*
Content-Length: 443

{
  "templateId": "text",
  "files": [
    {
      "data": "text",
      "type": "SELFIE"
    }
  ],
  "attributes": {
    "cpf": "text",
    "rg": "text",
    "name": "text",
    "birthDate": "text",
    "fatherName": "text",
    "motherName": "text",
    "uf": "text",
    "cnpj": "text",
    "cep": "text",
    "email": "[email protected]",
    "phoneNumber": "text",
    "plate": "text",
    "documentCountry": "text",
    "holderName": "text",
    "holderCpf": "text",
    "analysisDate": "2025-08-15"
  },
  "metadata": {},
  "referenceToken": "text",
  "_callbackUrl": "https://example.com"
}

{
  "requestId": "6cb8093c-14ef-4fd1-810b-ee9fa5f9aae9",
  "id": "6021a21b3811c35ecb8dea20"
}

Upload file

post

/files

Upload a file to be used in transactions. The file will be stored temporarily and can be referenced in transaction creation.

Required Permission: Create Transaction Files

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Header parameters

AuthorizationstringRequired

Access token. See more in the 'Authentication' topic.

Example: Bearer your_token_here

Body

filestring · binaryRequired

File to be uploaded. Accepted formats: application/pdf, image/png, image/jpeg, image/bmp, image/webp, image/heif

Responses

201

Created

application/json

requestIdstringOptional

Unique identifier of request.

Example: 6cb8093c-14ef-4fd1-810b-ee9fa5f9aae9

messagestringOptional

Success message.

Example: File sent successfully.

400

Bad request

application/json

401

Unauthorized

application/json

403

Forbidden

application/json

422

Unprocessable Entity

application/json

500

Internal Server Error

application/json

post/files

POST /v1/transactions/files HTTP/1.1
Host: api.us.prd.caf.io
Authorization: text
Content-Type: multipart/form-data
Accept: */*
Content-Length: 17

{
  "file": "binary"
}

{
  "requestId": "6cb8093c-14ef-4fd1-810b-ee9fa5f9aae9",
  "message": "File sent successfully.",
  "data": {
    "filename": "document.pdf"
  }
}

List transactions

get

Get your transaction list summarized with pagination and filters.

Required Permission: Read Transaction

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

_limitnumberOptional

The maximum amount of records that should be returned in the response, e.g. _limit=5. Max value is 10 and default is 10.

_orderstringOptional

Sort the records returned in response by creation date in ascending or descending order. Descending (default): _order=desc Ascending : _order=asc

_templatesstringOptional

Search for too many template models by references of the templateId on the account. For multiple templates, separate the values using the pipe symbol, e.g. _templates=templateId1|templateId2|templateId3.

_startCreatedDatestring · dateOptional

Search the records created on or after any given day, e.g. _startCreatedDate=2022-01-01.

_endCreatedDatestring · dateOptional

Search the records created on or before a specified day, e.g. _endCreatedDate=2022-01-30.

Header parameters

AuthorizationstringRequired

Access token. See more in the 'Authentication' topic

Example: Bearer your_token_here

Responses

200

Success

application/json

requestIdstringRequired

Unique identifier of request.

Example: 6cb8093c-14ef-4fd1-810b-ee9fa5f9aae9

totalItemsintegerRequired

Total amount of transactions according to the filter used.

Example: 2

401

Unauthorized

application/json

500

Internal Server Error

application/json

get/

GET /v1/transactions/ HTTP/1.1
Host: api.us.prd.caf.io
Authorization: text
Accept: */*

{
  "requestId": "6cb8093c-14ef-4fd1-810b-ee9fa5f9aae9",
  "items": [
    {
      "id": "6388ac6b409eff000804dadf",
      "status": "APPROVED",
      "createdAt": "2022-09-08T22:10:14.816Z",
      "data": {
        "cpf": "00011122233",
        "birthDate": "01/01/2000",
        "name": "John Doe"
      }
    }
  ],
  "totalItems": 2
}

Get transaction by ID

get

/{transactionId}

Retrieve the result data of a transaction.

Required Permission: Read Transaction

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

transactionIdstringRequired

Transaction identifier.

Query parameters

_includePfRelationshipsbooleanOptional

Flag for including transactions related to onboarding pf_pf. Default is 'false'. e.g. _includePfRelationships=true.

Default: false

_includeCroppedImagesbooleanOptional

Flag to include the cropped versions of the images of the sended documents. Default is 'false'. e.g. _includeCroppedImages=true.

Default: false

_langstringOptional

Flag to set the language in the description of the reasons for manual failures. Possible values are 'en' or 'pt'. Default is 'pt'. e.g. _lang=en.

Default: pt

Header parameters

AuthorizationstringRequired

Access token. See more in the 'Authentication' topic

Responses

200

Success

application/json

requestIdstringRequired

Unique identifier of request.

Example: 2b8f373-c462-4bbf-9a4f-8aeb7d71ec53

idstringRequired

Unique identifier of transaction.

Example: 6388a3e9a73b280008ba31ad

statusstring · enumRequired

Status of transaction.

Example: APPROVEDPossible values:

customStatusstring · nullableOptional

Merchant-defined custom status configured in Trust. There is no global enum because the available values are specific to each tenant. Returns null when no custom status applies.

templateIdstringOptional

Unique ID of the Query Template.

Example: 638a021fdeb2b90008c790d1

onboardingIdstringOptional

Unique identifier of the onboarding that generated the transaction. Note that these values are only returned for transactions that originated from the service Web Onboarding.

createdAtstring · date-timeRequired

Transaction creation date.

Example: 2022-09-08T22:10:14.816Z

typestringOptional

Document type sent:

• "rg" (Brazilian General Registry) The RG is a document used to identify Brazilian citizens.

• "cnh" (Brazilian Driver's License) It is a mandatory document for any citizen who intends to drive a motor vehicle.

• "crlv" (Vehicle Registration and License Certificate) Is the document issued annually to indicate that the vehicle is fit to circulate on Brazilian streets.

• "rne" (Brazilian Foreigner Registry) Is a document that certifies the identity of foreign individuals with temporary or permanent residence in Brazil.

• "rnm" (Brazilian Migratory Registry) Is the alphanumeric register number resulting from the identification of each immigrant through his or her personal information and fingerprints.

• "ctps" (Employment and Social Security Card) Is a document that contains information about the worker's professional life and his affiliation to the National Institute of Social Security - INSS.

• "passport" Personal and non-transferable document, issued by the authority of a State for the free transit of its nationals in the country that admits them to its territory.

• "outros" (Others) When there is a document in the image but it is not of a type mapped by us.

• "invalido" (Invalid) When there is no document in the image.

Example: cnh

sectionsobjectRequired

Contains the data on the services performed as defined by the Query template. Each attribute represents a service.

fraudbooleanOptional

Indicates whether it is an attempt at fraud or not.

Example: false

documentscopyRequestDatestring · date-timeOptional

Datetime the document went to documentscopy.

Example: 2022-09-08T22:11:05.816Z

variablesobjectOptional

Variables of Web Onboarding.

metadataobjectOptional

Some internal control fields + the fields sent in the metadata attribute of the transaction creation.

400

Bad request

application/json

401

Unauthorized

application/json

500

Internal Server Error

application/json

get/{transactionId}

GET /v1/transactions/{transactionId} HTTP/1.1
Host: api.us.prd.caf.io
Authorization: text
Accept: */*

{
  "requestId": "2b8f373-c462-4bbf-9a4f-8aeb7d71ec53",
  "id": "6388a3e9a73b280008ba31ad",
  "status": "APPROVED",
  "customStatus": null,
  "templateId": "638a021fdeb2b90008c790d1",
  "onboardingId": null,
  "attributes": {
    "cpf": "00011122233",
    "nit": "123456789",
    "phoneNumber": "+5511999999999",
    "name": "John Doe",
    "email": "[email protected]",
    "birthDate": "1990-01-01",
    "companyId": "123456789",
    "cnpj": "12345678000195",
    "fantasyName": "Doe Enterprises",
    "officialName": "Doe & Partners Ltda.",
    "monthlyBilling": "50000.00",
    "annuallyBilling": "600000.00",
    "scoreCheckGroup": "A",
    "address": {
      "street": "Main St",
      "number": "123",
      "complement": "Apartment 45",
      "neighborhood": "Downtown",
      "zipCode": "12345678",
      "city": "São Paulo",
      "state": "SP"
    },
    "acceptedTermsData": [
      {
        "name": "Privacy Policy",
        "link": "https://example.com/privacy",
        "datetime": "2024-01-01T12:00:00Z",
        "userIp": "192.168.0.1",
        "userAgent": "Mozilla/5.0"
      }
    ],
    "customForms": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "relationships": [
      {
        "cpf": "00011122233",
        "cnpj": "12345678000195"
      }
    ],
    "qsa": [
      {
        "documentNumber": "00011122233",
        "cpf": "00011122233",
        "partialCpf": "***.111.222-**",
        "name": "Jane Doe",
        "email": "[email protected]",
        "phoneNumber": "+5511999999999",
        "onboardingId": "abcd1234",
        "onboardingToken": "xyz987"
      }
    ],
    "employee": {
      "name": "John Doe",
      "occupation": "Software Engineer",
      "email": "[email protected]",
      "phoneNumber": 5511999999999
    },
    "coordinates": {
      "latitude": -23.55052,
      "longitude": -46.633308,
      "accuracy": 5
    },
    "deviceId": "12345abcd",
    "userIp": "192.168.0.1",
    "monthlyIncome": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "occupation": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "motherName": "Mary Doe",
    "issueDate": "2024-01-01",
    "rg": 12345678,
    "rgIssueDate": "2024-01-01",
    "partners": [
      {
        "documentNumber": 11122233,
        "cpf": 11122233,
        "partialCpf": "000.111.***",
        "name": "John Doe",
        "participation": 50,
        "type": "Administrator"
      }
    ]
  },
  "createdAt": "2022-09-08T22:10:14.816Z",
  "type": "cnh",
  "images": {
    "back": "https://example.com/image-back.jpg",
    "front": "https://example.com/image-front.jpg",
    "selfie": "https://example.com/selfie.jpg",
    "selectedBack": "https://example.com/image-back-cropped.jpg",
    "selectedFront": "https://example.com/image-front-cropped.jpg"
  },
  "sections": {},
  "fraud": false,
  "files": [
    {
      "name": "Address proof",
      "src": "https://example.com/address-proof.pdf"
    }
  ],
  "documentscopyRequestDate": "2022-09-08T22:11:05.816Z",
  "relatedTransactions": {},
  "history": [
    {
      "type": "STATUS_UPDATE",
      "status": "REPROVED",
      "date": "2022-09-08T22:12:17.816Z"
    }
  ],
  "statusReasons": [
    {
      "category": "VALIDATION",
      "resultStatus": "APPROVED",
      "resultCustomStatus": "text",
      "code": "facematch_is_equal",
      "status": "VALID",
      "description": null,
      "descriptions": [
        null
      ],
      "user": null,
      "date": null,
      "reviewType": null
    }
  ],
  "manualReprovalReasons": [
    {
      "code": "50",
      "reason": "Documento ilegível: qualidade da foto está ruim."
    }
  ],
  "variables": {},
  "metadata": {}
}

Ensure your OAuth2 client has the necessary permissions for each endpoint. Permissions are managed in Trust. Requests without proper permissions will result in a 403 Forbidden error.

Last updated 4 days ago