Transação

Quando você envia uma consulta aos serviços Anti-Fraud, você cria uma Transação. Uma transação pode conter a execução de um ou mais serviços configurados no modelo de consulta ou informados no corpo da requisição. Esses serviços podem ser análises internas ou consultas externas que são executadas na esteira de processamento. Depois disso, com base nas regras de validação, o status é definido para a transação.

Os serviços e as regras de validação podem ser configurados somente no template da consulta.

Uma transação é caracterizada por um endpoint em que os serviços necessários podem ser informados e por um conjunto de regras validadas.

Documentação relacionada:

Se você usa os SDKs da Certta e precisa vincular tokens móveis a transações, acesse Vinculação de transações
Para entender a estrutura e os serviços disponíveis nas respostas de transações, acesse Transações

Webhooks de transação: Transações criadas diretamente por meio de POST /transactions não emitem TRANSACTIONPROCESSSTARTEDEVENT. Use a transação id retornada pela requisição de criação para correlacionar os subsequentes TRANSACTIONSTATUSUPDATEDEVENT e eventos relacionados. Consulte Eventos de webhook.

Para detalhes sobre autenticação, acesse Autenticação.

Requisitos de autenticação:

Os endpoints regulares usam OAuth2 autenticação com URL base: https://api.us.prd.caf.io
Para segurança aprimorada, alguns endpoints também podem oferecer suporte a mTLS autenticação com URL base: https://mtls.us.prd.caf.io
Para obter informações sobre a implementação de mTLS, acesse Usando mTLS

Endpoints compatíveis

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

Autorizações

AuthorizationstringObrigatório

Bearer authentication header of the form Bearer <token>.

Parâmetros de consulta

originstringObrigatório

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

Parâmetros de cabeçalho

AuthorizationstringObrigatório

Access token.

Example: Bearer your_token_here

Corpo

templateIdstringObrigatório

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

metadataobjectOpcional

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

referenceTokenstringOpcional

Mobile Token (Session Token).

_callbackUrlstring · uriOpcional

Callback URL (webhook).

Respostas

200

Success

application/json

requestIdstringOpcional

Unique identifier of request.

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

idstringOpcional

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

Autorizações

AuthorizationstringObrigatório

Bearer authentication header of the form Bearer <token>.

Parâmetros de cabeçalho

AuthorizationstringObrigatório

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

Example: Bearer your_token_here

Corpo

filestring · binaryObrigatório

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

Respostas

201

Created

application/json

requestIdstringOpcional

Unique identifier of request.

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

messagestringOpcional

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

Autorizações

AuthorizationstringObrigatório

Bearer authentication header of the form Bearer <token>.

Parâmetros de consulta

_limitnumberOpcional

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

_orderstringOpcional

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

_templatesstringOpcional

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 · dateOpcional

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

_endCreatedDatestring · dateOpcional

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

Parâmetros de cabeçalho

AuthorizationstringObrigatório

Access token. See more in the 'Authentication' topic

Example: Bearer your_token_here

Respostas

200

Success

application/json

requestIdstringObrigatório

Unique identifier of request.

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

totalItemsintegerObrigatório

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

Autorizações

AuthorizationstringObrigatório

Bearer authentication header of the form Bearer <token>.

Parâmetros de rota

transactionIdstringObrigatório

Transaction identifier.

Parâmetros de consulta

_includePfRelationshipsbooleanOpcional

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

Default: false

_includeCroppedImagesbooleanOpcional

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

Default: false

_langstringOpcional

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

Parâmetros de cabeçalho

AuthorizationstringObrigatório

Access token. See more in the 'Authentication' topic

Respostas

200

Success

application/json

requestIdstringObrigatório

Unique identifier of request.

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

idstringObrigatório

Unique identifier of transaction.

Example: 6388a3e9a73b280008ba31ad

statusstring · enumObrigatório

Status of transaction.

Example: APPROVEDValores possíveis:

customStatusstring · anulávelOpcional

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.

templateIdstringOpcional

Unique ID of the Query Template.

Example: 638a021fdeb2b90008c790d1

onboardingIdstringOpcional

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-timeObrigatório

Transaction creation date.

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

typestringOpcional

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

sectionsobjectObrigatório

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

fraudbooleanOpcional

Indicates whether it is an attempt at fraud or not.

Example: false

documentscopyRequestDatestring · date-timeOpcional

Datetime the document went to documentscopy.

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

variablesobjectOpcional

Variables of Web Onboarding.

metadataobjectOpcional

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": {}
}

Certifique-se de que seu OAuth2 cliente tenha as permissões necessárias para cada endpoint. As permissões são gerenciadas em Trust. Requisições sem as permissões adequadas resultarão em um 403 Forbidden erro.

Atualizado há 6 dias