components: schemas: AbatementObject: additionalProperties: true properties: modality: examples: - PERCENT minLength: 1 type: string value: examples: - "3.00" minLength: 1 type: string required: - modality - value type: object AccountDetails: additionalProperties: false properties: branch: examples: - "0001" type: string number: examples: - "123456789" type: string participant: examples: - "12345678" type: string type: enum: - CACC - SVGS - TRAN - OTHR examples: - TRAN type: string required: - branch - number - participant - type type: object AccountOutput: additionalProperties: false properties: branch: description: Bank branch code where the account is held (4 digits) examples: - "0001" type: string id: description: Unique identifier of the customer account examples: - 550e8400-e29b-41d4-a716-446655440000 type: string number: description: "Unique account number at the institution, as sent to DICT: 1-20 uppercase letters or digits, ending in a digit" examples: - "123456789" type: string openingDate: description: Date when the account was opened examples: - "2020-01-15T10:30:00Z" format: date-time type: string participant: description: ISPB of the participant institution (8 uppercase alphanumeric characters) examples: - "12345678" type: string type: description: Kind of account holding this Pix key enum: - CACC - SLRY - SVGS - TRAN - OTHR examples: - TRAN type: string required: - id - participant - branch - number - type - openingDate type: object AcknowledgeClaimOutput: additionalProperties: false properties: accountId: description: Unique identifier of the account associated with this claim examples: - 550e8400-e29b-41d4-a716-446655440002 type: string bacenClaimId: description: BACEN DICT identifier for this claim examples: - cc91b1b0-8465-44b1-a760-15dd3717ea9b type: string cancelReason: description: Reason for cancellation (if applicable) examples: - "" type: string cancelledBy: description: Who cancelled the claim (if applicable) examples: - "" type: string claimer: $ref: "#/components/schemas/Claimer" description: Account owner information claimerAccount: $ref: "#/components/schemas/ClaimerAccount" description: Account information of the claimer completionPeriodEnd: description: Deadline for claim completion - D+14 from creation (ISO 8601 UTC) examples: - "2020-09-14T13:48:55.970Z" format: date-time type: string confirmReason: description: Reason the claim was confirmed (if applicable) examples: - "" type: string createdAt: description: Timestamp when the claim was created (ISO 8601 UTC) examples: - "2020-08-17T13:48:36Z" format: date-time type: string donorParticipant: description: ISPB of the donor PSP (current key holder) examples: - "30306294" type: string holderId: description: UUID of the account holder (claimer) examples: - 550e8400-e29b-41d4-a716-446655440001 type: string id: description: Internal UUID of the claim examples: - 550e8400-e29b-41d4-a716-446655440000 type: string key: description: The PIX key value (phone, email, CPF, CNPJ, or EVP) examples: - "+5561988887777" type: string keyType: description: Type of PIX key examples: - PHONE type: string resolutionPeriodEnd: description: Deadline for donor response - D+7 from creation (ISO 8601 UTC) examples: - "2020-08-24T13:48:55.970Z" format: date-time type: string status: description: Current status of the claim (should be WAITING_RESOLUTION after acknowledge) examples: - WAITING_RESOLUTION type: string type: description: Type of claim (OWNERSHIP or PORTABILITY) examples: - OWNERSHIP type: string updatedAt: description: Timestamp when the claim was last updated (ISO 8601 UTC) examples: - "2024-01-20T14:45:00Z" format: date-time type: string required: - id - accountId - bacenClaimId - holderId - status - type - key - keyType - claimer - claimerAccount - donorParticipant - confirmReason - cancelReason - cancelledBy - resolutionPeriodEnd - completionPeriodEnd - createdAt - updatedAt type: object AdminCompleteCollectionBody: additionalProperties: false properties: id: description: Identifier of the completed collection type: string status: description: Collection status after completion (COMPLETED on success) type: string required: - id - status type: object AmountObject: additionalProperties: true properties: abatement: $ref: "#/components/schemas/AbatementObject" discount: $ref: "#/components/schemas/DiscountObject" fine: $ref: "#/components/schemas/FineObject" interest: $ref: "#/components/schemas/InterestObject" original: examples: - "100.00" minLength: 1 type: string required: - original type: object AuthorizationOutput: additionalProperties: false properties: accountId: examples: - 019cf6ef-e418-7ced-80c0-7b9816faa798 type: string amount: $ref: "#/components/schemas/AuthorizationRequestAmountProfile" approvedAt: format: date-time type: string authorizationRequestId: examples: - 019cf6ef-e418-7ced-80c0-7b9816faa798 type: string cancelReason: enum: - PAYER - FRAUD - EXPIRED - RECEIVER type: string cancellationReason: examples: - Customer reported unauthorized charge type: string cancellationReasonKind: enum: - PAYER - FRAUD - EXPIRED - RECEIVER examples: - FRAUD type: string cancelledAt: format: date-time type: string cancelledByOperatorId: examples: - op-9 type: string createdAt: format: date-time type: string destination: $ref: "#/components/schemas/AuthorizationRequestDestination" expiredAt: format: date-time type: string externalAuthorizationId: examples: - AUT-2026-04-001 type: string id: examples: - 019cf6ef-e418-7ced-80c0-7b9816faa798 type: string nextChargeAmount: examples: - "29.90" type: string nextChargeAt: format: date-time type: string periodicity: $ref: "#/components/schemas/AuthorizationRequestPeriodicity" receiverMaxAmount: examples: - "500.00" type: string retryPolicy: examples: - RETRY_3X_7D type: string status: enum: - AUTHORIZED - CANCELLED - EXPIRED examples: - AUTHORIZED type: string updatedAt: format: date-time type: string required: - id - authorizationRequestId - accountId - externalAuthorizationId - destination - periodicity - amount - retryPolicy - status - approvedAt - createdAt - updatedAt type: object AuthorizationRequestAmountProfile: additionalProperties: false properties: fixed: examples: - "29.90" type: string max: examples: - "500.00" type: string min: examples: - "10.00" type: string type: object AuthorizationRequestDestination: additionalProperties: false properties: account: examples: - "123456" type: string accountType: enum: - CACC - SVGS - TRAN - OTHR examples: - CACC type: string bank: examples: - "30306294" type: string branch: examples: - "0001" type: string document: examples: - "11222333000181" type: string key: examples: - contato@streaming.co type: string name: examples: - Streaming Co type: string personType: enum: - NATURAL_PERSON - LEGAL_PERSON examples: - LEGAL_PERSON type: string type: object AuthorizationRequestOutput: additionalProperties: false properties: acceptedMaxAmount: examples: - "500.00" type: string accountId: examples: - 019cf6ef-e418-7ced-80c0-7b9816faa798 type: string amount: $ref: "#/components/schemas/AuthorizationRequestAmountProfile" approvingAt: format: date-time type: string cancellationCode: examples: - ACCL type: string cancellationRequester: examples: - PSP_PAYEE type: string cancelledAt: format: date-time type: string confirmedAt: format: date-time type: string createdAt: format: date-time type: string description: examples: - Streaming subscription type: string destination: $ref: "#/components/schemas/AuthorizationRequestDestination" expiredAt: format: date-time type: string externalRequestId: examples: - RREC-2026-04-001 type: string firstChargeId: examples: - 019cf6ef-e418-7ced-80c0-7b9816faa798 type: string id: examples: - 019cf6ef-e418-7ced-80c0-7b9816faa798 type: string journey: examples: - J1 type: string payeeRejectionCode: examples: - MD20 type: string payeeRejectionDescription: type: string periodicity: $ref: "#/components/schemas/AuthorizationRequestPeriodicity" rejectedAt: format: date-time type: string replyFailedAt: format: date-time type: string replyFailureReason: type: string retryPolicy: examples: - RETRY_3X_7D type: string status: enum: - PENDING - INITIATED - APPROVING - CONFIRMED - REJECTED - PAYMENT_FAILED - REPLY_FAILED - CANCELLED - EXPIRED examples: - PENDING type: string updatedAt: format: date-time type: string validUntil: examples: - "2026-06-30T23:59:59Z" format: date-time type: string required: - id - accountId - externalRequestId - destination - periodicity - amount - retryPolicy - validUntil - journey - status - createdAt - updatedAt type: object AuthorizationRequestPeriodicity: additionalProperties: false properties: customDays: examples: - 30 format: int64 type: integer type: enum: - WEEKLY - MONTHLY - QUARTERLY - SEMIANNUAL - ANNUAL - CUSTOM examples: - MONTHLY type: string required: - type type: object CancelAuthorizationInput: additionalProperties: false properties: cancelledBy: examples: - agent-4417 maxLength: 255 type: string evidenceReference: examples: - FRAUD-CASE-2026-0042 maxLength: 200 type: string reasonKind: enum: - PAYER - FRAUD examples: - PAYER minLength: 1 type: string reasonText: examples: - Customer reported unauthorized charge maxLength: 500 type: string required: - reasonKind type: object CancelAuthorizationOutput: additionalProperties: false properties: authorization: $ref: "#/components/schemas/CancelledAuthorizationView" required: - authorization type: object CancelClaimOutput: additionalProperties: false properties: accountId: description: Unique identifier of the account associated with this claim examples: - 550e8400-e29b-41d4-a716-446655440002 type: string bacenClaimId: description: BACEN DICT identifier for this claim examples: - cc91b1b0-8465-44b1-a760-15dd3717ea9b type: string cancelReason: description: Reason for cancellation examples: - FRAUD type: string cancelledBy: description: Who cancelled the claim (DONOR or CLAIMER) examples: - DONOR type: string claimer: $ref: "#/components/schemas/Claimer" description: Account owner information claimerAccount: $ref: "#/components/schemas/ClaimerAccount" description: Account information of the claimer completedAt: description: Timestamp when the claim was completed (ISO 8601 UTC) examples: - "2020-08-31T13:48:55.970Z" format: date-time type: string completionPeriodEnd: description: Deadline for claim completion - D+14 from creation (ISO 8601 UTC) examples: - "2020-09-14T13:48:55.970Z" format: date-time type: string confirmReason: description: Reason the claim was confirmed examples: - DEFAULT_OPERATION type: string createdAt: description: Timestamp when the claim was created (ISO 8601 UTC) examples: - "2020-08-17T13:48:36Z" format: date-time type: string donorParticipant: description: ISPB of the donor PSP (current key holder) examples: - "30306294" type: string holderId: description: UUID of the account holder (claimer) examples: - 550e8400-e29b-41d4-a716-446655440001 type: string id: description: Internal UUID of the claim examples: - 550e8400-e29b-41d4-a716-446655440000 type: string key: description: The PIX key value (phone, email, CPF, CNPJ, or EVP) examples: - "+5561988887777" type: string keyType: description: Type of PIX key examples: - PHONE type: string resolutionPeriodEnd: description: Deadline for donor response - D+7 from creation (ISO 8601 UTC) examples: - "2020-08-31T13:48:55.970Z" format: date-time type: string status: description: Current status of the claim examples: - CANCELLED type: string type: description: Type of claim (OWNERSHIP or PORTABILITY) examples: - OWNERSHIP type: string updatedAt: description: Timestamp when the claim was last updated (ISO 8601 UTC) examples: - "2024-01-20T14:45:00Z" format: date-time type: string required: - id - accountId - bacenClaimId - holderId - status - type - key - keyType - claimer - claimerAccount - donorParticipant - confirmReason - cancelReason - cancelledBy - completedAt - resolutionPeriodEnd - completionPeriodEnd - createdAt - updatedAt type: object CancelInfractionReportOutput: additionalProperties: false properties: accountId: description: Account ID (UUID) of the contested Pix transfer when the report arrived through BTG; empty when it was opened through this API examples: - 550e8400-e29b-41d4-a716-446655440000 type: string analysisDetails: description: Detailed analysis from counterparty examples: - Analysis confirms fraudulent activity pattern type: string analysisResult: description: Analysis result from counterparty (if closed) enum: - AGREED - DISAGREED examples: - AGREED type: string bacenFundsRecoveryId: description: BACEN/BTG funds-recovery identifier linking this infraction to its MED Funds Recovery process examples: - 91d65e98-97c0-4b0f-b577-73625da1f9fc type: string contactInformation: $ref: "#/components/schemas/ContactInformation" description: Contact information of the person reporting the fraud counterpartyParticipant: description: ISPB of the counterparty PSP involved in the transaction examples: - "87654321" type: string createdAt: description: Timestamp when the report was created (ISO 8601 UTC) examples: - "2023-11-07T05:31:56Z" format: date-time type: string fraudMarkerId: description: Unique fraud marker identifier from BACEN examples: - FM123456789 type: string id: description: Unique identifier for the infraction report (UUID) examples: - 550e8400-e29b-41d4-a716-446655440000 type: string infractionAmount: description: Monetary amount of the infraction in BRL examples: - "1500.00" type: string reason: description: Report reason type examples: - REFUND_REQUEST type: string reportDetails: description: Detailed description of the fraud incident examples: - Customer reported receiving a call from fake bank employee requesting PIX payment for supposed security verification type: string reporterParticipant: description: ISPB of the PSP reporting the infraction examples: - "12345678" type: string situationType: description: Type of fraud situation examples: - SCAM type: string status: description: Current status of the infraction report enum: - OPEN - ACKNOWLEDGED - CLOSED - CANCELLED examples: - CANCELLED type: string transactionDepth: description: Depth of the infraction's transaction in the DICT tracking graph (root = 1). Set by DICT; absent until DICT provides it. examples: - 1 format: int64 type: integer transactionId: description: PIX End-to-End transaction ID (32 alphanumeric characters) examples: - E12345678202411241430ABCDEFGHIJK type: string updatedAt: description: Timestamp when the report was last updated (ISO 8601 UTC) examples: - "2023-11-07T06:45:30Z" format: date-time type: string required: - id - accountId - transactionId - reason - situationType - contactInformation - status - reporterParticipant - counterpartyParticipant - createdAt - updatedAt type: object CancelledAuthorizationView: additionalProperties: false properties: cancellationReasonKind: enum: - PAYER - FRAUD examples: - PAYER type: string cancelledAt: examples: - "2026-05-05T22:30:00Z" format: date-time type: string effectiveFrom: examples: - "2026-05-06" format: date type: string id: examples: - 019cf6ef-e418-7ced-80c0-7b9816faa798 type: string status: enum: - CANCELLED examples: - CANCELLED type: string required: - id - status - cancellationReasonKind - cancelledAt - effectiveFrom type: object ChargeAttemptOutput: additionalProperties: false properties: attemptedAt: format: date-time type: string dayIndex: examples: - 0 format: int64 type: integer endToEndId: examples: - E30306294202606241200abcdef00001 type: string failureCode: examples: - DEBIT_FAILED type: string failureMessage: examples: - The debit attempt could not be completed. type: string outcome: enum: - EXECUTED - FAILED - CANCELLED examples: - EXECUTED type: string scheduleId: examples: - 019cf6ef-e418-7ced-80c0-7b9816faa798 type: string scheduledFor: examples: - "2026-04-24T03:00:00Z" format: date-time type: string required: - scheduleId - dayIndex - scheduledFor type: object ChargeOutput: additionalProperties: false properties: accountId: examples: - 019cf6ef-e418-7ced-80c0-7b9816faa798 type: string amount: examples: - "29.90" type: string attemptCount: examples: - 1 format: int64 type: integer attempts: items: $ref: "#/components/schemas/ChargeAttemptOutput" type: array authorizationId: examples: - 019cf6ef-e418-7ced-80c0-7b9816faa798 type: string authorizationRequestId: examples: - 019cf6ef-e418-7ced-80c0-7b9816faa798 type: string cancelledAt: format: date-time type: string createdAt: format: date-time type: string currentDayIndex: examples: - 0 format: int64 type: integer currentScheduleId: examples: - 019cf6ef-e418-7ced-80c0-7b9816faa798 type: string dueDate: examples: - "2026-04-25" format: date type: string executedAt: format: date-time type: string externalChargeId: examples: - 90d0b9e1551447f695985409bf9b7fb5 type: string failedAt: format: date-time type: string failureCode: examples: - CHARGE_REJECTED type: string id: examples: - 019cf6ef-e418-7ced-80c0-7b9816faa798 type: string journey: enum: - J1 - J2 - J3 - J4 examples: - J4 type: string maxAttempts: examples: - 4 format: int64 type: integer recurrenceId: examples: - 019cf6ef-e418-7ced-80c0-7b9816faa798 type: string status: enum: - RECEIVED - SCHEDULED - EXECUTED - FAILED - CANCELLED examples: - SCHEDULED type: string updatedAt: format: date-time type: string required: - id - accountId - authorizationRequestId - externalChargeId - amount - dueDate - attemptCount - maxAttempts - status - journey - attempts - createdAt - updatedAt type: object CheckKeysInput: additionalProperties: false properties: keys: description: List of PIX keys to verify existence items: $ref: "#/components/schemas/KeyCheckItem" maxItems: 200 minItems: 1 type: array required: - keys type: object CheckKeysOutput: additionalProperties: false properties: keys: description: Existence status for each verified key items: $ref: "#/components/schemas/KeyCheckResult" type: array required: - keys type: object ClaimListItem: additionalProperties: false properties: accountId: description: Unique identifier of the account associated with this claim examples: - 550e8400-e29b-41d4-a716-446655440002 type: string bacenClaimId: description: BACEN DICT identifier for this claim examples: - cc91b1b0-8465-44b1-a760-15dd3717ea9b type: string cancelReason: description: Reason for cancellation examples: - FRAUD type: string cancelledBy: description: Who cancelled the claim examples: - DONOR type: string claimer: $ref: "#/components/schemas/Claimer" description: Account owner information claimerAccount: $ref: "#/components/schemas/ClaimerAccount" description: Account information of the claimer completionPeriodEnd: description: Deadline for claim completion examples: - "2020-09-14T13:48:55.970Z" format: date-time type: string confirmReason: description: Reason the claim was confirmed examples: - DEFAULT_OPERATION type: string createdAt: description: Timestamp when the claim was created examples: - "2020-08-17T13:48:36Z" format: date-time type: string donorParticipant: description: ISPB of the donor PSP examples: - "30306294" type: string holderId: description: UUID of the account holder (claimer) examples: - 550e8400-e29b-41d4-a716-446655440001 type: string id: description: Internal UUID of the claim examples: - 550e8400-e29b-41d4-a716-446655440000 type: string key: description: The PIX key value examples: - "+5561988887777" type: string keyType: description: Type of PIX key examples: - PHONE type: string resolutionPeriodEnd: description: Deadline for donor response examples: - "2020-08-24T13:48:55.970Z" format: date-time type: string status: description: Current status of the claim examples: - OPEN type: string type: description: Type of claim (OWNERSHIP or PORTABILITY) examples: - OWNERSHIP type: string updatedAt: description: Timestamp when the claim was last updated examples: - "2024-01-20T14:45:00Z" format: date-time type: string required: - id - accountId - bacenClaimId - holderId - status - type - key - keyType - claimer - claimerAccount - donorParticipant - confirmReason - cancelReason - cancelledBy - resolutionPeriodEnd - completionPeriodEnd - createdAt - updatedAt type: object Claimer: additionalProperties: false properties: document: description: Identification document of the account owner (CPF or CNPJ) examples: - "52998224725" type: string name: description: Full name or legal name of the account owner examples: - Antonio Jose Raimundo type: string type: description: Whether the account owner is a person or organization enum: - NATURAL_PERSON - LEGAL_PERSON examples: - NATURAL_PERSON type: string required: - document - name - type type: object ClaimerAccount: additionalProperties: false properties: branch: description: Bank branch code where the account is held (4 digits) examples: - "0001" type: string number: description: "Unique account number at the institution, as sent to DICT: 1-20 uppercase letters or digits, ending in a digit" examples: - "2227654330" type: string openingDate: description: Date when the account was opened (ISO 8601 UTC) examples: - "2020-08-17T13:48:36Z" format: date-time type: string participant: description: ISPB of the participant institution (8 uppercase alphanumeric characters) examples: - "30306294" type: string type: description: Type of account holding the Pix key enum: - CACC - SVGS - TRAN - OTHR examples: - TRAN type: string required: - branch - number - openingDate - participant - type type: object CloseInfractionReportInput: additionalProperties: false properties: analysisDetails: description: Detailed analysis notes. Max 2000 characters. Required if fraudType is OTHER examples: - Fraud pattern confirmed through transaction history analysis maxLength: 2000 type: string analysisResult: description: "Analysis result: AGREED or DISAGREED" enum: - AGREED - DISAGREED examples: - AGREED minLength: 1 type: string fraudType: description: Type of fraud detected. Required if analysisResult is AGREED enum: - APPLICATION_FRAUD - MULE_ACCOUNT - SCAMMER_ACCOUNT - OTHER - UNKNOWN - "" examples: - SCAMMER_ACCOUNT type: string required: - analysisResult type: object CloseInfractionReportOutput: additionalProperties: false properties: accountId: description: Account ID (UUID) of the contested Pix transfer when the report arrived through BTG; empty when it was opened through this API examples: - 550e8400-e29b-41d4-a716-446655440000 type: string analysisDetails: description: Detailed analysis from counterparty examples: - Analysis confirms fraudulent activity pattern type: string analysisResult: description: Analysis result from counterparty enum: - AGREED - DISAGREED examples: - AGREED type: string bacenFundsRecoveryId: description: BACEN/BTG funds-recovery identifier linking this infraction to its MED Funds Recovery process examples: - 91d65e98-97c0-4b0f-b577-73625da1f9fc type: string contactInformation: $ref: "#/components/schemas/ContactInformation" description: Contact information of the person reporting the fraud counterpartyParticipant: description: ISPB of the counterparty PSP involved in the transaction examples: - "87654321" type: string createdAt: description: Timestamp when the report was created (ISO 8601 UTC) examples: - "2023-11-07T05:31:56Z" format: date-time type: string fraudMarkerId: description: Unique fraud marker identifier from BACEN examples: - FM123456789 type: string id: description: Unique identifier for the infraction report (UUID) examples: - 550e8400-e29b-41d4-a716-446655440000 type: string infractionAmount: description: Monetary amount of the infraction in BRL examples: - "1500.00" type: string reason: description: Report reason type examples: - REFUND_REQUEST type: string reportDetails: description: Detailed description of the fraud incident examples: - Customer reported receiving a call from fake bank employee requesting PIX payment for supposed security verification type: string reporterParticipant: description: ISPB of the PSP reporting the infraction examples: - "12345678" type: string situationType: description: Type of fraud situation examples: - SCAM type: string status: description: Current status of the infraction report enum: - OPEN - ACKNOWLEDGED - CLOSED - CANCELLED examples: - CLOSED type: string transactionDepth: description: Depth of the infraction's transaction in the DICT tracking graph (root = 1). Set by DICT; absent until DICT provides it. examples: - 1 format: int64 type: integer transactionId: description: PIX End-to-End transaction ID (32 alphanumeric characters) examples: - E12345678202411241430ABCDEFGHIJK type: string updatedAt: description: Timestamp when the report was last updated (ISO 8601 UTC) examples: - "2023-11-07T06:45:30Z" format: date-time type: string required: - id - accountId - transactionId - reason - situationType - contactInformation - status - reporterParticipant - counterpartyParticipant - createdAt - updatedAt type: object CloseRefundInput: additionalProperties: false properties: effectiveRefundedAmount: description: "Amount effectively refunded in BRL (format: 0.00 to 9999999999.99). May differ from the requested amount for PARTIALLY_ACCEPTED" examples: - "50.25" minLength: 1 type: string refundAnalysisDetails: description: Analysis comments. Max 2000 characters. Required if result is REJECTED and rejection reason is INVALID_REQUEST examples: - Analysis confirms fraud. Refund approved. maxLength: 2000 type: string refundAnalysisResult: description: Analysis result enum: - TOTALLY_ACCEPTED - PARTIALLY_ACCEPTED - REJECTED examples: - TOTALLY_ACCEPTED minLength: 1 type: string refundRejectionReason: description: Rejection reason. Required if result is REJECTED enum: - NO_BALANCE - ACCOUNT_CLOSURE - INVALID_REQUEST - OTHER - "" examples: - NO_BALANCE type: string refundTransactionId: description: Transaction ID for executing refund. Required if result is TOTALLY_ACCEPTED or PARTIALLY_ACCEPTED examples: - E98765432202411241500REFUNDTRANS type: string required: - refundAnalysisResult - effectiveRefundedAmount type: object CompleteClaimOutput: additionalProperties: false properties: accountId: description: Unique identifier of the account associated with this claim examples: - 550e8400-e29b-41d4-a716-446655440002 type: string bacenClaimId: description: BACEN DICT claim identifier (UUID) examples: - cc91b1b0-8465-44b1-a760-15dd3717ea9b type: string cancelReason: description: Reason for cancellation enum: - USER_REQUESTED - ACCOUNT_CLOSURE - DEFAULT_OPERATION - FRAUD - RECONCILIATION - COURT_ORDER - PARTICIPANT_EXCLUSION examples: - FRAUD type: string cancelledBy: description: Who cancelled the claim (DONOR or CLAIMER) enum: - DONOR - CLAIMER examples: - DONOR type: string claimer: $ref: "#/components/schemas/Claimer" description: Account owner information claimerAccount: $ref: "#/components/schemas/ClaimerAccount" description: Account information of the claimer completedAt: description: Completion timestamp (ISO 8601 UTC) examples: - "2020-08-31T13:48:55Z" format: date-time type: string completionPeriodEnd: description: Completion deadline - D+14 (ISO 8601 UTC) examples: - "2020-09-07T13:48:55Z" format: date-time type: string confirmReason: description: Reason for confirmation enum: - USER_REQUESTED - ACCOUNT_CLOSURE - DEFAULT_OPERATION - FRAUD - RECONCILIATION examples: - DEFAULT_OPERATION type: string createdAt: description: Creation timestamp (ISO 8601 UTC) examples: - "2020-08-17T13:48:36Z" format: date-time type: string donorParticipant: description: ISPB of the donor PSP (8 uppercase alphanumeric characters) examples: - "12345678" type: string holderId: description: Account holder identifier (UUID) examples: - 550e8400-e29b-41d4-a716-446655440001 type: string id: description: Internal claim identifier (UUID) examples: - 550e8400-e29b-41d4-a716-446655440000 type: string key: description: PIX key value examples: - "+5561988887777" type: string keyType: description: Type of PIX key enum: - PHONE - EMAIL - CPF - CNPJ - EVP examples: - PHONE type: string resolutionPeriodEnd: description: Resolution deadline - D+7 (ISO 8601 UTC) examples: - "2020-08-24T13:48:55Z" format: date-time type: string status: description: Current status of the claim enum: - OPEN - WAITING_RESOLUTION - CONFIRMED - CANCELLED - COMPLETED examples: - COMPLETED type: string type: description: Claim type (OWNERSHIP or PORTABILITY) enum: - OWNERSHIP - PORTABILITY examples: - PORTABILITY type: string updatedAt: description: Last update timestamp (ISO 8601 UTC) examples: - "2020-08-17T14:00:00Z" format: date-time type: string required: - accountId - cancelReason - cancelledBy - claimer - claimerAccount - completedAt - completionPeriodEnd - confirmReason - createdAt - donorParticipant - bacenClaimId - holderId - id - key - keyType - resolutionPeriodEnd - status - type - updatedAt type: object ConfirmClaimOutput: additionalProperties: false properties: accountId: description: Unique identifier of the account associated with this claim examples: - 550e8400-e29b-41d4-a716-446655440002 type: string bacenClaimId: description: BACEN DICT identifier for this claim examples: - cc91b1b0-8465-44b1-a760-15dd3717ea9b type: string cancelReason: description: Reason for cancellation (if applicable) examples: - "" type: string cancelledBy: description: Who cancelled the claim (if applicable) examples: - "" type: string claimer: $ref: "#/components/schemas/Claimer" description: Account owner information claimerAccount: $ref: "#/components/schemas/ClaimerAccount" description: Account information of the claimer completionPeriodEnd: description: Deadline for claim completion - D+14 from creation (ISO 8601 UTC) examples: - "2020-09-14T13:48:55.970Z" format: date-time type: string confirmReason: description: Reason the claim was confirmed examples: - DEFAULT_OPERATION type: string createdAt: description: Timestamp when the claim was created (ISO 8601 UTC) examples: - "2020-08-17T13:48:36Z" format: date-time type: string donorParticipant: description: ISPB of the donor PSP (current key holder) examples: - "30306294" type: string holderId: description: UUID of the account holder (claimer) examples: - 550e8400-e29b-41d4-a716-446655440001 type: string id: description: Internal UUID of the claim examples: - 550e8400-e29b-41d4-a716-446655440000 type: string key: description: The PIX key value (phone, email, CPF, CNPJ, or EVP) examples: - "+5561988887777" type: string keyType: description: Type of PIX key examples: - PHONE type: string resolutionPeriodEnd: description: Deadline for donor response - D+7 from creation (ISO 8601 UTC) examples: - "2020-08-24T13:48:55.970Z" format: date-time type: string status: description: Current status of the claim (should be CONFIRMED) examples: - CONFIRMED type: string type: description: Type of claim (OWNERSHIP or PORTABILITY) examples: - OWNERSHIP type: string updatedAt: description: Timestamp when the claim was last updated (ISO 8601 UTC) examples: - "2024-01-20T14:45:00Z" format: date-time type: string required: - id - accountId - bacenClaimId - holderId - status - type - key - keyType - claimer - claimerAccount - donorParticipant - confirmReason - cancelReason - cancelledBy - resolutionPeriodEnd - completionPeriodEnd - createdAt - updatedAt type: object ConfirmRecurrenceFromQRInput: additionalProperties: false properties: decision: enum: - ACCEPTED - REJECTED examples: - ACCEPTED minLength: 1 type: string idRec: examples: - RR0000000000000000001 maxLength: 64 minLength: 1 type: string journey: enum: - J2 - J4 examples: - J2 minLength: 1 type: string receiverMaxAmount: examples: - "500.00" type: string required: - idRec - decision - journey type: object ConfirmRecurrenceFromQROutput: additionalProperties: false properties: authorizationRequest: $ref: "#/components/schemas/AuthorizationRequestOutput" required: - authorizationRequest type: object ContactInformation: additionalProperties: true properties: email: description: Email address of the customer reporting the fraud examples: - customer@example.com minLength: 1 type: string phone: description: Phone number of the customer (E.164 format recommended) examples: - "+5511999999999" minLength: 1 type: string required: - email - phone type: object CreateClaimInput: additionalProperties: false properties: key: description: Pix key value to claim (phone, email, CPF, CNPJ, or EVP) examples: - "+5561988887777" minLength: 1 type: string type: description: Type of claim (OWNERSHIP or PORTABILITY) enum: - OWNERSHIP - PORTABILITY examples: - OWNERSHIP minLength: 1 type: string required: - key - type type: object CreateClaimOutput: additionalProperties: false properties: accountId: description: Unique identifier of the account examples: - 550e8400-e29b-41d4-a716-446655440002 type: string bacenClaimId: description: BACEN DICT identifier for this claim examples: - cc91b1b0-8465-44b1-a760-15dd3717ea9b type: string cancelReason: description: Reason provided when the claim was cancelled enum: - USER_REQUESTED - ACCOUNT_CLOSURE - DEFAULT_OPERATION - FRAUD - RECONCILIATION - COURT_ORDER - PARTICIPANT_EXCLUSION examples: - FRAUD type: string cancelledBy: description: Who cancelled the claim (donor PSP or claimer PSP) enum: - DONOR - CLAIMER examples: - DONOR type: string claimer: $ref: "#/components/schemas/Claimer" description: Account owner information claimerAccount: $ref: "#/components/schemas/ClaimerAccount" description: Account information of the claimer completedAt: description: Timestamp when the claim was completed examples: - "2020-08-31T13:48:55Z" format: date-time type: string completionPeriodEnd: description: Deadline for completing the claim process (D+14 from creation) examples: - "2020-09-07T13:48:55Z" format: date-time type: string confirmReason: description: Reason provided when the claim was confirmed enum: - USER_REQUESTED - ACCOUNT_CLOSURE - DEFAULT_OPERATION - FRAUD - RECONCILIATION examples: - DEFAULT_OPERATION type: string createdAt: description: Timestamp when the claim was created examples: - "2020-08-17T13:48:36Z" format: date-time type: string donorParticipant: description: ISPB of the donor PSP that currently holds the key examples: - "30306294" type: string holderId: description: Unique identifier of the account holder examples: - 550e8400-e29b-41d4-a716-446655440001 type: string id: description: Unique identifier of the claim examples: - 550e8400-e29b-41d4-a716-446655440000 type: string key: description: Pix key value being claimed examples: - "+5561988887777" type: string keyType: description: Type of Pix key being claimed enum: - PHONE - EMAIL - CPF - CNPJ - EVP examples: - PHONE type: string resolutionPeriodEnd: description: Deadline for donor PSP to respond (D+7 from creation) examples: - "2020-08-24T13:48:55Z" format: date-time type: string status: description: Current status of the claim enum: - OPEN - WAITING_RESOLUTION - CONFIRMED - CANCELLED - COMPLETED examples: - OPEN type: string type: description: Type of claim being processed enum: - OWNERSHIP - PORTABILITY examples: - OWNERSHIP type: string updatedAt: description: Timestamp when the claim was last updated examples: - "2020-08-17T14:00:00Z" format: date-time type: string required: - id - accountId - bacenClaimId - holderId - status - type - key - keyType - claimer - claimerAccount - donorParticipant - confirmReason - cancelReason - cancelledBy - completedAt - resolutionPeriodEnd - completionPeriodEnd - createdAt - updatedAt type: object CreateDueDateCollectionInput: additionalProperties: false properties: additionalInfo: additionalProperties: type: string examples: - customerId: "67890" orderId: "12345" type: object amount: $ref: "#/components/schemas/AmountObject" debtor: $ref: "#/components/schemas/DebtorInput" description: examples: - "Payment for order #12345" type: string dueDate: examples: - "2024-12-31" minLength: 1 type: string locationInformation: $ref: "#/components/schemas/LocationInformationDTO" metadata: additionalProperties: {} type: object receiverKey: examples: - "+5511999999999" minLength: 1 type: string tags: examples: - - ecommerce - subscription items: type: string type: array txId: examples: - TXabcdefghijklmno123456789 minLength: 1 type: string validAfterDue: examples: - 5 format: int64 minimum: 1 type: integer required: - txId - receiverKey - amount - dueDate - validAfterDue - debtor type: object CreateEntryInput: additionalProperties: false properties: account: $ref: "#/components/schemas/ReconciliationAccountInput" description: Pre-populated account data for reconciliation mode holder: $ref: "#/components/schemas/ReconciliationHolderInput" description: Pre-populated holder data for reconciliation mode key: description: Pix key value to register (email, phone, CPF, CNPJ, or EVP) examples: - john.doe@example.com type: string keyCreationDate: description: Original key creation date from BTG DICT (reconciliation mode) examples: - "2024-01-15T10:30:00Z" format: date-time type: string keyOwnershipDate: description: Date when ownership was established from BTG DICT (reconciliation mode) examples: - "2024-01-15T10:30:00Z" format: date-time type: string keyType: description: Type of Pix key being created enum: - EMAIL - PHONE - CPF - CNPJ - EVP examples: - EMAIL minLength: 1 type: string metadata: additionalProperties: {} description: Optional key-value map for storing custom attributes type: object requestId: description: Unique request identifier from BTG VSync data (for idempotency during reconciliation) examples: - 680e8400-e29b-41d4-a716-446655440002 type: string required: - keyType type: object CreateFraudMarkerInput: additionalProperties: false properties: fraudType: description: Classification of the type of fraud enum: - APPLICATION_FRAUD - MULE_ACCOUNT - SCAMMER_ACCOUNT - OTHER examples: - MULE_ACCOUNT minLength: 1 type: string key: description: Pix key value associated with the fraudulent activity (8-32 characters) examples: - fraud@example.com maxLength: 32 minLength: 8 type: string taxIdNumber: description: CPF or CNPJ of the person or entity being marked for fraud examples: - "52998224725" minLength: 1 type: string required: - taxIdNumber - fraudType type: object CreateFundsRecoveryInput: additionalProperties: false properties: contactInformation: $ref: "#/components/schemas/ContactInformation" description: Contact information of the person reporting the fraud reportDetails: description: Detailed description of the fraud incident (max 2000 characters) examples: - Customer reported receiving a call from fake bank employee maxLength: 2000 type: string rootTransactionId: description: Pix End-to-End transaction ID (32 characters) examples: - E12345678202411241430ABCDEFGHIJK minLength: 1 type: string situationType: description: Type of fraud situation enum: - SCAM - ACCOUNT_TAKEOVER - COERCION - FRAUDULENT_ACCESS - OTHER - UNKNOWN examples: - SCAM minLength: 1 type: string trackingGraphParameters: $ref: "#/components/schemas/TrackingGraphParametersInput" description: Optional parameters for tracking graph generation required: - rootTransactionId - situationType - contactInformation type: object CreateFundsRecoveryOutput: additionalProperties: false properties: bacenFundsRecoveryId: description: BACEN/BTG funds recovery external identifier examples: - 91d65e98-97c0-4b0f-b577-73625da1f9fc type: string contactInformation: $ref: "#/components/schemas/ContactInformation" description: Contact information of the person reporting the fraud createdAt: description: Creation timestamp (ISO 8601 UTC) examples: - "2023-11-07T05:31:56Z" format: date-time type: string id: description: Unique identifier for the funds recovery (UUID) examples: - 550e8400-e29b-41d4-a716-446655440000 type: string reportDetails: description: Detailed description of the fraud incident examples: - Customer reported receiving a call from fake bank employee type: string reporterParticipant: description: ISPB of the PSP reporting the fraud (8 uppercase alphanumeric characters) examples: - "12345678" type: string rootTransactionId: description: Pix End-to-End transaction ID (32 characters) examples: - E12345678202411241430ABCDEFGHIJK type: string situationType: description: Type of fraud situation enum: - SCAM - ACCOUNT_TAKEOVER - COERCION - FRAUDULENT_ACCESS - OTHER - UNKNOWN examples: - SCAM type: string status: description: Current status of the funds recovery enum: - CREATED - TRACKED - AWAITING_ANALYSIS - ANALYSED - REFUNDING - COMPLETED - CANCELLED examples: - CREATED type: string trackingGraph: $ref: "#/components/schemas/TrackingGraphOutput" description: Tracking graph generated during creation (when trackingGraphParameters provided) updatedAt: description: Last update timestamp (ISO 8601 UTC) examples: - "2023-11-07T05:31:56Z" format: date-time type: string required: - id - bacenFundsRecoveryId - rootTransactionId - situationType - status - reporterParticipant - createdAt - updatedAt type: object CreateImmediateCollectionInput: additionalProperties: false properties: additionalInfo: additionalProperties: type: string examples: - customerId: "67890" orderId: "12345" type: object amount: examples: - "100.00" minLength: 1 type: string debtorDocument: examples: - "52998224725" type: string debtorName: examples: - João da Silva type: string description: examples: - "Payment for order #12345" type: string expirationSeconds: examples: - 3600 format: int64 minimum: 1 type: integer locationInformation: $ref: "#/components/schemas/LocationInformationDTO" metadata: additionalProperties: {} type: object receiverKey: examples: - "+5511999999999" minLength: 1 type: string tags: examples: - - ecommerce - subscription items: type: string type: array transactionAmount: examples: - "150.00" type: string txId: examples: - TXabcdefghijklmno123456789 minLength: 1 type: string withdrawalAmount: examples: - "50.00" type: string required: - txId - receiverKey - amount - expirationSeconds type: object CreateInfractionReportInput: additionalProperties: false properties: contactInformation: $ref: "#/components/schemas/ContactInformation" description: Contact information of the person reporting the fraud reason: description: Report reason type enum: - REFUND_REQUEST - REFUND_CANCELLED examples: - REFUND_REQUEST minLength: 1 type: string reportDetails: description: Detailed description of the fraud incident (max 2000 characters) examples: - Customer reported receiving a call from fake bank employee requesting PIX payment for supposed security verification maxLength: 2000 type: string situationType: description: Type of fraud situation enum: - SCAM - ACCOUNT_TAKEOVER - COERCION - FRAUDULENT_ACCESS - OTHER - UNKNOWN examples: - SCAM minLength: 1 type: string transactionId: description: Pix End-to-End transaction ID (32 characters) examples: - E12345678202411241430ABCDEFGHIJK minLength: 1 type: string required: - transactionId - reason - situationType - contactInformation type: object CreateInfractionReportOutput: additionalProperties: false properties: accountId: description: Account ID (UUID) of the contested Pix transfer when the report arrived through BTG; empty when it was opened through this API examples: - 550e8400-e29b-41d4-a716-446655440000 type: string analysisDetails: description: Detailed analysis from counterparty (max 2000 characters) examples: - Analysis confirms fraudulent activity pattern type: string analysisResult: description: Analysis result from counterparty (if closed) enum: - AGREED - DISAGREED examples: - AGREED type: string bacenFundsRecoveryId: description: BACEN/BTG funds-recovery identifier linking this infraction to its MED Funds Recovery process examples: - 91d65e98-97c0-4b0f-b577-73625da1f9fc type: string contactInformation: $ref: "#/components/schemas/ContactInformation" description: Contact information of the person reporting the fraud counterpartyParticipant: description: ISPB of the counterparty PSP (8 uppercase alphanumeric characters) examples: - "87654321" type: string createdAt: description: Creation timestamp (ISO 8601 UTC) examples: - "2023-11-07T05:31:56Z" format: date-time type: string fraudMarkerId: description: Unique fraud marker identifier from BACEN examples: - FM123456789 type: string id: description: Unique identifier for the infraction report (UUID) examples: - 550e8400-e29b-41d4-a716-446655440000 type: string infractionAmount: description: Monetary amount of the infraction in BRL examples: - "1500.00" type: string reason: description: Report reason type examples: - REFUND_REQUEST type: string reportDetails: description: Detailed description of the fraud incident examples: - Customer reported receiving a call from fake bank employee requesting PIX payment for supposed security verification type: string reporterParticipant: description: ISPB of the PSP reporting the infraction (8 uppercase alphanumeric characters) examples: - "12345678" type: string situationType: description: Type of fraud situation examples: - SCAM type: string status: description: Current status of the infraction report enum: - OPEN - ACKNOWLEDGED - CLOSED - CANCELLED examples: - OPEN type: string transactionDepth: description: Depth of the infraction's transaction in the DICT tracking graph (root = 1). Set by DICT; absent until DICT provides it. examples: - 1 format: int64 type: integer transactionId: description: PIX End-to-End transaction ID (32 alphanumeric characters) examples: - E12345678202411241430ABCDEFGHIJK type: string updatedAt: description: Last update timestamp (ISO 8601 UTC) examples: - "2023-11-07T05:31:56Z" format: date-time type: string required: - id - accountId - transactionId - reason - situationType - contactInformation - status - reporterParticipant - counterpartyParticipant - createdAt - updatedAt type: object CreateRefundCashoutInput: additionalProperties: false properties: amount: examples: - "100.50" minLength: 1 type: string description: examples: - Customer reported unauthorized transaction maxLength: 140 type: string metadata: additionalProperties: {} type: object operations: items: $ref: "#/components/schemas/RefundOperation" maxItems: 50 minItems: 1 type: array required: - amount type: object CreateRefundInput: additionalProperties: false properties: refundAmount: description: "Amount in BRL with 2 decimal places (format: 0.00 to 9999999999.99)" examples: - "100.50" minLength: 1 type: string refundDetails: description: Detailed justification (max 2000 characters) examples: - Customer reports unauthorized transaction. Card was stolen. maxLength: 2000 minLength: 1 type: string refundReason: description: Reason for refund request enum: - FRAUD - OPERATIONAL_FLAW - REFUND_CANCELLED examples: - FRAUD minLength: 1 type: string transactionId: description: Pix End-to-End transaction ID (32 characters) examples: - E12345678202411241430ABCDEFGHIJK minLength: 1 type: string required: - transactionId - refundReason - refundAmount - refundDetails type: object CreateReportJobRequest: additionalProperties: false properties: referenceMonth: description: Reference month to compute, in YYYY-MM format (-03 reference timezone). Must be a month that has already closed. examples: - 2026-05 pattern: ^\d{4}-(0[1-9]|1[0-2])$ type: string required: - referenceMonth type: object CreateScheduleInput: additionalProperties: false properties: amount: examples: - "100.50" minLength: 1 type: string description: examples: - Recurring charge installment 03/12 maxLength: 140 type: string endToEndId: examples: - E1234567820260815060012345678901 type: string initiationId: examples: - 550e8400-e29b-41d4-a716-446655440010 minLength: 1 type: string maxAttempts: examples: - 2 format: int64 maximum: 2 type: integer recurrenceId: examples: - 01988a7c-1234-7abc-8def-111122223333 type: string scheduledFor: examples: - "2026-08-15T00:00:00Z" format: date-time minLength: 1 type: string required: - initiationId - scheduledFor - amount type: object CreateStaticBRCodeInput: additionalProperties: false properties: amount: description: Fixed payment amount (optional, payer chooses if not provided) examples: - "100.00" type: string clientRequestId: description: Idempotency token that will be echoed by BTG examples: - 8c4ffd09-a264-4779-8d7e-fd24c971d7ff minLength: 1 type: string description: description: Custom message or description shown to the payer examples: - "Payment for order #12345" type: string merchant: $ref: "#/components/schemas/StaticBRCodeMerchantInput" description: Optional merchant metadata overrides receiverKey: description: Pix key that will receive the payment examples: - "+5511999999999" minLength: 1 type: string tags: description: Custom tags for categorization and correlation examples: - - checkout - web items: type: string type: array txId: description: Transaction identification (txid) to be sent on the payment message examples: - ORDER-12345 type: string required: - clientRequestId - receiverKey type: object DebtorInput: additionalProperties: true properties: address: examples: - Rua das Flores, 123 type: string city: examples: - São Paulo type: string document: examples: - "52998224725" minLength: 1 type: string email: examples: - joao@example.com type: string name: examples: - João da Silva minLength: 1 type: string state: examples: - SP type: string zipCode: examples: - 01310-100 type: string required: - name - document type: object DebtorOutput: additionalProperties: false properties: document: examples: - "52998224725" type: string name: examples: - João da Silva type: string required: - name - document type: object DecideAuthorizationRequestInput: additionalProperties: false properties: decision: enum: - ACCEPTED - REJECTED examples: - ACCEPTED minLength: 1 type: string receiverMaxAmount: examples: - "500.00" type: string required: - decision type: object DecideAuthorizationRequestOutput: additionalProperties: false properties: authorizationRequest: $ref: "#/components/schemas/AuthorizationRequestOutput" required: - authorizationRequest type: object DecodeAmountObject: additionalProperties: false properties: abatement: description: Abatement configuration (optional) type: string discount: description: Discount configuration (optional) type: string final: description: Final amount considering all adjustments (discounts, fines, abatements, interests) examples: - "100.00" type: string fine: description: Fine configuration (optional) type: string interest: description: Interest configuration (optional) type: string original: description: Original collection amount in decimal format examples: - "100.00" type: string required: - original - final type: object DecodeInput: additionalProperties: false properties: cityCode: description: City code based on IBGE Municipal Code Table (optional, used for COBV) examples: - "3550308" type: string emv: description: EMV QR Code payload string to decode (text content from scanned QR Code) examples: - 00020126580014br.gov.bcb.pix... minLength: 1 type: string paymentDate: description: Payment date in ISO8601 format (defaults to current date if not provided) examples: - "2024-12-31" type: string required: - emv type: object DestinationAccountOutput: additionalProperties: false properties: branch: examples: - "0001" type: string number: examples: - "123456789" type: string participant: examples: - "12345678" type: string type: examples: - CACC type: string required: - branch - number - participant - type type: object DestinationOutput: additionalProperties: false properties: account: $ref: "#/components/schemas/DestinationAccountOutput" key: examples: - john.doe@example.com type: string owner: $ref: "#/components/schemas/DestinationOwnerOutput" required: - account - owner type: object DestinationOwnerOutput: additionalProperties: false properties: document: examples: - "52998224725" type: string name: examples: - John Doe type: string tradeName: examples: - John's Business type: string type: examples: - NATURAL_PERSON type: string required: - document - name - type type: object DiscountDateFixed: additionalProperties: true properties: date: examples: - "2024-12-25" type: string value: examples: - "10.00" type: string type: object DiscountObject: additionalProperties: true properties: discountDateFixed: items: $ref: "#/components/schemas/DiscountDateFixed" maxItems: 3 minItems: 1 type: array modality: examples: - AMOUNT_ADVANCE_BUSINESS_DAY minLength: 1 type: string value: examples: - "5.00" type: string required: - modality type: object DueDateCollectionOutput: additionalProperties: false properties: additionalInfo: additionalProperties: type: string examples: - customerId: "67890" orderId: "12345" type: object amount: $ref: "#/components/schemas/AmountObject" createdAt: examples: - "2024-01-15T10:30:00Z" format: date-time type: string debtor: $ref: "#/components/schemas/DebtorOutput" deletedAt: examples: - "2024-01-25T10:30:00Z" format: date-time type: string description: examples: - "Payment for order #12345" type: string dueDate: examples: - "2024-12-31" type: string emv: examples: - 00020126580014br.gov.bcb.pix... type: string id: examples: - 550e8400-e29b-41d4-a716-446655440010 type: string locationUrl: examples: - https://api.example.com/qr/550e8400 type: string metadata: additionalProperties: {} type: object receiver: $ref: "#/components/schemas/ReceiverOutput" receiverKey: examples: - "+5511999999999" type: string review: examples: - 0 format: int64 type: integer status: examples: - ACTIVE type: string tags: examples: - - ecommerce - subscription items: type: string type: array txId: examples: - TXabcdefghijklmno123456789 type: string updatedAt: examples: - "2024-01-20T14:45:00Z" format: date-time type: string validAfterDue: examples: - 5 format: int64 type: integer required: - id - txId - status - amount - receiverKey - dueDate - validAfterDue - debtor - receiver - emv - locationUrl - review - createdAt - updatedAt type: object DueDateDecodeDebtor: additionalProperties: false properties: address: description: Debtor address examples: - Rua Example, 123 type: string city: description: Debtor city examples: - São Paulo type: string document: description: Debtor CPF or CNPJ identifier examples: - "52998224725" type: string email: description: Debtor email examples: - john.doe@example.com type: string name: description: Debtor name examples: - John Doe type: string state: description: Debtor state examples: - SP type: string zipCode: description: Debtor postal code examples: - 01310-100 type: string required: - name - document type: object DueDateDecodeOutput: additionalProperties: false properties: additionalInfo: description: List of additional information strings examples: - - "Invoice: 12345" items: type: string type: array amount: $ref: "#/components/schemas/DecodeAmountObject" description: Amount structure containing original value, fines, interest, discounts and abatement debtor: $ref: "#/components/schemas/DueDateDecodeDebtor" description: Payer identification information description: description: Custom message or description for the collection examples: - "Payment for invoice #12345" type: string dueDate: description: Due date for the collection (ISO8601 format) examples: - "2024-12-31" type: string receiver: $ref: "#/components/schemas/DueDateDecodeReceiver" description: Receiver or merchant identification information receiverKey: description: Pix key that will receive the payment examples: - "+5511999999999" type: string recurrence: $ref: "#/components/schemas/RecurrenceDecodeData" description: Pix Automático recurrence data (present only for recurrence-bearing QR codes) review: description: Review number of the collection examples: - 0 format: int64 type: integer status: description: Status of the collection, as BTG returns it examples: - ATIVA type: string txId: description: Unique transaction identifier for this collection examples: - TXabcdefghijklmno123456789 type: string type: description: QR Code type identifier (DUE_DATE) examples: - DUE_DATE type: string validAfterDue: description: Number of days the collection remains valid after the due date examples: - 30 format: int64 type: integer required: - type - review - dueDate - validAfterDue - receiverKey - txId - debtor - receiver - amount - status type: object DueDateDecodeReceiver: additionalProperties: false properties: address: description: Street address of the receiver examples: - Av. Paulista, 1000 type: string city: description: City of the receiver examples: - São Paulo type: string document: description: CPF or CNPJ of the receiver examples: - "11222333000181" type: string name: description: Name of the receiver examples: - Merchant ABC type: string state: description: State (UF) of the receiver examples: - SP type: string tradeName: description: Trade name of the receiver examples: - ABC Store type: string zipCode: description: Postal code (CEP) of the receiver examples: - 01310-100 type: string required: - name - document - address - city - state - zipCode type: object EntryOutput: additionalProperties: false properties: account: $ref: "#/components/schemas/AccountOutput" description: Account information associated with this Pix key createdAt: description: Timestamp when the entity was created examples: - "2024-01-15T10:30:00Z" format: date-time type: string holderId: description: Unique identifier of the customer who owns this Pix key examples: - 550e8400-e29b-41d4-a716-446655440001 type: string id: description: Unique identifier of the Pix key entry examples: - 550e8400-e29b-41d4-a716-446655440010 type: string keyCreationDate: description: Date when this Pix key was created on DICT examples: - "2024-01-15T10:30:00Z" format: date-time type: string keyOwnershipDate: description: Date when the customer became the owner of this Pix key examples: - "2024-01-15T10:30:00Z" format: date-time type: string keyType: description: Type of Pix key that was created enum: - EMAIL - PHONE - CPF - CNPJ - EVP examples: - EMAIL type: string keyValue: description: Pix key value that was registered examples: - john.doe@example.com type: string metadata: additionalProperties: {} description: Custom key-value attributes associated with this entry type: object owner: $ref: "#/components/schemas/OwnerOutput" description: Owner information associated with this Pix key requestId: description: Unique identifier for this creation request (for idempotency) examples: - 680e8400-e29b-41d4-a716-446655440002 type: string status: description: Operational status of this Pix key enum: - ACTIVE - INACTIVE examples: - ACTIVE type: string updatedAt: description: Timestamp when the entity was last updated examples: - "2024-01-20T14:45:00Z" format: date-time type: string required: - id - keyValue - keyType - account - owner - holderId - keyCreationDate - keyOwnershipDate - requestId - status - createdAt - updatedAt type: object FeeChargeResponse: additionalProperties: false properties: applied: examples: - true type: boolean calculationType: examples: - segment type: string fees: items: $ref: "#/components/schemas/FeeEntryResponse" type: array netAmount: examples: - "97.50" type: string totalAmount: examples: - "2.50" type: string required: - applied - calculationType - totalAmount - netAmount - fees type: object FeeEntryResponse: additionalProperties: false properties: amount: examples: - "1.50" type: string calculationType: examples: - PERCENTAGE type: string calculationValue: examples: - "1.5" type: string creditAccount: examples: - 01989f9e-6508-79f8-9540-835be49fbd0d type: string feeLabel: examples: - PIX_FEE type: string required: - feeLabel - amount - creditAccount - calculationType - calculationValue type: object FineObject: additionalProperties: true properties: modality: examples: - PERCENT minLength: 1 type: string value: examples: - "2.00" minLength: 1 type: string required: - modality - value type: object FraudMarkerInfractionReport: additionalProperties: false properties: id: description: Unique identifier of the related infraction report (UUID) examples: - 550e8400-e29b-41d4-a716-446655440001 type: string reporterParticipant: description: ISPB of the participant that filed the infraction report (8 uppercase alphanumeric characters) examples: - "12345678" type: string required: - id - reporterParticipant type: object FraudMarkerOutput: additionalProperties: false properties: createdAt: description: Timestamp when the fraud marker was created (ISO 8601 UTC) examples: - "2024-01-15T10:30:00Z" format: date-time type: string deletedAt: description: Timestamp when the fraud marker was soft-deleted (ISO 8601 UTC) examples: - "2024-01-20T14:45:00Z" format: date-time type: - string - "null" document: description: CPF or CNPJ of the person or entity marked for fraud examples: - "52998224725" type: string fraudType: description: Classification of the type of fraud enum: - APPLICATION_FRAUD - MULE_ACCOUNT - SCAMMER_ACCOUNT - OTHER - UNKNOWN examples: - MULE_ACCOUNT type: string id: description: Unique identifier of the fraud marker (UUID) examples: - 550e8400-e29b-41d4-a716-44665544f999 type: string infractionReport: $ref: "#/components/schemas/FraudMarkerInfractionReport" description: Reference to the infraction report that originated this fraud marker key: description: Pix key value associated with the fraud marker examples: - fraud@example.com type: - string - "null" status: description: Current operational status of the fraud marker enum: - REGISTERED - CANCELLED examples: - REGISTERED type: string updatedAt: description: Timestamp when the fraud marker was last updated (ISO 8601 UTC) examples: - "2024-01-15T10:30:00Z" format: date-time type: string required: - id - document - key - fraudType - status - infractionReport - createdAt - updatedAt - deletedAt type: object FraudMarkersStatistics: additionalProperties: false properties: applicationFrauds: $ref: "#/components/schemas/TimeBasedValues" description: Counters for APPLICATION_FRAUD type markers distinctFraudReporters: $ref: "#/components/schemas/TimeBasedValues" description: Number of distinct fraud reporters muleAccounts: $ref: "#/components/schemas/TimeBasedValues" description: Counters for MULE_ACCOUNT type markers otherFrauds: $ref: "#/components/schemas/TimeBasedValues" description: Counters for OTHER type fraud markers scammerAccounts: $ref: "#/components/schemas/TimeBasedValues" description: Counters for SCAMMER_ACCOUNT type markers totalFraudTransactionAmount: $ref: "#/components/schemas/TimeBasedValues" description: Total fraud transaction amount (BRL) unknownFrauds: $ref: "#/components/schemas/TimeBasedValues" description: Counters for UNKNOWN type fraud markers (historical) watermark: description: Datetime of last considered event for fraud marker statistics examples: - "2024-01-15T10:30:00Z" format: date-time type: string type: object FullReconciliationJobInfo: additionalProperties: false properties: createdAt: description: When the job was created (ISO 8601 UTC) examples: - "2024-01-15T10:30:00Z" format: date-time type: string expiresAt: description: When the WAITING_FILE status expires (ISO 8601 UTC) examples: - "2024-01-15T12:30:00Z" format: date-time type: string fileRequestId: description: ID returned by BTG for the file request examples: - 770e8400-e29b-41d4-a716-446655440002 type: string jobId: description: ID of the created job (UUID) examples: - 550e8400-e29b-41d4-a716-446655440000 type: string keyType: description: PIX key type for this job examples: - CPF type: string status: description: Initial status of the job examples: - WAITING_FILE type: string required: - jobId - keyType - status - fileRequestId - expiresAt - createdAt type: object FullReconciliationOutput: additionalProperties: false properties: jobs: description: Information about the created jobs items: $ref: "#/components/schemas/FullReconciliationJobInfo" type: array message: description: Details about the reconciliation operation examples: - Created 2 full reconciliation jobs type: string skippedKeyTypes: description: Key types that were skipped items: $ref: "#/components/schemas/SkippedKeyTypeInfo" type: array required: - message - jobs type: object FundsRecoveryInfractionOutput: additionalProperties: false properties: analysisDetails: description: Details of the counterparty analysis examples: - Funds confirmed and blocked type: string analysisResult: description: Result of the counterparty analysis examples: - AGREED type: string bacenFundsRecoveryId: description: BACEN/BTG funds recovery external identifier examples: - ca1b9c01-ff9e-4a58-90ab-d31512e15ce0 type: string counterpartyParticipant: description: ISPB of the counterparty participant (8 digits) examples: - "87654321" type: string creationTime: description: Creation timestamp (ISO 8601 UTC) examples: - "2024-01-15T10:30:00Z" format: date-time type: string fraudMarkerId: description: Associated fraud marker identifier (UUID) examples: - 550e8400-e29b-41d4-a716-446655440000 type: string fundsRecoveryId: description: Funds recovery identifier (UUID) examples: - 550e8400-e29b-41d4-a716-446655440000 type: string id: description: Unique identifier of the infraction report (UUID) examples: - 550e8400-e29b-41d4-a716-446655440000 type: string lastModified: description: Last modification timestamp (ISO 8601 UTC) examples: - "2024-01-15T11:30:00Z" format: date-time type: string reason: description: Reason for the infraction report examples: - REFUND_REQUEST type: string reportDetails: description: Detailed description of the infraction examples: - Customer reported fraudulent transaction type: string reporterParticipant: description: ISPB of the reporting participant (8 digits) examples: - "12345678" type: string situationType: description: Type of fraud situation examples: - SCAM type: string status: description: Current status of the infraction report examples: - OPEN type: string transactionDepth: description: Depth of the infraction's transaction in the DICT tracking graph (root = 1). Set by DICT. examples: - 1 format: int64 type: integer transactionId: description: Pix End-to-End transaction ID (32 characters) examples: - E12345678202411241430ABCDEFGHIJK type: string required: - id - transactionId - fundsRecoveryId - reason - situationType - status - reporterParticipant - counterpartyParticipant - creationTime - lastModified type: object FundsRecoveryOutput: additionalProperties: false properties: bacenFundsRecoveryId: description: BACEN/BTG funds recovery external identifier examples: - 91d65e98-97c0-4b0f-b577-73625da1f9fc type: string contactInformation: $ref: "#/components/schemas/ContactInformation" description: Contact information of the person reporting the fraud createdAt: description: Creation timestamp (ISO 8601 UTC) examples: - "2023-11-07T05:31:56Z" format: date-time type: string id: description: Unique identifier for the funds recovery (UUID) examples: - 550e8400-e29b-41d4-a716-446655440000 type: string reportDetails: description: Detailed description of the fraud incident examples: - Customer reported receiving a call from fake bank employee type: string reporterParticipant: description: ISPB of the PSP reporting the fraud (8 uppercase alphanumeric characters) examples: - "12345678" type: string rootTransactionId: description: Pix End-to-End transaction ID (32 characters) examples: - E12345678202411241430ABCDEFGHIJK type: string situationType: description: Type of fraud situation enum: - SCAM - ACCOUNT_TAKEOVER - COERCION - FRAUDULENT_ACCESS - OTHER - UNKNOWN examples: - SCAM type: string status: description: Current status of the funds recovery enum: - CREATED - TRACKED - AWAITING_ANALYSIS - ANALYSED - REFUNDING - COMPLETED - CANCELLED examples: - CREATED type: string updatedAt: description: Last update timestamp (ISO 8601 UTC) examples: - "2023-11-07T05:31:56Z" format: date-time type: string required: - id - bacenFundsRecoveryId - rootTransactionId - situationType - status - reporterParticipant - createdAt - updatedAt type: object FundsRecoveryRefundOutput: additionalProperties: false properties: analysisResult: description: Result of the refund analysis examples: - TOTALLY_ACCEPTED type: string bacenFundsRecoveryId: description: BACEN/BTG funds recovery external identifier examples: - ca1b9c01-ff9e-4a58-90ab-d31512e15ce0 type: string contestedParticipant: description: ISPB of the contested participant (8 digits) examples: - "87654321" type: string creationTime: description: Creation timestamp (ISO 8601 UTC) examples: - "2024-01-15T10:30:00Z" format: date-time type: string fundsRecoveryId: description: Funds recovery identifier (UUID) examples: - 550e8400-e29b-41d4-a716-446655440000 type: string id: description: Unique identifier of the refund (UUID) examples: - 550e8400-e29b-41d4-a716-446655440000 type: string lastModified: description: Last modification timestamp (ISO 8601 UTC) examples: - "2024-01-15T11:30:00Z" format: date-time type: string refundAmount: description: Refund amount in BRL examples: - "100.50" type: string refundReason: description: Reason for the refund request examples: - FRAUD type: string refundTransactionId: description: Transaction ID of the executed refund (32 characters) examples: - E12345678202411241430ABCDEFGHIJK type: string requestingParticipant: description: ISPB of the requesting participant (8 digits) examples: - "12345678" type: string status: description: Current status of the refund examples: - OPEN type: string transactionId: description: Pix End-to-End transaction ID (32 characters) examples: - E12345678202411241430ABCDEFGHIJK type: string required: - id - transactionId - fundsRecoveryId - refundReason - refundAmount - status - requestingParticipant - contestedParticipant - creationTime - lastModified type: object GetAllAuthorizationRequestsOutput: additionalProperties: false properties: items: items: $ref: "#/components/schemas/AuthorizationRequestOutput" type: array limit: examples: - 10 format: int64 type: integer page: examples: - 1 format: int64 type: integer total: examples: - 42 format: int64 type: integer required: - items - limit - page - total type: object GetAllAuthorizationsOutput: additionalProperties: false properties: items: items: $ref: "#/components/schemas/AuthorizationOutput" type: array limit: examples: - 10 format: int64 type: integer page: examples: - 1 format: int64 type: integer total: examples: - 42 format: int64 type: integer required: - items - limit - page - total type: object GetAllClaimsOutput: additionalProperties: false properties: items: description: Array of claims items: $ref: "#/components/schemas/ClaimListItem" type: array limit: description: Number of items per page examples: - 10 format: int64 type: integer page: description: Current page number examples: - 1 format: int64 type: integer total: description: Total number of claims matching the filters examples: - 42 format: int64 type: integer required: - items - limit - page - total type: object GetAllEntriesOutput: additionalProperties: false properties: items: description: Array of entries for the current page items: $ref: "#/components/schemas/EntryOutput" type: array limit: description: Number of items per page examples: - 10 format: int64 type: integer page: description: Current page number examples: - 1 format: int64 type: integer total: description: Total number of entries matching the filters (across all pages) examples: - 42 format: int64 type: integer required: - items - page - limit - total type: object GetAllFraudMarkersOutput: additionalProperties: false properties: hasMoreElements: description: Indicates if there are more elements available examples: - true type: boolean items: description: Array of fraud marker objects items: $ref: "#/components/schemas/FraudMarkerOutput" type: array required: - items - hasMoreElements type: object GetAllFundsRecoveriesOutput: additionalProperties: false properties: items: description: Array of funds recoveries for the current page items: $ref: "#/components/schemas/FundsRecoveryOutput" type: array limit: description: Number of items per page examples: - 10 format: int64 type: integer page: description: Current page number examples: - 1 format: int64 type: integer total: description: Total number of funds recoveries matching the filters examples: - 42 format: int64 type: integer required: - items - page - limit - total type: object GetAllInfractionReportsOutput: additionalProperties: false properties: items: description: Array of infraction reports for the current page items: $ref: "#/components/schemas/InfractionReportListItem" type: array limit: description: Number of items per page examples: - 10 format: int64 type: integer page: description: Current page number examples: - 1 format: int64 type: integer total: description: Total number of infraction reports matching the filters examples: - 42 format: int64 type: integer required: - items - page - limit - total type: object GetAllReconciliationJobsOutput: additionalProperties: false properties: items: description: Array of reconciliation jobs for the current page items: $ref: "#/components/schemas/ReconciliationJobOutput" type: array limit: description: Number of items per page examples: - 10 format: int64 type: integer page: description: Current page number examples: - 1 format: int64 type: integer total: description: Total number of reconciliation jobs matching the filters examples: - 25 format: int64 type: integer required: - items - page - limit - total type: object GetAllRefundsOutput: additionalProperties: false properties: items: description: Refund requests on the current page items: $ref: "#/components/schemas/RefundOutput" type: array limit: description: Number of items per page examples: - 10 format: int64 type: integer page: description: Current page number examples: - 1 format: int64 type: integer total: description: Total number of refund requests matching the filters examples: - 85 format: int64 type: integer required: - items - page - limit - total type: object GetAllVSyncStatesOutput: additionalProperties: false properties: items: description: Array of VSync states for the current page items: $ref: "#/components/schemas/VSyncStateOutput" type: array limit: description: Number of items per page examples: - 10 format: int64 type: integer page: description: Current page number examples: - 1 format: int64 type: integer total: description: Total number of VSync states matching the filters examples: - 5 format: int64 type: integer required: - items - page - limit - total type: object GetClaimOutput: additionalProperties: false properties: accountId: description: Unique identifier of the account associated with this claim examples: - 550e8400-e29b-41d4-a716-446655440002 type: string bacenClaimId: description: BACEN DICT identifier for this claim examples: - cc91b1b0-8465-44b1-a760-15dd3717ea9b type: string cancelReason: description: Reason for cancellation (if applicable) examples: - FRAUD type: string cancelledBy: description: Who cancelled the claim (if applicable) examples: - DONOR type: string claimer: $ref: "#/components/schemas/Claimer" description: Account owner information claimerAccount: $ref: "#/components/schemas/ClaimerAccount" description: Account information of the claimer completionPeriodEnd: description: Deadline for claim completion - D+14 from creation (ISO 8601 UTC) examples: - "2020-09-14T13:48:55.970Z" format: date-time type: string confirmReason: description: Reason the claim was confirmed (if applicable) examples: - DEFAULT_OPERATION type: string createdAt: description: Timestamp when the claim was created (ISO 8601 UTC) examples: - "2020-08-17T13:48:36Z" format: date-time type: string donorParticipant: description: ISPB of the donor PSP (current key holder) examples: - "30306294" type: string holderId: description: UUID of the account holder (claimer) examples: - 550e8400-e29b-41d4-a716-446655440001 type: string id: description: Internal UUID of the claim examples: - 550e8400-e29b-41d4-a716-446655440000 type: string key: description: The PIX key value (phone, email, CPF, CNPJ, or EVP) examples: - "+5561988887777" type: string keyType: description: Type of PIX key examples: - PHONE type: string resolutionPeriodEnd: description: Deadline for donor response - D+7 from creation (ISO 8601 UTC) examples: - "2020-08-24T13:48:55.970Z" format: date-time type: string status: description: Current status of the claim examples: - OPEN type: string type: description: Type of claim (OWNERSHIP or PORTABILITY) examples: - OWNERSHIP type: string updatedAt: description: Timestamp when the claim was last updated (ISO 8601 UTC) examples: - "2024-01-20T14:45:00Z" format: date-time type: string required: - id - accountId - bacenClaimId - holderId - status - type - key - keyType - claimer - claimerAccount - donorParticipant - confirmReason - cancelReason - cancelledBy - resolutionPeriodEnd - completionPeriodEnd - createdAt - updatedAt type: object GetEntryOutput: additionalProperties: false properties: account: $ref: "#/components/schemas/AccountOutput" description: Account information associated with this PIX key creationDate: description: When this PIX key entry was created examples: - "2024-01-15T10:30:00Z" format: date-time type: string holderId: description: Unique identifier of the customer who owns this PIX key examples: - 550e8400-e29b-41d4-a716-446655440001 type: string id: description: Unique identifier for this PIX key entry examples: - 950e8400-e29b-41d4-a716-446655440000 type: string keyOwnershipDate: description: When the customer became the owner of this PIX key examples: - "2024-01-15T10:30:00Z" format: date-time type: string keyType: description: Type of this PIX key examples: - EMAIL type: string keyValue: description: Actual PIX key that was registered examples: - john.doe@example.com type: string metadata: additionalProperties: {} description: Optional key-value pairs for custom attributes type: object owner: $ref: "#/components/schemas/OwnerOutput" description: Owner information associated with this PIX key requestId: description: Unique identifier for this creation request (for idempotency) examples: - 680e8400-e29b-41d4-a716-446655440002 type: string status: description: Operational status of this PIX key examples: - ACTIVE type: string required: - id - holderId - keyType - keyValue - status - account - owner - creationDate - requestId - keyOwnershipDate - metadata type: object GetInfractionReportOutput: additionalProperties: false properties: accountId: description: Account ID (UUID) of the contested Pix transfer when the report arrived through BTG; empty when it was opened through this API examples: - 550e8400-e29b-41d4-a716-446655440000 type: string analysisDetails: description: Detailed analysis from counterparty examples: - Analysis confirms fraudulent activity pattern type: string analysisResult: description: Analysis result from counterparty (if closed) enum: - AGREED - DISAGREED examples: - AGREED type: string bacenFundsRecoveryId: description: BACEN/BTG funds-recovery identifier linking this infraction to its MED Funds Recovery process examples: - 91d65e98-97c0-4b0f-b577-73625da1f9fc type: string bacenInfractionReportId: description: BACEN/BTG infraction report external identifier examples: - 91d65e98-97c0-4b0f-b577-73625da1f9fc type: string contactInformation: $ref: "#/components/schemas/ContactInformation" description: Contact information of the person reporting the fraud counterpartyParticipant: description: ISPB of the counterparty PSP involved in the transaction examples: - "87654321" type: string createdAt: description: Timestamp when the report was created (ISO 8601 UTC) examples: - "2023-11-07T05:31:56Z" format: date-time type: string fraudMarkerId: description: Unique fraud marker identifier from BACEN examples: - FM123456789 type: string id: description: Unique identifier for the infraction report (UUID) examples: - 550e8400-e29b-41d4-a716-446655440000 type: string infractionAmount: description: Monetary amount of the infraction in BRL examples: - "1500.00" type: string reason: description: Report reason type examples: - REFUND_REQUEST type: string reportDetails: description: Detailed description of the fraud incident examples: - Customer reported receiving a call from fake bank employee type: string reporterParticipant: description: ISPB of the PSP reporting the infraction examples: - "12345678" type: string situationType: description: Type of fraud situation examples: - SCAM type: string status: description: Current status of the infraction report enum: - OPEN - ACKNOWLEDGED - CLOSED - CANCELLED examples: - OPEN type: string transactionDepth: description: Depth of the infraction's transaction in the DICT tracking graph (root = 1). Set by DICT; absent until DICT provides it. examples: - 1 format: int64 type: integer transactionId: description: PIX End-to-End transaction ID (32 alphanumeric characters) examples: - E12345678202411241430ABCDEFGHIJK type: string updatedAt: description: Timestamp when the report was last updated (ISO 8601 UTC) examples: - "2023-11-07T05:31:56Z" format: date-time type: string required: - id - bacenInfractionReportId - accountId - transactionId - reason - situationType - contactInformation - status - reporterParticipant - counterpartyParticipant - createdAt - updatedAt type: object GetKeyOutput: additionalProperties: false properties: account: $ref: "#/components/schemas/AccountOutput" description: Account information associated with this PIX key creationDate: description: When this PIX key entry was created examples: - "2024-01-15T10:30:00Z" format: date-time type: string endToEndId: description: Unique identifier for the end-to-end transaction tracking examples: - 550e8400-e29b-41d4-a716-446655440003 type: string key: description: PIX key value that was registered examples: - john.doe@example.com type: string keyOwnershipDate: description: When the customer became the owner of this PIX key examples: - "2024-01-15T10:30:00Z" format: date-time type: string keyType: description: Type of this PIX key enum: - CPF - CNPJ - EMAIL - PHONE examples: - EMAIL type: string owner: $ref: "#/components/schemas/OwnerOutput" description: Owner information associated with this PIX key required: - endToEndId - key - keyType - account - owner - creationDate - keyOwnershipDate type: object ImmediateCollectionOutput: additionalProperties: false properties: additionalInfo: additionalProperties: type: string examples: - customerId: "67890" orderId: "12345" type: object amount: examples: - "100.00" type: string createdAt: examples: - "2024-01-15T10:30:00Z" format: date-time type: string debtorDocument: examples: - "52998224725" type: string debtorName: examples: - João da Silva type: string description: examples: - "Payment for order #12345" type: string emv: examples: - 00020126580014br.gov.bcb.pix... type: string expirationSeconds: examples: - 3600 format: int64 type: integer id: examples: - 550e8400-e29b-41d4-a716-446655440000 type: string locationUrl: examples: - https://api.example.com/qr/550e8400 type: string metadata: additionalProperties: {} type: object receiverKey: examples: - "+5511999999999" type: string status: examples: - ACTIVE type: string tags: examples: - - ecommerce - subscription items: type: string type: array txId: examples: - TXN123456789 type: string updatedAt: examples: - "2024-01-15T10:30:00Z" format: date-time type: string required: - id - txId - status - amount - receiverKey - expirationSeconds - createdAt - updatedAt type: object ImmediateDecodeDebtor: additionalProperties: false properties: document: description: CPF or CNPJ of the debtor examples: - "52998224725" type: string name: description: Name of the debtor (payer) examples: - John Doe type: string required: - name - document type: object ImmediateDecodeOutput: additionalProperties: false properties: additionalInfo: additionalProperties: type: string description: Key-value map containing additional information type: object amount: description: "Charge original amount in decimal format with 2 decimal places. NOT the payable total for withdrawal-bearing charges: 0.00 for Pix Saque and the purchase value only for Pix Troco — the payable total is withdrawalAmount, resp. transactionAmount + withdrawalAmount" examples: - "100.00" type: string debtor: $ref: "#/components/schemas/ImmediateDecodeDebtor" description: Payer identification information (optional) description: description: Custom message or description for the collection examples: - "Payment for order #12345" type: string emv: description: Original EMV payload from the QR code examples: - 00020126580014br.gov.bcb.pix... type: string expirationInSeconds: description: Time in seconds until the collection expires examples: - 3600 format: int64 type: integer receiverKey: description: Pix key that will receive the payment examples: - "+5511999999999" type: string recurrence: $ref: "#/components/schemas/RecurrenceDecodeData" description: Pix Automático recurrence data (present only for recurrence-bearing QR codes) review: description: Review number of the collection examples: - 0 format: int64 type: integer status: description: Status of the collection, as BTG returns it examples: - ATIVA type: string txId: description: Unique transaction identifier for this collection examples: - TXabcdefghijklmno123456789 type: string type: description: QR Code type identifier (IMMEDIATE) examples: - IMMEDIATE type: string withdrawal: $ref: "#/components/schemas/WithdrawalDecodeData" description: Pix Saque/Troco data (present only for withdrawal or change charges) required: - type - review - amount - expirationInSeconds - receiverKey - txId - emv - status type: object InfractionReportListItem: additionalProperties: false properties: accountId: description: Account ID (UUID) of the contested Pix transfer when the report arrived through BTG; empty when it was opened through this API examples: - 550e8400-e29b-41d4-a716-446655440000 type: string analysisDetails: description: Detailed analysis from counterparty examples: - Analysis confirms fraudulent activity type: string analysisResult: description: Analysis result from counterparty (if closed) examples: - AGREED type: string bacenFundsRecoveryId: description: BACEN/BTG funds-recovery identifier linking this infraction to its MED Funds Recovery process examples: - 91d65e98-97c0-4b0f-b577-73625da1f9fc type: string bacenInfractionReportId: description: BACEN/BTG infraction report external identifier examples: - 91d65e98-97c0-4b0f-b577-73625da1f9fc type: string contactInformation: $ref: "#/components/schemas/ContactInformation" description: Contact information of the person reporting the fraud counterpartyParticipant: description: ISPB of the counterparty PSP involved in the transaction examples: - "12345678" type: string createdAt: description: Timestamp when the report was created (ISO 8601 UTC) examples: - "2024-01-15T10:30:00Z" format: date-time type: string fraudMarkerId: description: Unique fraud marker identifier from BACEN examples: - FM123456789 type: string id: description: Unique identifier for the infraction report (UUID) examples: - 550e8400-e29b-41d4-a716-446655440000 type: string infractionAmount: description: Monetary amount of the infraction in BRL examples: - "1500.00" type: string reason: description: Report reason type examples: - REFUND_REQUEST type: string reportDetails: description: Detailed description of the fraud incident examples: - Customer reported unauthorized transaction type: string reporterParticipant: description: ISPB of the PSP reporting the infraction examples: - "30306294" type: string situationType: description: Type of fraud situation examples: - SCAM type: string status: description: Current status of the infraction report examples: - OPEN type: string transactionDepth: description: Depth of the infraction's transaction in the DICT tracking graph (root = 1). Set by DICT; absent until DICT provides it. examples: - 1 format: int64 type: integer transactionId: description: PIX End-to-End transaction ID (32 alphanumeric characters) examples: - E12345678202411241430ABCDEFGHIJK type: string updatedAt: description: Timestamp when the report was last updated (ISO 8601 UTC) examples: - "2024-01-20T14:45:00Z" format: date-time type: string required: - id - bacenInfractionReportId - accountId - transactionId - reason - situationType - contactInformation - status - reporterParticipant - counterpartyParticipant - createdAt - updatedAt type: object InfractionReportsStatistics: additionalProperties: false properties: openReports: description: Number of currently open infraction reports examples: - 0 format: int64 type: integer openReportsDistinctReporters: description: Number of distinct participants with open reports examples: - 0 format: int64 type: integer rejectedReports: $ref: "#/components/schemas/TimeBasedValues" description: Counters for rejected infraction reports watermark: description: Datetime of last considered event for infraction report statistics examples: - "2024-01-15T10:30:00Z" format: date-time type: string type: object InitiateTransferOutput: additionalProperties: false properties: createdAt: examples: - "2024-01-15T10:30:00Z" type: string destination: $ref: "#/components/schemas/DestinationOutput" emv: examples: - 00020126...5802BR5913Fulano... type: string endToEndId: examples: - E1234567820240101000001234567890 type: string expiresAt: examples: - "2024-01-15T11:00:00Z" type: string id: examples: - 550e8400-e29b-41d4-a716-446655440010 type: string initiationType: examples: - MANUAL type: string qrCodeDetails: {} updatedAt: examples: - "2024-01-15T10:30:00Z" type: string required: - id - initiationType - endToEndId - expiresAt - createdAt - updatedAt type: object InterestObject: additionalProperties: true properties: modality: examples: - PERCENTAGE_PER_MONTH_CALENDAR_DAYS minLength: 1 type: string value: examples: - "1.00" minLength: 1 type: string required: - modality - value type: object KeyCheckItem: additionalProperties: true properties: key: description: PIX key value to verify examples: - "+5561999999922" type: string type: object KeyCheckResult: additionalProperties: false properties: hasEntry: description: Indicates if the key exists in the DICT system examples: - true type: boolean key: description: PIX key that was verified examples: - "+5561999999922" type: string required: - key - hasEntry type: object KeyEntriesStatistics: additionalProperties: false properties: distinctAccounts: $ref: "#/components/schemas/TimeBasedValues" description: Number of distinct accounts with this key watermark: description: Datetime of last considered event for key entry statistics examples: - "2024-01-15T10:30:00Z" format: date-time type: string type: object KeyStatistics: additionalProperties: false properties: entries: $ref: "#/components/schemas/KeyEntriesStatistics" description: DICT entry statistics for this key fraudMarkers: $ref: "#/components/schemas/FraudMarkersStatistics" description: Fraud marker statistics for this key infractionReports: $ref: "#/components/schemas/InfractionReportsStatistics" description: Infraction report statistics for this key spi: $ref: "#/components/schemas/SpiStatistics" description: SPI settlement statistics for this key required: - infractionReports - entries type: object KeyStatisticsOutput: additionalProperties: false properties: keyStatistics: $ref: "#/components/schemas/KeyStatistics" description: Statistics for the Pix key entity ownerStatistics: $ref: "#/components/schemas/PersonStatisticsOutput" description: Statistics for the key's current owner required: - keyStatistics - ownerStatistics type: object LedgerInfo: additionalProperties: false properties: destinationOperationId: examples: - 550e8400-e29b-41d4-a716-446655440013 type: string revert: $ref: "#/components/schemas/LedgerRevertInfo" sourceOperationId: examples: - 550e8400-e29b-41d4-a716-446655440012 type: string transactionId: examples: - 550e8400-e29b-41d4-a716-446655440011 type: string type: object LedgerRevertInfo: additionalProperties: false properties: destinationOperationId: examples: - 550e8400-e29b-41d4-a716-446655440016 type: string sourceOperationId: examples: - 550e8400-e29b-41d4-a716-446655440015 type: string transactionId: examples: - 550e8400-e29b-41d4-a716-446655440014 type: string type: object LegacyErrorBody: additionalProperties: false properties: code: type: string fields: additionalProperties: type: string type: object headers: additionalProperties: type: string type: object message: type: string paths: additionalProperties: type: string type: object queryParams: additionalProperties: type: string type: object raw: type: string title: type: string required: - code - title - message type: object ListChargesByAuthorizationOutput: additionalProperties: false properties: items: items: $ref: "#/components/schemas/ChargeOutput" type: array limit: examples: - 10 format: int64 type: integer page: examples: - 1 format: int64 type: integer total: examples: - 42 format: int64 type: integer required: - items - limit - page - total type: object ListDueDateCollectionsOutput: additionalProperties: false properties: items: items: $ref: "#/components/schemas/DueDateCollectionOutput" type: array limit: examples: - 20 format: int64 type: integer page: examples: - 1 format: int64 type: integer total: examples: - 150 format: int64 type: integer required: - items - page - limit type: object ListFundsRecoveryInfractionsOutput: additionalProperties: false properties: infractionReports: description: List of infraction reports associated with the funds recovery items: $ref: "#/components/schemas/FundsRecoveryInfractionOutput" type: array required: - infractionReports type: object ListFundsRecoveryRefundsOutput: additionalProperties: false properties: refunds: description: List of refunds associated with the funds recovery items: $ref: "#/components/schemas/FundsRecoveryRefundOutput" type: array required: - refunds type: object ListImmediateCollectionsOutput: additionalProperties: false properties: items: items: $ref: "#/components/schemas/ImmediateCollectionOutput" type: array limit: examples: - 10 format: int64 type: integer page: examples: - 1 format: int64 type: integer total: examples: - 150 format: int64 type: integer required: - items - limit - page - total type: object ListInboundWebhooksOutput: additionalProperties: false properties: items: items: $ref: "#/components/schemas/WebhookInboundOutput" type: array limit: examples: - 20 format: int64 type: integer page: examples: - 1 format: int64 type: integer totalItems: examples: - 42 format: int64 type: integer required: - items - page - limit - totalItems type: object ListOutboundWebhooksOutput: additionalProperties: false properties: items: items: $ref: "#/components/schemas/WebhookOutboundOutput" type: array limit: examples: - 20 format: int64 type: integer page: examples: - 1 format: int64 type: integer totalItems: examples: - 42 format: int64 type: integer required: - items - page - limit - totalItems type: object ListStaticBRCodesOutput: additionalProperties: false properties: items: description: Array of static BR Codes in this page items: $ref: "#/components/schemas/StaticBRCodeOutput" type: array limit: description: Number of items per page examples: - 20 format: int64 type: integer page: description: Current page number examples: - 1 format: int64 type: integer required: - items - page - limit type: object LocationInformationDTO: additionalProperties: true properties: categoryCode: examples: - "5411" type: string merchantCity: examples: - São Paulo type: string merchantName: examples: - Loja ABC type: string postalCode: examples: - 01310-100 type: string type: object OwnerDetails: additionalProperties: false properties: document: examples: - 12ABC34501DE35 type: string name: examples: - John Doe type: string tradeName: examples: - John's Business type: string type: enum: - NATURAL_PERSON - LEGAL_PERSON examples: - NATURAL_PERSON type: string required: - document - name - type type: object OwnerOutput: additionalProperties: false properties: document: description: Identification document of the account owner (CPF or CNPJ) examples: - "52998224725" type: string name: description: Full name or registered name of the account owner examples: - John Doe type: string tradeName: description: Business trade name or commercial alias examples: - John's Business type: string type: description: Whether the account owner is a person or organization enum: - NATURAL_PERSON - LEGAL_PERSON examples: - NATURAL_PERSON type: string required: - type - document - name - tradeName type: object PayAndConfirmFromQRInput: additionalProperties: false properties: amount: examples: - "29.90" minLength: 1 type: string description: examples: - Payment for services type: string idRec: examples: - RR0000000000000000001 maxLength: 64 minLength: 1 type: string initiationId: examples: - 550e8400-e29b-41d4-a716-446655440010 minLength: 1 type: string receiverMaxAmount: examples: - "500.00" type: string required: - idRec - initiationId - amount type: object PayAndConfirmFromQROutput: additionalProperties: false properties: authorizationRequest: $ref: "#/components/schemas/AuthorizationRequestOutput" cashoutId: examples: - 550e8400-e29b-41d4-a716-446655440010 type: string cashoutStatus: enum: - CREATED - PENDING - PROCESSING - COMPLETED examples: - PROCESSING type: string required: - authorizationRequest - cashoutId - cashoutStatus type: object PercentileRail: additionalProperties: false properties: perc50: format: double type: number perc99: format: double type: number transactionCount: format: int64 type: integer required: - perc50 - perc99 - transactionCount type: object PersonEntriesStatistics: additionalProperties: false properties: registeredAccounts: description: Number of accounts with registered Pix keys examples: - 2 format: int64 type: integer watermark: description: Datetime of last considered event for entry statistics examples: - "2024-01-15T10:30:00Z" format: date-time type: string type: object PersonStatisticsOutput: additionalProperties: false properties: entries: $ref: "#/components/schemas/PersonEntriesStatistics" description: Pix key entries statistics fraudMarkers: $ref: "#/components/schemas/FraudMarkersStatistics" description: Fraud marker statistics infractionReports: $ref: "#/components/schemas/InfractionReportsStatistics" description: Infraction report statistics spi: $ref: "#/components/schemas/SpiStatistics" description: SPI settlement statistics required: - fraudMarkers - infractionReports - entries type: object ReceiverOutput: additionalProperties: false properties: address: examples: - Rua das Flores, 123 type: string city: examples: - São Paulo type: string document: examples: - "52998224725" type: string name: examples: - João da Silva type: string state: examples: - SP type: string tradeName: examples: - Company Name type: string zipCode: examples: - 01310-100 type: string required: - name - document - address - city - state - zipCode type: object ReconciliationAccountInput: additionalProperties: true properties: branch: description: Bank branch code where the account is held examples: - "0001" type: string id: description: Unique identifier of the customer account (reconciliation mode) examples: - 550e8400-e29b-41d4-a716-446655440000 type: string number: description: Unique account number at the institution examples: - "123456789" type: string openingDate: description: Date when the account was opened examples: - "2020-01-15T10:30:00Z" format: date-time type: string participant: description: ISPB of the participant institution (8 alphanumeric characters) examples: - "30306294" type: string type: description: Kind of account holding this Pix key examples: - TRAN type: string type: object ReconciliationHolderInput: additionalProperties: true properties: document: description: Holder's CPF or CNPJ document examples: - "52998224725" type: string id: description: Unique identifier of the holder in CRM (reconciliation mode) examples: - 550e8400-e29b-41d4-a716-446655440001 type: string name: description: Holder's full name or company name examples: - John Doe type: string personType: description: "Person type: NATURAL_PERSON or LEGAL_PERSON" examples: - NATURAL_PERSON type: string tradeName: description: Business trade name (for LEGAL_PERSON) examples: - John's Business type: string type: object ReconciliationJobOutput: additionalProperties: false properties: completedAt: description: When the job finished - success, failure, or cancellation (ISO 8601 UTC) examples: - "2024-01-15T11:30:00Z" format: date-time type: string createdAt: description: When this reconciliation job was created (ISO 8601 UTC) examples: - "2024-01-15T10:30:00Z" format: date-time type: string entriesAdded: description: Number of entries created locally during reconciliation examples: - 10 format: int64 type: integer entriesRemoved: description: Number of entries soft-deleted locally during reconciliation examples: - 5 format: int64 type: integer errorMessage: description: Error details when status is FAILED examples: - File download failed type: string expiresAt: description: Expiration timestamp for WAITING_FILE jobs (ISO 8601 UTC) examples: - "2024-01-15T12:30:00Z" format: date-time type: string fileId: description: BTG file ID for FULL_RECONCILIATION jobs examples: - file-123456 type: string id: description: Unique identifier for this reconciliation job (UUID v7) examples: - 0192c3a4-5b6d-7e8f-9a0b-1c2d3e4f5a6b type: string jobType: description: Type of reconciliation job examples: - FULL_RECONCILIATION type: string keyType: description: PIX key type for this reconciliation job examples: - CPF type: string orphanEntries: description: Number of entries without holder in CRM examples: - 2 format: int64 type: integer processedItems: description: Number of CIDs/events processed examples: - 850 format: int64 type: integer reason: description: Reason for job creation examples: - Manual reconciliation requested type: string startedAt: description: When processing started (ISO 8601 UTC) examples: - "2024-01-15T10:30:00Z" format: date-time type: string status: description: Current status of the reconciliation job examples: - COMPLETED type: string syncFrom: description: Start date for EVENT_SYNC jobs (ISO 8601 UTC) examples: - "2024-01-15T10:30:00Z" format: date-time type: string totalItems: description: Total number of CIDs/events to process examples: - 1000 format: int64 type: integer updatedAt: description: When this reconciliation job was last updated (ISO 8601 UTC) examples: - "2024-01-15T11:30:00Z" format: date-time type: string required: - id - keyType - jobType - status - processedItems - entriesAdded - entriesRemoved - orphanEntries - createdAt - updatedAt type: object RecurrenceDecodeAmount: additionalProperties: false properties: amountRec: description: Fixed recurrence amount examples: - "29.90" type: string debitorMinimumAmount: description: Minimum debit amount for variable recurrences examples: - "10.00" type: string type: object RecurrenceDecodeCalendar: additionalProperties: false properties: finalDate: description: Last eligible debit date (optional) examples: - "2027-06-01" format: date type: string initialDate: description: First eligible debit date examples: - "2026-06-01" format: date type: string periodicity: description: Recurrence periodicity (WEEKLY, MONTHLY, QUARTERLY, SEMIANNUAL, ANNUAL, CUSTOM) enum: - WEEKLY - MONTHLY - QUARTERLY - SEMIANNUAL - ANNUAL - CUSTOM examples: - MONTHLY type: string required: - initialDate - periodicity type: object RecurrenceDecodeData: additionalProperties: false properties: amount: $ref: "#/components/schemas/RecurrenceDecodeAmount" description: Recurrence value profile calendar: $ref: "#/components/schemas/RecurrenceDecodeCalendar" description: Recurrence schedule idRec: description: BACEN recurrence identifier examples: - RR0000000000000000001 type: string link: $ref: "#/components/schemas/RecurrenceDecodeLink" description: Recurrence contract/debtor binding payee: $ref: "#/components/schemas/RecurrenceDecodePayee" description: Recurrence receiver/merchant recLocationUrl: description: Recurrence location URL (cache token for the recurrence payload) examples: - https://pix.example.com/rec/v2/abc123 type: string recurrenceCreationDate: description: Recurrence creation timestamp examples: - "2026-05-28T12:00:00Z" format: date-time type: string retryPolicy: description: Receiver multi-day retry policy (NO_RETRY, RETRY_3X_7D) enum: - NO_RETRY - RETRY_3X_7D examples: - RETRY_3X_7D type: string required: - idRec - recLocationUrl type: object RecurrenceDecodeDebtor: additionalProperties: false properties: cnpj: description: Debtor CNPJ (legal person) examples: - "96256999000103" type: string cpf: description: Debtor CPF (natural person) examples: - "61869782062" type: string name: description: Debtor name examples: - John Doe type: string required: - name type: object RecurrenceDecodeLink: additionalProperties: false properties: contract: description: Receiver contract reference examples: - contract-2026-001 type: string debtor: $ref: "#/components/schemas/RecurrenceDecodeDebtor" description: Recurrence debtor object: description: Recurrence object/description (optional) examples: - Streaming subscription type: string required: - contract type: object RecurrenceDecodeOutput: additionalProperties: false properties: recurrence: $ref: "#/components/schemas/RecurrenceDecodeData" description: Pix Automático recurrence data type: description: QR Code type identifier (RECURRENCE) examples: - RECURRENCE type: string required: - type - recurrence type: object RecurrenceDecodePayee: additionalProperties: false properties: cnpj: description: Receiver CNPJ examples: - "81626496000105" type: string name: description: Receiver name examples: - Streaming Co type: string participantIspb: description: Receiver PSP ISPB examples: - "12345678" type: string required: - cnpj - name - participantIspb type: object RefundAccountOutput: additionalProperties: false properties: accountNumber: description: Account number examples: - "123456" type: string accountType: description: Account type (CACC, SVGS, TRAN) examples: - CACC type: string branch: description: Branch number examples: - "0001" type: string document: description: CPF or CNPJ of the account holder examples: - "12345678909" type: string participant: description: ISPB code of the participant institution examples: - "99999011" type: string type: object RefundCashoutOutput: additionalProperties: false properties: accountId: examples: - 01989f9e-6508-79f8-9540-835be49fbd0d type: string amount: examples: - "100.50" type: string createdAt: examples: - "2024-01-15T10:30:00Z" type: string deletedAt: type: string description: examples: - Customer reported unauthorized transaction type: string id: examples: - 550e8400-e29b-41d4-a716-446655440001 type: string ledger: $ref: "#/components/schemas/LedgerInfo" metadata: additionalProperties: {} type: object originalEndToEndId: examples: - E12345678202411241430ABCDEFGHIJK type: string returnEndToEndId: examples: - D3030629420200808185300887639654 type: string status: enum: - CREATED - PENDING - PROCESSING - COMPLETED - REJECTED - FAILED - CANCELLED examples: - PENDING type: string type: enum: - CASHOUT - CASHIN examples: - CASHOUT type: string updatedAt: examples: - "2024-01-15T10:30:00Z" type: string required: - id - originalEndToEndId - returnEndToEndId - amount - status - type - accountId - createdAt - updatedAt type: object RefundOperation: additionalProperties: true properties: accountAlias: examples: - "@account/alias-conta-cliente" maxLength: 255 minLength: 1 type: string amount: examples: - "100.50" minLength: 1 type: string required: - accountAlias - amount type: object RefundOutput: additionalProperties: false properties: accountId: description: Account ID (UUID) of the contested Pix transfer when the request arrived through BTG; empty when it was opened through this API or the plugin could not resolve the contested transfer examples: - 550e8400-e29b-41d4-a716-446655440000 type: string analysisDetails: description: Analysis comments (max 2000 characters) examples: - Analysis confirms fraud. Refund approved. type: string analysisResult: description: Analysis result (if closed) enum: - TOTALLY_ACCEPTED - PARTIALLY_ACCEPTED - REJECTED examples: - TOTALLY_ACCEPTED type: string bacenFundsRecoveryId: description: BACEN/BTG funds-recovery identifier resolved via the associated infraction report (read-only, JOIN-derived) examples: - 91d65e98-97c0-4b0f-b577-73625da1f9fc type: string bacenRefundRequestId: description: BACEN/BTG refund request external identifier examples: - 3d48532f-a1b2-4422-81c3-b7dc852e262b type: string contestedParticipant: description: ISPB of the contested participant (8 uppercase alphanumeric characters) examples: - "12345678" type: string createdAt: description: Creation timestamp (ISO 8601 UTC) examples: - "2024-01-15T10:30:00Z" format: date-time type: string effectiveRefundedAmount: description: Amount effectively refunded in BRL examples: - "100.00" type: string id: description: Unique identifier of the refund request (UUID) examples: - 550e8400-e29b-41d4-a716-44665544r001 type: string infractionReportId: description: Related infraction report ID (UUID) examples: - 550e8400-e29b-41d4-a716-44665544f001 type: string monitorAccount: description: BACEN flag for account monitoring examples: - true type: boolean refundAccount: $ref: "#/components/schemas/RefundAccountOutput" description: Refund destination account details refundAmount: description: "Refund amount in BRL (format: 0.00)" examples: - "100.50" type: string refundDetails: description: Detailed justification (max 2000 characters) examples: - Customer reports unauthorized transaction type: string refundReason: description: Reason for the refund enum: - FRAUD - OPERATIONAL_FLAW - REFUND_CANCELLED examples: - FRAUD type: string refundRejectionReason: description: Rejection reason (if rejected) enum: - NO_BALANCE - ACCOUNT_CLOSURE - INVALID_REQUEST - OTHER examples: - NO_BALANCE type: string refundTransactionId: description: Refund transaction ID (if accepted, 32 characters) examples: - E98765432202411241500REFUNDTRANS type: string requestingParticipant: description: ISPB of the requesting participant (8 uppercase alphanumeric characters) examples: - "30306294" type: string status: description: Current status of the refund request enum: - OPEN - CLOSED - CANCELLED examples: - OPEN type: string transactionId: description: Pix End-to-End transaction ID (32 characters) examples: - E12345678202411241430ABCDEFGHIJK type: string updatedAt: description: Last update timestamp (ISO 8601 UTC) examples: - "2024-01-15T10:30:00Z" format: date-time type: string required: - id - bacenRefundRequestId - accountId - transactionId - requestingParticipant - contestedParticipant - refundReason - refundAmount - status - createdAt - updatedAt type: object RefundsListOutput: additionalProperties: false properties: items: items: $ref: "#/components/schemas/RefundCashoutOutput" type: array limit: examples: - 10 format: int64 type: integer page: examples: - 1 format: int64 type: integer total: examples: - 42 format: int64 type: integer required: - items - page - limit - total type: object ReportJobListResponse: additionalProperties: false properties: items: description: List of report job executions items: $ref: "#/components/schemas/ReportJobResponse" type: array limit: description: Maximum number of items per page examples: - 10 format: int64 type: integer page: description: Current page number examples: - 1 format: int64 type: integer total: description: Total count of matching items examples: - 42 format: int64 type: integer required: - items - page - limit - total type: object ReportJobResponse: additionalProperties: false properties: completedAt: description: When the job reached a terminal state. format: date-time type: string errorMessage: description: Generic failure reason when status is FAILED, including manual cancellations. type: string referenceMonth: description: Reference month of the job, in YYYY-MM format. examples: - 2026-05 type: string requestedAt: description: When the job was accepted. format: date-time type: string result: description: Computed percentiles. Present only when status is COMPLETED. oneOf: - $ref: "#/components/schemas/TemposTransacoesStatistics" - type: "null" startedAt: description: When background processing started. Absent while PENDING. format: date-time type: string status: description: PENDING = accepted, not started; RUNNING = in progress; COMPLETED = result available; FAILED = see errorMessage (includes cancelled jobs). enum: - PENDING - RUNNING - COMPLETED - FAILED type: string required: - referenceMonth - status - requestedAt type: object RetryWebhookOutput: additionalProperties: false properties: id: examples: - 019cf6ef-e418-7ced-80c0-7b9816faa798 type: string status: enum: - RECEIVED - PENDING type: string required: - id - status type: object ScheduleAttemptOutput: additionalProperties: false properties: attemptedAt: examples: - "2026-08-15T06:00:02Z" format: date-time type: string endToEndId: examples: - E1234567820260815060011111111111 type: string failureMessage: examples: - "Midaz error: balance below required (06:00 BRT attempt)" type: string failureReason: enum: - INSUFFICIENT_FUNDS - BTG_REJECTED - MIDAZ_REJECTED - VALIDATION_FAILED - SCHEDULE_STALE_TIMEOUT examples: - INSUFFICIENT_FUNDS type: string initiationId: examples: - a1111111-1111-4111-8111-111111111111 type: string transferId: examples: - f1a2b3c4-1111-4d5e-9f6a-7b8c9d0e1f23 type: string required: - attemptedAt - failureReason - failureMessage type: object ScheduleDestination: additionalProperties: false properties: account: $ref: "#/components/schemas/ScheduleDestinationAccount" key: examples: - john.doe@example.com type: string owner: $ref: "#/components/schemas/ScheduleDestinationOwner" required: - account - owner type: object ScheduleDestinationAccount: additionalProperties: false properties: branch: examples: - "0001" type: string number: examples: - "123456789" type: string participant: examples: - "12345678" type: string type: enum: - CACC - SVGS - TRAN - OTHR examples: - CACC type: string required: - branch - number - participant - type type: object ScheduleDestinationOwner: additionalProperties: false properties: document: examples: - "52998224725" type: string name: examples: - John Doe type: string tradeName: examples: - John's Business type: string required: - document - name type: object ScheduleOutput: additionalProperties: false properties: accountId: examples: - 019cf6ef-e418-7ced-80c0-7b9816faa798 type: string amount: examples: - "100.50" type: string attemptCount: examples: - 0 format: int64 type: integer attempts: items: $ref: "#/components/schemas/ScheduleAttemptOutput" type: array cancelledAt: examples: - "2026-05-19T09:15:33Z" format: date-time type: string createdAt: examples: - "2026-05-26T12:30:00Z" format: date-time type: string description: examples: - Recurring charge installment 03/12 type: string destination: $ref: "#/components/schemas/ScheduleDestination" endToEndId: examples: - E1234567820260815060012345678901 type: string executedAt: examples: - "2026-08-15T06:00:04Z" format: date-time type: string failedAt: examples: - "2026-08-15T06:00:04Z" format: date-time type: string failureMessage: type: string failureReason: enum: - INSUFFICIENT_FUNDS - BTG_REJECTED - MIDAZ_REJECTED - VALIDATION_FAILED - SCHEDULE_STALE_TIMEOUT - SCHEDULE_RETRIES_EXHAUSTED examples: - INSUFFICIENT_FUNDS type: string firedAt: examples: - "2026-08-15T06:00:04Z" format: date-time type: string id: examples: - 01989f9e-6508-79f8-9540-835be49fbd0d type: string initiationId: examples: - 550e8400-e29b-41d4-a716-446655440010 type: string initiationType: enum: - MANUAL - KEY - QR_CODE examples: - MANUAL type: string maxAttempts: examples: - 2 format: int64 type: integer recurrenceId: examples: - 01988a7c-1234-7abc-8def-111122223333 type: string scheduledFor: examples: - "2026-08-15T09:00:00Z" format: date-time type: string status: enum: - SCHEDULED - PROCESSING - EXECUTED - FAILED - CANCELLED examples: - SCHEDULED type: string transferId: examples: - c8d27e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f type: string updatedAt: examples: - "2026-05-26T12:30:00Z" format: date-time type: string required: - id - accountId - initiationId - status - scheduledFor - amount - initiationType - destination - attemptCount - maxAttempts - attempts - createdAt - updatedAt type: object SchedulesListOutput: additionalProperties: false properties: items: items: $ref: "#/components/schemas/ScheduleOutput" type: array limit: examples: - 10 format: int64 type: integer page: examples: - 1 format: int64 type: integer total: examples: - 42 format: int64 type: integer required: - items - page - limit - total type: object SkippedKeyTypeInfo: additionalProperties: false properties: keyType: description: PIX key type that was skipped examples: - CNPJ type: string reason: description: Explanation of why the key type was skipped examples: - Already synchronized (SYNCED) type: string syncStatus: description: Current sync status of this key type examples: - SYNCED type: string required: - keyType - reason type: object SourceDestination: additionalProperties: false properties: account: $ref: "#/components/schemas/AccountDetails" key: examples: - chave@pix.com type: string owner: $ref: "#/components/schemas/OwnerDetails" type: object SpiStatistics: additionalProperties: false properties: settlements: $ref: "#/components/schemas/TimeBasedValues" description: Settlement transaction counters watermark: description: Datetime of last considered event for SPI statistics examples: - "2024-01-15T10:30:00Z" format: date-time type: string type: object StaticBRCodeMerchant: additionalProperties: false properties: categoryCode: description: Merchant category code (MCC) examples: - "5411" type: string city: description: City where the merchant is located examples: - São Paulo type: string name: description: Name of the merchant examples: - Loja ABC type: string postalCode: description: Postal code (CEP) of the merchant examples: - "01310000" type: string type: object StaticBRCodeMerchantInput: additionalProperties: true properties: categoryCode: description: Merchant category code (MCC) examples: - "5411" type: string city: description: City where the merchant is located examples: - São Paulo type: string name: description: Name of the merchant examples: - Loja ABC type: string postalCode: description: Postal code (CEP) of the merchant examples: - "01310000" type: string type: object StaticBRCodeOutput: additionalProperties: false properties: amount: description: Fixed payment amount (optional) examples: - "100.00" type: string base64: description: Base64-encoded QR code image (when requested) examples: - data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA... type: string createdAt: description: Timestamp when the BR Code was created examples: - "2024-01-15T10:30:00Z" type: string description: description: Custom message or description shown to the payer examples: - "Payment for order #12345" type: string emv: description: QR code payload in EMV format examples: - 000201010212... type: string id: description: Unique identifier of the BR Code examples: - 550e8400-e29b-41d4-a716-446655440010 type: string merchant: $ref: "#/components/schemas/StaticBRCodeMerchant" description: Merchant metadata for this BR Code receiverKey: description: Pix key that will receive the payment examples: - "+5511999999999" type: string tags: description: Array of custom tags for categorization examples: - - checkout - web items: type: string type: array txId: description: Transaction identification (txid) sent on the payment message examples: - ORDER-12345 type: string required: - id - emv - receiverKey - createdAt type: object StaticDecodeMerchant: additionalProperties: false properties: categoryCode: description: Merchant category code (MCC) examples: - "5411" type: string city: description: City where the merchant is located examples: - São Paulo type: string name: description: Name of the merchant examples: - Loja ABC type: string postalCode: description: Postal code (CEP) of the merchant examples: - 01310-100 type: string type: object StaticDecodeOutput: additionalProperties: false properties: amount: description: Fixed payment amount (optional) examples: - "100.00" type: string description: description: Custom message or description shown to the payer examples: - "Payment for order #12345" type: string merchant: $ref: "#/components/schemas/StaticDecodeMerchant" description: Merchant information from the QR code receiverKey: description: Pix key that will receive the payment examples: - "+5511999999999" type: string recurrence: $ref: "#/components/schemas/RecurrenceDecodeData" description: Pix Automático recurrence data (present only for recurrence-bearing QR codes) txId: description: Transaction identification (txid) sent on the payment message examples: - TX123ABC type: string type: description: QR Code type identifier (STATIC) examples: - STATIC type: string required: - type - receiverKey type: object TemposTransacoesStatistics: additionalProperties: false properties: liqForaSpi: $ref: "#/components/schemas/PercentileRail" liqSpi: $ref: "#/components/schemas/PercentileRail" referenceMonth: type: string unit: type: string required: - referenceMonth - unit - liqSpi - liqForaSpi type: object TimeBasedValues: additionalProperties: false properties: d90: description: Counter for the last 90 days examples: - "36" type: string m12: description: Counter for the last 12 months examples: - "51" type: string m60: description: Counter for the last 60 months (5 years) examples: - "44" type: string type: object TrackingGraphAccountOutput: additionalProperties: false properties: id: description: Identifier of the account node in the graph examples: - 1 format: int64 type: integer openingDate: description: Date the account was opened examples: - "2020-01-15" type: string ownerId: description: Identifier of the owning person node examples: - 1 format: int64 type: integer participant: description: ISPB of the participant institution (8 digits) examples: - "12345678" type: string required: - id - ownerId - participant - openingDate type: object TrackingGraphOutput: additionalProperties: false properties: accounts: description: Accounts involved in the transaction graph items: $ref: "#/components/schemas/TrackingGraphAccountOutput" type: array creationTime: description: Graph creation timestamp examples: - "2023-11-07T05:31:56Z" format: date-time type: string fundsRecoveryId: description: Funds recovery identifier examples: - 550e8400-e29b-41d4-a716-446655440000 type: string parameters: $ref: "#/components/schemas/TrackingGraphParametersOutput" description: Parameters used for graph generation persons: description: Persons involved in the transaction graph items: $ref: "#/components/schemas/TrackingGraphPersonOutput" type: array rootTransactionId: description: Root transaction ID examples: - E12345678202411241430ABCDEFGHIJK type: string transactions: description: Transactions in the graph items: $ref: "#/components/schemas/TrackingGraphTxOutput" type: array required: - fundsRecoveryId - rootTransactionId - parameters - persons - accounts - transactions - creationTime type: object TrackingGraphParametersInput: additionalProperties: true properties: hopWindow: description: Time window for hop analysis examples: - PT24H type: string maxHops: description: "Maximum number of hops: 1 to 2; BTG default 2" examples: - 2 format: int64 type: integer maxTransactions: description: "Maximum number of transactions: at least 1; BTG enforces the upper bound and reports it in PIX-0295" examples: - 5 format: int64 type: integer minTransactionAmount: description: "Minimum transaction amount to include: 1 to 10 digits, a dot and 2 decimal places, e.g. 200.00" examples: - "200.00" type: string type: object TrackingGraphParametersOutput: additionalProperties: false properties: hopWindow: description: Time window for hop analysis examples: - PT24H type: string maxHops: description: Maximum number of hops followed examples: - 2 format: int64 type: integer maxTransactions: description: Maximum number of transactions included in the graph examples: - 5 format: int64 type: integer minTransactionAmount: description: Minimum transaction amount included in the graph examples: - "200.00" type: string required: - minTransactionAmount - maxTransactions - hopWindow - maxHops type: object TrackingGraphPersonOutput: additionalProperties: false properties: entityCreationDate: description: Date the person entity was created examples: - "2020-01-15" type: string id: description: Identifier of the person node in the graph examples: - 1 format: int64 type: integer type: description: Person type (NATURAL_PERSON or LEGAL_PERSON) examples: - NATURAL_PERSON type: string required: - id - type type: object TrackingGraphTxOutput: additionalProperties: false properties: amount: description: Transaction amount in BRL examples: - 1000.5 format: double type: number creditorAccountId: description: Identifier of the creditor account node examples: - 2 format: int64 type: integer debtorAccountId: description: Identifier of the debtor account node examples: - 1 format: int64 type: integer id: description: Transaction End-to-End identifier examples: - E12345678202411241430ABCDEFGHIJK type: string refundableAmount: description: Refundable amount in BRL examples: - 1000.5 format: double type: number settlementTime: description: Settlement timestamp (ISO 8601 UTC) examples: - "2023-11-07T05:31:56Z" type: string transactionDepth: description: Depth of the transaction in the DICT tracking graph (root = 1). Set by DICT. examples: - 1 format: int64 type: integer required: - id - debtorAccountId - creditorAccountId - amount - refundableAmount - settlementTime type: object TransactionReportListOutput: additionalProperties: false properties: items: items: $ref: "#/components/schemas/TransactionReportResponse" type: array limit: examples: - 10 format: int64 type: integer page: examples: - 1 format: int64 type: integer total: examples: - 42 format: int64 type: integer required: - items - page - limit - total type: object TransactionReportParty: additionalProperties: false properties: account: examples: - "123456" type: string accountType: examples: - CACC type: string bank: examples: - "12345678" type: string branch: examples: - "0001" type: string document: examples: - "52998224725" type: string key: examples: - email@test.com type: string required: - bank type: object TransactionReportResponse: additionalProperties: false properties: amount: examples: - "100.50" type: string clientRequestId: examples: - 550e8400-e29b-41d4-a716-446655440000 type: string confirmedAt: examples: - "2024-01-15T10:32:00Z" format: date-time type: string createdAt: examples: - "2024-01-15T10:30:00Z" format: date-time type: string creditParty: $ref: "#/components/schemas/TransactionReportParty" debitParty: $ref: "#/components/schemas/TransactionReportParty" endToEndId: examples: - E12345678202411241430ABCDEFGHIJK type: string id: examples: - 01989f9e-6508-79f8-9540-835be49fbd0d type: string initiationType: examples: - DICT type: string pactualId: examples: - 550e8400-e29b-41d4-a716-446655440001 type: string returnId: examples: - D12345678202411241430ABCDEFGHIJK type: string status: enum: - PENDING - PROCESSING - CONFIRMED - ERROR examples: - CONFIRMED type: string submittedAt: examples: - "2024-01-15T10:31:00Z" format: date-time type: string transactionDate: examples: - "2024-01-15T10:30:00Z" format: date-time type: string updatedAt: examples: - "2024-01-15T10:32:00Z" format: date-time type: string required: - id - endToEndId - clientRequestId - status - amount - initiationType - debitParty - creditParty - transactionDate - createdAt - updatedAt type: object TransactionReportSubmitOutput: additionalProperties: false properties: id: examples: - 550e8400-e29b-41d4-a716-446655440000 type: string status: examples: - PROCESSING type: string required: - id - status type: object TransferResponse: additionalProperties: false properties: accountId: examples: - 01989f9e-6508-79f8-9540-835be49fbd0d type: string aliasId: examples: - 01989f9e-6508-79f8-9540-835be49fbd0e type: string amount: examples: - "100.50" type: string createdAt: examples: - "2024-01-15T10:30:15Z" type: string deletedAt: type: string description: examples: - Pix Cashin Transfer type: string destination: $ref: "#/components/schemas/SourceDestination" endToEndId: examples: - E1234567820240101000001234567890 type: string feeCharge: $ref: "#/components/schemas/FeeChargeResponse" id: examples: - 550e8400-e29b-41d4-a716-446655440010 type: string initiatedAt: examples: - "2024-01-15T10:30:00Z" type: string initiationType: enum: - MANUAL - KEY - QR_CODE examples: - KEY type: string ledger: $ref: "#/components/schemas/LedgerInfo" metadata: additionalProperties: {} type: object paymentType: enum: - IMMEDIATE - SCHEDULED examples: - IMMEDIATE type: string purpose: enum: - TRANSFER - INSTANT_PAYMENT_REFUND - CHANGE - WITHDRAWAL examples: - TRANSFER type: string source: $ref: "#/components/schemas/SourceDestination" status: enum: - CREATED - PENDING - PROCESSING - COMPLETED - FAILED - REVERSED examples: - COMPLETED type: string txId: description: Transaction ID (txId) declared by the QR Code this cash-in paid. For a dynamic QR Code it is the charge's own txId, proven against that charge before the cash-in was accepted. For a static BR Code it is whatever reference label the code declared, which may match no charge. initiationType answers QR_CODE for both, so treat this as a correlation hint rather than proof a charge was paid. Absent for a payment with no QR Code and for every cash-out. examples: - cob7f3a9c2e4b118d type: string type: enum: - CASHIN - CASHOUT examples: - CASHIN type: string updatedAt: examples: - "2024-01-15T10:35:00Z" type: string urgency: enum: - HIGH - NORMAL examples: - HIGH type: string withdrawal: $ref: "#/components/schemas/WithdrawalBreakdownResponse" required: - id - amount - endToEndId - status - type - paymentType - initiationType - urgency - purpose - accountId - createdAt - updatedAt type: object TransfersListOutput: additionalProperties: false properties: items: items: $ref: "#/components/schemas/TransferResponse" type: array limit: examples: - 10 format: int64 type: integer page: examples: - 1 format: int64 type: integer total: examples: - 42 format: int64 type: integer required: - items - page - limit - total type: object UnblockRefundOutput: additionalProperties: false properties: btgStatus: description: Status retrieved from BTG (for transparency) examples: - CONFIRMED type: string message: description: Additional context about the unblock result examples: - Refund successfully unblocked. type: string refund: $ref: "#/components/schemas/RefundCashoutOutput" description: Updated refund details after the unblock attempt required: - refund - message - btgStatus type: object UnblockTransferOutput: additionalProperties: false properties: btgStatus: type: string message: type: string transfer: $ref: "#/components/schemas/TransferResponse" required: - transfer - message - btgStatus type: object UpdateAmountObject: additionalProperties: true properties: abatement: $ref: "#/components/schemas/AbatementObject" discount: $ref: "#/components/schemas/DiscountObject" fine: $ref: "#/components/schemas/FineObject" interest: $ref: "#/components/schemas/InterestObject" original: description: Optional; when sent it must equal the collection's current original amount examples: - "100.00" type: string type: object UpdateDueDateCollectionInput: additionalProperties: false properties: additionalInfo: additionalProperties: type: string examples: - customerId: "67890" orderId: "12345" type: object amount: $ref: "#/components/schemas/UpdateAmountObject" debtor: $ref: "#/components/schemas/DebtorInput" description: examples: - "Payment for order #12345" type: string dueDate: examples: - "2024-12-31" type: string metadata: additionalProperties: {} type: object receiverKey: examples: - "+5511999999999" type: string tags: examples: - - ecommerce - subscription items: type: string type: array validAfterDue: examples: - 5 format: int64 type: integer type: object UpdateEntryAccountInput: additionalProperties: true properties: branch: description: Bank branch code where the account is held (4 digits) examples: - "0001" minLength: 1 type: string number: description: "Unique account number at the institution: 1-20 uppercase letters or digits. A letter check digit is sent to DICT as 0" examples: - "123456789" minLength: 1 type: string openingDate: description: Date when the account was opened examples: - "2020-01-15T10:30:00Z" format: date-time type: string participant: description: ISPB of the participant institution (8 alphanumeric characters) examples: - "12345678" minLength: 1 type: string type: description: Type of account holding the Pix key enum: - CACC - SLRY - SVGS - TRAN - OTHR examples: - TRAN minLength: 1 type: string required: - branch - number - openingDate - participant - type type: object UpdateEntryInput: additionalProperties: false properties: account: $ref: "#/components/schemas/UpdateEntryAccountInput" description: Updated account information metadata: additionalProperties: {} description: Optional key-value map for updating custom attributes (JSON Merge Patch semantics) type: object owner: $ref: "#/components/schemas/UpdateEntryOwnerInput" description: Updated owner information required: - account - owner type: object UpdateEntryOwnerInput: additionalProperties: true properties: name: description: Full name or registered name of the account owner examples: - Jane Doe minLength: 1 type: string tradeName: description: Business trade name or alias examples: - Jane's Business type: string required: - name type: object UpdateFundsRecoveryInput: additionalProperties: false properties: contactInformation: $ref: "#/components/schemas/ContactInformation" description: Contact information of the person reporting the fraud reportDetails: description: Detailed description of the fraud incident (max 2000 characters) examples: - Updated details about the fraud incident maxLength: 2000 type: string situationType: description: Type of fraud situation enum: - SCAM - ACCOUNT_TAKEOVER - COERCION - FRAUDULENT_ACCESS - OTHER - UNKNOWN examples: - SCAM minLength: 1 type: string required: - situationType - contactInformation type: object UpdateImmediateCollectionInput: additionalProperties: false properties: additionalInfo: additionalProperties: type: string examples: - status: updated version: "2" type: object amount: examples: - "150.00" type: string debtorDocument: examples: - "52998224725" type: string debtorName: examples: - Maria Santos type: string description: examples: - Updated payment description type: string expirationSeconds: examples: - 7200 exclusiveMinimum: 0 format: int64 type: integer metadata: additionalProperties: {} type: object receiverKey: examples: - "+5511988888888" type: string tags: examples: - - updated - revised items: type: string type: array type: object VSyncStateOutput: additionalProperties: false properties: createdAt: description: When this VSync state record was created (ISO 8601 UTC) examples: - "2024-01-15T10:30:00Z" format: date-time type: string id: description: Unique identifier for this VSync state (UUID v7) examples: - 0192c3a4-5b6d-7e8f-9a0b-1c2d3e4f5a6b type: string keyType: description: PIX key type for this VSync state (CPF, CNPJ, EMAIL, PHONE, EVP) examples: - CPF type: string lastCidCreatedAt: description: Creation timestamp of the last CID processed (ISO 8601 UTC) examples: - "2024-01-15T10:30:00Z" format: date-time type: string lastFullReconciliation: description: When the last full reconciliation was performed (ISO 8601 UTC) examples: - "2024-01-15T10:30:00Z" format: date-time type: string lastSyncCheck: description: When the last sync check was performed with BTG (ISO 8601 UTC) examples: - "2024-01-15T10:30:00Z" format: date-time type: string lastSyncStatus: description: Current synchronization status (SYNCED, OUT_OF_SYNC, RECONCILING, ERROR) examples: - SYNCED type: string lastSyncTimestamp: description: When the local VSync was last calculated (ISO 8601 UTC) examples: - "2024-01-15T10:30:00Z" format: date-time type: string localVSync: description: Local VSync value (64 hex characters) examples: - "0000000000000000000000000000000000000000000000000000000000000000" type: string updatedAt: description: When this VSync state record was last updated (ISO 8601 UTC) examples: - "2024-01-15T10:30:00Z" format: date-time type: string required: - id - keyType - localVSync - lastSyncStatus - createdAt - updatedAt type: object WebhookInboundOutput: additionalProperties: false properties: attemptCount: examples: - 0 format: int64 type: integer createdAt: examples: - "2026-05-21T12:00:00Z" format: date-time type: string entityType: examples: - DICT_CLAIM type: string errorMessage: examples: - timeout calling downstream type: string id: examples: - 019cf6ef-e418-7ced-80c0-7b9816faa798 type: string lastAttemptAt: examples: - "2026-05-21T12:00:00Z" format: date-time type: string maxRetries: examples: - 3 format: int64 type: integer nextRetryAt: examples: - "2026-05-21T12:00:00Z" format: date-time type: string payload: {} processedAt: examples: - "2026-05-21T12:00:00Z" format: date-time type: string receivedAt: examples: - "2026-05-21T12:00:00Z" format: date-time type: string requestId: examples: - 560d59b9-3c74-46f8-be67-fee895b8e89e type: string source: examples: - BTG type: string status: enum: - RECEIVED - PROCESSING - SENT - FAILED examples: - RECEIVED type: string updatedAt: examples: - "2026-05-21T12:00:00Z" format: date-time type: string required: - id - requestId - entityType - source - status - attemptCount - maxRetries - receivedAt - createdAt - updatedAt type: object WebhookOutboundOutput: additionalProperties: false properties: attemptCount: examples: - 0 format: int64 type: integer createdAt: examples: - "2026-05-21T12:00:00Z" format: date-time type: string deadLetter: examples: - false type: boolean deliveredAt: examples: - "2026-05-21T12:00:00Z" format: date-time type: string entityId: examples: - 019cf6ef-e418-7ced-80c0-7b9816faa798 type: string entityType: examples: - DICT_ENTRY type: string errorMessage: examples: - timeout calling target URL type: string failedAt: examples: - "2026-05-21T12:00:00Z" format: date-time type: string failureReason: examples: - max_retries_exceeded type: string flowType: examples: - DICT type: string id: examples: - 019cf6ef-e418-7ced-80c0-7b9816faa798 type: string lastAttemptAt: examples: - "2026-05-21T12:00:00Z" format: date-time type: string maxRetries: examples: - 3 format: int64 type: integer movedBy: examples: - outbound-worker type: string nextRetryAt: examples: - "2026-05-21T12:00:00Z" format: date-time type: string payload: {} requestId: examples: - 560d59b9-3c74-46f8-be67-fee895b8e89e type: string status: enum: - PENDING - PROCESSING - SENT - FAILED - DEAD_LETTER examples: - PENDING type: string targetUrl: examples: - https://client.example.com/webhooks type: string updatedAt: examples: - "2026-05-21T12:00:00Z" format: date-time type: string required: - id - requestId - entityId - entityType - flowType - status - attemptCount - maxRetries - createdAt - updatedAt type: object WithdrawalBreakdownResponse: additionalProperties: false properties: agentMode: enum: - AGTEC - AGTOT - AGPSS examples: - AGTEC type: string transactionAmount: examples: - "80.00" type: string withdrawalAmount: examples: - "50.00" type: string withdrawalServiceProvider: examples: - "12345678" type: string required: - withdrawalAmount - agentMode - withdrawalServiceProvider type: object WithdrawalDecodeData: additionalProperties: false properties: agentMode: description: BACEN withdrawal agent modality examples: - AGTOT type: string amountEditable: description: Whether the payer may change the withdrawal amount examples: - false type: boolean nature: description: Withdrawal nature (WITHDRAWAL for Pix Saque, CHANGE for Pix Troco) enum: - WITHDRAWAL - CHANGE examples: - WITHDRAWAL type: string transactionAmount: description: Purchase amount (present only for Pix Troco) examples: - "80.00" type: string withdrawalAmount: description: Withdrawal amount handed to the payer as cash examples: - "50.00" type: string withdrawalServiceProvider: description: ISPB of the withdrawal service provider examples: - "12345678" type: string required: - nature - withdrawalAmount - agentMode - withdrawalServiceProvider - amountEditable type: object securitySchemes: BearerAuth: bearerFormat: JWT description: JWT bearer token issued by the identity provider. scheme: bearer type: http info: contact: email: contact@lerian.studio name: Lerian Studio url: https://lerian.studio description: API for Pix Indirect via BTG. It covers DICT keys and claims; MED infraction reports, fraud markers, refund requests, and funds recoveries; DICT statistics and reconciliation; Pix transfers, refunds, and schedules; static QR codes and QR code decoding; immediate and due-date collections; Pix Automático for the payer; transaction reports and TemposTransacoes statistics; and inbound and outbound webhook records. license: name: Lerian Studio General License title: Pix BTG API version: 1.14.0 openapi: 3.1.0 paths: /v1/admin/collections/{collection_id}/complete: post: description: Use this operator endpoint to change a collection from ACTIVE to COMPLETED. It changes only the collection status and makes no call to Midaz or BTG. A collection in any other status is rejected. Identify the collection by its id (collection_id), not by its txId. operationId: collection-admin-complete parameters: - description: Identifier of the collection to force-complete in: path name: collection_id required: true schema: description: Identifier of the collection to force-complete type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/AdminCompleteCollectionBody" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Complete a Charge tags: - Admin x-mint: href: /pt/reference/interfaces/pix-btg/complete-a-charge /v1/brcode/static: get: description: "Use this endpoint to list the static Pix BR Codes issued with the institution's BTG credentials, across every account; `X-Account-Id` is not read. Answers `items: []` when the page holds no codes." operationId: brcode-list-static parameters: - description: Page number (defaults to 1) explode: false in: query name: page schema: default: 1 description: Page number (defaults to 1) format: int64 type: integer - description: Page size (defaults to 20, maximum 100) explode: false in: query name: limit schema: default: 20 description: Page size (defaults to 20, maximum 100) format: int64 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/ListStaticBRCodesOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: List Static QR Codes tags: - Static QR Codes x-mint: href: /pt/reference/interfaces/pix-btg/list-static-qr-codes post: description: |- Use this endpoint to create a static Pix BR Code that can be reused for multiple payments. **Notes:** - Static QR Codes are reusable and can be paid multiple times - Amount is optional - if not provided, the payer will enter the amount - The receiver key must be owned by the account holder making the request - The QR Code payload (EMV) is generated following the EMV QCO specification operationId: brcode-create-static parameters: - description: Account ID (UUID format) in: header name: X-Account-Id required: true schema: description: Account ID (UUID format) format: uuid type: string - description: Returns the rendered QR code in base64 alongside the EMV payload explode: false in: query name: include_base64 schema: default: false description: Returns the rendered QR code in base64 alongside the EMV payload type: boolean requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateStaticBRCodeInput" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/StaticBRCodeOutput" description: Created "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "413": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Request Entity Too Large "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Create a Static QR Code tags: - Static QR Codes x-mint: href: /pt/reference/interfaces/pix-btg/create-a-static-qr-code /v1/brcode/static/{brcode_id}: get: description: "Use this endpoint to retrieve a static Pix BR Code by its BTG id. The read is institution-wide: any code issued with the institution's BTG credentials is returned, whichever account created it, and `X-Account-Id` is not read." operationId: brcode-get-static parameters: - description: Static BR Code identifier in: path name: brcode_id required: true schema: description: Static BR Code identifier type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/StaticBRCodeOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Retrieve Static QR Code Details tags: - Static QR Codes x-mint: href: /pt/reference/interfaces/pix-btg/retrieve-a-static-qr-code /v1/collections/duedate: get: description: Use this endpoint to list all due date collections for an account with optional filters and pagination. Returns empty array [] if no collections match the criteria. operationId: collection-list-duedate parameters: - description: Account ID (UUID format) in: header name: X-Account-Id required: true schema: description: Account ID (UUID format) format: uuid type: string - description: Maximum number of collections per page (1-100) explode: false in: query name: limit schema: default: 10 description: Maximum number of collections per page (1-100) format: int64 type: integer - description: Page number for pagination (starting at 1) explode: false in: query name: page schema: default: 1 description: Page number for pagination (starting at 1) format: int64 type: integer - description: "Status filter. Allowed values: ACTIVE, COMPLETED, REMOVED_BY_RECEIVER, REMOVED_BY_PSP" explode: false in: query name: status schema: description: "Status filter. Allowed values: ACTIVE, COMPLETED, REMOVED_BY_RECEIVER, REMOVED_BY_PSP" items: type: string type: array - description: Tags filter explode: false in: query name: tags schema: description: Tags filter items: type: string type: array - description: Metadata key to filter by explode: false in: query name: metadata.key schema: description: Metadata key to filter by type: string - description: Metadata value to filter by (requires metadata.key) explode: false in: query name: metadata.value schema: description: Metadata value to filter by (requires metadata.key) type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/ListDueDateCollectionsOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: List Dynamic Charges with Due Date tags: - Due Date Collections x-mint: href: /pt/reference/interfaces/pix-btg/list-dynamic-charges-with-due-date post: description: |- Use this endpoint to create a due date Pix collection (cobrança com vencimento) with complex payment rules including fines, interest, discounts, and rebates. **Notes:** - Similar to traditional boletos with Pix payment capability - Due date defines when payment is expected - Supports complex amount calculations with fines, interest, discounts, and rebates - Requires complete debtor and receiver information - Transaction ID (txId) must be unique per receiver - Collection remains valid for a configurable period after the due date operationId: collection-create-duedate parameters: - description: Account ID (UUID format) in: header name: X-Account-Id required: true schema: description: Account ID (UUID format) format: uuid type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateDueDateCollectionInput" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/DueDateCollectionOutput" description: Created "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "413": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Request Entity Too Large "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Create a Dynamic Charge with Due Date tags: - Due Date Collections x-mint: href: /pt/reference/interfaces/pix-btg/create-a-dynamic-charge-with-due-date /v1/collections/duedate/{collection_id}: get: description: Use this endpoint to retrieve detailed information about a specific due date collection. operationId: collection-get-duedate parameters: - description: Identifier of the due date collection in: path name: collection_id required: true schema: description: Identifier of the due date collection type: string - description: Account ID (UUID format) in: header name: X-Account-Id required: true schema: description: Account ID (UUID format) format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/DueDateCollectionOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Retrieve Dynamic Charge with Due Date Details tags: - Due Date Collections x-mint: href: /pt/reference/interfaces/pix-btg/retrieve-dynamic-charge-with-due-date-details patch: description: "Use this endpoint to update a due date collection. Only collections in ACTIVE status can be updated. The charge amount cannot change: amount.original is optional, and when sent it must repeat the current amount; any other value answers 400 PIX-0004." operationId: collection-update-duedate parameters: - description: Identifier of the due date collection in: path name: collection_id required: true schema: description: Identifier of the due date collection type: string - description: Account ID (UUID format) in: header name: X-Account-Id required: true schema: description: Account ID (UUID format) format: uuid type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/UpdateDueDateCollectionInput" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/DueDateCollectionOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "413": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Request Entity Too Large "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Update a Dynamic Charge with Due Date tags: - Due Date Collections x-mint: href: /pt/reference/interfaces/pix-btg/update-a-dynamic-charge-with-due-date /v1/collections/immediate: get: description: Use this endpoint to list all immediate collections for an account with optional filters and pagination. Returns empty array [] if no collections match the criteria. operationId: collection-list-immediate parameters: - description: Account ID (UUID format) in: header name: X-Account-Id required: true schema: description: Account ID (UUID format) format: uuid type: string - description: Maximum number of collections per page (1-100) explode: false in: query name: limit schema: default: 10 description: Maximum number of collections per page (1-100) format: int64 type: integer - description: Page number for pagination (starting at 1) explode: false in: query name: page schema: default: 1 description: Page number for pagination (starting at 1) format: int64 type: integer - description: "Status filter. Allowed values: ACTIVE, COMPLETED, EXPIRED, DELETED" explode: false in: query name: status schema: description: "Status filter. Allowed values: ACTIVE, COMPLETED, EXPIRED, DELETED" items: type: string type: array - description: Tags filter explode: false in: query name: tags schema: description: Tags filter items: type: string type: array - description: Metadata key to filter by explode: false in: query name: metadata.key schema: description: Metadata key to filter by type: string - description: Metadata value to filter by (requires metadata.key) explode: false in: query name: metadata.value schema: description: Metadata value to filter by (requires metadata.key) type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/ListImmediateCollectionsOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: List Immediate Charges tags: - Immediate Collections x-mint: href: /pt/reference/interfaces/pix-btg/list-immediate-charges post: description: |- Use this endpoint to create an immediate Pix collection (cobrança imediata) with a dynamic QR Code that is valid for a defined period. **Notes:** - Each immediate collection is unique and can only be paid once - Amount and expiration time are required - Transaction ID (txId) must be unique per receiver - Status changes to COMPLETED when payment is received operationId: collection-create-immediate parameters: - description: Account ID (UUID format) in: header name: X-Account-Id required: true schema: description: Account ID (UUID format) format: uuid type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateImmediateCollectionInput" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/ImmediateCollectionOutput" description: Created "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "413": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Request Entity Too Large "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Create an Immediate Charge tags: - Immediate Collections x-mint: href: /pt/reference/interfaces/pix-btg/create-an-immediate-charge /v1/collections/immediate/{collection_id}: delete: description: |- Use this endpoint to delete (cancel) an immediate collection. **Notes:** - This operation cancels the collection and changes its status - Collections with status COMPLETED cannot be deleted - The deletion reason is required operationId: collection-delete-immediate parameters: - description: Identifier of the immediate collection in: path name: collection_id required: true schema: description: Identifier of the immediate collection type: string - description: Account ID (UUID format) in: header name: X-Account-Id required: true schema: description: Account ID (UUID format) format: uuid type: string - description: "Reason for deletion. Valid values: DELETED_BY_USER, DELETED_BY_PSP" in: header name: X-Reason required: true schema: description: "Reason for deletion. Valid values: DELETED_BY_USER, DELETED_BY_PSP" enum: - DELETED_BY_USER - DELETED_BY_PSP type: string responses: "204": description: No Content "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Delete an Immediate Charge tags: - Immediate Collections x-mint: href: /pt/reference/interfaces/pix-btg/delete-an-immediate-charge get: description: Use this endpoint to retrieve detailed information about a specific immediate collection. operationId: collection-get-immediate parameters: - description: Identifier of the immediate collection in: path name: collection_id required: true schema: description: Identifier of the immediate collection type: string - description: Account ID (UUID format) in: header name: X-Account-Id required: true schema: description: Account ID (UUID format) format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/ImmediateCollectionOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Retrieve Immediate Charge Details tags: - Immediate Collections x-mint: href: /pt/reference/interfaces/pix-btg/retrieve-immediate-charge-details put: description: |- Use this endpoint to update an immediate collection. Only collections in ACTIVE status can be updated. **Mutable Fields (can be updated):** - expirationSeconds: Time in seconds until collection expires - receiverKey: PIX key that will receive the payment - debtorDocument: CPF/CNPJ of the payer (must be provided with debtorName) - debtorName: Name of the payer (must be provided with debtorDocument) - description: Custom description for the collection - additionalInfo: Additional key-value information - tags: Array of custom tags **Immutable Fields (cannot be updated):** - id, accountId, txId, amount, status, pactualId, emv, locationUrl, createdAt, updatedAt **State Restrictions:** - Collections can ONLY be updated when status is ACTIVE - Collections with status COMPLETED, DELETED, or EXPIRED cannot be updated operationId: collection-update-immediate parameters: - description: Identifier of the immediate collection in: path name: collection_id required: true schema: description: Identifier of the immediate collection type: string - description: Account ID (UUID format) in: header name: X-Account-Id required: true schema: description: Account ID (UUID format) format: uuid type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/UpdateImmediateCollectionInput" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/ImmediateCollectionOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "413": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Request Entity Too Large "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Update an Immediate Charge tags: - Immediate Collections x-mint: href: /pt/reference/interfaces/pix-btg/update-an-immediate-charge /v1/dict/claims: get: description: Use this endpoint to list key claims with filters and pagination. Returns empty array [] if no claims match the criteria. operationId: dict-get-all-claims parameters: - description: Maximum number of claims per page (1-100) explode: false in: query name: limit schema: default: 10 description: Maximum number of claims per page (1-100) format: int64 type: integer - description: Page number for pagination explode: false in: query name: page schema: default: 1 description: Page number for pagination format: int64 type: integer - description: "Filter by claim type: OWNERSHIP, PORTABILITY" explode: false in: query name: type schema: description: "Filter by claim type: OWNERSHIP, PORTABILITY" type: string - description: "Filter by status (comma-separated, OR-matched): OPEN, WAITING_RESOLUTION, CONFIRMED, CANCELLED, COMPLETED" explode: false in: query name: status schema: description: "Filter by status (comma-separated, OR-matched): OPEN, WAITING_RESOLUTION, CONFIRMED, CANCELLED, COMPLETED" items: type: string type: array - description: Filter by Pix key value explode: false in: query name: key_value schema: description: Filter by Pix key value type: string - description: "Sort direction: asc or desc" explode: false in: query name: sort_order schema: default: asc description: "Sort direction: asc or desc" type: string - description: Filter by BACEN claim ID (UUID) explode: false in: query name: bacen_claim_id schema: description: Filter by BACEN claim ID (UUID) format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/GetAllClaimsOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: List Key Claims tags: - Claims x-mint: href: /pt/reference/interfaces/pix-btg/list-claims post: description: Use this endpoint to create a new key claim for portability or ownership. operationId: dict-create-claim parameters: - description: Account ID (UUID format) in: header name: X-Account-Id required: true schema: description: Account ID (UUID format) format: uuid type: string - description: "Reason for claim: USER_REQUESTED, ACCOUNT_CLOSURE, DEFAULT_OPERATION, FRAUD, RECONCILIATION" in: header name: X-Reason required: true schema: description: "Reason for claim: USER_REQUESTED, ACCOUNT_CLOSURE, DEFAULT_OPERATION, FRAUD, RECONCILIATION" enum: - USER_REQUESTED - ACCOUNT_CLOSURE - DEFAULT_OPERATION - FRAUD - RECONCILIATION type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateClaimInput" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/CreateClaimOutput" description: Created "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "413": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Request Entity Too Large "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Create a Key Claim tags: - Claims x-mint: href: /pt/reference/interfaces/pix-btg/create-a-claim /v1/dict/claims/{claim_id}: get: description: Use this endpoint to retrieve the details of a specific key claim. operationId: dict-get-claim parameters: - description: Claim ID (UUID format) in: path name: claim_id required: true schema: description: Claim ID (UUID format) format: uuid type: string - description: Account ID (UUID format) in: header name: X-Account-Id required: true schema: description: Account ID (UUID format) format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/GetClaimOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Get a Key Claim tags: - Claims x-mint: href: /pt/reference/interfaces/pix-btg/retrieve-a-claim /v1/dict/claims/{claim_id}/acknowledge: post: description: Use this endpoint to acknowledge receipt of a claim by the donor participant. operationId: dict-acknowledge-claim parameters: - description: Claim ID (UUID) in: path name: claim_id required: true schema: description: Claim ID (UUID) format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/AcknowledgeClaimOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Acknowledge a Key Claim tags: - Claims x-mint: href: /pt/reference/interfaces/pix-btg/acknowledge-a-claim /v1/dict/claims/{claim_id}/cancel: post: description: Use this endpoint to cancel a portability or ownership claim. operationId: dict-cancel-claim parameters: - description: Claim ID (UUID) in: path name: claim_id required: true schema: description: Claim ID (UUID) format: uuid type: string - description: Account ID (UUID format) in: header name: X-Account-Id required: true schema: description: Account ID (UUID format) format: uuid type: string - description: "Reason for cancellation: USER_REQUESTED, ACCOUNT_CLOSURE, DEFAULT_OPERATION, FRAUD, RECONCILIATION, COURT_ORDER (donor only)" in: header name: X-Reason required: true schema: description: "Reason for cancellation: USER_REQUESTED, ACCOUNT_CLOSURE, DEFAULT_OPERATION, FRAUD, RECONCILIATION, COURT_ORDER (donor only)" enum: - USER_REQUESTED - ACCOUNT_CLOSURE - DEFAULT_OPERATION - FRAUD - RECONCILIATION - COURT_ORDER type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/CancelClaimOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Cancel a Key Claim tags: - Claims x-mint: href: /pt/reference/interfaces/pix-btg/cancel-a-claim /v1/dict/claims/{claim_id}/complete: post: description: Use this endpoint to complete a claim by the claimer. As a result, the link between the key and the claiming party is created. operationId: dict-complete-claim parameters: - description: Claim ID (UUID) in: path name: claim_id required: true schema: description: Claim ID (UUID) format: uuid type: string - description: Account ID (UUID format) in: header name: X-Account-Id required: true schema: description: Account ID (UUID format) format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/CompleteClaimOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Complete a Key Claim tags: - Claims x-mint: href: /pt/reference/interfaces/pix-btg/complete-a-claim /v1/dict/claims/{claim_id}/confirm: post: description: Use this endpoint to confirm a claim operation. As a consequence, the link between the key and the donor participant is removed. operationId: dict-confirm-claim parameters: - description: Claim ID (UUID) in: path name: claim_id required: true schema: description: Claim ID (UUID) format: uuid type: string - description: Account ID (UUID format) in: header name: X-Account-Id required: true schema: description: Account ID (UUID format) format: uuid type: string - description: "Reason for confirmation: USER_REQUESTED, ACCOUNT_CLOSURE, DEFAULT_OPERATION, FRAUD, or RECONCILIATION" in: header name: X-Reason required: true schema: description: "Reason for confirmation: USER_REQUESTED, ACCOUNT_CLOSURE, DEFAULT_OPERATION, FRAUD, or RECONCILIATION" enum: - USER_REQUESTED - ACCOUNT_CLOSURE - DEFAULT_OPERATION - FRAUD - RECONCILIATION type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/ConfirmClaimOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Confirm a Key Claim tags: - Claims x-mint: href: /pt/reference/interfaces/pix-btg/confirm-a-claim /v1/dict/entries: get: description: Use this endpoint to list all Pix entries for an account with optional filters. Returns empty array [] if no entries match the criteria. operationId: dict-get-all-entries parameters: - description: Account ID (UUID format) - required in: header name: X-Account-Id required: true schema: description: Account ID (UUID format) - required format: uuid type: string - description: "Page number for pagination (default: 1, minimum: 1)" explode: false in: query name: page schema: default: 1 description: "Page number for pagination (default: 1, minimum: 1)" format: int64 type: integer - description: "Maximum number of items per page (default: 10, range: 1-100)" explode: false in: query name: limit schema: default: 10 description: "Maximum number of items per page (default: 10, range: 1-100)" format: int64 type: integer - description: "Filter by key type: CPF, CNPJ, EMAIL, PHONE, EVP" explode: false in: query name: key_type schema: description: "Filter by key type: CPF, CNPJ, EMAIL, PHONE, EVP" type: string - description: Filter by key value (e.g., email address or phone number) explode: false in: query name: key_value schema: description: Filter by key value (e.g., email address or phone number) type: string - description: Filter by entry ID (UUID format) explode: false in: query name: id schema: description: Filter by entry ID (UUID format) format: uuid type: string - description: "Filter by operational status (comma-separated, OR-matched): ACTIVE, INACTIVE" explode: false in: query name: status schema: description: "Filter by operational status (comma-separated, OR-matched): ACTIVE, INACTIVE" items: type: string type: array - description: "Sort direction: asc or desc (default: asc)" explode: false in: query name: sort_order schema: description: "Sort direction: asc or desc (default: asc)" type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/GetAllEntriesOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: List All Pix Entries tags: - Entries x-mint: href: /pt/reference/interfaces/pix-btg/list-entries post: description: Use this endpoint to create a new Pix entry associated with an account and its data. operationId: dict-create-entry parameters: - description: Account ID (UUID format) in: header name: X-Account-Id required: true schema: description: Account ID (UUID format) format: uuid type: string - description: "Reason for creating the entry. Valid values: USER_REQUESTED, RECONCILIATION" in: header name: X-Reason required: true schema: description: "Reason for creating the entry. Valid values: USER_REQUESTED, RECONCILIATION" enum: - USER_REQUESTED - RECONCILIATION type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateEntryInput" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/EntryOutput" description: Created "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "413": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Request Entity Too Large "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Create a Pix Entry tags: - Entries x-mint: href: /pt/reference/interfaces/pix-btg/create-entry /v1/dict/entries/{entry_id}: delete: description: Use this endpoint to delete (inactivate) an existing Pix entry associated with an account. operationId: dict-delete-entry parameters: - description: Entry ID (UUID format) in: path name: entry_id required: true schema: description: Entry ID (UUID format) format: uuid type: string - description: Account ID (UUID format) in: header name: X-Account-Id required: true schema: description: Account ID (UUID format) format: uuid type: string - description: "Reason for deletion: USER_REQUESTED, ACCOUNT_CLOSURE, BRANCH_TRANSFER, RECONCILIATION, FRAUD, or RFB_VALIDATION" in: header name: X-Reason required: true schema: description: "Reason for deletion: USER_REQUESTED, ACCOUNT_CLOSURE, BRANCH_TRANSFER, RECONCILIATION, FRAUD, or RFB_VALIDATION" enum: - USER_REQUESTED - ACCOUNT_CLOSURE - BRANCH_TRANSFER - RECONCILIATION - FRAUD - RFB_VALIDATION type: string responses: "204": description: No Content "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Delete a Pix Entry tags: - Entries x-mint: href: /pt/reference/interfaces/pix-btg/delete-an-entry get: description: Use this endpoint to retrieve a Pix entry by its unique identifier. operationId: dict-get-entry parameters: - description: Entry ID (UUID format) in: path name: entry_id required: true schema: description: Entry ID (UUID format) type: string - description: Account ID (UUID format) in: header name: X-Account-Id required: true schema: description: Account ID (UUID format) format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/GetEntryOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Get a Pix Entry tags: - Entries x-mint: href: /pt/reference/interfaces/pix-btg/retrieve-an-entry patch: description: Use this endpoint to update an existing Pix entry data associated with an account. operationId: dict-update-entry parameters: - description: Unique identifier of the Pix entry (UUID format) in: path name: entry_id required: true schema: description: Unique identifier of the Pix entry (UUID format) format: uuid type: string - description: Unique identifier of the Midaz Ledger Account (UUID format) in: header name: X-Account-Id required: true schema: description: Unique identifier of the Midaz Ledger Account (UUID format) format: uuid type: string - description: "Specifies the reason for Pix key entry update. Valid values: USER_REQUESTED, BRANCH_TRANSFER, RECONCILIATION" in: header name: X-Reason required: true schema: description: "Specifies the reason for Pix key entry update. Valid values: USER_REQUESTED, BRANCH_TRANSFER, RECONCILIATION" enum: - USER_REQUESTED - BRANCH_TRANSFER - RECONCILIATION type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/UpdateEntryInput" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/EntryOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "413": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Request Entity Too Large "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Update a Pix Entry Data tags: - Entries x-mint: href: /pt/reference/interfaces/pix-btg/update-an-entry /v1/dict/fraud-markers: get: description: |- Use this endpoint to list fraud markers with filters. Returns empty array [] if no markers match the criteria. **Notes:** - This endpoint is a proxy to BTG and does not persist data locally. - Uses cursor-based pagination via modified_after/modified_before filters. - When hasMoreElements is true, use the updatedAt of the last item as modified_after for the next request. operationId: dict-get-all-fraud-markers parameters: - description: Maximum number of fraud markers to return (1-200) explode: false in: query name: limit required: true schema: description: Maximum number of fraud markers to return (1-200) format: int64 type: integer - description: "Filter by modification time (greater than or equal). Format: ISO 8601" explode: false in: query name: modified_after schema: description: "Filter by modification time (greater than or equal). Format: ISO 8601" type: string - description: "Filter by modification time (less than or equal). Format: ISO 8601" explode: false in: query name: modified_before schema: description: "Filter by modification time (less than or equal). Format: ISO 8601" type: string - description: Filter by CPF or CNPJ document explode: false in: query name: tax_id schema: description: Filter by CPF or CNPJ document type: string - description: "Filter by status: REGISTERED or CANCELLED" explode: false in: query name: status schema: description: "Filter by status: REGISTERED or CANCELLED" type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/GetAllFraudMarkersOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: List Fraud Markers tags: - Fraud Markers x-mint: href: /pt/reference/interfaces/pix-btg/list-fraud-markers post: description: |- Use this endpoint to register a fraud marker for a tax ID or Pix key. **Notes:** - Fraud markers are used to flag documents (CPF/CNPJ) or Pix keys associated with fraudulent activity. - The taxIdNumber field is required and represents the person/entity being marked. - The key field is optional and can be used to associate the marker with a specific Pix key. - Fraud markers can also be automatically created when closing an infraction report with AGREED result. operationId: dict-create-fraud-marker requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateFraudMarkerInput" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/FraudMarkerOutput" description: Created "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "413": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Request Entity Too Large "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Create a Fraud Marker tags: - Fraud Markers x-mint: href: /pt/reference/interfaces/pix-btg/create-a-fraud-marker /v1/dict/fraud-markers/{fraud_marker_id}/cancel: post: description: |- Use this endpoint to cancel a previously registered fraud marker. **Notes:** - Cancellation is only allowed for markers in REGISTERED status. - Only the participant who created the fraud marker can cancel it. - For fraud markers created from infraction report closures, the counterparty participant who closed the infraction can cancel the marker. - Cancelled markers cannot be reactivated. operationId: dict-cancel-fraud-marker parameters: - description: Fraud Marker ID (UUID format) in: path name: fraud_marker_id required: true schema: description: Fraud Marker ID (UUID format) format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/FraudMarkerOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Cancel a Fraud Marker tags: - Fraud Markers x-mint: href: /pt/reference/interfaces/pix-btg/cancel-a-fraud-marker /v1/dict/funds-recoveries: get: description: Use this endpoint to list funds recovery requests with optional filters and pagination. operationId: dict-get-all-funds-recoveries parameters: - description: Account ID (UUID) from X-Account-Id header in: header name: X-Account-Id schema: description: Account ID (UUID) from X-Account-Id header format: uuid type: string - description: "The maximum number of items to include in the response (default: 10, range: 1-100)" explode: false in: query name: limit schema: default: 10 description: "The maximum number of items to include in the response (default: 10, range: 1-100)" format: int64 type: integer - description: "The number of the page that you want to retrieve (default: 1, minimum: 1)" explode: false in: query name: page schema: default: 1 description: "The number of the page that you want to retrieve (default: 1, minimum: 1)" format: int64 type: integer - description: "The order used to sort the results: asc or desc" explode: false in: query name: sort_order schema: default: asc description: "The order used to sort the results: asc or desc" type: string - description: "Filter by funds recovery status (comma-separated for OR match): CREATED, TRACKED, AWAITING_ANALYSIS, ANALYSED, REFUNDING, COMPLETED, CANCELLED" explode: false in: query name: status schema: description: "Filter by funds recovery status (comma-separated for OR match): CREATED, TRACKED, AWAITING_ANALYSIS, ANALYSED, REFUNDING, COMPLETED, CANCELLED" items: type: string type: array - description: "Filter by situation type: SCAM, ACCOUNT_TAKEOVER, COERCION, FRAUDULENT_ACCESS, OTHER, UNKNOWN" explode: false in: query name: situation_type schema: description: "Filter by situation type: SCAM, ACCOUNT_TAKEOVER, COERCION, FRAUDULENT_ACCESS, OTHER, UNKNOWN" type: string - description: Filter by root transaction ID (32 characters) explode: false in: query name: root_transaction_id schema: description: Filter by root transaction ID (32 characters) type: string - description: Filter by BACEN/BTG funds recovery external identifier explode: false in: query name: bacen_funds_recovery_id schema: description: Filter by BACEN/BTG funds recovery external identifier type: string - description: Filter by funds recoveries modified after this timestamp (RFC3339 format) explode: false in: query name: modified_after schema: description: Filter by funds recoveries modified after this timestamp (RFC3339 format) type: string - description: Filter by funds recoveries modified before this timestamp (RFC3339 format) explode: false in: query name: modified_before schema: description: Filter by funds recoveries modified before this timestamp (RFC3339 format) type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/GetAllFundsRecoveriesOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: List Funds Recoveries tags: - Funds Recovery x-mint: href: /pt/reference/interfaces/pix-btg/list-funds-recoveries post: description: |- Use this endpoint to create a new funds recovery request for a Pix transaction suspected of fraud. **Notes:** - The rootTransactionId must be a valid 32-character Pix End-to-End ID - situationType indicates the type of fraud situation (SCAM, ACCOUNT_TAKEOVER, COERCION, FRAUDULENT_ACCESS, OTHER, UNKNOWN) - Contact information (email and phone) is required for communication during the recovery process operationId: dict-create-funds-recovery parameters: - description: Account ID (UUID) from X-Account-Id header in: header name: X-Account-Id schema: description: Account ID (UUID) from X-Account-Id header format: uuid type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateFundsRecoveryInput" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/CreateFundsRecoveryOutput" description: Created "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "413": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Request Entity Too Large "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Create a Funds Recovery Request tags: - Funds Recovery x-mint: href: /pt/reference/interfaces/pix-btg/create-a-funds-recovery-request /v1/dict/funds-recoveries/{funds_recovery_id}: get: description: Use this endpoint to retrieve the full details of a single funds recovery request. operationId: dict-get-funds-recovery parameters: - description: Funds Recovery ID (UUID format) in: path name: funds_recovery_id required: true schema: description: Funds Recovery ID (UUID format) format: uuid type: string - description: Account ID (UUID) from X-Account-Id header in: header name: X-Account-Id schema: description: Account ID (UUID) from X-Account-Id header format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/FundsRecoveryOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Retrieve Funds Recovery details tags: - Funds Recovery x-mint: href: /pt/reference/interfaces/pix-btg/retrieve-funds-recovery-details patch: description: |- Use this endpoint to update an existing funds recovery request. Updates are only allowed for requests in CREATED, TRACKED, or AWAITING_ANALYSIS status. **Notes:** - Only the situationType, reportDetails, and contactInformation can be updated - Updates are not allowed for requests in terminal states (COMPLETED, CANCELLED) operationId: dict-update-funds-recovery parameters: - description: Funds Recovery ID (UUID format) in: path name: funds_recovery_id required: true schema: description: Funds Recovery ID (UUID format) format: uuid type: string - description: Account ID (UUID) from X-Account-Id header in: header name: X-Account-Id schema: description: Account ID (UUID) from X-Account-Id header format: uuid type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/UpdateFundsRecoveryInput" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/FundsRecoveryOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "413": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Request Entity Too Large "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Update a Funds Recovery Request tags: - Funds Recovery x-mint: href: /pt/reference/interfaces/pix-btg/update-a-funds-recovery-request /v1/dict/funds-recoveries/{funds_recovery_id}/cancel: post: description: |- Use this endpoint to cancel a funds recovery request. Cancellation is allowed before refund has been initiated (CREATED, TRACKED, AWAITING_ANALYSIS, or ANALYSED status). **Notes:** - Cancelled requests cannot be reopened or modified - Cancellation is not allowed for requests in REFUNDING, COMPLETED, or CANCELLED status operationId: dict-cancel-funds-recovery parameters: - description: Funds Recovery ID (UUID format) in: path name: funds_recovery_id required: true schema: description: Funds Recovery ID (UUID format) format: uuid type: string - description: Account ID (UUID) from X-Account-Id header in: header name: X-Account-Id schema: description: Account ID (UUID) from X-Account-Id header format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/FundsRecoveryOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Cancel a Funds Recovery Request tags: - Funds Recovery x-mint: href: /pt/reference/interfaces/pix-btg/cancel-a-funds-recovery-request /v1/dict/funds-recoveries/{funds_recovery_id}/infraction-reports: get: description: Use this endpoint to list all infraction reports associated with a funds recovery request. operationId: dict-list-funds-recovery-infraction-reports parameters: - description: Funds Recovery ID (UUID format) in: path name: funds_recovery_id required: true schema: description: Funds Recovery ID (UUID format) format: uuid type: string - description: Account ID (UUID) from X-Account-Id header in: header name: X-Account-Id schema: description: Account ID (UUID) from X-Account-Id header format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/ListFundsRecoveryInfractionsOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: List Infraction Reports tags: - Funds Recovery x-mint: href: /pt/reference/interfaces/pix-btg/list-funds-recovery-infraction-reports /v1/dict/funds-recoveries/{funds_recovery_id}/refund: post: description: |- Use this endpoint to request a refund for a funds recovery. This is only allowed when the funds recovery is in ANALYSED status. **Notes:** - Refund request triggers the MED refund flow - The funds recovery status will transition to REFUNDING operationId: dict-request-funds-recovery-refund parameters: - description: Funds Recovery ID (UUID format) in: path name: funds_recovery_id required: true schema: description: Funds Recovery ID (UUID format) format: uuid type: string - description: Account ID (UUID) from X-Account-Id header in: header name: X-Account-Id schema: description: Account ID (UUID) from X-Account-Id header format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/FundsRecoveryOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Request Refund tags: - Funds Recovery x-mint: href: /pt/reference/interfaces/pix-btg/request-funds-recovery-refund /v1/dict/funds-recoveries/{funds_recovery_id}/refunds: get: description: Use this endpoint to list all refunds associated with a funds recovery request. operationId: dict-list-funds-recovery-refunds parameters: - description: Funds Recovery ID (UUID format) in: path name: funds_recovery_id required: true schema: description: Funds Recovery ID (UUID format) format: uuid type: string - description: Account ID (UUID) from X-Account-Id header in: header name: X-Account-Id schema: description: Account ID (UUID) from X-Account-Id header format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/ListFundsRecoveryRefundsOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: List Refunds tags: - Funds Recovery x-mint: href: /pt/reference/interfaces/pix-btg/list-funds-recovery-refunds /v1/dict/funds-recoveries/{funds_recovery_id}/tracking-graph: get: description: |- Use this endpoint to retrieve the tracking graph for a funds recovery request. The tracking graph shows the flow of funds from the root transaction. **Notes:** - The query parameters min_transaction_amount, max_transactions, hop_window and max_hops are deprecated: accepted for compatibility and ignored, because BTG returns the graph built with the parameters used when the funds recovery was created - The graph includes persons, accounts, and transactions related to the fraud operationId: dict-get-funds-recovery-tracking-graph parameters: - description: Funds Recovery ID (UUID format) in: path name: funds_recovery_id required: true schema: description: Funds Recovery ID (UUID format) format: uuid type: string - description: Account ID (UUID) from X-Account-Id header in: header name: X-Account-Id schema: description: Account ID (UUID) from X-Account-Id header format: uuid type: string - deprecated: true description: "Minimum transaction amount to include in the graph. Accepted for compatibility and ignored: BTG returns the graph built with the parameters used when the funds recovery was created." explode: false in: query name: min_transaction_amount schema: deprecated: true description: "Minimum transaction amount to include in the graph. Accepted for compatibility and ignored: BTG returns the graph built with the parameters used when the funds recovery was created." type: string - deprecated: true description: "Maximum number of transactions to include. Accepted for compatibility and ignored: BTG returns the graph built with the parameters used when the funds recovery was created." explode: false in: query name: max_transactions schema: deprecated: true description: "Maximum number of transactions to include. Accepted for compatibility and ignored: BTG returns the graph built with the parameters used when the funds recovery was created." format: int64 type: integer - deprecated: true description: "Time window for hop analysis (ISO 8601 duration). Accepted for compatibility and ignored: BTG returns the graph built with the parameters used when the funds recovery was created." explode: false in: query name: hop_window schema: deprecated: true description: "Time window for hop analysis (ISO 8601 duration). Accepted for compatibility and ignored: BTG returns the graph built with the parameters used when the funds recovery was created." type: string - deprecated: true description: "Maximum number of hops to follow. Accepted for compatibility and ignored: BTG returns the graph built with the parameters used when the funds recovery was created." explode: false in: query name: max_hops schema: deprecated: true description: "Maximum number of hops to follow. Accepted for compatibility and ignored: BTG returns the graph built with the parameters used when the funds recovery was created." format: int64 type: integer responses: "200": content: application/json: schema: $ref: "#/components/schemas/TrackingGraphOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Retrieve Tracking Graph tags: - Funds Recovery x-mint: href: /pt/reference/interfaces/pix-btg/retrieve-funds-recovery-tracking-graph /v1/dict/infraction-reports: get: description: Use this endpoint to list infraction reports with optional filters and pagination. operationId: dict-get-all-infraction-reports parameters: - description: "The number of the page that you want to retrieve (minimum: 1)" explode: false in: query name: page schema: default: 1 description: "The number of the page that you want to retrieve (minimum: 1)" format: int64 type: integer - description: "The maximum number of items to include in the response (range: 1-100)" explode: false in: query name: limit schema: default: 10 description: "The maximum number of items to include in the response (range: 1-100)" format: int64 type: integer - description: "The order used to sort the results: asc or desc" explode: false in: query name: sort_order schema: default: asc description: "The order used to sort the results: asc or desc" type: string - description: "Filter by infraction status (comma-separated for OR match): OPEN, ACKNOWLEDGED, CLOSED, CANCELLED" explode: false in: query name: status schema: description: "Filter by infraction status (comma-separated for OR match): OPEN, ACKNOWLEDGED, CLOSED, CANCELLED" items: type: string type: array - description: Filter by the SPI transaction identifier associated with the report explode: false in: query name: transaction_id schema: description: Filter by the SPI transaction identifier associated with the report type: string - description: Filter by the ISPB of the reporting participant explode: false in: query name: reporter_participant schema: description: Filter by the ISPB of the reporting participant type: string - description: Filter by the ISPB of the counterparty institution explode: false in: query name: counterparty_participant schema: description: Filter by the ISPB of the counterparty institution type: string - description: Filter by the BACEN analysis result (AGREED or DISAGREED) explode: false in: query name: analysis_result schema: description: Filter by the BACEN analysis result (AGREED or DISAGREED) type: string - description: "Filter by reports modified after this timestamp (RFC3339 format: 2024-01-15T10:30:00Z)" explode: false in: query name: modified_after schema: description: "Filter by reports modified after this timestamp (RFC3339 format: 2024-01-15T10:30:00Z)" type: string - description: "Filter by reports modified before this timestamp (RFC3339 format: 2024-01-15T10:30:00Z)" explode: false in: query name: modified_before schema: description: "Filter by reports modified before this timestamp (RFC3339 format: 2024-01-15T10:30:00Z)" type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/GetAllInfractionReportsOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: List Infraction Reports tags: - Infraction Reports x-mint: href: /pt/reference/interfaces/pix-btg/list-infraction-reports post: deprecated: true description: |- **DEPRECATED:** This endpoint is deprecated and will be removed in a future release due to MED 2.0 changes. The MED 2.0 specification introduces a new flow where infraction reports are replaced by a simplified dispute resolution mechanism handled through the Special Return flow. Use this endpoint to report infractions associated to Pix transfers. This endpoint must be used when there is a fraud related to a transaction in scenarios where the client is the payer PSP, meaning the transaction was initiated and sent from an account within your arrangement. **Notes:** - Transactions can only be reported within 90 days from the transaction date operationId: dict-create-infraction-report requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateInfractionReportInput" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/CreateInfractionReportOutput" description: Created "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "413": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Request Entity Too Large "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Create an Infraction Report tags: - Infraction Reports x-mint: href: /pt/reference/interfaces/pix-btg/create-an-infraction-report /v1/dict/infraction-reports/{infraction_id}: get: description: Use this endpoint to retrieve the full details of a single infraction report. operationId: dict-get-infraction-report parameters: - description: Unique identifier of the infraction report (UUID format) in: path name: infraction_id required: true schema: description: Unique identifier of the infraction report (UUID format) format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/GetInfractionReportOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Retrieve Infraction Report details tags: - Infraction Reports x-mint: href: /pt/reference/interfaces/pix-btg/retrieve-an-infraction-report /v1/dict/infraction-reports/{infraction_id}/acknowledge: post: description: Use this endpoint to acknowledge receipt of an infraction report notification. This endpoint is used by the counterparty participant to acknowledge that they have received and are aware of the infraction report filed against a transaction. The report must be in OPEN status to be acknowledged. This operation is idempotent. operationId: dict-acknowledge-infraction-report parameters: - description: Unique identifier of the infraction report to acknowledge (UUID format) in: path name: infraction_id required: true schema: description: Unique identifier of the infraction report to acknowledge (UUID format) format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/GetInfractionReportOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Acknowledge an Infraction Report tags: - Infraction Reports x-mint: href: /pt/reference/interfaces/pix-btg/acknowledge-an-infraction-report /v1/dict/infraction-reports/{infraction_id}/cancel: post: description: |- Use this endpoint to cancel an infraction report that is no longer valid. This endpoint is used to cancel infractions reported by your own PSP. **Notes:** - Cancellation is only allowed for reports in OPEN or ACKNOWLEDGED status - Cancelled reports cannot be reopened or modified - Cancellation reason should be provided for audit purposes operationId: dict-cancel-infraction-report parameters: - description: Infraction Report ID (UUID format) in: path name: infraction_id required: true schema: description: Infraction Report ID (UUID format) format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/CancelInfractionReportOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Cancel an Infraction Report tags: - Infraction Reports x-mint: href: /pt/reference/interfaces/pix-btg/cancel-an-infraction-report /v1/dict/infraction-reports/{infraction_id}/close: post: deprecated: true description: |- **DEPRECATED:** This endpoint is deprecated and will be removed in a future release due to MED 2.0 changes. MED 2.0 manages infraction report updates through the Funds Recovery lifecycle. Use this endpoint to submit the closure analysis for an infraction report received. This endpoint must be used to respond to infractions reported to your PSP, meaning when the account was the receiver of the transaction reported as fraud, within 7 days with the analysis result. **Notes:** - Closing a report sets its status to CLOSED and records the analysis result - Once closed, the report cannot be modified - For `REFUND_REQUEST` infractions, the report must be closed by the payee's PSP - For `REFUND_CANCELLED` infractions, the report must be closed by the payer's PSP operationId: dict-close-infraction-report parameters: - description: Unique identifier of the infraction report (UUID format) in: path name: infraction_id required: true schema: description: Unique identifier of the infraction report (UUID format) format: uuid type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CloseInfractionReportInput" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/CloseInfractionReportOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "413": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Request Entity Too Large "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Close an Infraction Report tags: - Infraction Reports x-mint: href: /pt/reference/interfaces/pix-btg/close-an-infraction-report /v1/dict/keys/check: post: description: Use this endpoint to verify if the provided Pix keys exist in the DICT system. operationId: dict-check-keys requestBody: content: application/json: schema: $ref: "#/components/schemas/CheckKeysInput" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/CheckKeysOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "413": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Request Entity Too Large "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Check Pix Keys Existence tags: - Keys x-mint: href: /pt/reference/interfaces/pix-btg/check-keys-existence /v1/dict/keys/{key}: get: description: Use this endpoint to retrieve Pix key details for payment purposes. operationId: dict-get-key parameters: - description: Pix key value (CPF, CNPJ, Email, or Phone) in: path name: key required: true schema: description: Pix key value (CPF, CNPJ, Email, or Phone) type: string - description: Account ID (UUID format) in: header name: X-Account-Id required: true schema: description: Account ID (UUID format) format: uuid type: string - description: End-to-end transaction identifier in: header name: X-End-To-End-Id required: true schema: description: End-to-end transaction identifier type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/GetKeyOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Retrieve a Pix Key tags: - Keys x-mint: href: /pt/reference/interfaces/pix-btg/retrieve-a-key /v1/dict/reconciliation: get: description: |- Use this endpoint to list all reconciliation jobs with optional filters. Returns empty array [] if no jobs match the criteria. operationId: dict-get-all-reconciliation-jobs parameters: - description: "Page number for pagination (default: 1, minimum: 1)" explode: false in: query name: page schema: default: 1 description: "Page number for pagination (default: 1, minimum: 1)" format: int64 type: integer - description: "Maximum number of items per page (default: 10, range: 1-100)" explode: false in: query name: limit schema: default: 10 description: "Maximum number of items per page (default: 10, range: 1-100)" format: int64 type: integer - description: "Filter by key type: CPF, CNPJ, EMAIL, PHONE, EVP" explode: false in: query name: key_type schema: description: "Filter by key type: CPF, CNPJ, EMAIL, PHONE, EVP" type: string - description: "Filter by job type: EVENT_SYNC, FULL_RECONCILIATION" explode: false in: query name: job_type schema: description: "Filter by job type: EVENT_SYNC, FULL_RECONCILIATION" type: string - description: "Filter by status (comma-separated, OR-matched): WAITING_FILE, PENDING, PROCESSING, COMPLETED, FAILED, CANCELLED" explode: false in: query name: status schema: description: "Filter by status (comma-separated, OR-matched): WAITING_FILE, PENDING, PROCESSING, COMPLETED, FAILED, CANCELLED" items: type: string type: array - description: "Sort direction: asc or desc (default: desc - newest first)" explode: false in: query name: sort_order schema: description: "Sort direction: asc or desc (default: desc - newest first)" type: string - description: Filter from date (YYYY-MM-DD) explode: false in: query name: start_date schema: description: Filter from date (YYYY-MM-DD) type: string - description: Filter to date (YYYY-MM-DD) explode: false in: query name: end_date schema: description: Filter to date (YYYY-MM-DD) type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/GetAllReconciliationJobsOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: List All Reconciliation Jobs tags: - Reconciliation x-mint: href: /pt/reference/interfaces/pix-btg/list-all-reconciliation-jobs /v1/dict/reconciliation/full: post: description: |- Triggers full reconciliation for all key types that are currently out of sync. This endpoint detects which key types have OUT_OF_SYNC status and requests CID files from BTG for each of them. The actual reconciliation processing happens asynchronously via webhooks when the files become available. **Response codes:** - **202 Accepted**: One or more reconciliation jobs were created - **200 OK**: All key types are already synchronized (no jobs created) - **409 Conflict**: Requested outside the entry write block window (PIX-3011) operationId: dict-start-full-reconciliation responses: "200": content: application/json: schema: $ref: "#/components/schemas/FullReconciliationOutput" description: OK "202": content: application/json: schema: $ref: "#/components/schemas/FullReconciliationOutput" description: One or more reconciliation jobs were created "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Start Full Reconciliation tags: - Reconciliation x-mint: href: /pt/reference/interfaces/pix-btg/start-full-reconciliation /v1/dict/refund-requests: get: description: Use this endpoint to list refund requests with filters and pagination. Returns empty array [] if no requests match the criteria. operationId: dict-get-all-refunds parameters: - description: "Maximum number of items per page (default: 10, range: 1-100)" explode: false in: query name: limit schema: default: 10 description: "Maximum number of items per page (default: 10, range: 1-100)" format: int64 type: integer - description: "Page number for pagination (default: 1, minimum: 1)" explode: false in: query name: page schema: default: 1 description: "Page number for pagination (default: 1, minimum: 1)" format: int64 type: integer - description: "Sort direction for results: asc or desc" explode: false in: query name: sort_order schema: default: asc description: "Sort direction for results: asc or desc" type: string - description: Filter by original Pix transaction ID (32 characters) explode: false in: query name: transaction_id schema: description: Filter by original Pix transaction ID (32 characters) type: string - description: "Filter by refund status (comma-separated for OR match): OPEN, CLOSED, CANCELLED" explode: false in: query name: status schema: description: "Filter by refund status (comma-separated for OR match): OPEN, CLOSED, CANCELLED" items: type: string type: array - description: Filter by requesting participant ISPB (8 uppercase alphanumeric characters) explode: false in: query name: requesting_participant schema: description: Filter by requesting participant ISPB (8 uppercase alphanumeric characters) type: string - description: Filter by contested participant ISPB (8 uppercase alphanumeric characters) explode: false in: query name: contested_participant schema: description: Filter by contested participant ISPB (8 uppercase alphanumeric characters) type: string - description: Filter by related infraction report ID (UUID) explode: false in: query name: infraction_id schema: description: Filter by related infraction report ID (UUID) format: uuid type: string - description: "Filter by refund analysis result: TOTALLY_ACCEPTED, PARTIALLY_ACCEPTED, REJECTED" explode: false in: query name: analysis_result schema: description: "Filter by refund analysis result: TOTALLY_ACCEPTED, PARTIALLY_ACCEPTED, REJECTED" type: string - description: Filter by refund transaction ID (32 characters) explode: false in: query name: refund_transaction_id schema: description: Filter by refund transaction ID (32 characters) type: string - description: "Filter by refunds modified after this timestamp (RFC3339 format: 2024-01-15T10:30:00Z)" explode: false in: query name: modified_after schema: description: "Filter by refunds modified after this timestamp (RFC3339 format: 2024-01-15T10:30:00Z)" type: string - description: "Filter by refunds modified before this timestamp (RFC3339 format: 2024-01-15T10:30:00Z)" explode: false in: query name: modified_before schema: description: "Filter by refunds modified before this timestamp (RFC3339 format: 2024-01-15T10:30:00Z)" type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/GetAllRefundsOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: List Refund Requests tags: - Refund Requests x-mint: href: /pt/reference/interfaces/pix-btg/list-refund-requests post: description: |- Use this endpoint to open a refund request for a Pix transaction. **Notes:** - Refund requests must be associated with a valid Pix transaction. - Requests can optionally be linked to an infraction report. - The contested participant must respond within the specified timeframe. operationId: dict-create-refund requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateRefundInput" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/RefundOutput" description: Created "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "413": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Request Entity Too Large "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Create a Refund Request tags: - Refund Requests x-mint: href: /pt/reference/interfaces/pix-btg/create-a-refund-request /v1/dict/refund-requests/{refund_id}: get: description: Use this endpoint to retrieve the details of a specific refund request. operationId: dict-get-refund parameters: - description: Refund Request ID (UUID format) in: path name: refund_id required: true schema: description: Refund Request ID (UUID format) format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/RefundOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Retrieve a Refund Request tags: - Refund Requests x-mint: href: /pt/reference/interfaces/pix-btg/retrieve-a-refund-request /v1/dict/refund-requests/{refund_id}/cancel: post: description: |- Use this endpoint to cancel a refund request before it is processed. **Notes:** - Cancellation is only allowed for requests in OPEN status. - Cancelled requests cannot be reopened or modified. - This operation notifies BACEN and the contested participant. operationId: dict-cancel-refund parameters: - description: Refund Request ID (UUID format) in: path name: refund_id required: true schema: description: Refund Request ID (UUID format) format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/RefundOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Cancel a Refund Request tags: - Refund Requests x-mint: href: /pt/reference/interfaces/pix-btg/cancel-a-refund-request /v1/dict/refund-requests/{refund_id}/close: post: description: |- Use this endpoint to provide the closure decision and outcome for a refund request. **Notes:** - This operation is typically triggered by BACEN's analysis completion. - Closing a request sets its status to CLOSED and records the analysis result. - For accepted refunds, a refund transaction ID is recorded. - Once closed, the request cannot be modified. operationId: dict-close-refund parameters: - description: Refund Request ID (UUID format) in: path name: refund_id required: true schema: description: Refund Request ID (UUID format) format: uuid type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CloseRefundInput" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/RefundOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "413": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Request Entity Too Large "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Close a Refund Request tags: - Refund Requests x-mint: href: /pt/reference/interfaces/pix-btg/close-a-refund-request /v1/dict/statistics/keys/{key}: get: description: |- Use this endpoint to fetch usage and risk statistics for a specific Pix key. **Notes:** - Returns both key-level statistics and owner-level statistics in a single response. - Key statistics track data specific to the Pix key as an entity independent of its current owner. - Owner statistics provide the same data as the person statistics endpoint for the key's current owner. - This endpoint queries the provider directly and does not store data locally. - Use this information for comprehensive risk assessment when processing payments to a Pix key. operationId: dict-get-key-statistics parameters: - description: Pix key value (CPF, CNPJ, email, phone, or EVP). Maximum 77 characters. in: path name: key required: true schema: description: Pix key value (CPF, CNPJ, email, phone, or EVP). Maximum 77 characters. maxLength: 77 type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/KeyStatisticsOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Get Key Statistics tags: - Statistics x-mint: href: /pt/reference/interfaces/pix-btg/retrieve-key-statistics /v1/dict/statistics/persons/{tax_id}: get: description: |- Use this endpoint to fetch aggregated Pix statistics for a person identified by their tax ID (CPF or CNPJ). **Notes:** - Statistics include transaction settlement data, fraud markers, infraction reports, and entry information. - Data is aggregated over different time periods: d90 (last 90 days), m12 (last 12 months), m60 (last 60 months). - This endpoint queries the provider directly and does not store data locally. - Use this information for risk assessment before processing Pix transactions. operationId: dict-get-person-statistics parameters: - description: "Tax identifier (CPF: 11 digits or alphanumeric CNPJ)" in: path name: tax_id required: true schema: description: "Tax identifier (CPF: 11 digits or alphanumeric CNPJ)" type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/PersonStatisticsOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Get Person Statistics tags: - Statistics x-mint: href: /pt/reference/interfaces/pix-btg/retrieve-person-statistics /v1/dict/vsync: get: description: |- Use this endpoint to list all VSync states for PIX key types with optional filters. Returns empty array [] if no VSync states match the criteria. Note: This table has at most 5 records (one per PIX key type: CPF, CNPJ, EMAIL, PHONE, EVP). operationId: dict-get-all-vsync-states parameters: - description: "Page number for pagination (default: 1, minimum: 1)" explode: false in: query name: page schema: default: 1 description: "Page number for pagination (default: 1, minimum: 1)" format: int64 type: integer - description: "Maximum number of items per page (default: 5, range: 1-100)" explode: false in: query name: limit schema: default: 5 description: "Maximum number of items per page (default: 5, range: 1-100)" format: int64 type: integer - description: "Filter by key type: CPF, CNPJ, EMAIL, PHONE, EVP" explode: false in: query name: key_type schema: description: "Filter by key type: CPF, CNPJ, EMAIL, PHONE, EVP" type: string - description: "Filter by sync status (comma-separated, OR-matched): SYNCED, OUT_OF_SYNC, RECONCILING, ERROR" explode: false in: query name: status schema: description: "Filter by sync status (comma-separated, OR-matched): SYNCED, OUT_OF_SYNC, RECONCILING, ERROR" items: type: string type: array - description: "Sort direction: asc or desc (default: asc)" explode: false in: query name: sort_order schema: description: "Sort direction: asc or desc (default: asc)" type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/GetAllVSyncStatesOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: List All VSync States tags: - Reconciliation x-mint: href: /pt/reference/interfaces/pix-btg/list-all-vsync-states /v1/qrcodes/decode: post: description: "Use this endpoint to decode a Pix BR Code payload and extract the payment data it contains. This service supports all Pix QR Code types: static, immediate collections, and due date collections. When the code carries a Pix Automático recurrence location, the response includes a `recurrence` block. When an immediate collection carries Pix Saque or Pix Troco data, the response includes a `withdrawal` block. The response type varies with the QR code type (STATIC, IMMEDIATE, DUE_DATE, or RECURRENCE)." operationId: decode-qr-code parameters: - description: Unique identifier of the Midaz Ledger Account (UUID format) in: header name: X-Account-Id required: true schema: description: Unique identifier of the Midaz Ledger Account (UUID format) format: uuid type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/DecodeInput" required: true responses: "200": content: application/json: schema: oneOf: - $ref: "#/components/schemas/StaticDecodeOutput" - $ref: "#/components/schemas/ImmediateDecodeOutput" - $ref: "#/components/schemas/DueDateDecodeOutput" - $ref: "#/components/schemas/RecurrenceDecodeOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "413": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Request Entity Too Large "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Decode a Pix QR Code tags: - Decode x-mint: href: /pt/reference/interfaces/pix-btg/decode-a-pix-qr-code /v1/recurrences/payer/authorization-requests: get: description: List authorization requests belonging to the authenticated payer with optional filters and page/limit pagination. operationId: recurring-list-authorization-requests parameters: - description: Account ID (UUID format) in: header name: X-Account-Id required: true schema: description: Account ID (UUID format) format: uuid type: string - description: Page number (default 1, minimum 1) explode: false in: query name: page schema: default: 1 description: Page number (default 1, minimum 1) format: int64 type: integer - description: Page size (default 10, range 1-100) explode: false in: query name: limit schema: default: 10 description: Page size (default 10, range 1-100) format: int64 type: integer - description: "Filter by status (comma-separated, OR-matched): PENDING, INITIATED, APPROVING, CONFIRMED, REJECTED, PAYMENT_FAILED, REPLY_FAILED, CANCELLED, EXPIRED" explode: false in: query name: status schema: description: "Filter by status (comma-separated, OR-matched): PENDING, INITIATED, APPROVING, CONFIRMED, REJECTED, PAYMENT_FAILED, REPLY_FAILED, CANCELLED, EXPIRED" items: type: string type: array - description: ISO 8601 UTC lower bound on createdAt explode: false in: query name: start_date schema: description: ISO 8601 UTC lower bound on createdAt examples: - "2026-06-09T00:00:00Z" type: string - description: ISO 8601 UTC upper bound on createdAt explode: false in: query name: end_date schema: description: ISO 8601 UTC upper bound on createdAt examples: - "2026-06-09T00:00:00Z" type: string - description: "Sort order: asc or desc (default desc)" explode: false in: query name: sort_order schema: default: desc description: "Sort order: asc or desc (default desc)" type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/GetAllAuthorizationRequestsOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: List Pix Automático Authorization Requests tags: - Pix Automático x-mint: href: /pt/reference/interfaces/pix-btg/list-pix-automatico-authorization-requests /v1/recurrences/payer/authorization-requests/{id}: get: description: Retrieve a single authorization request by id. Scoped to the authenticated payer. operationId: recurring-get-authorization-request parameters: - description: Authorization Request ID (UUID format) in: path name: id required: true schema: description: Authorization Request ID (UUID format) format: uuid type: string - description: Account ID (UUID format) in: header name: X-Account-Id required: true schema: description: Account ID (UUID format) format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/AuthorizationRequestOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Get a Pix Automático Authorization Request tags: - Pix Automático x-mint: href: /pt/reference/interfaces/pix-btg/get-a-pix-automatico-authorization-request /v1/recurrences/payer/authorization-requests/{id}/decision: post: description: Accept or reject a pending authorization request. Uses the DICT "external first, persist after" pattern. `X-Idempotency` is optional but recommended; replays within the window are de-duplicated. operationId: recurring-decide-authorization-request parameters: - description: Authorization Request ID (UUID format) in: path name: id required: true schema: description: Authorization Request ID (UUID format) format: uuid type: string - description: Account ID (UUID format) in: header name: X-Account-Id required: true schema: description: Account ID (UUID format) format: uuid type: string - description: Idempotency key (optional; replays within the window are de-duplicated). in: header name: X-Idempotency schema: description: Idempotency key (optional; replays within the window are de-duplicated). type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/DecideAuthorizationRequestInput" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/DecideAuthorizationRequestOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "413": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Request Entity Too Large "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Decide on a Pix Automático Authorization Request tags: - Pix Automático x-mint: href: /pt/reference/interfaces/pix-btg/decide-on-a-pix-automatico-authorization-request /v1/recurrences/payer/authorizations: get: description: List active authorizations belonging to the authenticated payer with optional filters and page/limit pagination. Includes computed `nextChargeAt` / `nextChargeAmount`. operationId: recurring-list-authorizations parameters: - description: "Account ID (UUID format). Optional: absent spans all accounts (cross-account search)." in: header name: X-Account-Id schema: description: "Account ID (UUID format). Optional: absent spans all accounts (cross-account search)." format: uuid type: string - description: Page number (default 1, minimum 1) explode: false in: query name: page schema: default: 1 description: Page number (default 1, minimum 1) format: int64 type: integer - description: Page size (default 10, range 1-100) explode: false in: query name: limit schema: default: 10 description: Page size (default 10, range 1-100) format: int64 type: integer - description: "Filter by status (comma-separated, OR-matched): AUTHORIZED, CANCELLED, EXPIRED" explode: false in: query name: status schema: description: "Filter by status (comma-separated, OR-matched): AUTHORIZED, CANCELLED, EXPIRED" items: type: string type: array - description: Filter by receiver document (CPF or CNPJ, unmasked) explode: false in: query name: receiver_document schema: description: Filter by receiver document (CPF or CNPJ, unmasked) type: string - description: "Filter by cancellation reason kind: PAYER, FRAUD, EXPIRED, RECEIVER" explode: false in: query name: cancellation_reason_kind schema: description: "Filter by cancellation reason kind: PAYER, FRAUD, EXPIRED, RECEIVER" type: string - description: ISO 8601 UTC lower bound on createdAt explode: false in: query name: start_date schema: description: ISO 8601 UTC lower bound on createdAt examples: - "2026-06-09T00:00:00Z" type: string - description: ISO 8601 UTC upper bound on createdAt explode: false in: query name: end_date schema: description: ISO 8601 UTC upper bound on createdAt examples: - "2026-06-09T00:00:00Z" type: string - description: "Sort order: asc or desc (default desc)" explode: false in: query name: sort_order schema: default: desc description: "Sort order: asc or desc (default desc)" type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/GetAllAuthorizationsOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: List Pix Automático Authorizations tags: - Pix Automático x-mint: href: /pt/reference/interfaces/pix-btg/list-pix-automatico-authorizations /v1/recurrences/payer/authorizations/{authorizationId}/charges: get: description: List the charges belonging to one authorization, scoped to the authenticated payer. Supports page/limit pagination plus status and createdAt date-range filters. operationId: recurring-list-charges-by-authorization parameters: - description: Authorization ID (UUID format) in: path name: authorizationId required: true schema: description: Authorization ID (UUID format) format: uuid type: string - description: Account ID (UUID format) in: header name: X-Account-Id required: true schema: description: Account ID (UUID format) format: uuid type: string - description: Page number (default 1, minimum 1) explode: false in: query name: page schema: default: 1 description: Page number (default 1, minimum 1) format: int64 type: integer - description: Page size (default 10, range 1-100) explode: false in: query name: limit schema: default: 10 description: Page size (default 10, range 1-100) format: int64 type: integer - description: "Filter by status (comma-separated, OR-matched): RECEIVED, SCHEDULED, EXECUTED, FAILED, CANCELLED" explode: false in: query name: status schema: description: "Filter by status (comma-separated, OR-matched): RECEIVED, SCHEDULED, EXECUTED, FAILED, CANCELLED" items: type: string type: array - description: ISO 8601 UTC lower bound on createdAt explode: false in: query name: start_date schema: description: ISO 8601 UTC lower bound on createdAt examples: - "2026-06-09T00:00:00Z" type: string - description: ISO 8601 UTC upper bound on createdAt explode: false in: query name: end_date schema: description: ISO 8601 UTC upper bound on createdAt examples: - "2026-06-09T00:00:00Z" type: string - description: "Sort order: asc or desc (default desc)" explode: false in: query name: sort_order schema: default: desc description: "Sort order: asc or desc (default desc)" type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/ListChargesByAuthorizationOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: List Pix Automático Charges by Authorization tags: - Pix Automático x-mint: href: /pt/reference/interfaces/pix-btg/list-pix-automatico-charges-by-authorization /v1/recurrences/payer/authorizations/{id}: get: description: Retrieve a single authorization by id. Scoped to the authenticated payer. operationId: recurring-get-authorization parameters: - description: Authorization ID (UUID format) in: path name: id required: true schema: description: Authorization ID (UUID format) format: uuid type: string - description: Account ID (UUID format) in: header name: X-Account-Id required: true schema: description: Account ID (UUID format) format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/AuthorizationOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Get a Pix Automático Authorization tags: - Pix Automático x-mint: href: /pt/reference/interfaces/pix-btg/get-a-pix-automatico-authorization /v1/recurrences/payer/authorizations/{id}/cancel: post: description: Cancel an active authorization. `reasonKind=PAYER` cancels the caller's own mandate; `reasonKind=FRAUD` records the caller as the operator and requires `reasonText`. `X-Idempotency` is optional but recommended; replays within the window are de-duplicated. operationId: recurring-cancel-authorization parameters: - description: Authorization ID (UUID format) in: path name: id required: true schema: description: Authorization ID (UUID format) format: uuid type: string - description: Account ID (UUID format) in: header name: X-Account-Id required: true schema: description: Account ID (UUID format) format: uuid type: string - description: Idempotency key (optional; replays within the window are de-duplicated). in: header name: X-Idempotency schema: description: Idempotency key (optional; replays within the window are de-duplicated). type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CancelAuthorizationInput" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/CancelAuthorizationOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "413": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Request Entity Too Large "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Cancel a Pix Automático Authorization tags: - Pix Automático x-mint: href: /pt/reference/interfaces/pix-btg/cancel-a-pix-automatico-authorization /v1/recurrences/payer/charges/{id}: get: description: Retrieve a single charge by id. Scoped to the authenticated payer. The response carries the sanitized attempts array; the internal debit result code is never exposed. operationId: recurring-get-charge parameters: - description: Charge ID (UUID format) in: path name: id required: true schema: description: Charge ID (UUID format) format: uuid type: string - description: Account ID (UUID format) in: header name: X-Account-Id required: true schema: description: Account ID (UUID format) format: uuid type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/ChargeOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Get a Pix Automático Charge tags: - Pix Automático x-mint: href: /pt/reference/interfaces/pix-btg/get-a-pix-automatico-charge /v1/recurrences/payer/qr/confirm: post: description: Approve or reject a recurrence scanned from a QR Code (journeys J2 and J4 step 2). `X-Idempotency` is optional but recommended; replays within the window are de-duplicated. operationId: recurring-confirm-recurrence-from-qr parameters: - description: Account ID (UUID format) in: header name: X-Account-Id required: true schema: description: Account ID (UUID format) format: uuid type: string - description: Idempotency key (optional; replays within the window are de-duplicated). in: header name: X-Idempotency schema: description: Idempotency key (optional; replays within the window are de-duplicated). type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/ConfirmRecurrenceFromQRInput" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/ConfirmRecurrenceFromQROutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "413": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Request Entity Too Large "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Confirm a scanned Pix Automático recurrence tags: - Pix Automático x-mint: href: /pt/reference/interfaces/pix-btg/confirm-a-scanned-pix-automatico-recurrence /v1/recurrences/payer/qr/pay-and-confirm: post: description: Process the pre-created immediate-charge cashout (`initiationId`) and confirm the scanned recurrence (`idRec`) as one inseparable act. Returns 200 when the cashout settled immediately (authorization request is APPROVING); 202 when it is still processing. The payer account is the authenticated `X-Account-Id`. `X-Idempotency` is optional but recommended; replays within the window are de-duplicated. operationId: recurring-pay-and-confirm-from-qr parameters: - description: Account ID (UUID format) in: header name: X-Account-Id required: true schema: description: Account ID (UUID format) format: uuid type: string - description: Idempotency key (optional; replays within the window are de-duplicated). in: header name: X-Idempotency schema: description: Idempotency key (optional; replays within the window are de-duplicated). type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/PayAndConfirmFromQRInput" required: true responses: "200": content: application/json: schema: $ref: "#/components/schemas/PayAndConfirmFromQROutput" description: OK "202": content: application/json: schema: $ref: "#/components/schemas/PayAndConfirmFromQROutput" description: The immediate-charge cashout is still processing (authorization request not yet APPROVING) "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "413": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Request Entity Too Large "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Pay and confirm a scanned Pix Automático recurrence tags: - Pix Automático x-mint: href: /pt/reference/interfaces/pix-btg/pay-and-confirm-a-scanned-pix-automatico-recurrence /v1/refunds: get: description: Use this endpoint to list refunds with optional filters and pagination. operationId: payment-list-refunds parameters: - description: Account ID (UUID format) in: header name: X-Account-Id required: true schema: description: Account ID (UUID format) type: string - description: "Page number for pagination (default: 1)" explode: false in: query name: page schema: description: "Page number for pagination (default: 1)" type: string - description: "Maximum number of items per page (default: 10, range: 1-100)" explode: false in: query name: limit schema: description: "Maximum number of items per page (default: 10, range: 1-100)" type: string - description: "Sort direction for results: asc or desc" explode: false in: query name: sort_order schema: description: "Sort direction for results: asc or desc" type: string - description: Filter by the original Pix transfer end-to-end identifier explode: false in: query name: end_to_end schema: description: Filter by the original Pix transfer end-to-end identifier type: string - description: "Filter by refund status; comma-separated for multiple (OR-matched), e.g. PENDING,COMPLETED. Allowed: CREATED, PENDING, PROCESSING, COMPLETED, REJECTED, FAILED, CANCELLED" explode: false in: query name: status schema: description: "Filter by refund status; comma-separated for multiple (OR-matched), e.g. PENDING,COMPLETED. Allowed: CREATED, PENDING, PROCESSING, COMPLETED, REJECTED, FAILED, CANCELLED" type: string - description: Filter by refund direction (CASHOUT or CASHIN) explode: false in: query name: type schema: description: Filter by refund direction (CASHOUT or CASHIN) type: string - description: Filter by refunds modified after this timestamp (RFC3339) explode: false in: query name: modified_after schema: description: Filter by refunds modified after this timestamp (RFC3339) type: string - description: Filter by refunds modified before this timestamp (RFC3339) explode: false in: query name: modified_before schema: description: Filter by refunds modified before this timestamp (RFC3339) type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/RefundsListOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: List Refunds tags: - Refunds x-mint: href: /pt/reference/interfaces/pix-btg/list-refunds /v1/refunds/{refund_id}: get: description: Use this endpoint to retrieve a refund by its unique identifier. operationId: payment-get-refund parameters: - description: Refund ID (UUID format) in: path name: refund_id required: true schema: description: Refund ID (UUID format) type: string - description: Unique identifier of the Midaz Ledger Account (UUID format) in: header name: X-Account-Id required: true schema: description: Unique identifier of the Midaz Ledger Account (UUID format) type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/RefundCashoutOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Get a Refund tags: - Refunds x-mint: href: /pt/reference/interfaces/pix-btg/get-a-refund /v1/refunds/{refund_id}/unblock: post: description: "Use this endpoint to unblock a refund stuck in PROCESSING or PENDING status. The endpoint fetches the current reversal status from BTG and triggers the appropriate refund settlement flow if BTG shows the reversal has completed or failed; the optional request body field allowNotFoundUnblock (default false) opts into resolving a CASHOUT refund as FAILED when BTG reports the reversal absent (404), or an intra-PSP refund parked at CREATED that Midaz holds no transaction for (nothing reverted). An inter-PSP refund at CREATED is refused with 422 (PIX-0470): its Midaz debit may exist unrecorded, so an operator resolves it. A refund of an intra-PSP transfer, which BTG never holds, is settled on Midaz alone at CREATED, PENDING or PROCESSING, 65 minutes after its last write. A PENDING refund updated less than 150 seconds ago is also refused with 422 (PIX-0470): the create flow may still be sending it to BTG. The request body is intentionally an opaque raw-bytes payload (no typed schema): unknown fields are ignored, and an empty body is valid." operationId: payment-unblock-refund parameters: - description: Refund ID (UUID format) in: path name: refund_id required: true schema: description: Refund ID (UUID format) type: string - description: Unique identifier of the Midaz Ledger Account (UUID format) in: header name: X-Account-Id required: true schema: description: Unique identifier of the Midaz Ledger Account (UUID format) type: string requestBody: content: application/octet-stream: schema: contentMediaType: application/octet-stream format: binary type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/UnblockRefundOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Unblock a Pix Refund tags: - Refunds x-mint: href: /pt/reference/interfaces/pix-btg/unblock-a-pix-refund /v1/schedules: get: description: List schedules belonging to the caller's account with optional status filter and pagination. operationId: payment-list-schedules parameters: - description: Account ID owning the schedules (UUID format) in: header name: X-Account-Id required: true schema: description: Account ID owning the schedules (UUID format) type: string - description: "Filter by schedule status; comma-separated for multiple (OR-matched), e.g. SCHEDULED,EXECUTED. Allowed: SCHEDULED, PROCESSING, EXECUTED, FAILED, CANCELLED" explode: false in: query name: status schema: description: "Filter by schedule status; comma-separated for multiple (OR-matched), e.g. SCHEDULED,EXECUTED. Allowed: SCHEDULED, PROCESSING, EXECUTED, FAILED, CANCELLED" type: string - description: "Page number for pagination (default: 1)" explode: false in: query name: page schema: description: "Page number for pagination (default: 1)" type: string - description: "Maximum number of items per page (default: 10, range: 1-100)" explode: false in: query name: limit schema: description: "Maximum number of items per page (default: 10, range: 1-100)" type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/SchedulesListOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: List Pix Schedules tags: - Schedules x-mint: href: /pt/reference/interfaces/pix-btg/list-pix-schedules post: description: Create a single-shot scheduled Pix instruction. The schedule is persisted with status SCHEDULED; the schedule worker dispatches the cashout at the scheduled fire time. The destination snapshot comes from the payment initiation that initiationId references. An endToEndId already held by a Pix or by another schedule returns 409 PIX-0423. operationId: payment-create-schedule parameters: - description: Account ID owning the schedule (UUID format) in: header name: X-Account-Id required: true schema: description: Account ID owning the schedule (UUID format) format: uuid type: string - description: Idempotency anchor (UUID v4 recommended); replays return the cached 201. in: header name: X-Idempotency schema: description: Idempotency anchor (UUID v4 recommended); replays return the cached 201. maxLength: 255 type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateScheduleInput" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/ScheduleOutput" description: Created "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "413": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Request Entity Too Large "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Create a Pix Schedule tags: - Schedules x-mint: href: /pt/reference/interfaces/pix-btg/create-a-pix-schedule /v1/schedules/{schedule_id}: delete: description: "Cancel a schedule that is still in SCHEDULED status. Compare-and-swap: a PROCESSING row returns 409 PIX-0809, a terminal row returns 409 PIX-0814, a cross-account request returns 404 PIX-0800." operationId: payment-cancel-schedule parameters: - description: Schedule ID (UUID v7) in: path name: schedule_id required: true schema: description: Schedule ID (UUID v7) type: string - description: Account ID owning the schedule (UUID format) in: header name: X-Account-Id required: true schema: description: Account ID owning the schedule (UUID format) type: string responses: "204": description: No Content "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Cancel a Pix Schedule tags: - Schedules x-mint: href: /pt/reference/interfaces/pix-btg/cancel-a-pix-schedule get: description: Retrieve a schedule by its unique identifier. Cross-account lookups return 404 — existence is never leaked across accounts. operationId: payment-get-schedule parameters: - description: Schedule ID (UUID v7) in: path name: schedule_id required: true schema: description: Schedule ID (UUID v7) type: string - description: Account ID owning the schedule (UUID format) in: header name: X-Account-Id required: true schema: description: Account ID owning the schedule (UUID format) type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/ScheduleOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Get a Pix Schedule tags: - Schedules x-mint: href: /pt/reference/interfaces/pix-btg/get-a-pix-schedule /v1/statistics/tempos-transacoes/jobs: get: description: Use this endpoint to see every execution across all reference months, not just the latest attempt per month — getting the job of a reference month returns only the latest one, which hides superseded attempts (e.g. a cancelled run followed by a retry). Supports filtering by status and reference-month range, and pagination. operationId: listTemposTransacoesReportJobs parameters: - description: Maximum number of items per page (max 100, default 10) explode: false in: query name: limit schema: description: Maximum number of items per page (max 100, default 10) type: string - description: Page number for pagination (default 1) explode: false in: query name: page schema: description: Page number for pagination (default 1) type: string - description: "Sort direction applied to requestedAt: asc or desc (default desc)" explode: false in: query name: sort_order schema: description: "Sort direction applied to requestedAt: asc or desc (default desc)" type: string - description: Report job statuses, comma-separated (PENDING, RUNNING, COMPLETED, FAILED) explode: false in: query name: status schema: description: Report job statuses, comma-separated (PENDING, RUNNING, COMPLETED, FAILED) type: string - description: Filter by reference month >= this value (YYYY-MM). Must be provided together with reference_month_end. explode: false in: query name: reference_month_start schema: description: Filter by reference month >= this value (YYYY-MM). Must be provided together with reference_month_end. examples: - 2026-01 type: string - description: Filter by reference month <= this value (YYYY-MM). Must be provided together with reference_month_start. explode: false in: query name: reference_month_end schema: description: Filter by reference month <= this value (YYYY-MM). Must be provided together with reference_month_start. examples: - 2026-06 type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/ReportJobListResponse" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: List TemposTransacoes report job executions tags: - Statistics x-mint: href: /pt/reference/interfaces/pix-btg/list-transaction-times-jobs post: description: Use this endpoint to start the asynchronous computation of the BACEN TemposTransacoes payer-experience percentiles for a closed reference month. Returns immediately with the job in PENDING; poll the job or wait for the completion webhook for the result. Only one active job (PENDING/RUNNING) per reference month is allowed (409 otherwise), and at most two jobs run concurrently service-wide (429 beyond that). operationId: createTemposTransacoesReportJob requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateReportJobRequest" required: true responses: "202": content: application/json: schema: $ref: "#/components/schemas/ReportJobResponse" description: Accepted "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "413": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Request Entity Too Large "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Trigger the asynchronous TemposTransacoes computation tags: - Statistics x-mint: href: /pt/reference/interfaces/pix-btg/create-transaction-times-job /v1/statistics/tempos-transacoes/jobs/{referenceMonth}: get: description: Use this endpoint to read the current state of the reference month's latest computation job. When status is COMPLETED, result carries the computed percentiles in the same shape delivered by webhook. operationId: getTemposTransacoesReportJob parameters: - description: Reference month of the job, in YYYY-MM format (-03 reference timezone). in: path name: referenceMonth required: true schema: description: Reference month of the job, in YYYY-MM format (-03 reference timezone). examples: - 2026-05 pattern: ^\d{4}-(0[1-9]|1[0-2])$ type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/ReportJobResponse" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Get the TemposTransacoes job of a reference month tags: - Statistics x-mint: href: /pt/reference/interfaces/pix-btg/get-transaction-times-job /v1/statistics/tempos-transacoes/jobs/{referenceMonth}/cancel: post: description: Use this endpoint to mark the reference month's active (PENDING/RUNNING) job as FAILED, releasing the month for a new attempt. An already-terminal job (COMPLETED/FAILED) is rejected with 422, not returned unchanged. Bookkeeping only — background processing is not guaranteed to stop, and a computation that finishes afterwards overwrites the cancellation with the real result. operationId: cancelTemposTransacoesReportJob parameters: - description: Reference month of the job, in YYYY-MM format (-03 reference timezone). in: path name: referenceMonth required: true schema: description: Reference month of the job, in YYYY-MM format (-03 reference timezone). examples: - 2026-05 pattern: ^\d{4}-(0[1-9]|1[0-2])$ type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/ReportJobResponse" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Cancel a stuck or long-running TemposTransacoes job tags: - Statistics x-mint: href: /pt/reference/interfaces/pix-btg/cancel-transaction-times-job /v1/transaction-reports: get: description: Use this endpoint to list TRCK002 transaction reports with optional filters and pagination. operationId: payment-list-transaction-reports parameters: - description: Maximum number of items per page (max 100, default 10) explode: false in: query name: limit schema: description: Maximum number of items per page (max 100, default 10) type: string - description: Page number for pagination (default 1) explode: false in: query name: page schema: description: Page number for pagination (default 1) type: string - description: "Sort direction applied to created_at: asc or desc" explode: false in: query name: sort_order schema: description: "Sort direction applied to created_at: asc or desc" type: string - description: Filter by the PIX end-to-end identifier explode: false in: query name: end_to_end_id schema: description: Filter by the PIX end-to-end identifier type: string - description: Filter by the return identification (refund reports) explode: false in: query name: return_identification schema: description: Filter by the return identification (refund reports) type: string - description: Filter by initiation type; case-insensitive (MANUAL, DICT, STATIC_QRCODE, DYNAMIC_QRCODE) explode: false in: query name: initiation_type schema: description: Filter by initiation type; case-insensitive (MANUAL, DICT, STATIC_QRCODE, DYNAMIC_QRCODE) type: string - description: Transaction statuses, comma-separated (PENDING, PROCESSING, CONFIRMED, ERROR) explode: false in: query name: status schema: description: Transaction statuses, comma-separated (PENDING, PROCESSING, CONFIRMED, ERROR) type: string - description: Filter by reports created on or after this timestamp (RFC3339) explode: false in: query name: created_at_start schema: description: Filter by reports created on or after this timestamp (RFC3339) type: string - description: Filter by reports created on or before this timestamp (RFC3339) explode: false in: query name: created_at_end schema: description: Filter by reports created on or before this timestamp (RFC3339) type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/TransactionReportListOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: List Transaction Reports tags: - Transaction Reports x-mint: href: /pt/reference/interfaces/pix-btg/list-transaction-reports /v1/transaction-reports/{id}/submit: post: description: "Use this endpoint to manually trigger the submission of a TRCK002 transaction report to BTG. Fallback for reports not submitted through the normal worker-driven flow. Idempotent: reports already PROCESSING or CONFIRMED are left unchanged. Accepted for asynchronous processing; the final outcome is delivered later via the BTG CAMT025 status webhook." operationId: payment-submit-transaction-report parameters: - description: Transaction Report ID (UUID format) in: path name: id required: true schema: description: Transaction Report ID (UUID format) type: string responses: "202": content: application/json: schema: $ref: "#/components/schemas/TransactionReportSubmitOutput" description: Accepted "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Submit a Transaction Report tags: - Transaction Reports x-mint: href: /pt/reference/interfaces/pix-btg/submit-a-transaction-report /v1/transfers: get: description: Use this endpoint to list Pix Transfers with optional filters and pagination. operationId: payment-list-transfers parameters: - description: Account ID (UUID format) in: header name: X-Account-Id required: true schema: description: Account ID (UUID format) type: string - description: "Page number for pagination (default: 1)" explode: false in: query name: page schema: description: "Page number for pagination (default: 1)" type: string - description: "Maximum number of items per page (default: 10, range: 1-100)" explode: false in: query name: limit schema: description: "Maximum number of items per page (default: 10, range: 1-100)" type: string - description: "Sort direction for results: asc or desc" explode: false in: query name: sort_order schema: description: "Sort direction for results: asc or desc" type: string - description: Filter by the Pix transfer end-to-end identifier explode: false in: query name: end_to_end schema: description: Filter by the Pix transfer end-to-end identifier type: string - description: "Filter by transfer status; comma-separated for multiple (OR-matched), e.g. PENDING,COMPLETED. Allowed: CREATED, REJECTED, PENDING, PROCESSING, COMPLETED, FAILED, CANCELLED" explode: false in: query name: status schema: description: "Filter by transfer status; comma-separated for multiple (OR-matched), e.g. PENDING,COMPLETED. Allowed: CREATED, REJECTED, PENDING, PROCESSING, COMPLETED, FAILED, CANCELLED" type: string - description: Filter by transfer direction (CASHOUT or CASHIN) explode: false in: query name: type schema: description: Filter by transfer direction (CASHOUT or CASHIN) type: string - description: Filter by transfers modified after this timestamp (RFC3339) explode: false in: query name: modified_after schema: description: Filter by transfers modified after this timestamp (RFC3339) type: string - description: Filter by transfers modified before this timestamp (RFC3339) explode: false in: query name: modified_before schema: description: Filter by transfers modified before this timestamp (RFC3339) type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/TransfersListOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: List Pix Transfers tags: - Transfers x-mint: href: /pt/reference/interfaces/pix-btg/list-pix-transfers /v1/transfers/cashout/initiate: post: description: "Use this endpoint to start a Pix cash-out by creating an initiation record. This endpoint retrieves and validates destination information without moving funds. Supports MANUAL, KEY, and QR_CODE initiation. An endToEndId already held by a Pix or by a schedule returns 409 PIX-0423. The request body is intentionally an opaque raw-bytes payload (no typed schema): unknown fields are ignored." operationId: payment-initiate-transfer parameters: - description: Account ID (UUID format) in: header name: X-Account-Id schema: description: Account ID (UUID format) type: string requestBody: content: application/octet-stream: schema: contentMediaType: application/octet-stream format: binary type: string responses: "201": content: application/json: schema: $ref: "#/components/schemas/InitiateTransferOutput" description: Created "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Initiate a Pix Transfer tags: - Transfers x-mint: href: /pt/reference/interfaces/pix-btg/initiate-a-pix-transfer /v1/transfers/cashout/process: post: description: "Process a previously initiated Pix cash-out and move funds between accounts. A cash-out whose Midaz debit outcome is unknown is still answered 201, at status CREATED, and keeps its initiation; its outcome arrives later by the transfer webhook. The request body is intentionally an opaque raw-bytes payload (no typed schema): unknown fields are ignored." operationId: payment-process-cashout parameters: - description: Account ID (UUID format) in: header name: X-Account-Id schema: description: Account ID (UUID format) type: string - description: Transaction purpose (TRANSFER, INSTANT_PAYMENT_REFUND, WITHDRAWAL for a Pix Saque charge, CHANGE for a Pix Troco charge). Defaults to TRANSFER. in: header name: X-Purpose schema: description: Transaction purpose (TRANSFER, INSTANT_PAYMENT_REFUND, WITHDRAWAL for a Pix Saque charge, CHANGE for a Pix Troco charge). Defaults to TRANSFER. type: string requestBody: content: application/octet-stream: schema: contentMediaType: application/octet-stream format: binary type: string responses: "201": content: application/json: schema: $ref: "#/components/schemas/TransferResponse" description: Created "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Process a Pix Transfer tags: - Transfers x-mint: href: /pt/reference/interfaces/pix-btg/process-a-pix-transfer /v1/transfers/{transfer_id}: get: description: Use this endpoint to retrieve a Pix transfer by its unique identifier. operationId: payment-get-transfer parameters: - description: Transfer ID (UUID format) in: path name: transfer_id required: true schema: description: Transfer ID (UUID format) type: string - description: Unique identifier of the Midaz Ledger Account (UUID format) in: header name: X-Account-Id required: true schema: description: Unique identifier of the Midaz Ledger Account (UUID format) type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/TransferResponse" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Get a Pix Transfer tags: - Transfers x-mint: href: /pt/reference/interfaces/pix-btg/retrieve-a-pix-transfer /v1/transfers/{transfer_id}/refunds: post: description: Use this endpoint to initiate a refund for a previously received Pix transfer. Optionally provide an operations array for distributed partial refunds from multiple accounts. Only received Pix transfers (cash-in) can be refunded; the sum of all refunds cannot exceed the original amount. A create carries X-Idempotency or X-Return-End-To-End; one with neither is refused 400 PIX-0001 and moves no money, and a resend with either anchor returns the first refund. A refund whose Midaz debit outcome is unknown is still answered 201, at status CREATED, and stays reserved against the original amount; its outcome arrives later by the refund webhook. operationId: payment-create-refund parameters: - description: Database UUID of the original Pix transfer (cashin) in: path name: transfer_id required: true schema: description: Database UUID of the original Pix transfer (cashin) format: uuid type: string - description: Account ID that received the original transfer (UUID format) in: header name: X-Account-Id required: true schema: description: Account ID that received the original transfer (UUID format) format: uuid type: string - description: Refund reason code in: header name: X-Reason required: true schema: description: Refund reason code enum: - BE08 - FR01 - MD06 - SL02 type: string - description: Custom return end-to-end ID (32 chars, D prefix); required unless X-Idempotency is sent in: header name: X-Return-End-To-End schema: description: Custom return end-to-end ID (32 chars, D prefix); required unless X-Idempotency is sent type: string - description: Idempotency key of the create; required unless X-Return-End-To-End is sent in: header name: X-Idempotency schema: description: Idempotency key of the create; required unless X-Return-End-To-End is sent type: string requestBody: content: application/json: schema: $ref: "#/components/schemas/CreateRefundCashoutInput" required: true responses: "201": content: application/json: schema: $ref: "#/components/schemas/RefundCashoutOutput" description: Created "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "413": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Request Entity Too Large "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Refund a Received Pix Transfer tags: - Refunds x-mint: href: /pt/reference/interfaces/pix-btg/refund-a-received-pix-transfer /v1/transfers/{transfer_id}/unblock: post: description: "Use this endpoint to unblock a transaction that is stuck in PENDING or PROCESSING status. The endpoint fetches the current status from BTG and triggers the appropriate settlement flow if BTG shows the transaction has completed or failed. The optional request body field allowNotFoundUnblock (default false) gates ONLY the not-found branches: a BTG 404, which reverts a cash-out's Midaz debit and fails it, and an intra-PSP cash-out parked at CREATED that Midaz holds no transaction for, which fails with nothing reverted; a cash-out whose status changed while BTG was queried is refused with 422 (PIX-0470) and nothing is reverted. An inter-PSP cash-out at CREATED is refused with 422 (PIX-0470): its Midaz debit may exist unrecorded, so an operator resolves it. An intra-PSP cash-out, which BTG never holds, is settled on Midaz alone: at CREATED 65 minutes after its creation, at PENDING 65 minutes after its last write. A cash-out at PENDING updated less than 150 seconds ago is also refused with 422 (PIX-0470): the cash-out flow may still be sending it to BTG. A repeat on a terminal cash-out closes a schedule it left PROCESSING and re-sends the recurring module's terminal event and a reverted rejection's client webhook, then answers 422; a 500 after the terminal write means one of these failed: repeat the call, which never reverts again. The request body is intentionally an opaque raw-bytes payload (no typed schema): unknown fields are ignored, and an empty body is valid." operationId: payment-unblock-transfer parameters: - description: Transfer ID (UUID format) in: path name: transfer_id required: true schema: description: Transfer ID (UUID format) type: string - description: Unique identifier of the Midaz Ledger Account (UUID format) in: header name: X-Account-Id required: true schema: description: Unique identifier of the Midaz Ledger Account (UUID format) type: string requestBody: content: application/octet-stream: schema: contentMediaType: application/octet-stream format: binary type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/UnblockTransferOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Unblock a Pix Transfer tags: - Transfers x-mint: href: /pt/reference/interfaces/pix-btg/unblock-a-pix-transfer /v1/webhooks/inbound: get: description: Lists persisted inbound webhooks (received from BTG). The entity_type query parameter is required. operationId: webhook-list-inbound parameters: - description: "The authorization token. Important: This header is required only if your environment has the Access Manager plugin enabled." in: header name: Authorization schema: description: "The authorization token. Important: This header is required only if your environment has the Access Manager plugin enabled." type: string - description: "Required. Inbound entity type. Uppercased server-side. One of: DICT_CLAIM, DICT_REFUND, DICT_CID_FILE, INFRACTION_REPORT_V2, PIX_DOWNLOAD, PIX_PAYMENT, PIX_PAYMENT_INBOUND, PIX_REVERSAL, PIX_REVERSAL_INBOUND." explode: false in: query name: entity_type schema: description: "Required. Inbound entity type. Uppercased server-side. One of: DICT_CLAIM, DICT_REFUND, DICT_CID_FILE, INFRACTION_REPORT_V2, PIX_DOWNLOAD, PIX_PAYMENT, PIX_PAYMENT_INBOUND, PIX_REVERSAL, PIX_REVERSAL_INBOUND." examples: - DICT_CLAIM type: string - description: "Filter by status: RECEIVED, PROCESSING, SENT, FAILED. Multiple comma-separated values are OR-matched." explode: false in: query name: status schema: description: "Filter by status: RECEIVED, PROCESSING, SENT, FAILED. Multiple comma-separated values are OR-matched." examples: - - RECEIVED items: type: string type: array - description: Filter by original BTG clientRequestId. explode: false in: query name: request_id schema: description: Filter by original BTG clientRequestId. examples: - 560d59b9-3c74-46f8-be67-fee895b8e89e type: string - description: Filter rows with created_at >= this RFC3339 timestamp. explode: false in: query name: created_after schema: description: Filter rows with created_at >= this RFC3339 timestamp. examples: - "2026-05-21T12:00:00Z" type: string - description: Filter rows with created_at <= this RFC3339 timestamp. explode: false in: query name: created_before schema: description: Filter rows with created_at <= this RFC3339 timestamp. examples: - "2026-05-21T12:00:00Z" type: string - description: Items per page (integer 1-100, default 20). explode: false in: query name: limit schema: description: Items per page (integer 1-100, default 20). examples: - "20" type: string - description: Page number (integer >= 1, default 1). explode: false in: query name: page schema: description: Page number (integer >= 1, default 1). examples: - "1" type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/ListInboundWebhooksOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: List inbound webhooks tags: - Webhooks x-mint: href: /pt/reference/interfaces/pix-btg/list-inbound-webhooks /v1/webhooks/inbound/{id}: get: description: Gets a single inbound webhook by id. Intended for low-frequency operator use. operationId: webhook-get-inbound parameters: - description: "The authorization token. Important: This header is required only if your environment has the Access Manager plugin enabled." in: header name: Authorization schema: description: "The authorization token. Important: This header is required only if your environment has the Access Manager plugin enabled." type: string - description: Inbound webhook id (UUID). in: path name: id required: true schema: description: Inbound webhook id (UUID). examples: - 019cf6ef-e418-7ced-80c0-7b9816faa798 type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/WebhookInboundOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Get inbound webhook by id tags: - Webhooks x-mint: href: /pt/reference/interfaces/pix-btg/get-an-inbound-webhook /v1/webhooks/inbound/{id}/retry: post: description: Re-arms a FAILED inbound webhook so it is retried. Returns 202 Accepted. The retry preserves the current attempt count and raises the retry ceiling. operationId: webhook-retry-inbound parameters: - description: "The authorization token. Important: This header is required only if your environment has the Access Manager plugin enabled." in: header name: Authorization schema: description: "The authorization token. Important: This header is required only if your environment has the Access Manager plugin enabled." type: string - description: Inbound webhook id (UUID). in: path name: id required: true schema: description: Inbound webhook id (UUID). examples: - 019cf6ef-e418-7ced-80c0-7b9816faa798 type: string responses: "202": content: application/json: schema: $ref: "#/components/schemas/RetryWebhookOutput" description: Accepted "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Retry inbound webhook tags: - Webhooks x-mint: href: /pt/reference/interfaces/pix-btg/retry-an-inbound-webhook /v1/webhooks/outbound: get: description: Lists persisted outbound webhooks (sent to clients). The flow_type query parameter is required. Dead-letter rows are surfaced transparently with status="DEAD_LETTER". operationId: webhook-list-outbound parameters: - description: "The authorization token. Important: This header is required only if your environment has the Access Manager plugin enabled." in: header name: Authorization schema: description: "The authorization token. Important: This header is required only if your environment has the Access Manager plugin enabled." type: string - description: "Required. Outbound flow type. Uppercased server-side. One of: DICT, PAYMENT, COLLECTION, PIX, TRANSFER, REFUND, RECURRING." explode: false in: query name: flow_type schema: description: "Required. Outbound flow type. Uppercased server-side. One of: DICT, PAYMENT, COLLECTION, PIX, TRANSFER, REFUND, RECURRING." examples: - DICT type: string - description: Filter by internal entity type (e.g. CLAIM, REFUND, INFRACTION_REPORT under DICT; CASHIN, CASHOUT under TRANSFER/REFUND). explode: false in: query name: entity_type schema: description: Filter by internal entity type (e.g. CLAIM, REFUND, INFRACTION_REPORT under DICT; CASHIN, CASHOUT under TRANSFER/REFUND). examples: - CLAIM type: string - description: Filter by entity id in UUID format. explode: false in: query name: entity_id schema: description: Filter by entity id in UUID format. examples: - 019cf6ef-e418-7ced-80c0-7b9816faa798 type: string - description: "Filter by status: PENDING, PROCESSING, SENT, FAILED, DEAD_LETTER. Multiple comma-separated values are OR-matched. DEAD_LETTER is a virtual, API-only value that surfaces dead-lettered webhooks." explode: false in: query name: status schema: description: "Filter by status: PENDING, PROCESSING, SENT, FAILED, DEAD_LETTER. Multiple comma-separated values are OR-matched. DEAD_LETTER is a virtual, API-only value that surfaces dead-lettered webhooks." examples: - - PENDING items: type: string type: array - description: Filter by originating request id. explode: false in: query name: request_id schema: description: Filter by originating request id. examples: - 560d59b9-3c74-46f8-be67-fee895b8e89e type: string - description: Filter rows with created_at >= this RFC3339 timestamp. explode: false in: query name: created_after schema: description: Filter rows with created_at >= this RFC3339 timestamp. examples: - "2026-05-21T12:00:00Z" type: string - description: Filter rows with created_at <= this RFC3339 timestamp. explode: false in: query name: created_before schema: description: Filter rows with created_at <= this RFC3339 timestamp. examples: - "2026-05-21T12:00:00Z" type: string - description: Items per page (integer 1-100, default 20). explode: false in: query name: limit schema: description: Items per page (integer 1-100, default 20). examples: - "20" type: string - description: Page number (integer >= 1, default 1). explode: false in: query name: page schema: description: Page number (integer >= 1, default 1). examples: - "1" type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/ListOutboundWebhooksOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: List outbound webhooks tags: - Webhooks x-mint: href: /pt/reference/interfaces/pix-btg/list-outbound-webhooks /v1/webhooks/outbound/{id}: get: description: Gets a single outbound webhook by id. Dead-letter rows are resolved transparently and surfaced with status="DEAD_LETTER" and additional dead-letter fields populated. operationId: webhook-get-outbound parameters: - description: "The authorization token. Important: This header is required only if your environment has the Access Manager plugin enabled." in: header name: Authorization schema: description: "The authorization token. Important: This header is required only if your environment has the Access Manager plugin enabled." type: string - description: Outbound webhook id (UUID). in: path name: id required: true schema: description: Outbound webhook id (UUID). examples: - 019cf6ef-e418-7ced-80c0-7b9816faa798 type: string responses: "200": content: application/json: schema: $ref: "#/components/schemas/WebhookOutboundOutput" description: OK "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Get outbound webhook by id tags: - Webhooks x-mint: href: /pt/reference/interfaces/pix-btg/get-an-outbound-webhook /v1/webhooks/outbound/{id}/retry: post: description: Re-arms a FAILED outbound webhook. A webhook that has already moved to the dead-letter queue is restored (preserving its original id) and removed from the dead-letter queue atomically. Returns 202 Accepted. operationId: webhook-retry-outbound parameters: - description: "The authorization token. Important: This header is required only if your environment has the Access Manager plugin enabled." in: header name: Authorization schema: description: "The authorization token. Important: This header is required only if your environment has the Access Manager plugin enabled." type: string - description: Outbound webhook id (UUID). in: path name: id required: true schema: description: Outbound webhook id (UUID). examples: - 019cf6ef-e418-7ced-80c0-7b9816faa798 type: string responses: "202": content: application/json: schema: $ref: "#/components/schemas/RetryWebhookOutput" description: Accepted "400": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Bad Request "500": content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Internal Server Error default: content: application/json: schema: $ref: "#/components/schemas/LegacyErrorBody" description: Error summary: Retry outbound webhook tags: - Webhooks x-mint: href: /pt/reference/interfaces/pix-btg/retry-an-outbound-webhook security: - BearerAuth: [] servers: - url: https://api.example.com description: Replace the example host with the URL provided during environment onboarding.