---
updatedAt: 2026-04-23T18:12:51.000Z
agentTools:
siteIndex: https://developers.pismo.io/llms.txt
projectIndex: https://developers.pismo.io/pismo-docs/llms.txt
---
# Create fraud marker
Creates a fraud marker.
On PSP timeout, a `202 Accepted` response is returned with a fraud marker ID. The process continues asynchronously and, if it doesn't succeed, a failure event is emitted.
This endpoint generates a Fraud Marker registration event or failure event.
# OpenAPI definition
```json
{
"openapi": "3.1.0",
"info": {
"title": "Instant payments - Pix management",
"description": "API responsible for providing Pix operations (related to DICT) via integrating with external providers",
"contact": {
"name": "API Support",
"url": "https://developers.pismo.io/support/"
},
"license": {
"name": "Copyright Pismo"
},
"version": "0.0.1"
},
"servers": [
{
"url": "https://sandbox.pismolabs.io/pix-dict",
"description": "Sandbox API server for testing."
}
],
"tags": [
{
"name": "Anti-fraud",
"description": "Manage anti-fraud endpoints"
}
],
"components": {
"securitySchemes": {
"BearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT"
}
},
"parameters": {
"AuthHeader": {
"in": "header",
"name": "Authorization",
"required": true,
"description": "Account token - token encoded with a Pismo account ID. Tokens can expire quickly, which can result in a 401 Unauthorized message.",
"schema": {
"type": "string",
"example": "Bearer eyJhbGci...IUzUx"
}
},
"IdempotencyKeyHeader": {
"name": "Idempotency-Key",
"in": "header",
"description": "A unique UUID identifier to ensure the operation remains idempotent, allowing for operation repitition without causing unintended effects or duplication. An idempotent operation is one that can be applied multiple times, yet the outcome remains the same. it ensures that network errors, retries, or failures can occur without introducing inconsistencies.\n",
"required": true,
"schema": {
"type": "string"
},
"example": "550e8400-e29b-41d4-a716-446655440000"
}
},
"headers": {
"XCidResponseHeader": {
"description": "Request tracking identifier.",
"schema": {
"type": "string"
}
}
},
"schemas": {
"BacenCreationDateTime": {
"type": "string",
"format": "date-time",
"description": "Date of infraction report creation. RFC 3339 date-time value. For example - `2023-04-12T23:20:50.52Z`. \n",
"example": "2020-08-13T13:49:03Z"
},
"BacenLastModifiedDateTime": {
"type": "string",
"format": "date-time",
"description": "Date of infraction report modification. RFC 3339 date-time value. For example - `2023-04-12T23:20:50.52Z`. \n",
"example": "2020-08-13T13:49:03Z"
},
"DocumentNumber": {
"type": "string",
"description": "A government document number, such as a Social Security number (US) or Cadastro de Pessoas Físicas number (Brazil). Must be numeric with 11-14 digits.\n",
"minLength": 11,
"maxLength": 14,
"example": "123412341234"
},
"FraudMarkerAcceptedResponse": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"$ref": "#/components/schemas/FraudMarkerID"
}
}
},
"FraudMarkerCreationRequest": {
"type": "object",
"required": [
"document_number",
"fraud_type"
],
"properties": {
"document_number": {
"type": "string",
"description": "User's tax ID number (CPF or CNPJ) associated with the fraud marker."
},
"fraud_type": {
"type": "string",
"description": "Type of fraud. For fraud marking coming from infraction reports closed in API V1, the value `UNKNOWN` will appear.",
"example": "APPLICATION_FRAUD",
"enum": [
"APPLICATION_FRAUD",
"MULE_ACCOUNT",
"SCAMMER_ACCOUNT",
"OTHER",
"UNKNOWN"
]
},
"key": {
"type": "string",
"description": "Key associated with fraud marker. It must be reported, if known",
"maxLength": 77
}
}
},
"FraudMarkerFraudType": {
"type": "string",
"description": "Verified fraud type",
"example": "APPLICATION_FRAUD",
"enum": [
"APPLICATION_FRAUD",
"MULE_ACCOUNT",
"SCAMMER_ACCOUNT",
"OTHER",
"UNKNOWN"
]
},
"FraudMarkerID": {
"type": "string",
"format": "uuid",
"description": "Fraud marker ID",
"example": "ea8bc045-9ff7-439f-a318-2e6f974707a5"
},
"FraudMarkerKey": {
"type": "string",
"description": "Key to which the fraud marker will be associated. It must be reported, if known",
"maxLength": 77
},
"FraudMarkerResponse": {
"required": [
"id",
"document_number",
"fraud_type",
"status",
"bacen_creation_datetime",
"bacen_last_modified_datetime"
],
"type": "object",
"properties": {
"id": {
"$ref": "#/components/schemas/FraudMarkerID"
},
"document_number": {
"$ref": "#/components/schemas/DocumentNumber"
},
"fraud_type": {
"$ref": "#/components/schemas/FraudMarkerFraudType"
},
"status": {
"$ref": "#/components/schemas/InfractionFraudMarkerStatus"
},
"key": {
"$ref": "#/components/schemas/FraudMarkerKey"
},
"bacen_creation_datetime": {
"$ref": "#/components/schemas/BacenCreationDateTime"
},
"bacen_last_modified_datetime": {
"$ref": "#/components/schemas/BacenLastModifiedDateTime"
}
}
},
"InfractionFraudMarkerStatus": {
"type": "string",
"description": "Fraud marker status",
"example": "REGISTERED",
"enum": [
"REGISTERED",
"CANCELLED"
]
},
"message.DetailMessage": {
"type": "object",
"properties": {
"external": {
"type": "array",
"items": {
"$ref": "#/components/schemas/message.ExternalMessage"
}
},
"parameters": {
"type": "array",
"items": {
"$ref": "#/components/schemas/message.ParameterMessage"
}
},
"payload": {
"type": "array",
"items": {
"$ref": "#/components/schemas/message.PayloadMessage"
}
}
}
},
"message.ExternalMessage": {
"required": [
"code",
"message"
],
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Error code",
"example": "PBE315"
},
"message": {
"type": "string",
"description": "Error message",
"example": "Generic error"
}
}
},
"message.Message": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Error code",
"example": "EPDA0001"
},
"details": {
"$ref": "#/components/schemas/message.DetailMessage"
},
"message": {
"type": "string",
"description": "Error message",
"example": "User not found"
}
}
},
"message.ParameterMessage": {
"type": "object",
"required": [
"field",
"message"
],
"properties": {
"field": {
"type": "string",
"description": "Parameter in error",
"example": "query parameter"
},
"message": {
"type": "string",
"description": "Error message",
"example": "Generic error"
}
}
},
"message.PayloadMessage": {
"type": "object",
"required": [
"field",
"message"
],
"properties": {
"field": {
"type": "string",
"description": "Field in error",
"example": "Entity.field"
},
"message": {
"type": "string",
"description": "Error messsage",
"example": "Generic error"
}
}
}
},
"responses": {
"401Unauthorized": {
"description": "Unauthorized",
"headers": {
"x-cid": {
"$ref": "#/components/headers/XCidResponseHeader"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/message.Message"
},
"examples": {
"Provider service error": {
"value": {
"code": "EPDG0013",
"message": "Unauthorized access to the provider service"
}
}
}
}
}
},
"403Forbidden": {
"description": "Forbidden",
"headers": {
"x-cid": {
"$ref": "#/components/headers/XCidResponseHeader"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/message.Message"
},
"examples": {
"EPDA0009": {
"summary": "Missing required header 'x-tenant'",
"value": {
"code": "EPDA0009",
"message": "Missing required header 'x-tenant'"
}
},
"EPDA0010": {
"summary": "Missing required header 'x-account-id'",
"value": {
"code": "EPDA0010",
"message": "Missing required header 'x-account-id'"
}
},
"EPDA0152": {
"summary": "Missing required param 'id'",
"value": {
"code": "EPDA0152",
"message": "Missing required param 'id'"
}
}
}
}
}
},
"429TooManyRequests": {
"description": "Too many requests",
"headers": {
"x-cid": {
"$ref": "#/components/headers/XCidResponseHeader"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/message.Message"
}
}
}
},
"502BadGateway": {
"description": "Bad Gateway",
"headers": {
"x-cid": {
"$ref": "#/components/headers/XCidResponseHeader"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/message.Message"
},
"examples": {
"Provider authentication service error": {
"value": {
"code": "EPDG0020",
"message": "Provider authentication service is unable to complete the request"
}
}
}
}
}
},
"504GatewayTimeout2": {
"description": "Gateway Timeout",
"headers": {
"x-cid": {
"$ref": "#/components/headers/XCidResponseHeader"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/message.Message"
},
"examples": {
"Service timeout": {
"value": {
"code": "EPDA0000",
"message": "Timeout while executing the request"
}
},
"Provider timeout": {
"value": {
"code": "EPDG0000",
"message": "Timeout while executing the request"
}
}
}
}
}
}
}
},
"security": [
{
"BearerAuth": []
}
],
"x-readme": {
"explorer-enabled": true,
"proxy-enabled": true,
"samples-enabled": true
},
"paths": {
"/v2/pix/fraud-markers": {
"post": {
"summary": "Create fraud marker",
"description": "Creates a fraud marker. \n\nOn PSP timeout, a `202 Accepted` response is returned with a fraud marker ID. The process continues asynchronously and, if it doesn't succeed, a failure event is emitted.\n\nThis endpoint generates a Fraud Marker registration event or failure event.\n",
"operationId": "post-v2-pix-fraud-marker-create",
"tags": [
"Anti-fraud"
],
"parameters": [
{
"$ref": "#/components/parameters/AuthHeader"
},
{
"$ref": "#/components/parameters/IdempotencyKeyHeader"
}
],
"requestBody": {
"description": "Fraud Marker",
"content": {
"*/*": {
"schema": {
"$ref": "#/components/schemas/FraudMarkerCreationRequest"
}
}
},
"required": true
},
"responses": {
"201": {
"description": "OK",
"headers": {
"x-cid": {
"$ref": "#/components/headers/XCidResponseHeader"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FraudMarkerResponse"
}
}
}
},
"202": {
"description": "Accepted. The process will be processed asynchronous and will send a event via SNS when OK",
"headers": {
"x-cid": {
"$ref": "#/components/headers/XCidResponseHeader"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FraudMarkerAcceptedResponse"
}
}
}
},
"400": {
"description": "Bad Request",
"headers": {
"x-cid": {
"$ref": "#/components/headers/XCidResponseHeader"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/message.Message"
},
"examples": {
"Invalid binding": {
"value": {
"code": "EPDA0002",
"message": "Failed to unmarshal request body"
}
},
"Validate errors": {
"value": {
"code": "EPDA0003",
"message": "There are invalid fields when trying to validate request body",
"details": {
"payload": [
{
"field": "FraudMarkerCreationRequest.fraud_type",
"message": "Field validation for 'fraud_type' failed on the 'oneof' tag"
}
]
}
}
}
}
}
}
},
"401": {
"$ref": "#/components/responses/401Unauthorized"
},
"403": {
"$ref": "#/components/responses/403Forbidden"
},
"409": {
"description": "Conflict",
"headers": {
"x-cid": {
"$ref": "#/components/headers/XCidResponseHeader"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/message.Message"
},
"examples": {
"Fraud marker already registered": {
"summary": "Fraud marker already registered with different value",
"value": {
"code": "EPDA0166",
"message": "Fraud marker already registered with different values for the idempotency key"
}
}
}
}
}
},
"429": {
"$ref": "#/components/responses/429TooManyRequests"
},
"500": {
"description": "Internal Server Error",
"headers": {
"x-cid": {
"$ref": "#/components/headers/XCidResponseHeader"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/message.Message"
},
"examples": {
"Provider service communication error": {
"value": {
"code": "EPDA0029",
"message": "Internal errors while attempting to communicate with the provider service"
}
},
"Invalid client error": {
"value": {
"code": "EPDG0005",
"message": "Invalid Pix provider '{provider_name}'"
}
},
"Failed marshalling object": {
"value": {
"code": "EPDG0006",
"message": "Failed to marshal JSON object"
}
},
"Failed unmarshalling object": {
"value": {
"code": "EPDG0007",
"message": "Failed to unmarshal JSON object"
}
},
"Error reading response data": {
"value": {
"code": "EPDG0010",
"message": "I/O error while reading response data: '{details}'"
}
},
"Provider service error": {
"value": {
"code": "EPDG0016",
"message": "Provider service returned an internal error while trying to access the resource",
"details": {
"external": [
{
"code": "PBE315",
"message": "Generic error"
}
]
}
}
}
}
}
}
},
"502": {
"$ref": "#/components/responses/502BadGateway"
},
"503": {
"description": "Service Unavailable",
"headers": {
"x-cid": {
"$ref": "#/components/headers/XCidResponseHeader"
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/message.Message"
},
"examples": {
"Provider service unavailable": {
"value": {
"code": "EPDG0017",
"message": "Provider service resource is unavailable"
}
},
"Provider authentication service unavailable": {
"value": {
"code": "EPDG0021",
"message": "Provider authentication service is unavailable"
}
}
}
}
}
},
"504": {
"$ref": "#/components/responses/504GatewayTimeout2"
}
},
"security": [
{
"BearerAuth": []
}
]
}
}
}
}
```