openapi: 3.1.0 info: title: API AbacatePay description: API para gerenciamento de cobranças e pagamentos usando o AbacatePay. version: 1.0.0 servers: - url: 'https://api.abacatepay.com/v2' description: Único servidor para os ambientes de produção e sandbox. paths: /customers/create: post: summary: Criar um cliente description: > Permite que você crie um cliente para a sua loja. **Campo obrigatório**: Apenas o `email` é obrigatório para criar um cliente. **Recomendado**: Embora os demais campos sejam opcionais, é altamente recomendado fornecer `name`, `cellphone`, `taxId` e `zipCode` quando disponíveis, pois essas informações melhoram a experiência do cliente no checkout e facilitam a identificação. security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object description: > Os dados do seu cliente. **Obrigatório**: Apenas `email` é obrigatório. **Opcional mas recomendado**: `name`, `cellphone`, `taxId`, `zipCode` e `metadata` são opcionais, mas recomendados para melhor experiência do cliente. required: - email additionalProperties: false example: email: daniel_lima@abacatepay.com properties: email: type: string description: E-mail do cliente (obrigatório) example: daniel_lima@abacatepay.com name: type: string description: Nome completo do seu cliente (opcional) example: Daniel Lima x-mint: hidden: true cellphone: type: string description: Celular do cliente (opcional) example: (11) 4002-8922 x-mint: hidden: true taxId: type: string description: CPF ou CNPJ válido do cliente (opcional) example: 123.456.789-01 x-mint: hidden: true zipCode: type: string description: CEP do cliente (opcional) example: 01310-100 x-mint: hidden: true metadata: type: object description: >- Metadados adicionais do cliente. Campo livre para a sua aplicação (opcional) additionalProperties: true example: source: landing-page campaign: black-friday-2025 x-mint: hidden: true responses: '200': description: Cliente criado com sucesso. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Customer' error: type: string nullable: true example: null success: $ref: '#/components/schemas/Success' '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro descrevendo o motivo da falha na autenticação. example: Token de autenticação inválido ou ausente. /customers/list: get: summary: Listar clientes description: > Retorna todos os clientes que você cadastrou com suporte a paginação. Você pode usar essa rota para visualizar todos os seus clientes e suas informações. **Alternativa**: Você também pode visualizar e gerenciar seus clientes pelo [Dashboard da AbacatePay](https://app.abacatepay.com/clientes). security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/QueryAfter' - $ref: '#/components/parameters/QueryBefore' - $ref: '#/components/parameters/QueryLimit' - $ref: '#/components/parameters/QueryStartDate' - $ref: '#/components/parameters/QueryEndDate' - name: id in: query description: Filtrar por identificador único do cliente required: false schema: type: string example: cust_aebxkhDZNaMmJeKsy0AHS0FQ - name: email in: query description: Filtrar por e-mail do cliente required: false schema: type: string example: daniel_lima@abacatepay.com - name: taxId in: query description: Filtrar por CPF ou CNPJ do cliente required: false schema: type: string example: 123.456.789-01 - name: name in: query description: Filtrar por nome do cliente required: false schema: type: string example: Daniel Lima - name: cellphone in: query description: Filtrar por telefone do cliente required: false schema: type: string example: (11) 4002-8922 responses: '200': description: Lista de clientes retornada com sucesso. content: application/json: schema: type: object properties: data: type: array description: Lista de clientes. items: $ref: '#/components/schemas/Customer' success: $ref: '#/components/schemas/Success' error: type: string example: null nullable: true pagination: $ref: '#/components/schemas/PaginationCursor' '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro descrevendo o motivo da falha na autenticação. example: Token de autenticação inválido ou ausente. /customers/get: get: summary: Buscar um cliente description: > Retorna os dados de um cliente específico baseado em filtros. Você pode usar essa rota para buscar um cliente por ID ou outros critérios. security: - bearerAuth: [] parameters: - name: id in: query description: Identificador único público do cliente required: false schema: type: string example: cust_aebxkhDZNaMmJeKsy0AHS0FQ - name: email in: query description: E-mail do cliente required: false schema: type: string format: email example: daniel_lima@abacatepay.com - name: taxId in: query description: CPF ou CNPJ do cliente required: false schema: type: string example: 123.456.789-01 responses: '200': description: Cliente encontrado com sucesso. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Customer' error: type: string example: null nullable: true success: $ref: '#/components/schemas/Success' '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro descrevendo o motivo da falha na autenticação. example: Token de autenticação inválido ou ausente. '404': description: Cliente não encontrado. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro indicando que o cliente não foi encontrado. example: Cliente não encontrado. /customers/delete: post: summary: Deletar um cliente description: | Remove um cliente da sua loja. Esta operação é irreversível. Use com cuidado. security: - bearerAuth: [] parameters: - name: id in: query required: true description: Identificador único público do cliente a ser deletado schema: type: string example: cust_aebxkhDZNaMmJeKsy0AHS0FQ responses: '200': description: Cliente deletado com sucesso. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Customer' error: type: string example: null nullable: true success: $ref: '#/components/schemas/Success' '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro descrevendo o motivo da falha na autenticação. example: Token de autenticação inválido ou ausente. '404': description: Cliente não encontrado. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro indicando que o cliente não foi encontrado. example: Cliente não encontrado. /coupons/create: post: summary: Criar um cupom description: > Permite que você crie um novo cupom que pode ser usado por seus clientes para aplicar descontos. **Alternativa**: Você também pode criar e gerenciar seus cupons pelo [Dashboard da AbacatePay](https://app.abacatepay.com/cupons). security: - bearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Coupon' responses: '200': description: Cupom criado com sucesso. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/CouponResponse' error: type: string nullable: true example: null success: $ref: '#/components/schemas/Success' '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro descrevendo o motivo da falha na autenticação. example: Token de autenticação inválido ou ausente. /coupons/list: get: summary: Listar cupons description: > Retorna todos os cupons que você criou com suporte a paginação. Você pode usar essa rota para visualizar todos os seus cupons, incluindo seus status (ativos, inativos ou expirados), descontos aplicados e quantas vezes foram utilizados. **Alternativa**: Você também pode visualizar e gerenciar seus cupons pelo [Dashboard da AbacatePay](https://app.abacatepay.com/cupons). security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/QueryAfter' - $ref: '#/components/parameters/QueryBefore' - $ref: '#/components/parameters/QueryLimit' - $ref: '#/components/parameters/QueryStartDate' - $ref: '#/components/parameters/QueryEndDate' - name: id in: query description: Filtrar por identificador único do cupom required: false schema: type: string example: DEYVIN_20 - name: status in: query description: Filtrar por status do cupom required: false schema: type: string enum: - ACTIVE - INACTIVE - EXPIRED responses: '200': description: Lista de cupons retornada com sucesso. content: application/json: schema: type: object properties: data: type: array description: Lista de cupons. items: $ref: '#/components/schemas/CouponResponse' success: $ref: '#/components/schemas/Success' error: type: string nullable: true example: null pagination: $ref: '#/components/schemas/PaginationCursor' '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro descrevendo o motivo da falha na autenticação. example: Token de autenticação inválido ou ausente. /coupons/get: get: summary: Buscar um cupom description: > Retorna os dados de um cupom específico baseado em filtros. Você pode usar essa rota para buscar um cupom por ID ou outros critérios. security: - bearerAuth: [] parameters: - name: id in: query description: Identificador único do cupom required: true schema: type: string example: MY_COUPON - name: status in: query description: Filtrar por status do cupom required: false schema: type: string enum: - ACTIVE - DISABLED - DELETED responses: '200': description: Cupom encontrado com sucesso. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/CouponResponse' error: type: string nullable: true example: null success: $ref: '#/components/schemas/Success' '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro descrevendo o motivo da falha na autenticação. example: Token de autenticação inválido ou ausente. '404': description: Cupom não encontrado. content: application/json: schema: type: object properties: error: type: string description: Mensagem de erro indicando que o cupom não foi encontrado. example: Cupom não encontrado. /coupons/delete: post: summary: Deletar um cupom description: | Remove um cupom da sua loja. Esta operação é irreversível. Use com cuidado. security: - bearerAuth: [] parameters: - name: id in: query required: true description: Identificador único do cupom a ser deletado schema: type: string example: MY_COUPON responses: '200': description: Cupom deletado com sucesso. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/CouponResponse' error: type: string nullable: true example: null success: $ref: '#/components/schemas/Success' '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro descrevendo o motivo da falha na autenticação. example: Token de autenticação inválido ou ausente. '404': description: Cupom não encontrado. content: application/json: schema: type: object properties: error: type: string description: Mensagem de erro indicando que o cupom não foi encontrado. example: Cupom não encontrado. /coupons/toggle: post: summary: Alternar status de um cupom description: | Alterna o status de um cupom entre ativo e inativo. Use essa rota para ativar ou desativar um cupom sem precisar deletá-lo. security: - bearerAuth: [] parameters: - name: id in: query required: true description: Identificador único do cupom schema: type: string example: MY_COUPON responses: '200': description: Status do cupom alternado com sucesso. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/CouponResponse' error: type: string nullable: true example: null success: $ref: '#/components/schemas/Success' '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro descrevendo o motivo da falha na autenticação. example: Token de autenticação inválido ou ausente. '404': description: Cupom não encontrado. content: application/json: schema: type: object properties: error: type: string description: Mensagem de erro indicando que o cupom não foi encontrado. example: Cupom não encontrado. /products/create: post: summary: Criar um produto description: > Permite que você crie um novo produto que pode ser usado em cobranças. Produtos podem ser avulsos (pagamento único) ou de assinatura; use o campo opcional `cycle` para definir a recorrência (`WEEKLY`, `MONTHLY`, `QUARTERLY`, `SEMIANNUALLY`, `ANNUALLY`). Quando `cycle` é omitido ou `null`, o produto é avulso. **Alternativa**: Você também pode criar e gerenciar seus produtos pelo [Dashboard da AbacatePay](https://app.abacatepay.com/produtos). security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object description: Dados necessários para criar um produto. required: - externalId - name - price - currency additionalProperties: false example: externalId: prod-123 name: Produto Exemplo price: 10000 currency: BRL properties: externalId: type: string description: Identificador único do produto no seu sistema. example: prod-123 name: type: string description: Nome do produto. example: Produto Exemplo price: type: number description: Preço do produto em centavos. minimum: 1 example: 10000 currency: type: string description: Moeda do produto. default: BRL example: BRL description: type: string description: Descrição opcional do produto. example: Descrição do produto x-mint: hidden: true imageUrl: type: string format: uri nullable: true description: URL da imagem do produto. Opcional. example: null fileUrl: type: string format: uri description: > URL pública de um PDF a ser vinculado ao produto. Opcional. O arquivo é baixado e armazenado pela AbacatePay — máximo 20 MB. Após o pagamento, o comprador recebe acesso ao download do arquivo. example: "https://exemplo.com/meu-ebook.pdf" cycle: type: string nullable: true description: > Opcional. Indica se o produto é uma assinatura. Quando omitido ou `null`, o produto é avulso (pagamento único). Valores possíveis: `WEEKLY`, `MONTHLY`, `QUARTERLY`, `SEMIANNUALLY`, `ANNUALLY`. enum: - WEEKLY - MONTHLY - QUARTERLY - SEMIANNUALLY - ANNUALLY example: null image: type: string format: uri description: URL da imagem do produto. example: https://cdn.exemplo.com/produto.png trialDays: type: integer description: >- Dias de teste gratuito antes da primeira cobrança. Só se aplica a produtos com `cycle` definido. minimum: 1 maximum: 90 example: 7 responses: '200': description: Produto criado com sucesso. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Product' error: type: string nullable: true example: null success: $ref: '#/components/schemas/Success' '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro descrevendo o motivo da falha na autenticação. example: Token de autenticação inválido ou ausente. /products/list: get: summary: Listar produtos description: > Retorna todos os produtos que você criou com suporte a paginação. Você pode usar essa rota para visualizar todos os seus produtos, incluindo status, preços, ciclo de assinatura (quando aplicável) e demais informações. **Alternativa**: Você também pode visualizar e gerenciar seus produtos pelo [Dashboard da AbacatePay](https://app.abacatepay.com/produtos). security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/QueryAfter' - $ref: '#/components/parameters/QueryBefore' - $ref: '#/components/parameters/QueryLimit' - $ref: '#/components/parameters/QueryStartDate' - $ref: '#/components/parameters/QueryEndDate' - name: id in: query description: Filtrar por identificador único do produto required: false schema: type: string example: prod_abc123xyz - name: externalId in: query description: Filtrar por identificador do produto no seu sistema required: false schema: type: string example: prod-123 - name: status in: query description: Filtrar por status do produto required: false schema: type: string enum: - ACTIVE - INACTIVE - name: keyword in: query description: Busca textual livre required: false schema: type: string - name: name in: query description: Filtrar por nome do produto required: false schema: type: string - name: currency in: query description: Filtrar por moeda do produto required: false schema: type: string example: BRL responses: '200': description: Lista de produtos retornada com sucesso. content: application/json: schema: type: object properties: data: type: array description: Lista de produtos. items: $ref: '#/components/schemas/Product' success: $ref: '#/components/schemas/Success' error: type: string nullable: true example: null pagination: $ref: '#/components/schemas/PaginationCursor' '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro descrevendo o motivo da falha na autenticação. example: Token de autenticação inválido ou ausente. /products/get: get: summary: Buscar um produto description: > Retorna os dados de um produto específico baseado em filtros, incluindo o campo `cycle` (assinatura ou avulso). Você pode usar essa rota para buscar um produto por ID ou externalId. security: - bearerAuth: [] parameters: - name: id in: query description: Identificador único público do produto required: false schema: type: string example: prod_abc123xyz - name: externalId in: query description: Identificador único do produto no seu sistema required: false schema: type: string example: prod-123 - name: name in: query description: Nome do produto required: false schema: type: string responses: '200': description: Produto encontrado com sucesso. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Product' error: type: string nullable: true example: null success: $ref: '#/components/schemas/Success' '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro descrevendo o motivo da falha na autenticação. example: Token de autenticação inválido ou ausente. '404': description: Produto não encontrado. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro indicando que o produto não foi encontrado. example: Produto não encontrado. /products/delete: post: summary: Deletar um produto description: | Remove um produto da sua loja (avulso ou de assinatura). Esta operação é irreversível. Use com cuidado. security: - bearerAuth: [] parameters: - name: id in: query required: true description: Identificador único público do produto a ser deletado schema: type: string example: prod_abc123xyz responses: '200': description: Produto deletado com sucesso. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Product' error: type: string nullable: true example: null success: $ref: '#/components/schemas/Success' '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro descrevendo o motivo da falha na autenticação. example: Token de autenticação inválido ou ausente. '404': description: Produto não encontrado. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro indicando que o produto não foi encontrado. example: Produto não encontrado. /checkouts/create: post: summary: Criar um Checkout description: Cria um Checkout para o cliente realizar o pagamento. security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - items additionalProperties: false example: items: - id: prod-1234 quantity: 2 methods: ['PIX', 'CARD'] properties: items: type: array description: > Lista de itens incluídos na cobrança. Este é o único campo obrigatório — o valor total é calculado a partir destes itens. minItems: 1 items: type: object additionalProperties: false required: - id - quantity properties: id: type: string description: ID público do produto na sua loja. example: prod-1234 quantity: type: integer description: Quantidade deste item. minimum: 1 example: 2 methods: type: array description: Métodos de pagamento disponíveis. Padrão ["PIX", "CARD"]. items: type: string enum: - PIX - CARD - BOLETO minItems: 1 default: ['PIX', 'CARD'] x-mint: hidden: true returnUrl: type: string format: uri description: >- URL para onde o cliente será redirecionado ao clicar em "Voltar" no checkout. x-mint: hidden: true completionUrl: type: string format: uri description: >- URL para onde o cliente será redirecionado após o pagamento ser concluído. x-mint: hidden: true customerId: type: string description: > ID de um cliente já cadastrado na sua loja. Se informado, o checkout será pré-preenchido com os dados deste cliente. **Exemplo**: `"cust_abcdefghij"` x-mint: hidden: true coupons: type: array description: | Lista de cupons que podem ser utilizados nesta cobrança. **Exemplo**: `["ABKT10", "ABKT5", "PROMO10"]` items: type: string maxItems: 50 x-mint: hidden: true externalId: type: string description: > ID da cobrança no seu sistema, caso queira manter uma referência própria. **Exemplo**: `"seu_id_123"` x-mint: hidden: true upSellProductId: type: string description: > ID de um produto avulso (sem `cycle`) a ser ofertado como upsell após a conclusão do pagamento. O produto deve estar com `status: ACTIVE` e **não pode ter `cycle`** — apenas produtos de pagamento único são aceitos. **Exemplo**: `"prod_bump456xyz"` x-mint: hidden: true dueDate: type: string format: date description: > Data de vencimento do boleto no formato `YYYY-MM-DD` (ex: `"2026-08-15"`). Opcional. Só é válido quando `methods` inclui `BOLETO`; ignorado nos demais métodos. Se omitido, o vencimento padrão é de 3 dias úteis. Não pode ser data no passado. Máximo de 365 dias no futuro. example: '2026-08-15' x-mint: hidden: true interest: description: >- Juros por atraso, aplicados apenas quando `methods` inclui `BOLETO`. Ignorado para PIX/CARD. allOf: - $ref: '#/components/schemas/BoletoInterest' x-mint: hidden: true fine: description: >- Multa por atraso, aplicada apenas quando `methods` inclui `BOLETO`. Ignorado para PIX/CARD. allOf: - $ref: '#/components/schemas/BoletoFine' x-mint: hidden: true metadata: type: object description: > Metadados adicionais da cobrança. Campo livre para a sua aplicação. **Exemplo**: ```json { "source": "landing-page-black-friday", "campaign": "BF-2025" } ``` additionalProperties: true x-mint: hidden: true card: type: object description: >- Configuração do pagamento por cartão. Só tem efeito quando `methods` inclui `CARD`. additionalProperties: false required: - maxInstallments properties: maxInstallments: type: integer description: Número máximo de parcelas oferecidas no checkout. minimum: 1 maximum: 12 example: 12 responses: '200': description: Cobrança criada com sucesso. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Billing' error: type: string nullable: true example: null success: $ref: '#/components/schemas/Success' '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string description: Motivo da falha na autenticação. example: Token de autenticação inválido ou ausente. /checkouts/get: get: summary: Buscar um Checkout description: > Retorna os dados de um Checkout específico usando o ID. Você pode usar essa rota para buscar um Checkout por ID e visualizar seus detalhes, status e informações relacionadas. security: - bearerAuth: [] parameters: - name: id in: query description: Identificador único do Checkout required: false schema: type: string example: bill_abc123xyz - name: externalId in: query description: Identificador do Checkout no seu sistema required: false schema: type: string example: pedido-123 - name: customerId in: query description: Identificador do cliente associado required: false schema: type: string example: cust_abc123xyz - name: method in: query description: Método de pagamento required: false schema: type: string enum: - PIX - CARD - BOLETO responses: '200': description: Cobrança encontrada com sucesso. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Billing' error: type: string nullable: true example: null success: $ref: '#/components/schemas/Success' '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro descrevendo o motivo da falha na autenticação. example: Token de autenticação inválido ou ausente. '404': description: Cobrança não encontrada. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro indicando que a cobrança não foi encontrada. example: Cobrança não encontrada. /checkouts/refund: post: summary: Reembolsar um Checkout description: > Reembolsa integralmente um Checkout pago (PIX ou Cartão). O valor reembolsado é igual ao valor original da transação — reembolsos parciais não são suportados. security: - bearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RefundRequest' responses: '200': description: Reembolso criado com sucesso. content: application/json: schema: $ref: '#/components/schemas/RefundResponse' '400': description: Reembolso recusado por regra de negócio. content: application/json: schema: $ref: '#/components/schemas/RefundError' '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string description: Motivo da falha na autenticação. example: Token de autenticação inválido ou ausente. /checkouts/delete: post: summary: Deletar um Checkout description: > Deleta um Checkout que ainda não foi pago. security: - bearerAuth: [] parameters: - name: id in: query description: Identificador único do Checkout required: true schema: type: string example: bill_abc123xyz responses: '200': description: Checkout deletado com sucesso. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Billing' error: type: string nullable: true example: null success: $ref: '#/components/schemas/Success' '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro descrevendo o motivo da falha na autenticação. example: Token de autenticação inválido ou ausente. /payment-links/create: post: summary: Criar um link de pagamento description: > Cria um link de pagamento (checkout com frequency MULTIPLE_PAYMENTS). Vários clientes podem pagar o mesmo link; não suporta customerId. security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - items additionalProperties: false example: items: - id: prod-1234 quantity: 2 methods: ['PIX', 'CARD'] properties: items: type: array description: > Lista de itens incluídos na cobrança. Este é o único campo obrigatório — o valor total é calculado a partir destes itens. minItems: 1 items: type: object additionalProperties: false required: - id - quantity properties: id: type: string description: ID público do produto na sua loja. example: prod-1234 quantity: type: integer description: Quantidade deste item. minimum: 1 example: 2 methods: type: array description: Métodos de pagamento disponíveis. Padrão ["PIX", "CARD"]. items: type: string enum: - PIX - CARD - BOLETO minItems: 1 default: ['PIX', 'CARD'] x-mint: hidden: true returnUrl: type: string format: uri description: >- URL para onde o cliente será redirecionado ao clicar em "Voltar" no checkout. x-mint: hidden: true completionUrl: type: string format: uri description: >- URL para onde o cliente será redirecionado após o pagamento ser concluído. x-mint: hidden: true coupons: type: array description: | Lista de cupons que podem ser utilizados nesta cobrança. **Exemplo**: `["ABKT10", "ABKT5", "PROMO10"]` items: type: string maxItems: 50 x-mint: hidden: true externalId: type: string description: > ID da cobrança no seu sistema, caso queira manter uma referência própria. **Exemplo**: `"seu_id_123"` x-mint: hidden: true dueDate: type: string format: date description: > Data de vencimento do boleto no formato `YYYY-MM-DD` (ex: `"2026-08-15"`). Opcional. Só é válido quando `methods` inclui `BOLETO`; ignorado nos demais métodos. Se omitido, o vencimento padrão é de 3 dias úteis. Não pode ser data no passado. Máximo de 365 dias no futuro. example: '2026-08-15' x-mint: hidden: true interest: description: >- Juros por atraso, aplicados apenas quando `methods` inclui `BOLETO`. Ignorado para PIX/CARD. allOf: - $ref: '#/components/schemas/BoletoInterest' x-mint: hidden: true fine: description: >- Multa por atraso, aplicada apenas quando `methods` inclui `BOLETO`. Ignorado para PIX/CARD. allOf: - $ref: '#/components/schemas/BoletoFine' x-mint: hidden: true metadata: type: object description: > Metadados adicionais da cobrança. Campo livre para a sua aplicação. **Exemplo**: ```json { "source": "landing-page-black-friday", "campaign": "BF-2025" } ``` additionalProperties: true x-mint: hidden: true card: type: object description: >- Configuração do pagamento por cartão. Só tem efeito quando `methods` inclui `CARD`. additionalProperties: false required: - maxInstallments properties: maxInstallments: type: integer description: Número máximo de parcelas oferecidas no checkout. minimum: 1 maximum: 12 example: 12 customerId: type: string description: > ID de um cliente já cadastrado na sua loja. Se informado, o checkout será pré-preenchido com os dados deste cliente. **Exemplo**: `"cust_abcdefghij"` x-mint: hidden: true upSellProductId: type: string description: > ID de um produto avulso (sem `cycle`) a ser ofertado como upsell após a conclusão do pagamento. O produto deve estar com `status: ACTIVE` e **não pode ter `cycle`** — apenas produtos de pagamento único são aceitos. **Exemplo**: `"prod_bump456xyz"` x-mint: hidden: true responses: '200': description: Link de pagamento criado com sucesso. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Billing' error: type: string nullable: true example: null success: $ref: '#/components/schemas/Success' '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro descrevendo o motivo da falha na autenticação. example: Token de autenticação inválido ou ausente. /checkouts/list: get: summary: Listar Checkouts description: > Retorna todos os Checkouts que você criou. Você pode usar essa rota para listar todos seus Checkouts e visualizar seus status, valores e informações relacionadas. security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/QueryAfter' - $ref: '#/components/parameters/QueryBefore' - $ref: '#/components/parameters/QueryLimit' - $ref: '#/components/parameters/QueryStartDate' - $ref: '#/components/parameters/QueryEndDate' - name: id in: query description: Filtrar por identificador único do Checkout required: false schema: type: string example: bill_abc123xyz - name: externalId in: query description: Filtrar por identificador do Checkout no seu sistema required: false schema: type: string example: pedido-123 - name: status in: query description: Filtrar por status do Checkout required: false schema: type: string enum: - PENDING - EXPIRED - CANCELLED - PAID - REFUNDED - name: keyword in: query description: Busca textual livre required: false schema: type: string - name: customerId in: query description: Filtrar pelo identificador do cliente associado required: false schema: type: string example: cust_abc123xyz - name: method in: query description: Filtrar por método de pagamento required: false schema: type: string enum: - PIX - CARD - BOLETO responses: '200': description: Checkouts listados com sucesso. content: application/json: schema: type: object properties: data: type: array description: Lista de Checkouts. items: $ref: '#/components/schemas/Billing' success: $ref: '#/components/schemas/Success' error: type: string nullable: true example: null pagination: $ref: '#/components/schemas/PaginationCursor' '401': description: Falha na autenticação. content: application/json: schema: type: object properties: error: type: string example: Token de autenticação inválido ou ausente. /payment-links/list: get: summary: Listar links de pagamento description: > Lista apenas links de pagamento (checkouts com frequency MULTIPLE_PAYMENTS). security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/QueryAfter' - $ref: '#/components/parameters/QueryBefore' - $ref: '#/components/parameters/QueryLimit' - $ref: '#/components/parameters/QueryStartDate' - $ref: '#/components/parameters/QueryEndDate' - name: id in: query description: Filtrar por identificador único do link de pagamento required: false schema: type: string example: bill_abc123xyz - name: externalId in: query description: Filtrar por identificador do link no seu sistema required: false schema: type: string example: pedido-123 - name: status in: query description: Filtrar por status do link de pagamento required: false schema: type: string enum: - PENDING - EXPIRED - CANCELLED - PAID - REFUNDED - name: keyword in: query description: Busca textual livre required: false schema: type: string - name: customerId in: query description: Filtrar pelo identificador do cliente associado required: false schema: type: string example: cust_abc123xyz - name: method in: query description: Filtrar por método de pagamento required: false schema: type: string enum: - PIX - CARD - BOLETO responses: '200': description: Links de pagamento listados com sucesso. content: application/json: schema: type: object properties: data: type: array description: Lista de links de pagamento. items: $ref: '#/components/schemas/Billing' success: $ref: '#/components/schemas/Success' error: type: string nullable: true example: null pagination: $ref: '#/components/schemas/PaginationCursor' '401': description: Falha na autenticação. content: application/json: schema: type: object properties: error: type: string example: Token de autenticação inválido ou ausente. /payment-links/get: get: summary: Buscar um link de pagamento description: > Retorna os dados de um link de pagamento específico (checkout com frequency MULTIPLE_PAYMENTS) usando o ID. security: - bearerAuth: [] parameters: - name: id in: query description: Identificador único do link de pagamento required: false schema: type: string example: bill_abc123xyz - name: externalId in: query description: Identificador do Checkout no seu sistema required: false schema: type: string example: pedido-123 - name: customerId in: query description: Identificador do cliente associado required: false schema: type: string example: cust_abc123xyz - name: method in: query description: Método de pagamento required: false schema: type: string enum: - PIX - CARD - BOLETO responses: '200': description: Link de pagamento encontrado com sucesso. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Billing' error: type: string nullable: true example: null success: $ref: '#/components/schemas/Success' '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro descrevendo o motivo da falha na autenticação. example: Token de autenticação inválido ou ausente. '404': description: Link de pagamento não encontrado. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro indicando que o link de pagamento não foi encontrado. example: Link de pagamento não encontrado. /payment-links/refund: post: summary: Reembolsar pagamento de link description: > Reembolsa um pagamento realizado em um link de pagamento. O valor reembolsado é igual ao valor original da transação — reembolsos parciais não são suportados. security: - bearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RefundRequest' responses: '200': description: Reembolso criado com sucesso. content: application/json: schema: $ref: '#/components/schemas/RefundResponse' '400': description: Reembolso recusado por regra de negócio. content: application/json: schema: $ref: '#/components/schemas/RefundError' '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string description: Motivo da falha na autenticação. example: Token de autenticação inválido ou ausente. /payment-links/delete: post: summary: Deletar um link de pagamento description: > Deleta um link de pagamento que ainda não foi pago. security: - bearerAuth: [] parameters: - name: id in: query description: Identificador único do link de pagamento required: true schema: type: string example: bill_abc123xyz responses: '200': description: Link de pagamento deletado com sucesso. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Billing' error: type: string nullable: true example: null success: $ref: '#/components/schemas/Success' '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro descrevendo o motivo da falha na autenticação. example: Token de autenticação inválido ou ausente. /transparents/create: post: summary: Criar Checkout Transparente description: >- Cria um checkout transparente. Use `"method": "PIX"` para gerar um QR Code ou `"method": "BOLETO"` para emitir um boleto com PIX alternativo incluído. security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object properties: method: type: string description: Método de pagamento. enum: - PIX - BOLETO default: PIX example: PIX data: type: object description: Dados da cobrança. properties: amount: type: number description: Valor da cobrança em centavos. expiresIn: type: number description: > PIX — tempo de expiração em segundos. Não se aplica a `method: "BOLETO"` (use `dueDate`). x-mint: hidden: true dueDate: type: string format: date description: > BOLETO — data de vencimento no formato `YYYY-MM-DD` (ex: `"2026-08-15"`). Opcional. Se omitido, o vencimento padrão é de 3 dias úteis. Não pode ser data no passado. Máximo de 365 dias no futuro. Ignorado quando `method` é `PIX`. example: '2026-08-15' x-mint: hidden: true description: type: string maxLength: 500 description: Descrição da cobrança. x-mint: hidden: true customer: type: object description: > Dados do pagador. Obrigatório para BOLETO (`name` e `taxId` sempre exigidos). Para PIX, se informado, todos os campos são obrigatórios. required: - name - taxId additionalProperties: false x-mint: hidden: true properties: name: type: string example: Daniel Lima taxId: type: string example: 123.456.789-01 email: type: string example: daniel_lima@abacatepay.com cellphone: type: string example: (11) 4002-8922 externalId: type: string description: ID no seu sistema para idempotência. x-mint: hidden: true interest: description: >- BOLETO — juros por atraso. Ignorado quando `method` é `PIX`. allOf: - $ref: '#/components/schemas/BoletoInterest' x-mint: hidden: true fine: description: >- BOLETO — multa por atraso. Ignorado quando `method` é `PIX`. allOf: - $ref: '#/components/schemas/BoletoFine' x-mint: hidden: true metadata: type: object additionalProperties: true x-mint: hidden: true utm: description: >- Parâmetros opcionais de campanha (UTM). Objeto e campos internos opcionais; valores enviados podem ser vistos no dashboard. allOf: - $ref: '#/components/schemas/TransparentCreateUtm' required: - amount additionalProperties: false required: - method - data additionalProperties: false responses: '200': description: Checkout transparente criado com sucesso content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/TransparentCharge' error: type: string example: null nullable: true success: $ref: '#/components/schemas/Success' example: data: id: bole_k8pqr2mnvx amount: 5000 status: PENDING devMode: false barCode: 23793.38128 60007.827263 37000.963779 4 10010000005000 url: https://app.abacatepay.com/pay/bole_k8pqr2mnvx/boleto brCode: 00020126580014BR.GOV.BCB.PIX0136d2b4e5f6-7890-abcd-ef12-34567890abcd5204000053039865802BR5914Mariana Costa6009SAO PAULO62070503***6304F1C2 brCodeBase64: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA... platformFee: 250 receiptUrl: null expiresAt: '2026-08-16T02:59:59.999Z' createdAt: '2026-07-27T14:22:10.381Z' updatedAt: '2026-07-27T14:22:10.381Z' metadata: faturaId: fatura-456 plano: pro error: null success: message: Checkout transparente criado com sucesso '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string example: Token de autenticação inválido ou ausente. /transparents/get: get: summary: Buscar um Checkout Transparente description: > Retorna os dados de um Checkout Transparente específico usando o ID. security: - bearerAuth: [] parameters: - name: id in: query description: Identificador único do Checkout Transparente required: true schema: type: string example: pix_char_z2rSk6042t1mCKgGgeBpJe1u responses: '200': description: Checkout Transparente encontrado com sucesso. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/PixQRCode' error: type: string nullable: true example: null success: $ref: '#/components/schemas/Success' '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro descrevendo o motivo da falha na autenticação. example: Token de autenticação inválido ou ausente. /transparents/check: get: summary: Checar Status description: Checar status do pagamento do QRCode Pix. security: - bearerAuth: [] responses: '200': description: Status retornado content: application/json: schema: type: object properties: data: type: object properties: id: type: string description: Identificador único do Checkout Transparente. example: pix_char_z2rSk6042t1mCKgGgeBpJe1u status: type: string description: Informação sobre o andamento do QRCode Pix. enum: - PENDING - EXPIRED - CANCELLED - PAID - UNDER_DISPUTE - REFUNDED - REDEEMED - APPROVED - FAILED example: PENDING expiresAt: type: string description: Data de expiração do QRCode Pix example: '2026-03-04T15:48:59.876Z' error: type: string example: null nullable: true success: $ref: '#/components/schemas/Success' '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro descrevendo o motivo da falha na autenticação. example: Token de autenticação inválido ou ausente. parameters: - name: id in: query description: Identificador único do Checkout Transparente required: true schema: type: string /transparents/simulate-payment: post: summary: Simular Pagamento description: Simula o pagamento de um QRCode Pix criado no modo de desenvolvimento. security: - bearerAuth: [] responses: '200': description: Pagamento ralizado com sucesso content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/PixQRCode' error: type: string example: null nullable: true success: $ref: '#/components/schemas/Success' '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro descrevendo o motivo da falha na autenticação. example: Token de autenticação inválido ou ausente. parameters: - name: id in: query description: Identificador único do Checkout Transparente required: true schema: type: string /transparents/list: get: summary: Listar Checkouts Transparentes description: > Retorna todos os Checkouts Transparentes (QRCodes PIX) que você criou. Você pode usar essa rota para listar todos os seus checkouts transparentes e visualizar seus status, valores e informações relacionadas. security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/QueryAfter' - $ref: '#/components/parameters/QueryBefore' - $ref: '#/components/parameters/QueryLimit' - $ref: '#/components/parameters/QueryStartDate' - $ref: '#/components/parameters/QueryEndDate' - name: id in: query description: Filtrar por identificador único do QRCode Pix required: false schema: type: string example: pix_char_123456 - name: status in: query description: Filtrar por status do QRCode Pix required: false schema: type: string enum: - PENDING - EXPIRED - CANCELLED - PAID - REFUNDED - name: externalId in: query description: Filtrar por identificador do Checkout Transparente no seu sistema required: false schema: type: string - name: method in: query description: Filtrar por método de pagamento required: false schema: type: string enum: - PIX - CARD - PIX_QRCODE - BOLETO responses: '200': description: Checkouts transparentes listados com sucesso. content: application/json: schema: type: object properties: data: type: array description: Lista de Checkouts Transparentes (QRCodes PIX). items: $ref: '#/components/schemas/PixQRCode' success: $ref: '#/components/schemas/Success' error: type: string nullable: true example: null pagination: $ref: '#/components/schemas/PaginationCursor' '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro descrevendo o motivo da falha na autenticação. example: Token de autenticação inválido ou ausente. /transparents/refund: post: summary: Reembolsar Checkout Transparente description: > Reembolsa integralmente um pagamento transparente (PIX ou Cartão). O valor reembolsado é igual ao valor original da transação — reembolsos parciais não são suportados. security: - bearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RefundRequest' responses: '200': description: Reembolso criado com sucesso. content: application/json: schema: $ref: '#/components/schemas/RefundResponse' '400': description: Reembolso recusado por regra de negócio. content: application/json: schema: $ref: '#/components/schemas/RefundError' '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string description: Motivo da falha na autenticação. example: Token de autenticação inválido ou ausente. /payouts/create: post: summary: Criar um payout description: > Permite que você crie um novo payout para transferir valores da sua conta AbacatePay. Você pode usar esta rota para: - **Realizar saques** da sua conta para sua própria chave PIX - **Enviar dinheiro** para outras contas - **Realizar pagamentos** diretamente pela API - **Efetuar transferências** para fornecedores, parceiros ou terceiros **Importante**: A chave PIX de destino não precisa ter a mesma titularidade do CNPJ da sua conta. Você pode realizar payouts para qualquer chave PIX válida. security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object description: Dados necessários para criar um payout. required: - amount - externalId - pix additionalProperties: false example: amount: 10000 externalId: saque-123 pix: {key: '11987654321', type: PHONE} properties: amount: type: number description: Valor do payout em centavos. minimum: 350 example: 10000 description: type: string description: Descrição opcional do payout. example: Saque para conta bancária x-mint: hidden: true externalId: type: string description: Identificador único do payout em seu sistema. example: saque-123 pix: type: object description: Chave PIX de destino do payout. required: - key - type additionalProperties: false properties: key: type: string description: Chave PIX de destino. example: '11987654321' type: type: string description: Tipo da chave PIX. enum: - CPF - CNPJ - PHONE - EMAIL - RANDOM - BR_CODE example: PHONE responses: '200': description: Payout criado com sucesso. content: application/json: schema: type: object properties: data: type: object description: Dados da transação de payout criada. properties: id: type: string description: Identificador único da transação. example: txn_abc123xyz status: type: string description: Status atual da transação. enum: - PENDING - EXPIRED - CANCELLED - COMPLETE - REFUNDED example: PENDING devMode: type: boolean description: >- Indica se a transação foi criada em ambiente de testes. example: false receiptUrl: type: string format: uri nullable: true description: URL do comprovante da transação. example: null amount: type: number description: Valor da transação em centavos. example: 10000 platformFee: type: number description: Taxa da plataforma em centavos. example: 100 externalId: type: string description: Identificador externo da transação. example: saque-123 createdAt: type: string format: date-time description: Data de criação da transação. example: '2024-11-04T18:38:28.573Z' updatedAt: type: string format: date-time description: Data de atualização da transação. example: '2024-11-04T18:38:28.573Z' error: type: string nullable: true example: null success: $ref: '#/components/schemas/Success' '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro descrevendo o motivo da falha na autenticação. example: Token de autenticação inválido ou ausente. /payouts/get: get: summary: Buscar payout description: >- Permite que você recupere os detalhes de um payout específico usando o externalId. security: - bearerAuth: [] parameters: - name: externalId in: query description: Identificador único do payout em seu sistema. required: false schema: type: string example: saque-123 - name: id in: query description: Identificador único do payout required: false schema: type: string example: payout_abc123xyz responses: '200': description: Detalhes do payout retornados com sucesso. content: application/json: schema: type: object properties: data: type: object description: Dados da transação de payout. properties: id: type: string description: Identificador único da transação. example: txn_abc123xyz status: type: string description: Status atual da transação. enum: - PENDING - EXPIRED - CANCELLED - COMPLETE - REFUNDED example: COMPLETE devMode: type: boolean description: >- Indica se a transação foi criada em ambiente de testes. example: false receiptUrl: type: string format: uri nullable: true description: URL do comprovante da transação. example: 'https://app.abacatepay.com/receipt/txn_abc123xyz' amount: type: number description: Valor da transação em centavos. example: 10000 platformFee: type: number description: Taxa da plataforma em centavos. example: 100 externalId: type: string description: Identificador externo da transação. example: saque-123 createdAt: type: string format: date-time description: Data de criação da transação. example: '2024-11-04T18:38:28.573Z' updatedAt: type: string format: date-time description: Data de atualização da transação. example: '2024-11-04T19:15:42.123Z' error: type: string nullable: true example: null success: $ref: '#/components/schemas/Success' '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro descrevendo o motivo da falha na autenticação. example: Token de autenticação inválido ou ausente. '404': description: Saque não encontrado. content: application/json: schema: type: object properties: data: type: string nullable: true example: null error: type: string description: Mensagem de erro indicando que o saque não foi encontrado. example: Saque não encontrado com o externalId fornecido. /payouts/list: get: summary: Listar payouts description: > Permite que você recupere uma lista de todos os payouts criados com suporte a paginação. security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/QueryAfter' - $ref: '#/components/parameters/QueryBefore' - $ref: '#/components/parameters/QueryLimit' - $ref: '#/components/parameters/QueryStartDate' - $ref: '#/components/parameters/QueryEndDate' - name: id in: query description: Filtrar por identificador único da transação required: false schema: type: string example: tran_123456 responses: '200': description: Lista de payouts retornada com sucesso. content: application/json: schema: type: object properties: data: type: array description: Lista de saques criados. items: $ref: '#/components/schemas/Transaction' success: $ref: '#/components/schemas/Success' error: type: string nullable: true example: null pagination: $ref: '#/components/schemas/PaginationCursor' '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro descrevendo o motivo da falha na autenticação. example: Token de autenticação inválido ou ausente. /pix/send: post: summary: Enviar PIX description: > Permite que você envie dinheiro via PIX para qualquer chave PIX que não seja do titular da conta. Você pode usar esta rota para: - **Enviar pagamentos** para fornecedores, parceiros ou terceiros - **Realizar transferências** para contas de outras pessoas ou empresas - **Efetuar pagamentos** diretamente pela API **Importante**: Esta funcionalidade é diferente dos payouts, pois permite enviar dinheiro para chaves PIX que não pertencem ao titular da conta. Use payouts quando quiser enviar para sua própria chave PIX. security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object description: Dados necessários para enviar um PIX. required: - amount - externalId - pix additionalProperties: false example: amount: 10000 externalId: pix-123 description: Pagamento para fornecedor pix: key: '11987654321' type: PHONE properties: amount: type: number description: Valor do PIX em centavos. minimum: 100 example: 10000 externalId: type: string description: Identificador único do PIX em seu sistema. example: pix-123 description: type: string description: Descrição opcional do PIX. example: Pagamento para fornecedor x-mint: hidden: true pix: type: object description: Dados da chave PIX de destino. required: - key - type additionalProperties: false properties: key: type: string description: Chave PIX de destino. example: '11987654321' type: type: string description: Tipo da chave PIX. enum: - CPF - CNPJ - PHONE - EMAIL - RANDOM - BR_CODE example: PHONE responses: '200': description: PIX enviado com sucesso. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/PixTransaction' error: type: string nullable: true example: null success: $ref: '#/components/schemas/Success' '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro descrevendo o motivo da falha na autenticação. example: Token de autenticação inválido ou ausente. /pix/get: get: summary: Buscar PIX description: > Permite que você recupere os detalhes de uma transação PIX específica usando o ID ou externalId. Você pode buscar usando: - `id`: Identificador único da transação PIX na AbacatePay - `externalId`: Identificador único do PIX em seu sistema **Importante**: Você deve fornecer pelo menos um dos parâmetros (`id` ou `externalId`). security: - bearerAuth: [] parameters: - name: id in: query description: Identificador único da transação PIX na AbacatePay. required: true schema: type: string example: txn_abc123xyz - name: externalId in: query description: Identificador único do PIX em seu sistema. required: false schema: type: string example: pix-123 responses: '200': description: Detalhes do PIX retornados com sucesso. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/PixTransaction' error: type: string nullable: true example: null success: $ref: '#/components/schemas/Success' '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro descrevendo o motivo da falha na autenticação. example: Token de autenticação inválido ou ausente. '404': description: PIX não encontrado. content: application/json: schema: type: object properties: data: type: string nullable: true example: null error: type: string description: Mensagem de erro indicando que o PIX não foi encontrado. example: PIX não encontrado com o ID ou externalId fornecido. /pix/list: get: summary: Listar PIX description: | Consulta um envio de PIX pelo `id`. Apesar do nome, esta rota não pagina nem aceita filtros: `id` é obrigatório e o contrato é o mesmo de `/pix/get`. security: - bearerAuth: [] parameters: - name: id in: query description: Identificador único do PIX enviado required: true schema: type: string example: pix_out_abc123xyz - name: externalId in: query description: Identificador do PIX no seu sistema required: false schema: type: string example: pix-123 responses: '200': description: Lista de PIX retornada com sucesso. content: application/json: schema: type: object properties: data: type: array description: Lista de transações PIX criadas. items: $ref: '#/components/schemas/PixTransaction' success: $ref: '#/components/schemas/Success' error: type: string nullable: true example: null pagination: $ref: '#/components/schemas/PaginationCursor' '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro descrevendo o motivo da falha na autenticação. example: Token de autenticação inválido ou ausente. /subscriptions/create: post: summary: Criar uma nova assinatura (Checkout de assinatura) description: > Cria um Checkout de assinatura — uma página de pagamento igual ao Checkout comum, mas para cobrança recorrente. Aceita os mesmos parâmetros do Checkout (`returnUrl`, `completionUrl`, `customerId`, `externalId`, `metadata`, `coupons`, `methods`). O Checkout de assinatura aceita **apenas um produto**; o ciclo (frequência) já deve estar definido no produto ao criá-lo na loja — não é enviado no checkout. security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object description: > Mesmos parâmetros do Checkout, com `items` contendo exatamente um item (`id` e `quantity`). O produto referenciado deve ter sido criado com ciclo de assinatura (frequency) na loja. required: - items additionalProperties: false example: items: - id: prod-1234 quantity: 1 customerId: cust_abc123xyz methods: ['CARD'] properties: items: type: array description: > Lista com **exatamente um** item. O produto deve ter sido criado com ciclo de assinatura (frequency). O valor total é calculado a partir do produto. minItems: 1 maxItems: 1 items: type: object required: - id - quantity additionalProperties: false properties: id: type: string description: >- ID público do produto na sua loja (produto criado com ciclo de assinatura). example: prod-1234 quantity: type: integer description: Quantidade (geralmente 1 para assinatura). minimum: 1 example: 1 methods: type: array description: Métodos de pagamento disponíveis. Assinaturas suportam apenas CARD. Padrão ["CARD"]. items: type: string enum: - PIX - CARD minItems: 1 default: ['CARD'] returnUrl: type: string format: uri description: >- URL para onde o cliente será redirecionado ao clicar em "Voltar" no checkout. completionUrl: type: string format: uri description: >- URL para onde o cliente será redirecionado após o pagamento ser concluído. customerId: type: string description: > ID de um cliente já cadastrado na sua loja. Se informado, o checkout será pré-preenchido com os dados deste cliente. coupons: type: array description: Lista de cupons que podem ser utilizados nesta cobrança. items: type: string maxItems: 50 externalId: type: string description: >- ID da assinatura no seu sistema, caso queira manter uma referência própria. metadata: type: object description: Metadados adicionais. Campo livre para a sua aplicação. additionalProperties: true card: type: object description: >- Configuração do pagamento por cartão. Só tem efeito quando `methods` inclui `CARD`. additionalProperties: false required: - maxInstallments properties: maxInstallments: type: integer description: Número máximo de parcelas oferecidas no checkout. minimum: 1 maximum: 12 example: 12 upSellProductId: type: string description: > ID de um produto avulso (sem `cycle`) a ser ofertado como upsell após a conclusão do pagamento. O produto deve estar com `status: ACTIVE` e **não pode ter `cycle`** — apenas produtos de pagamento único são aceitos. **Exemplo**: `"prod_bump456xyz"` x-mint: hidden: true dueDate: type: string format: date description: > Data de vencimento do boleto no formato `YYYY-MM-DD` (ex: `"2026-08-15"`). Opcional. Só é válido quando `methods` inclui `BOLETO`; ignorado nos demais métodos. Se omitido, o vencimento padrão é de 3 dias úteis. Não pode ser data no passado. Máximo de 365 dias no futuro. example: '2026-08-15' x-mint: hidden: true interest: description: >- Juros por atraso, aplicados apenas quando `methods` inclui `BOLETO`. Ignorado para PIX/CARD. allOf: - $ref: '#/components/schemas/BoletoInterest' x-mint: hidden: true fine: description: >- Multa por atraso, aplicada apenas quando `methods` inclui `BOLETO`. Ignorado para PIX/CARD. allOf: - $ref: '#/components/schemas/BoletoFine' x-mint: hidden: true retryPolicy: type: object description: >- Política de novas tentativas quando uma cobrança da assinatura falha. Se omitida, a assinatura usa 3 tentativas com 1 dia de intervalo. additionalProperties: false properties: maxRetry: type: integer description: >- Número máximo de tentativas de cobrança antes de a assinatura ser cancelada automaticamente. minimum: 1 maximum: 10 default: 3 example: 3 retryEvery: type: integer description: Dias entre cada tentativa. minimum: 1 maximum: 30 default: 1 example: 1 responses: '200': description: >- Checkout de assinatura criado com sucesso. Use a `url` retornada para redirecionar o cliente. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Billing' error: type: string nullable: true example: null success: $ref: '#/components/schemas/Success' '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro descrevendo o motivo da falha na autenticação. example: Token de autenticação inválido ou ausente. /subscriptions/list: get: summary: Listar assinaturas (Checkouts de assinatura) description: > Retorna todos os Checkouts de assinatura que você criou, com suporte a paginação baseada em cursor. Cada item possui o mesmo formato de um Checkout: `id`, `url`, `amount`, `items`, `status`, etc. security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/QueryAfter' - $ref: '#/components/parameters/QueryBefore' - $ref: '#/components/parameters/QueryLimit' - $ref: '#/components/parameters/QueryStartDate' - $ref: '#/components/parameters/QueryEndDate' - name: status in: query description: Filtrar por status do Checkout de assinatura required: false schema: type: string enum: - PENDING - EXPIRED - CANCELLED - PAID - REFUNDED responses: '200': description: Lista de Checkouts de assinatura retornada com sucesso. content: application/json: schema: type: object properties: data: type: array description: >- Lista de Checkouts de assinatura (mesmo payload de Checkout). items: $ref: '#/components/schemas/Billing' success: $ref: '#/components/schemas/Success' error: type: string nullable: true example: null pagination: $ref: '#/components/schemas/PaginationCursor' '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro descrevendo o motivo da falha na autenticação. example: Token de autenticação inválido ou ausente. /subscriptions/get: get: summary: Buscar uma assinatura description: > Retorna os dados de uma assinatura específica. Aceita os mesmos filtros de `/checkouts/get`, todos opcionais. security: - bearerAuth: [] parameters: - name: id in: query description: Identificador único da assinatura required: false schema: type: string example: bill_abc123xyz - name: externalId in: query description: Identificador da assinatura no seu sistema required: false schema: type: string example: assinatura-123 - name: customerId in: query description: Identificador do cliente associado required: false schema: type: string example: cust_abc123xyz - name: method in: query description: Método de pagamento required: false schema: type: string enum: - PIX - CARD responses: '200': description: Assinatura encontrada com sucesso. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Billing' error: type: string nullable: true example: null success: $ref: '#/components/schemas/Success' '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro descrevendo o motivo da falha na autenticação. example: Token de autenticação inválido ou ausente. /subscriptions/cancel: post: summary: Cancelar uma assinatura description: | Cancela imediatamente uma assinatura ativa. A assinatura passa para o status `CANCELLED` e nenhuma cobrança futura será gerada. Esta operação é irreversível. security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - id additionalProperties: false properties: id: type: string description: Identificador único da assinatura a ser cancelada example: subs_abc123xyz responses: '200': description: Assinatura cancelada com sucesso. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Subscription' error: type: string nullable: true example: null success: $ref: '#/components/schemas/Success' '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro descrevendo o motivo da falha na autenticação. example: Token de autenticação inválido ou ausente. '404': description: Assinatura não encontrada. content: application/json: schema: type: object properties: error: type: string description: Mensagem de erro indicando que a assinatura não foi encontrada. example: Subscription not found /subscriptions/change-plan: post: summary: Alterar plano da assinatura description: | Altera o produto principal de uma assinatura ativa. A mudança é agendada como `PENDING` e aplicada automaticamente no início do próximo ciclo de cobrança. Só pode existir uma alteração pendente por assinatura — uma nova chamada substitui a anterior ainda não aplicada. O produto informado em `productId` deve ter um ciclo de cobrança definido. Produtos avulsos (sem ciclo) retornam erro. security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - id additionalProperties: false properties: id: type: string description: Identificador único da assinatura a ser alterada. example: subs_abc123xyz productId: type: string description: Identificador do novo produto. Deve ter ciclo de cobrança definido. example: prod_plano_pro quantity: type: integer minimum: 1 description: Quantidade do novo produto. example: 1 items: type: array description: >- Lista de produtos do novo plano. Alternativa a `productId`/`quantity` quando a assinatura passa a ter mais de um produto. minItems: 1 items: type: object additionalProperties: false required: - productId - quantity properties: productId: type: string example: prod_abc123xyz quantity: type: integer minimum: 1 example: 1 responses: '200': description: Alteração de plano agendada com sucesso. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/SubscriptionUpdate' error: type: string nullable: true example: null success: $ref: '#/components/schemas/Success' '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string example: Token de autenticação inválido ou ausente. '404': description: Assinatura ou produto não encontrado. content: application/json: schema: type: object properties: error: type: string example: Subscription not found or not active '422': description: 'Dados inválidos (ex: produto sem ciclo).' content: application/json: schema: type: object properties: error: type: string example: Product must have a billing cycle /subscriptions/record-usage: post: summary: Registrar uso description: | Registra unidades de uso de um produto avulso (pay-as-you-go) em uma assinatura ativa. O registro é vinculado à próxima parcela pendente da assinatura e incluído na cobrança do ciclo atual. Use `action: "add"` para acrescentar unidades e `action: "subtract"` para estornar unidades já registradas. O produto informado em `productId` **não** deve ter ciclo de cobrança. Produtos de assinatura (com ciclo) retornam erro. security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - id - productId - units - action additionalProperties: false properties: id: type: string description: Identificador único da assinatura. example: subs_abc123xyz productId: type: string description: Identificador do produto de uso. Não deve ter ciclo de cobrança. example: prod_api_calls units: type: integer minimum: 1 description: Quantidade de unidades a registrar. example: 50 action: type: string enum: - add - subtract description: >- `add` para acrescentar unidades à próxima cobrança; `subtract` para estornar unidades já registradas no ciclo. example: add responses: '200': description: Uso registrado com sucesso. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/SubscriptionUsageRecord' error: type: string nullable: true example: null success: $ref: '#/components/schemas/Success' '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string example: Token de autenticação inválido ou ausente. '404': description: Assinatura ou produto não encontrado. content: application/json: schema: type: object properties: error: type: string example: Subscription not found or not active '422': description: 'Dados inválidos (ex: produto com ciclo enviado em vez de produto avulso).' content: application/json: schema: type: object properties: error: type: string example: Product must not have a billing cycle /stores/get: get: summary: Obter detalhes da loja description: >- Permite que você recupere os detalhes da sua conta/loja, incluindo informações de saldo. security: - bearerAuth: [] responses: '200': description: Detalhes da loja retornados com sucesso. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Store' error: type: string nullable: true example: null success: $ref: '#/components/schemas/Success' '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro descrevendo o motivo da falha na autenticação. example: Token de autenticação inválido ou ausente. /stores/list: get: summary: Listar lojas description: > Retorna as lojas visíveis para a sua chave de API. security: - bearerAuth: [] parameters: - $ref: '#/components/parameters/QueryAfter' - $ref: '#/components/parameters/QueryBefore' - $ref: '#/components/parameters/QueryLimit' - $ref: '#/components/parameters/QueryStartDate' - $ref: '#/components/parameters/QueryEndDate' - name: id in: query description: Filtrar por identificador único da loja required: false schema: type: string - name: name in: query description: Filtrar por nome da loja required: false schema: type: string responses: '200': description: Lojas listadas com sucesso. content: application/json: schema: type: object properties: data: type: array description: Lista de lojas. items: $ref: '#/components/schemas/Store' success: $ref: '#/components/schemas/Success' error: type: string nullable: true example: null pagination: $ref: '#/components/schemas/PaginationCursor' '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro descrevendo o motivo da falha na autenticação. example: Token de autenticação inválido ou ausente. /public-mrr/merchant-info: get: summary: Obter informações do merchant description: >- Retorna informações básicas da loja (ID, nome, website e data de criação). security: - bearerAuth: [] responses: '200': description: Informações do merchant retornadas com sucesso. content: application/json: schema: type: object properties: data: type: object properties: id: type: string description: Identificador único da loja example: store_abc123xyz name: type: string description: Nome da loja example: Example Tech website: type: string description: Website da loja example: 'https://www.example.com' createdAt: type: string format: date-time description: Data de criação da loja example: '2024-12-06T18:53:31.756Z' required: - id - name - website - createdAt additionalProperties: false error: type: string nullable: true example: null success: $ref: '#/components/schemas/Success' '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro descrevendo o motivo da falha na autenticação. example: Token de autenticação inválido ou ausente. /public-mrr/mrr: get: summary: Obter MRR (Monthly Recurring Revenue) description: >- Retorna o MRR (receita recorrente mensal) e o total de assinaturas ativas da loja. security: - bearerAuth: [] responses: '200': description: Dados de MRR retornados com sucesso. content: application/json: schema: type: object properties: data: type: object properties: mrr: type: number description: >- Receita recorrente mensal em centavos. Valor 0 indica que não há receita recorrente no momento. example: 0 totalActiveSubscriptions: type: integer description: >- Total de assinaturas ativas. Valor 0 indica que não há assinaturas ativas no momento. example: 0 required: - mrr - totalActiveSubscriptions additionalProperties: false error: type: string nullable: true example: null success: $ref: '#/components/schemas/Success' '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro descrevendo o motivo da falha na autenticação. example: Token de autenticação inválido ou ausente. /public-mrr/revenue: get: summary: Obter receita por período description: >- Retorna a receita total, total de transações e transações por dia em um período específico. Os dados são cacheados por 1 hora (3600 segundos) para melhor performance. A data de fim deve ser posterior à data de início. security: - bearerAuth: [] parameters: - name: startDate in: query required: true description: Data de início do período (formato YYYY-MM-DD) schema: type: string format: date example: '2024-01-01' - name: endDate in: query required: true description: Data de fim do período (formato YYYY-MM-DD) schema: type: string format: date example: '2024-01-31' responses: '200': description: Dados de receita retornados com sucesso. content: application/json: schema: type: object properties: data: type: object properties: totalRevenue: type: number description: Receita total do período em centavos example: 150000 totalTransactions: type: integer description: Total de transações no período example: 45 transactionsPerDay: type: object description: >- Objeto com transações agrupadas por dia (chave é a data no formato YYYY-MM-DD) additionalProperties: type: object properties: amount: type: number description: Valor total das transações do dia em centavos example: 5000 count: type: integer description: Quantidade de transações do dia example: 3 required: - amount - count additionalProperties: false example: '2024-01-15': amount: 5000 count: 3 '2024-01-16': amount: 3000 count: 2 required: - totalRevenue - totalTransactions - transactionsPerDay additionalProperties: false error: type: string nullable: true example: null success: $ref: '#/components/schemas/Success' '400': description: Erro de validação. Parâmetros inválidos ou ausentes. content: application/json: schema: type: object properties: error: type: string description: Mensagem de erro descrevendo o problema de validação. example: Start date and end date are required '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro descrevendo o motivo da falha na autenticação. example: Token de autenticação inválido ou ausente. /webhooks/create: post: summary: Criar um webhook description: > Cria um novo webhook para receber notificações automáticas de eventos da sua loja. O `endpoint` deve ser uma URL HTTPS válida e não pode apontar para endereços locais ou IPs privados. **Alternativa**: Você também pode criar e gerenciar seus webhooks pelo [Dashboard da AbacatePay](https://app.abacatepay.com/webhooks). security: - bearerAuth: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WebhookCreateInput' responses: '200': description: Webhook criado com sucesso. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/WebhookResponse' error: type: string nullable: true example: null success: $ref: '#/components/schemas/Success' '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro descrevendo o motivo da falha na autenticação. example: Token de autenticação inválido ou ausente. /webhooks/list: get: summary: Listar webhooks description: > Retorna todos os webhooks da sua loja com suporte a paginação e busca. **Alternativa**: Você também pode visualizar e gerenciar seus webhooks pelo [Dashboard da AbacatePay](https://app.abacatepay.com/webhooks). security: - bearerAuth: [] parameters: - name: search in: query description: Busca por nome, ID ou endpoint do webhook required: false schema: type: string example: pagamentos - $ref: '#/components/parameters/QueryAfter' - $ref: '#/components/parameters/QueryBefore' - $ref: '#/components/parameters/QueryLimit' - $ref: '#/components/parameters/QueryStartDate' - $ref: '#/components/parameters/QueryEndDate' - name: id in: query description: Filtrar por identificador único do webhook required: false schema: type: string example: webh_abc123xyz responses: '200': description: Lista de webhooks retornada com sucesso. content: application/json: schema: type: object properties: data: type: array description: Lista de webhooks. items: $ref: '#/components/schemas/WebhookResponse' success: $ref: '#/components/schemas/Success' error: type: string nullable: true example: null pagination: $ref: '#/components/schemas/PaginationCursor' '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro descrevendo o motivo da falha na autenticação. example: Token de autenticação inválido ou ausente. /webhooks/get: get: summary: Buscar um webhook description: Retorna os dados de um webhook específico pelo seu identificador. security: - bearerAuth: [] parameters: - name: id in: query description: Identificador único do webhook required: true schema: type: string example: webh_abc123xyz responses: '200': description: Webhook encontrado com sucesso. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/WebhookResponse' error: type: string nullable: true example: null success: $ref: '#/components/schemas/Success' '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro descrevendo o motivo da falha na autenticação. example: Token de autenticação inválido ou ausente. '404': description: Webhook não encontrado. content: application/json: schema: type: object properties: error: type: string description: Mensagem de erro indicando que o webhook não foi encontrado. example: Webhook não encontrado. /webhooks/delete: post: summary: Deletar um webhook description: | Remove um webhook da sua loja. Esta operação é irreversível. Use com cuidado. security: - bearerAuth: [] requestBody: required: true content: application/json: schema: type: object required: - id additionalProperties: false properties: id: type: string description: Identificador único do webhook a ser deletado example: webh_abc123xyz responses: '200': description: Webhook deletado com sucesso. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/WebhookResponse' error: type: string nullable: true example: null success: $ref: '#/components/schemas/Success' '401': description: Não autorizado. Falha na autenticação. content: application/json: schema: type: object properties: error: type: string description: >- Mensagem de erro descrevendo o motivo da falha na autenticação. example: Token de autenticação inválido ou ausente. '404': description: Webhook não encontrado. content: application/json: schema: type: object properties: error: type: string description: Mensagem de erro indicando que o webhook não foi encontrado. example: Webhook não encontrado. components: parameters: QueryAfter: name: after in: query description: Cursor para buscar itens após este ponto (use o `publicId` retornado em `pagination.next`). required: false schema: type: string QueryBefore: name: before in: query description: Cursor para buscar itens antes deste ponto (use o `publicId` retornado em `pagination.before`). required: false schema: type: string QueryLimit: name: limit in: query description: Quantidade de itens por página (1-100). required: false schema: type: integer minimum: 1 maximum: 100 default: 100 example: 100 QueryStartDate: name: startDate in: query description: > Filtra registros criados a partir desta data (inclusive). Formato `YYYY-MM-DD`. O intervalo é interpretado no fuso horário `America/Sao_Paulo` (00:00 do dia inicial). required: false schema: type: string format: date example: '2026-01-01' QueryEndDate: name: endDate in: query description: > Filtra registros criados até esta data (inclusive). Formato `YYYY-MM-DD`. O intervalo é interpretado no fuso horário `America/Sao_Paulo` (23:59:59.999 do dia final). required: false schema: type: string format: date example: '2026-01-31' schemas: Success: type: boolean description: Se a requisição obteve sucesso ou não. example: true RefundRequest: type: object required: - id additionalProperties: false properties: id: type: string description: > ID público do recurso a reembolsar. Aceita os prefixos `char_` / `pix_char_` / `card_` (payment intent) ou `bill_` (billing — resolvido para o payment intent pago). example: bill_abc123xyz reason: type: string maxLength: 500 description: Motivo do reembolso. Aparece no histórico da transação. example: Pedido cancelado pelo cliente. RefundResponse: type: object properties: data: type: object properties: refundPublicId: type: string description: ID público da transação de reembolso (WITHDRAW) criada. example: tran_refund789xyz error: type: string nullable: true example: null success: $ref: '#/components/schemas/Success' RefundError: type: object properties: data: nullable: true example: null error: type: string description: Código do erro de reembolso. enum: - LOCK_NOT_ACQUIRED - TRANSACTION_NOT_FOUND - TRANSACTION_NOT_REFUNDABLE - TRANSACTION_UNDER_DISPUTE - INVALID_METHOD - INSUFFICIENT_FUNDS - STORE_NOT_FOUND - REFUND_REQUEST_FAILED - REFUND_CONFIRMATION_FAILED example: TRANSACTION_UNDER_DISPUTE success: type: boolean example: false PaginationCursor: type: object description: Informações de paginação baseada em cursor. required: - hasMore - next - before additionalProperties: false properties: hasMore: type: boolean description: Indica se existe mais itens para carregar. next: type: string nullable: true description: Cursor para próxima página (usar em after). before: type: string nullable: true description: Cursor para página anterior (usar em before). BoletoInterest: type: object description: >- Juros por atraso aplicados ao boleto após o vencimento. Late interest applied to the boleto after the due date. Aplica-se apenas a `method: "BOLETO"`; ignorado nos demais métodos. additionalProperties: false required: - value properties: value: type: integer minimum: 0 description: >- Percentual de juros ao mês em centésimos de percentual (`100` = 1% ao mês, `250` = 2,5% ao mês). Quando `0` ou omitido, sem juros. Calculado pro rata die após o vencimento. EN: Monthly late-interest rate in hundredths of a percent (`100` = 1%/month). Accrues pro rata die after the due date; `0` or omitted disables interest. example: 100 BoletoFine: type: object description: >- Multa por atraso aplicada uma única vez após o vencimento do boleto. One-time late fine applied after the due date. Aplica-se apenas a `method: "BOLETO"`; ignorado nos demais métodos. additionalProperties: false required: - value - type properties: value: type: integer minimum: 0 description: >- Quando `type = "PERCENTAGE"`: centésimos de percentual sobre o valor do boleto (`200` = 2%). Quando `type = "FIXED"`: valor fixo em centavos (`1000` = R$ 10,00). Quando `0` ou omitido, sem multa. EN: With `type: "PERCENTAGE"`, value is in hundredths of a percent (`200` = 2%). With `type: "FIXED"`, value is in cents (`1000` = R$ 10.00). `0` or omitted disables the fine. example: 200 type: type: string description: >- Tipo da multa. `PERCENTAGE` aplica percentual sobre o valor do boleto; `FIXED` aplica um valor fixo em centavos. EN: Fine type. `PERCENTAGE` applies a percent of the boleto amount; `FIXED` applies a fixed amount in cents. enum: - PERCENTAGE - FIXED example: PERCENTAGE Customer: type: object description: Os dados do seu cliente. required: - id - devMode - name - cellphone - email - taxId additionalProperties: false properties: id: type: string description: Identificador único público do cliente example: cust_aebxkhDZNaMmJeKsy0AHS0FQ devMode: type: boolean description: Indica se o cliente foi criado em ambiente de testes. example: true name: type: string description: Nome completo do cliente example: Daniel Lima cellphone: type: string description: Celular do cliente example: (11) 4002-8922 email: type: string description: E-mail do cliente example: daniel_lima@abacatepay.com taxId: type: string description: CPF ou CNPJ do cliente example: 123.456.789-01 country: type: string description: País do cliente example: BR zipCode: type: string description: CEP do cliente example: 01310-100 metadata: type: object description: Metadados adicionais do cliente additionalProperties: true example: source: landing-page campaign: black-friday-2025 Coupon: type: object description: Os dados do seu cupom. required: - code - discount - discountKind - maxRedeems additionalProperties: false properties: code: type: string description: Identificador único do cupom example: DEYVIN_20 notes: type: string description: Descrição sbre o cupom example: Cupom de desconto pro meu público maxRedeems: type: number description: >- Quantidade de vezes em que o cupom pode ser resgatado. -1 Significa que esse cupom pode ser resgatado sem limites example: 10 default: -1 discountKind: type: string description: 'Tipo de desconto aplicado, porcentagem ou fixo' enum: - PERCENTAGE - FIXED discount: type: number description: Valor de desconto a ser aplicado startsAt: type: string format: date-time description: >- Início da validade do cupom. Se omitido, o cupom vale imediatamente. Precisa ser posterior a hoje. example: '2026-09-01T00:00:00.000Z' expiresAt: type: string format: date-time description: >- Fim da validade do cupom. Se omitido, o cupom não expira. Precisa ser posterior a hoje e a `startsAt`. example: '2026-12-31T23:59:59.000Z' CouponResponse: type: object description: Os dados do seu cupom. required: - id - discount - discountKind - status - createdAt - updatedAt additionalProperties: false properties: id: type: string description: Identificador único do cupom example: DEYVIN_20 notes: type: string description: Descrição sobre o cupom example: Cupom de desconto pro meu público maxRedeems: type: integer description: >- Quantidade de vezes em que o cupom pode ser resgatado. -1 significa ilimitado. example: -1 default: 10 redeemsCount: type: integer description: Quantidade de vezes que o cupom já foi resgatado. example: 0 discountKind: type: string description: 'Tipo de desconto aplicado, porcentagem ou fixo' enum: - PERCENTAGE - FIXED example: PERCENTAGE discount: type: number description: Valor de desconto a ser aplicado example: 123 devMode: type: boolean description: Indica se o cupom foi criado em ambiente de testes. example: true status: type: string description: Status atual do cupom. enum: - ACTIVE - INACTIVE - EXPIRED example: ACTIVE createdAt: type: string format: date-time description: Data de criação do cupom. example: '2025-05-25T23:43:25.250Z' updatedAt: type: string format: date-time description: Data de atualização do cupom. example: '2025-05-25T23:43:25.250Z' metadata: type: object description: Objeto chave valor para metadados do cupom default: {} Product: type: object description: > Os dados do seu produto. O campo `cycle` indica se o produto é uma assinatura (subscription). Quando `null`, o produto é avulso (pagamento único). Valores possíveis definem a recorrência da assinatura. A moeda (`currency`) é sempre `BRL`. required: - externalId - name - description - price - devMode - currency - createdAt - updatedAt - status - id additionalProperties: false properties: externalId: type: string description: Identificador único do produto no seu sistema example: prod-123 name: type: string description: Nome do produto example: Produto Exemplo description: type: string description: Descrição do produto example: Descrição do produto imageUrl: type: string format: uri nullable: true description: URL da imagem do produto example: null price: type: number description: Preço do produto em centavos example: 10000 devMode: type: boolean description: Indica se o produto foi criado em ambiente de testes example: false currency: type: string description: Moeda do produto (sempre BRL) enum: - BRL example: BRL createdAt: type: string format: date-time description: Data de criação do produto example: '2024-11-04T18:38:28.573Z' updatedAt: type: string format: date-time description: Data de atualização do produto example: '2024-11-04T18:38:28.573Z' status: type: string description: Status atual do produto (ProductStatus) enum: - ACTIVE - INACTIVE example: ACTIVE id: type: string description: Identificador único público do produto example: prod_abc123xyz cycle: type: string nullable: true description: > Indica se o produto é uma assinatura (ProductCycle). Quando `null`, o produto é avulso (pagamento único). Valores possíveis definem a recorrência da assinatura. enum: - WEEKLY - MONTHLY - QUARTERLY - SEMIANNUALLY - ANNUALLY example: null hasFile: type: boolean description: > Indica se o produto possui um arquivo PDF vinculado para download. Quando `true`, o comprador recebe acesso ao arquivo após o pagamento. example: false Billing: type: object properties: id: type: string description: Identificador único do Checkout. example: bill_abc123xyz externalId: type: string nullable: true description: ID do Checkout no seu sistema. example: pedido-123 url: type: string format: uri description: URL onde o usuário pode concluir o pagamento. example: 'https://app.abacatepay.com/pay/bill_abc123xyz' amount: type: number description: Valor total a ser pago em centavos. example: 10000 paidAmount: type: number nullable: true description: Valor já pago em centavos. Null se ainda não foi pago. example: null items: type: array description: Lista de itens no Checkout. items: type: object properties: id: type: string description: ID do produto. example: prod_456 quantity: type: integer description: Quantidade do item. example: 2 status: type: string description: Status atual do Checkout. enum: - PENDING - EXPIRED - CANCELLED - PAID - REFUNDED example: PENDING coupons: type: array description: Lista de cupons aplicados no Checkout. items: type: string example: [] devMode: type: boolean description: Indica se a cobrança foi criada em ambiente de testes. example: false customerId: type: string nullable: true description: ID do cliente associado ao Checkout. example: null returnUrl: type: string format: uri nullable: true description: URL para onde o cliente será redirecionado ao clicar em "Voltar". example: null completionUrl: type: string format: uri nullable: true description: URL para onde o cliente será redirecionado após o pagamento. example: null receiptUrl: type: string format: uri nullable: true description: URL do comprovante de pagamento. example: null upSellProductId: type: string nullable: true description: >- ID do produto de upsell vinculado ao Checkout. Null se nenhum produto de upsell foi informado na criação. example: prod_bump456xyz installmentsCount: type: integer nullable: true description: >- Número de parcelas do pagamento quando realizado via Cartão de crédito com mais de uma parcela. `null` para pagamentos à vista ou realizados por outros métodos (PIX, Boleto). example: 3 dueDate: type: string format: date nullable: true description: >- Data de vencimento do boleto (`YYYY-MM-DD`). `null` quando não foi configurada ou quando o método de pagamento não é BOLETO. example: '2026-08-15' interest: nullable: true description: >- Juros por atraso configurados para o boleto. `null` quando não foi configurado ou quando o método de pagamento não é BOLETO. allOf: - $ref: '#/components/schemas/BoletoInterest' fine: nullable: true description: >- Multa por atraso configurada para o boleto. `null` quando não foi configurada ou quando o método de pagamento não é BOLETO. allOf: - $ref: '#/components/schemas/BoletoFine' metadata: type: object description: Metadados adicionais do Checkout. additionalProperties: true example: {} createdAt: type: string format: date-time description: Data e hora de criação do Checkout. example: '2024-11-04T18:38:28.573Z' updatedAt: type: string format: date-time description: Data e hora da última atualização do Checkout. example: '2024-11-04T18:38:28.573Z' PixQRCode: type: object properties: id: type: string description: Identificador único do QRCode Pix. example: pix_char_123456 amount: type: number description: Valor a ser pago. example: 100 status: type: string description: Informação sobre o andamento do QRCode Pix. enum: - PENDING - EXPIRED - CANCELLED - PAID - UNDER_DISPUTE - REFUNDED - REDEEMED - APPROVED - FAILED example: PENDING devMode: type: boolean description: Ambiente no qual o QRCode Pix foi criado. example: true brCode: type: string description: Código copia-e-cola do QRCode Pix. example: 00020101021226950014br.gov.bcb.pix brCodeBase64: type: string description: Imagem em Base64 do QRCode Pix. example: 'data:image/png;base64,iVBORw0KGgoAAA' platformFee: type: number description: Taxas da plataforma example: 80 receiptUrl: type: string format: uri nullable: true description: >- URL do comprovante de pagamento. Preenchido após o pagamento ser confirmado; `null` enquanto a cobrança estiver pendente. example: null createdAt: type: string description: Data de criação do QRCode Pix. example: '2025-03-24T21:50:20.772Z' updatedAt: type: string description: Data de atualização do QRCode Pix. example: '2025-03-24T21:50:20.772Z' expiresAt: type: string description: Data de expiração do QRCode Pix example: '2025-03-25T21:50:20.772Z' metadata: type: object description: Metadados opcionais da cobrança. additionalProperties: true TransparentCreateUtm: type: object description: > Parâmetros UTM opcionais para campanha. Objeto inteiro e campos internos opcionais; podem ser consultados no dashboard. additionalProperties: false properties: source: type: string description: 'Opcional — ex.: origem ou fonte da campanha.' medium: type: string description: 'Opcional — ex.: meio ou canal.' campaign: type: string description: 'Opcional — nome ou identificador da campanha.' term: type: string description: 'Opcional — ex.: palavras-chave de anúncio.' content: type: string description: 'Opcional — ex.: variante criativa ou conteúdo.' TransparentCharge: type: object description: >- Dados da cobrança retornados pelo checkout transparente. Os campos `brCode` e `brCodeBase64` são sempre retornados (PIX direto ou PIX alternativo do boleto). Para boleto também retornam `barCode` e `url`. properties: id: type: string description: Identificador único da cobrança. example: bole_k8pqr2mnvx amount: type: number description: Valor a ser pago em centavos. example: 25000 status: type: string description: Status atual da cobrança. enum: - PENDING - EXPIRED - CANCELLED - PAID - UNDER_DISPUTE - REFUNDED - REDEEMED - APPROVED - FAILED example: PENDING devMode: type: boolean description: Indica se a cobrança foi criada em ambiente sandbox. example: false brCode: type: string description: >- Código copia-e-cola do QR Code PIX. Para `method: "BOLETO"`, representa o PIX alternativo da mesma cobrança. example: 00020126580014BR.GOV.BCB.PIX0136d2b4e5f6-7890-abcd-ef12-34567890abcd5204000053039865802BR5913Daniel Lima6009SAO PAULO62070503***6304F1C2 brCodeBase64: type: string description: >- Imagem em Base64 do QR Code PIX. Para `method: "BOLETO"`, representa o PIX alternativo da mesma cobrança. example: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA... barCode: type: string description: >- Linha digitável do boleto para pagamento no app do banco. Retornado quando `method` é `"BOLETO"`. example: 23793.38128 60007.827263 37000.963779 4 10010000025000 url: type: string description: >- URL para visualização e impressão do boleto. Retornado quando `method` é `"BOLETO"`. example: https://app.abacatepay.com/pay/bole_k8pqr2mnvx/boleto platformFee: type: number description: Taxa da plataforma em centavos. example: 250 interest: nullable: true description: >- Juros por atraso configurados para o boleto. `null` para `method: "PIX"` ou quando não foi configurado. allOf: - $ref: '#/components/schemas/BoletoInterest' fine: nullable: true description: >- Multa por atraso configurada para o boleto. `null` para `method: "PIX"` ou quando não foi configurada. allOf: - $ref: '#/components/schemas/BoletoFine' receiptUrl: type: string nullable: true description: >- URL do comprovante de pagamento. Preenchido após o pagamento ser confirmado; `null` enquanto a cobrança estiver pendente. example: null expiresAt: type: string description: >- Data de expiração da cobrança (ISO 8601). Para boleto, corresponde ao fim do dia de `dueDate` (ou do vencimento padrão de 3 dias úteis, se `dueDate` não foi informado). example: '2024-11-07T03:00:00.000Z' createdAt: type: string description: Data de criação. example: '2024-11-04T14:22:10.381Z' updatedAt: type: string description: Data da última atualização. example: '2024-11-04T14:22:10.381Z' metadata: type: object description: Campos livres enviados na requisição. additionalProperties: true BoletoTransparent: type: object properties: id: type: string description: Identificador único do boleto. example: bole_k8pqr2mnvx amount: type: number description: Valor a ser pago em centavos. example: 25000 status: type: string description: Status atual da cobrança. enum: - PENDING - EXPIRED - CANCELLED - PAID - UNDER_DISPUTE - REFUNDED example: PENDING devMode: type: boolean description: Indica se a cobrança foi criada em ambiente sandbox. example: false barCode: type: string description: Linha digitável do boleto para pagamento no app do banco. example: 23793.38128 60007.827263 37000.963779 4 10010000025000 url: type: string description: URL para visualização e impressão do boleto. example: https://app.abacatepay.com/pay/bole_k8pqr2mnvx/boleto brCode: type: string description: Código PIX copia e cola alternativo vinculado à mesma cobrança. example: 00020126580014BR.GOV.BCB.PIX0136d2b4e5f6-7890-abcd-ef12-34567890abcd5204000053039865802BR5913Mariana Costa6009SAO PAULO62070503***6304F1C2 brCodeBase64: type: string description: QR Code PIX alternativo em base64. example: data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA... platformFee: type: number description: Taxa da plataforma em centavos. example: 250 receiptUrl: type: string format: uri nullable: true description: >- URL do comprovante de pagamento. Preenchido após o pagamento ser confirmado; `null` enquanto a cobrança estiver pendente. example: null interest: nullable: true description: >- Juros por atraso configurados para o boleto. `null` quando não foi configurado. allOf: - $ref: '#/components/schemas/BoletoInterest' fine: nullable: true description: >- Multa por atraso configurada para o boleto. `null` quando não foi configurada. allOf: - $ref: '#/components/schemas/BoletoFine' expiresAt: type: string description: >- Data de expiração do boleto (ISO 8601), correspondente ao fim do dia de `dueDate` (ou do vencimento padrão de 3 dias úteis). example: '2024-11-07T03:00:00.000Z' createdAt: type: string description: Data de criação. example: '2024-11-04T14:22:10.381Z' updatedAt: type: string description: Data da última atualização. example: '2024-11-04T14:22:10.381Z' metadata: type: object description: Campos livres enviados na requisição. additionalProperties: true Transaction: type: object description: Dados de uma transação (pagamento ou saque). properties: id: type: string description: Identificador único da transação. example: tran_123456 status: type: string description: Status atual da transação. enum: - PENDING - EXPIRED - CANCELLED - COMPLETE - REFUNDED example: PENDING devMode: type: boolean description: Indica se a transação foi criada em ambiente de testes. example: true receiptUrl: type: string format: uri description: URL do comprovante da transação. example: 'https://abacatepay.com/receipt/tran_123456' kind: type: string description: Tipo da transação. enum: - PAYMENT - WITHDRAW example: WITHDRAW default: WITHDRAW amount: type: number description: Valor da transação em centavos. example: 5000 platformFee: type: number description: Taxa da plataforma em centavos. example: 80 externalId: type: string description: Identificador externo da transação. example: withdraw-1234 createdAt: type: string format: date-time description: Data de criação da transação. example: '2025-03-24T21:50:20.772Z' updatedAt: type: string format: date-time description: Data de atualização da transação. example: '2025-03-24T21:50:20.772Z' required: - id - status - devMode - receiptUrl - kind - amount - platformFee - createdAt - updatedAt PixTransaction: type: object description: Dados de uma transação PIX. properties: id: type: string description: Identificador único da transação PIX. example: txn_abc123xyz status: type: string description: Status atual da transação. enum: - PENDING - EXPIRED - CANCELLED - COMPLETE - REFUNDED example: PENDING devMode: type: boolean description: Indica se a transação foi criada em ambiente de testes. example: false receiptUrl: type: string format: uri description: URL do comprovante da transação. example: 'https://app.abacatepay.com/receipt/txn_abc123xyz' amount: type: number description: Valor da transação em centavos. example: 10000 platformFee: type: number description: Taxa da plataforma em centavos. example: 100 externalId: type: string nullable: true description: Identificador externo da transação. example: pix-123 createdAt: type: string format: date-time description: Data de criação da transação. example: '2024-11-04T18:38:28.573Z' updatedAt: type: string format: date-time description: Data de atualização da transação. example: '2024-11-04T18:38:28.573Z' required: - id - status - devMode - receiptUrl - amount - platformFee - createdAt - updatedAt Store: type: object description: Dados da loja/conta do usuário. required: - id - name - balance additionalProperties: false properties: id: type: string description: Identificador único da loja. example: store_abc123xyz name: type: string description: Nome da loja. example: Minha Loja balance: type: object description: Informações de saldo da loja. required: - available - pending - blocked additionalProperties: false properties: available: type: number description: Saldo disponível para saque em centavos. example: 50000 pending: type: number description: Saldo pendente de confirmação em centavos. example: 10000 blocked: type: number description: Saldo bloqueado em disputas em centavos. example: 0 Subscription: type: object description: Dados de uma assinatura (subscription). required: - id - name - description - amount - currency - method - status - customerId - devMode - events - createdAt - updatedAt additionalProperties: false properties: id: type: string description: Identificador único da assinatura. example: subs_abc123xyz name: type: string description: Nome da assinatura. example: Plano Premium Mensal description: type: string description: Descrição da assinatura. example: Assinatura mensal do plano premium amount: type: number description: Valor da assinatura em centavos. example: 10000 currency: type: string description: Moeda da assinatura. example: BRL method: type: string description: Método de pagamento da assinatura. enum: - PIX - CARD example: PIX status: type: string description: Status atual da assinatura. enum: - PENDING - ACTIVE - CANCELLED - EXPIRED - FAILED example: PENDING customerId: type: string description: Identificador do cliente que possui a assinatura. example: cust_abc123xyz devMode: type: boolean description: Indica se a assinatura foi criada em ambiente de testes. example: false createdAt: type: string format: date-time description: Data de criação da assinatura. example: '2024-11-04T18:38:28.573Z' updatedAt: type: string format: date-time description: Data de atualização da assinatura. example: '2024-11-04T18:38:28.573Z' SubscriptionUpdate: type: object description: Atualização de plano pendente de uma assinatura. required: - id - subscriptionId - status - productId - quantity - newAmount - requestedAt additionalProperties: false properties: id: type: string description: Identificador único da atualização de plano. example: subu_abc123xyz subscriptionId: type: string description: Identificador da assinatura associada. example: subs_abc123xyz status: type: string description: Status da atualização. enum: - PENDING - APPLIED - CANCELLED example: PENDING productId: type: string description: Identificador do novo produto. example: prod_plano_pro quantity: type: integer description: Quantidade do novo produto. example: 1 newAmount: type: integer description: Novo valor a ser cobrado por ciclo, em centavos (preço × quantidade). example: 4990 requestedAt: type: string format: date-time description: Data e hora em que a alteração foi solicitada. example: '2024-12-06T20:05:00.000Z' SubscriptionUsageRecord: type: object description: Registro de uso de um produto avulso em uma assinatura. required: - id - subscriptionId - productId - units - unitPrice - action - installmentNumber - recordedAt additionalProperties: false properties: id: type: string description: Identificador único do registro de uso. example: usgr_abc123xyz subscriptionId: type: string description: Identificador da assinatura associada. example: subs_abc123xyz productId: type: string description: Identificador do produto de uso. example: prod_api_calls units: type: integer description: Quantidade de unidades registradas. example: 50 unitPrice: type: integer description: Preço unitário em centavos no momento do registro. example: 100 action: type: string description: Tipo de ação aplicada ao uso. enum: - add - subtract example: add installmentNumber: type: integer description: Número da parcela em que este uso será cobrado. example: 2 recordedAt: type: string format: date-time description: Data e hora do registro. example: '2024-12-06T20:10:00.000Z' WebhookCreateInput: type: object description: Dados para criação de um webhook. required: - name - endpoint - secret - events additionalProperties: false properties: name: type: string description: Nome identificador do webhook example: Webhook de Pagamentos endpoint: type: string description: URL HTTPS que receberá as notificações de eventos example: 'https://meusite.com/webhooks/abacatepay' secret: type: string description: Sua chave usada para autenticar nosso webhook example: meu-secret-seguro events: type: array description: Lista de eventos que este webhook deve receber items: type: string enum: - checkout.completed - checkout.refunded - checkout.disputed - checkout.lost - transparent.completed - transparent.refunded - transparent.disputed - transparent.lost - subscription.completed - subscription.trial_started - subscription.cancelled - subscription.renewed - payout.completed - payout.failed - transfer.completed - transfer.failed example: - checkout.completed - subscription.renewed WebhookResponse: type: object description: Os dados do webhook. required: - id - name - endpoint - events - devMode - v2 - createdAt - updatedAt additionalProperties: false properties: id: type: string description: Identificador único do webhook example: webh_abc123xyz name: type: string description: Nome identificador do webhook example: Webhook de Pagamentos endpoint: type: string description: URL HTTPS que recebe as notificações de eventos example: 'https://meusite.com/webhooks/abacatepay' events: type: array description: Lista de eventos subscritos items: type: string example: - checkout.completed - subscription.renewed devMode: type: boolean description: Indica se o webhook foi criado em ambiente de testes example: false v2: type: boolean description: Indica se o webhook usa o formato de payload v2 example: true createdAt: type: string format: date-time description: Data de criação do webhook example: '2025-01-01T00:00:00.000Z' updatedAt: type: string format: date-time description: Data da última atualização do webhook example: '2025-01-01T00:00:00.000Z' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: > Todas as requisições devem incluir sua chave de API no header Authorization usando o formato `Bearer `. Sem esse header a requisição será rejeitada. Saiba mais sobre como criar e usar chaves de API na [documentação de autenticação](/pages/authentication).