> ## Documentation Index > Fetch the complete documentation index at: https://fastpay-mintlify-943e4c49.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Register a chargeback alert (admin) > Administrative endpoint that records a **chargeback alert** for a paid charge. In a single transaction it: 1. Refunds the charge (falling back to the manual refund queue when the PSP does not expose an API refund). 2. Debits the **chargeback alert fee** configured for the merchant (`merchant_settings.chargeback_alert_fee`, with the gateway default as fallback) from the merchant's available balance and credits the gateway's revenue balance. 3. Transitions the charge status to `pre_chargeback`. Requires the `admin.chargeback_alerts.create` permission. The operation is idempotent: a second call for the same charge returns `422`. See [Alertas de chargeback](/guias/alertas-de-chargeback) for the full flow, including the manual refund fallback. ## OpenAPI ````yaml /api-reference/openapi.yaml post /v1/charges/{id}/chargeback-alert openapi: 3.0.0 info: title: FastPay API version: 1.0.0 description: >- API for creating and managing payment charges. ## Authentication This API uses **Basic Authentication** for direct API access, such as creating charges. Use your API key as the username and an empty string as password. The header should be formatted as: `Authorization: Basic {base64(apiKey:)}`. For example: ``` Authorization: Basic YWxleG91dG9uOiIi ``` ## Webhooks FastPay sends webhooks to notify your application about charge status changes in real-time. Webhooks are sent via HTTP POST requests to your configured webhook endpoints. ### Webhook Events The following webhook events are available for charges: - `charge.created` - Sent when a new charge is created - `charge.pending` - Sent when a charge is pending payment - `charge.paid` - Sent when a charge is successfully paid - `charge.updated` - Sent when a charge is updated ### Webhook Payload Structure All webhook payloads follow this structure: ```json { "id": "webhook_event_id", "event": "charge.paid", "data": { // Complete charge object } } ``` ### Webhook Delivery - Webhooks are sent via HTTP POST requests - Content-Type: `application/json` - Retry logic is implemented for failed deliveries - Webhook events are stored in the database for audit purposes - Delivery logs are maintained for debugging and monitoring ### Webhook Security - Webhooks are sent to pre-configured endpoints - Endpoints can be enabled/disabled per merchant - Event filtering is supported (only receive specific events) - Failed deliveries are retried with exponential backoff servers: - url: https://api-global.fastpaybrasil.com description: Produção e Sandbox (diferenciados pela API key) security: [] paths: /v1/charges/{id}/chargeback-alert: post: tags: - Chargeback Alerts summary: Register a chargeback alert (admin) description: |- Administrative endpoint that records a **chargeback alert** for a paid charge. In a single transaction it: 1. Refunds the charge (falling back to the manual refund queue when the PSP does not expose an API refund). 2. Debits the **chargeback alert fee** configured for the merchant (`merchant_settings.chargeback_alert_fee`, with the gateway default as fallback) from the merchant's available balance and credits the gateway's revenue balance. 3. Transitions the charge status to `pre_chargeback`. Requires the `admin.chargeback_alerts.create` permission. The operation is idempotent: a second call for the same charge returns `422`. See [Alertas de chargeback](/guias/alertas-de-chargeback) for the full flow, including the manual refund fallback. parameters: - name: id in: path description: >- ID of the charge to register the alert against. Must be in `paid` status. required: true schema: type: string example: 2vorkDcXyvzifL63YX09S9VqcnI requestBody: required: false content: application/json: schema: type: object properties: reason: type: string maxLength: 500 description: Optional reason/notes for the alert. Stored for audit. example: Ethoca alert received on 2026-06-24 responses: '201': description: Chargeback alert registered successfully content: application/json: schema: type: object required: - chargeId - status - refund - alertFee properties: chargeId: type: string example: 2vorkDcXyvzifL63YX09S9VqcnI status: type: string enum: - pre_chargeback example: pre_chargeback refund: type: object required: - id - mode properties: id: type: string description: ID of the refund created for the charge. example: 2RhQg9M7ZCg3X3nMb9W1kX8Q mode: type: string enum: - api - manual description: |- `api` when the PSP confirmed the refund; `manual` when the request was added to the manual refund queue (`GET /v1/manual-refund-requests`). example: api alertFee: type: object required: - amount - currency properties: amount: type: number description: >- Fee amount debited from the merchant's available balance. example: 25 currency: type: string description: ISO 4217 currency code of the fee. example: BRL '400': description: |- Chargeback alert fee is not configured for the merchant or the stored value is invalid (`CHARGEBACK_ALERT_FEE_NOT_CONFIGURED`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized - invalid credentials content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden - missing `admin.chargeback_alerts.create` permission content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Charge not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: >- Charge is not in `paid` status, already has a `pre_chargeback`/`chargeback` status or already has a chargeback-alert-fee movement recorded. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - bearer: [] components: schemas: ErrorResponse: type: object properties: statusCode: type: integer description: HTTP status code example: 422 message: type: string description: Descriptive error message example: SubMerchant is not active error: type: string description: Error type example: Unprocessable Entity securitySchemes: bearer: type: http scheme: bearer bearerFormat: JWT description: |- JWT Bearer token authentication. Use the JWT token obtained from the login endpoint in the Authorization header as 'Bearer {token}'. ````