openapi: 3.1.0 info: title: GoatPay API description: > API pública merchant da GoatPay. Autenticação via header `X-API-Key: gp_live_...`. Respostas de sucesso usam o envelope `{ success, message, data, requestId }`. Campos internos (`accountId`, `metadata`, histórico de entregas de webhook, etc.) não são expostos. `providerTransactionId` aparece como `referenceId`; `providerInfractionId` como `infractionId`. Rate limit global: 100 requisições por minuto por API key (HTTP 429). Sem chave, limite por IP. version: 1.0.0 servers: - url: https://api.goatpay.com.br/v1 description: Produção security: - apiKeyAuth: [] tags: - name: pix description: >- Cobranças PIX (receber), reembolsos de depósito recebido e transferências PIX (enviar). Alias legado em payouts/* para envios. - name: transfer-internal description: Transferências entre contas GoatPay - name: transfer-scheduled description: Transferências programadas (agendar, repetir ou por saldo) - name: crypto description: Depósitos e transferências em criptomoeda - name: billings description: >- Cobranças avulsas (pagamento único) — boleto, cartão ou PIX na Conta Padrão (PF ou PJ) - name: subscriptions description: >- Assinaturas recorrentes com ciclo fixo — boleto, cartão ou PIX na Conta Padrão (PF ou PJ) - name: account description: Saldo e extrato - name: subaccount description: Subcontas merchant (carteiras lógicas sob a conta principal) - name: meds description: Disputas MED - name: webhooks description: Endpoints de webhook de saída - name: payouts description: Alias de transfer-pix para saques PIX - name: customers description: Clientes da loja (CRM) - name: products description: Produtos e entregas digitais - name: coupons description: Cupons de desconto para links - name: payment-links description: Links de pagamento e checkout hospedado paths: /payment-pix/create: post: tags: - pix summary: Criar cobrança PIX description: > Taxa GoatPay conforme configuração da conta (taxa fixa no trilho PADRAO). Com `coverFee: true`, `amount` é o líquido desejado (taxa somada no QR). Com `coverFee: false` (padrão), `amount` é o valor bruto do QR. Split interno opcional via `splitUser` + `splitTax` (% do líquido). Com `subaccountId`, o líquido credita a subconta no trilho PADRAO (requer PIX em subcontas habilitado). operationId: createPaymentPix requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePixDeposit' examples: bruto: summary: Valor bruto no QR value: amount: 100 description: Pedido 123 coverFee: false liquido: summary: Líquido fixo (taxa no QR) value: amount: 100 description: Pedido 123 coverFee: true responses: '200': $ref: '#/components/responses/PixDepositSuccess' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/RateLimited' /payment-pix/get/{id}: get: tags: - pix summary: Consultar cobrança PIX operationId: getPaymentPix parameters: - $ref: '#/components/parameters/ResourceId' responses: '200': $ref: '#/components/responses/PixDepositSuccess' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /payment-pix/list: get: tags: - pix summary: Listar cobranças PIX description: >- Retorna apenas cobranças (PIX_IN e split recebido). Paginação e filtros opcionais. operationId: listPaymentPix parameters: - $ref: '#/components/parameters/ListPage' - $ref: '#/components/parameters/ListPageSize' - $ref: '#/components/parameters/ListDateFrom' - $ref: '#/components/parameters/ListDateTo' - $ref: '#/components/parameters/ListStatus' - $ref: '#/components/parameters/ListExternalReference' - $ref: '#/components/parameters/ListSearch' - $ref: '#/components/parameters/ListSubaccountId' - $ref: '#/components/parameters/ListMerchantSubaccountId' responses: '200': $ref: '#/components/responses/PixDepositListSuccess' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' /refunds/create: post: tags: - pix summary: Solicitar reembolso PIX description: > Devolve um depósito PIX recebido (estorno SPI). Trilho **PADRÃO** apenas. Informe `transactionId` (ID da cobrança) ou `e2eId`. Estorno integral: `amount` deve igualar o bruto do depósito. Debita o líquido retido na subconta (ou conta principal) mais a taxa de saída PIX. Use `subaccountId` quando o depósito foi creditado em subconta. operationId: createPixRefund requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePixRefund' examples: porTransacao: summary: Por ID da cobrança value: transactionId: clx_pix_in refundId: devolucao-pedido-123 amount: 100 nature: ORIGINAL description: Estorno pedido porE2e: summary: Por EndToEndId value: e2eId: E12345678202505301234567890123456 refundId: devolucao-pedido-123 responses: '200': $ref: '#/components/responses/PixRefundSuccess' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' /refunds/get/{id}: get: tags: - pix summary: Consultar reembolso PIX description: >- Consulta estorno por ID da transação, `refundId` ou `e2eId` (mesmo parâmetro de rota). operationId: getPixRefund parameters: - $ref: '#/components/parameters/ResourceId' responses: '200': $ref: '#/components/responses/PixRefundSuccess' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /refunds/list: get: tags: - pix summary: Listar reembolsos PIX description: >- Lista depósitos com estorno solicitado, em andamento ou concluído. Paginação e filtros opcionais. operationId: listPixRefunds parameters: - $ref: '#/components/parameters/ListPage' - $ref: '#/components/parameters/ListPageSize' - $ref: '#/components/parameters/ListDateFrom' - $ref: '#/components/parameters/ListDateTo' - $ref: '#/components/parameters/ListStatus' - $ref: '#/components/parameters/ListExternalReference' - $ref: '#/components/parameters/ListSearch' responses: '200': $ref: '#/components/responses/PixRefundListSuccess' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' /transfer-pix/create: post: tags: - pix summary: Criar transferência PIX description: > Envia PIX para chave ou BR Code (saque). Taxa conforme configuração da conta (trilho PADRAO). Com `coverFee: true` (padrão), `amount` é o valor recebido pelo destinatário. `pixCopyPaste` (QR Code) só no trilho `PADRAO`. Com `subaccountId`, o débito sai do saldo da subconta (requer PIX em subcontas habilitado). Permissões legadas `payouts/*` usam as mesmas rotas em `/payouts/create`, `/payouts/get/{id}` e `/payouts/list`. operationId: createTransferPix requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePixTransfer' responses: '200': $ref: '#/components/responses/PixTransferSuccess' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/RateLimited' /transfer-pix/get/{id}: get: tags: - pix summary: Consultar transferência PIX operationId: getTransferPix parameters: - $ref: '#/components/parameters/ResourceId' responses: '200': $ref: '#/components/responses/PixTransferSuccess' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' /transfer-pix/list: get: tags: - pix summary: Listar transferências PIX description: Retorna apenas envios PIX (PIX_OUT). Paginação e filtros opcionais. operationId: listTransferPix parameters: - $ref: '#/components/parameters/ListPage' - $ref: '#/components/parameters/ListPageSize' - $ref: '#/components/parameters/ListDateFrom' - $ref: '#/components/parameters/ListDateTo' - $ref: '#/components/parameters/ListStatus' - $ref: '#/components/parameters/ListExternalReference' - $ref: '#/components/parameters/ListSearch' - $ref: '#/components/parameters/ListSubaccountId' - $ref: '#/components/parameters/ListMerchantSubaccountId' responses: '200': $ref: '#/components/responses/TransactionListSuccess' '401': $ref: '#/components/responses/Unauthorized' /transfer-scheduled/create: post: tags: - transfer-scheduled - pix summary: Criar programação de transferência description: > Agenda envio único, recorrente ou automático por saldo mínimo. O objeto `payload` define o destino (PIX, interna ou cripto) — mesmos campos do dashboard. Limite de 20 programações ativas por conta. operationId: createTransferScheduled requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateScheduledTransfer' responses: '200': $ref: '#/components/responses/ScheduledTransferSuccess' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' /transfer-scheduled/list: get: tags: - transfer-scheduled summary: Listar programações de transferência operationId: listTransferScheduled responses: '200': $ref: '#/components/responses/ScheduledTransferListSuccess' '401': $ref: '#/components/responses/Unauthorized' /transfer-scheduled/get/{id}: get: tags: - transfer-scheduled summary: Consultar programação operationId: getTransferScheduled parameters: - $ref: '#/components/parameters/ResourceId' responses: '200': $ref: '#/components/responses/ScheduledTransferSuccess' '404': $ref: '#/components/responses/NotFound' /transfer-scheduled/update/{id}: patch: tags: - transfer-scheduled summary: Atualizar programação description: Pausar/retomar (`status`) ou alterar data, recorrência e limiares. operationId: updateTransferScheduled parameters: - $ref: '#/components/parameters/ResourceId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateScheduledTransfer' responses: '200': $ref: '#/components/responses/ScheduledTransferSuccess' '404': $ref: '#/components/responses/NotFound' /transfer-scheduled/cancel/{id}: delete: tags: - transfer-scheduled summary: Cancelar programação operationId: cancelTransferScheduled parameters: - $ref: '#/components/parameters/ResourceId' responses: '200': $ref: '#/components/responses/ScheduledTransferCancelSuccess' '404': $ref: '#/components/responses/NotFound' /transfer-scheduled/run-now/{id}: post: tags: - transfer-scheduled summary: Executar programação agora description: >- Dispara a transferência imediatamente (exceto regras por saldo aguardando limiar). operationId: runTransferScheduledNow parameters: - $ref: '#/components/parameters/ResourceId' responses: '200': $ref: '#/components/responses/ScheduledTransferSuccess' '404': $ref: '#/components/responses/NotFound' /transfer-internal/create: post: tags: - transfer-internal summary: Transferir para outra conta GoatPay description: >- Sem taxa. Credita o destinatário pelo e-mail cadastrado. Mesmo trilho na origem e destino. operationId: createTransferInternal requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateInternalTransfer' responses: '200': $ref: '#/components/responses/InternalTransferSuccess' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' /transfer-internal/get/{id}: get: tags: - transfer-internal summary: Consultar transferência interna operationId: getTransferInternal parameters: - $ref: '#/components/parameters/ResourceId' responses: '200': $ref: '#/components/responses/InternalTransferSuccess' '404': $ref: '#/components/responses/NotFound' /transfer-internal/list: get: tags: - transfer-internal summary: Listar transferências internas description: >- Envios (INTERNAL_TRANSFER_OUT) e recebimentos (INTERNAL_TRANSFER_IN) com paginação e filtros. operationId: listTransferInternal parameters: - $ref: '#/components/parameters/ListPage' - $ref: '#/components/parameters/ListPageSize' - $ref: '#/components/parameters/ListDateFrom' - $ref: '#/components/parameters/ListDateTo' - $ref: '#/components/parameters/ListStatus' - $ref: '#/components/parameters/ListExternalReference' - $ref: '#/components/parameters/ListSearch' responses: '200': $ref: '#/components/responses/TransactionListSuccess' /payment-crypto/create: post: tags: - crypto summary: Criar cobrança em cripto operationId: createPaymentCrypto requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateCryptoDeposit' responses: '200': $ref: '#/components/responses/CryptoTransactionSuccess' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' /payment-crypto/get/{id}: get: tags: - crypto summary: Consultar cobrança cripto operationId: getPaymentCrypto parameters: - $ref: '#/components/parameters/ResourceId' responses: '200': $ref: '#/components/responses/CryptoTransactionSuccess' '404': $ref: '#/components/responses/NotFound' /payment-crypto/list: get: tags: - crypto summary: Listar cobranças cripto description: Retorna apenas depósitos (CRYPTO_IN). Paginação e filtros opcionais. operationId: listPaymentCrypto parameters: - $ref: '#/components/parameters/ListPage' - $ref: '#/components/parameters/ListPageSize' - $ref: '#/components/parameters/ListDateFrom' - $ref: '#/components/parameters/ListDateTo' - $ref: '#/components/parameters/ListStatus' - $ref: '#/components/parameters/ListExternalReference' - $ref: '#/components/parameters/ListSearch' responses: '200': $ref: '#/components/responses/TransactionListSuccess' /payment-crypto/currencies: get: tags: - crypto summary: Listar moedas cripto operationId: listPaymentCryptoCurrencies responses: '200': $ref: '#/components/responses/SuccessEnvelope' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' /payment-crypto/estimate: get: tags: - crypto summary: Estimar conversão BRL ↔ cripto description: > Cotação aproximada. - `payCurrency`: use o campo `code` de `GET /payment-crypto/currencies` (ex.: `usdttrc20`). - `direction=to_crypto` (padrão): `amount` em **reais** → `estimated_amount` em cripto. - `direction=from_crypto`: `amount` em **cripto** → `estimated_amount` em **reais**. operationId: estimatePaymentCrypto parameters: - name: amount in: query required: true description: >- Valor a converter. Em BRL se `direction=to_crypto`; na moeda `payCurrency` se `from_crypto`. schema: type: number example: 100 - name: payCurrency in: query required: true description: Código da moeda/rede (`code` de `/payment-crypto/currencies`). schema: type: string example: usdttrc20 - name: direction in: query description: 'to_crypto (padrão): BRL → cripto. from_crypto: cripto → BRL.' schema: type: string enum: - to_crypto - from_crypto default: to_crypto example: to_crypto responses: '200': $ref: '#/components/responses/SuccessEnvelope' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' /payment-crypto/min-amount: get: tags: - crypto summary: Valor mínimo em cripto description: >- Mínimo on-chain para depósito. `payCurrency` = `code` retornado em `/payment-crypto/currencies`. operationId: paymentCryptoMinAmount parameters: - name: payCurrency in: query required: true description: 'Código da moeda/rede (ex.: usdttrc20).' schema: type: string example: usdttrc20 responses: '200': $ref: '#/components/responses/SuccessEnvelope' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' /transfer-crypto/create: post: tags: - crypto summary: Solicitar transferência em cripto operationId: createTransferCrypto requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateCryptoTransfer' responses: '200': $ref: '#/components/responses/CryptoTransactionSuccess' '403': $ref: '#/components/responses/Forbidden' /transfer-crypto/get/{id}: get: tags: - crypto summary: Consultar transferência cripto operationId: getTransferCrypto parameters: - $ref: '#/components/parameters/ResourceId' responses: '200': $ref: '#/components/responses/CryptoTransactionSuccess' '404': $ref: '#/components/responses/NotFound' /transfer-crypto/list: get: tags: - crypto summary: Listar saques cripto description: Retorna apenas saques (CRYPTO_OUT). Paginação e filtros opcionais. operationId: listTransferCrypto parameters: - $ref: '#/components/parameters/ListPage' - $ref: '#/components/parameters/ListPageSize' - $ref: '#/components/parameters/ListDateFrom' - $ref: '#/components/parameters/ListDateTo' - $ref: '#/components/parameters/ListStatus' - $ref: '#/components/parameters/ListExternalReference' - $ref: '#/components/parameters/ListSearch' responses: '200': $ref: '#/components/responses/TransactionListSuccess' /customers/create: post: tags: - customers summary: Cadastrar cliente description: >- Permissão `customers/create`. Clientes são isolados pelo trilho PADRAO da API key. operationId: createStoreCustomer requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateStoreCustomer' responses: '200': $ref: '#/components/responses/StoreCustomerSuccess' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' /customers/get/{id}: get: tags: - customers summary: Consultar cliente operationId: getStoreCustomer parameters: - $ref: '#/components/parameters/ResourceId' responses: '200': $ref: '#/components/responses/StoreCustomerSuccess' '404': $ref: '#/components/responses/NotFound' /customers/list: get: tags: - customers summary: Listar clientes description: Paginação e busca por nome, e-mail ou documento. operationId: listStoreCustomers parameters: - $ref: '#/components/parameters/ListPage' - $ref: '#/components/parameters/ListPageSize' - name: search in: query schema: type: string maxLength: 120 - name: status in: query schema: type: string description: Ativo, Inativo, Bloqueado ou active/inactive/blocked responses: '200': $ref: '#/components/responses/StoreListSuccess' /customers/update/{id}: patch: tags: - customers summary: Atualizar cliente operationId: updateStoreCustomer parameters: - $ref: '#/components/parameters/ResourceId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateStoreCustomer' responses: '200': $ref: '#/components/responses/StoreCustomerSuccess' /customers/delete/{id}: delete: tags: - customers summary: Excluir cliente operationId: deleteStoreCustomer parameters: - $ref: '#/components/parameters/ResourceId' responses: '200': $ref: '#/components/responses/StoreDeleteSuccess' /products/create: post: tags: - products summary: Criar produto description: Permissão `products/create`. Upload de imagem apenas no dashboard. operationId: createStoreProduct requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateStoreProduct' responses: '200': $ref: '#/components/responses/StoreProductSuccess' /products/get/{id}: get: tags: - products summary: Consultar produto operationId: getStoreProduct parameters: - $ref: '#/components/parameters/ResourceId' responses: '200': $ref: '#/components/responses/StoreProductSuccess' '404': $ref: '#/components/responses/NotFound' /products/list: get: tags: - products summary: Listar produtos operationId: listStoreProducts parameters: - $ref: '#/components/parameters/ListPage' - $ref: '#/components/parameters/ListPageSize' - name: search in: query schema: type: string - name: status in: query schema: type: string enum: - ACTIVE - INACTIVE responses: '200': $ref: '#/components/responses/StoreListSuccess' /products/update/{id}: patch: tags: - products summary: Atualizar produto operationId: updateStoreProduct parameters: - $ref: '#/components/parameters/ResourceId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateStoreProduct' responses: '200': $ref: '#/components/responses/StoreProductSuccess' /products/delete/{id}: delete: tags: - products summary: Excluir produto operationId: deleteStoreProduct parameters: - $ref: '#/components/parameters/ResourceId' responses: '200': $ref: '#/components/responses/StoreDeleteSuccess' /coupons/create: post: tags: - coupons summary: Criar cupom operationId: createStoreCoupon requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateStoreCoupon' responses: '200': $ref: '#/components/responses/StoreCouponSuccess' /coupons/get/{id}: get: tags: - coupons summary: Consultar cupom operationId: getStoreCoupon parameters: - $ref: '#/components/parameters/ResourceId' responses: '200': $ref: '#/components/responses/StoreCouponSuccess' /coupons/list: get: tags: - coupons summary: Listar cupons operationId: listStoreCoupons parameters: - $ref: '#/components/parameters/ListPage' - $ref: '#/components/parameters/ListPageSize' - name: search in: query schema: type: string - name: status in: query schema: type: string responses: '200': $ref: '#/components/responses/StoreListSuccess' /coupons/update/{id}: patch: tags: - coupons summary: Atualizar cupom operationId: updateStoreCoupon parameters: - $ref: '#/components/parameters/ResourceId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateStoreCoupon' responses: '200': $ref: '#/components/responses/StoreCouponSuccess' /coupons/delete/{id}: delete: tags: - coupons summary: Excluir cupom operationId: deleteStoreCoupon parameters: - $ref: '#/components/parameters/ResourceId' responses: '200': $ref: '#/components/responses/StoreDeleteSuccess' /coupons/validate: post: tags: - coupons summary: Validar cupom para checkout description: Use antes de `POST /payment-links/checkout` com `couponCode`. operationId: validateStoreCoupon requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ValidateStoreCoupon' responses: '200': $ref: '#/components/responses/StoreCouponValidateSuccess' /payment-links/create: post: tags: - payment-links summary: Criar link de pagamento operationId: createPaymentLink requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePaymentLink' responses: '200': $ref: '#/components/responses/PaymentLinkSuccess' /payment-links/get/{id}: get: tags: - payment-links summary: Consultar link de pagamento operationId: getPaymentLink parameters: - $ref: '#/components/parameters/ResourceId' responses: '200': $ref: '#/components/responses/PaymentLinkSuccess' /payment-links/list: get: tags: - payment-links summary: Listar links de pagamento operationId: listPaymentLinks parameters: - $ref: '#/components/parameters/ListPage' - $ref: '#/components/parameters/ListPageSize' - name: search in: query schema: type: string - name: status in: query schema: type: string enum: - ACTIVE - INACTIVE responses: '200': $ref: '#/components/responses/StoreListSuccess' /payment-links/update/{id}: patch: tags: - payment-links summary: Atualizar link de pagamento operationId: updatePaymentLink parameters: - $ref: '#/components/parameters/ResourceId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePaymentLink' responses: '200': $ref: '#/components/responses/PaymentLinkSuccess' /payment-links/status/{id}: patch: tags: - payment-links summary: Ativar ou desativar link operationId: updatePaymentLinkStatus parameters: - $ref: '#/components/parameters/ResourceId' requestBody: required: true content: application/json: schema: type: object required: - status properties: status: type: string enum: - ACTIVE - INACTIVE responses: '200': $ref: '#/components/responses/PaymentLinkSuccess' /payment-links/delete/{id}: delete: tags: - payment-links summary: Excluir link de pagamento operationId: deletePaymentLink parameters: - $ref: '#/components/parameters/ResourceId' responses: '200': $ref: '#/components/responses/StoreDeleteSuccess' /payment-links/checkout: post: tags: - payment-links summary: Iniciar checkout do link description: > PIX ou cripto. Header opcional `Idempotency-Key`. Redirecione para `payCheckoutUrl`. Confirme com webhook `payment_link.paid` ou GET sessions. operationId: checkoutPaymentLink parameters: - name: Idempotency-Key in: header schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PaymentLinkCheckout' responses: '200': $ref: '#/components/responses/PaymentLinkCheckoutSuccess' /payment-links/sessions/get/{sessionId}: get: tags: - payment-links summary: Consultar sessão de checkout operationId: getPaymentLinkSession parameters: - name: sessionId in: path required: true schema: type: string responses: '200': $ref: '#/components/responses/PaymentLinkSessionSuccess' /billings/create: post: tags: - billings summary: Criar cobrança avulsa description: >- Pagamento único (boleto, cartão ou PIX). Para recorrência use `/subscriptions/create`. operationId: createBilling requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateBilling' responses: '200': $ref: '#/components/responses/SuccessEnvelope' '403': $ref: '#/components/responses/Forbidden' /billings/get/{id}: get: tags: - billings summary: Consultar cobrança avulsa operationId: getBilling parameters: - $ref: '#/components/parameters/ResourceId' responses: '200': $ref: '#/components/responses/SuccessEnvelope' '404': $ref: '#/components/responses/NotFound' /billings/list: get: tags: - billings summary: Listar cobranças avulsas operationId: listBillings parameters: - $ref: '#/components/parameters/ListPage' - $ref: '#/components/parameters/ListPageSize' responses: '200': $ref: '#/components/responses/SuccessEnvelope' /billings/refund: post: tags: - billings summary: Estornar cobrança avulsa operationId: refundBilling requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RefundBilling' responses: '200': $ref: '#/components/responses/SuccessEnvelope' '404': $ref: '#/components/responses/NotFound' /billings/tokenize-card: post: tags: - billings summary: Tokenizar cartão description: >- Gera creditCardToken sem cobrar. Reutilize em cobranças e assinaturas com cardToken. operationId: tokenizeBillingCard requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TokenizeBillingCard' responses: '200': $ref: '#/components/responses/SuccessEnvelope' '403': $ref: '#/components/responses/Forbidden' /subscriptions/create: post: tags: - subscriptions summary: Criar assinatura recorrente description: >- Plano com cobrança automática em ciclo fixo. Para pagamento único use `/billings/create`. operationId: createSubscription requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateSubscription' responses: '200': $ref: '#/components/responses/SuccessEnvelope' '403': $ref: '#/components/responses/Forbidden' /subscriptions/get/{id}: get: tags: - subscriptions summary: Consultar assinatura operationId: getSubscription parameters: - $ref: '#/components/parameters/ResourceId' responses: '200': $ref: '#/components/responses/SuccessEnvelope' '404': $ref: '#/components/responses/NotFound' /subscriptions/list: get: tags: - subscriptions summary: Listar assinaturas description: Lista assinaturas recorrentes com paginação e filtros opcionais. operationId: listSubscriptions parameters: - name: page in: query schema: type: integer minimum: 1 default: 1 - name: pageSize in: query schema: type: integer minimum: 1 maximum: 100 default: 50 - name: status in: query schema: type: string example: ACTIVE - name: cycle in: query schema: type: string example: MONTHLY - name: method in: query schema: type: string example: BOLETO - name: search in: query schema: type: string responses: '200': $ref: '#/components/responses/SuccessEnvelope' '403': $ref: '#/components/responses/Forbidden' /subscriptions/cancel/{id}: post: tags: - subscriptions summary: Cancelar assinatura operationId: cancelSubscription parameters: - $ref: '#/components/parameters/ResourceId' responses: '200': $ref: '#/components/responses/SuccessEnvelope' '404': $ref: '#/components/responses/NotFound' /subaccount/create: post: tags: - subaccount summary: Criar subconta description: > Cria subconta merchant com cadastro KYC (PF ou PJ). `externalReference` obrigatório na API pública. Subconta **PF**: `application/json`. Subconta **PJ**: `multipart/form-data` com campo `data` (JSON) e `registrationDocument` (PDF/JPG/PNG/WEBP, máx. 8 MB). operationId: createSubaccount requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateSubaccount' multipart/form-data: schema: type: object required: - data - registrationDocument properties: data: type: string description: JSON stringificado de CreateSubaccount (personType PJ). registrationDocument: type: string format: binary description: Comprovante de inscrição ou contrato social. responses: '200': $ref: '#/components/responses/SuccessEnvelope' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' /subaccount/delete: post: tags: - subaccount summary: Excluir subconta description: Exige saldo zerado em ambos os trilhos. operationId: deleteSubaccount requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubaccountIdBody' responses: '200': $ref: '#/components/responses/SuccessEnvelope' /subaccount/get/{id}: get: tags: - subaccount summary: Consultar subconta operationId: getSubaccount parameters: - $ref: '#/components/parameters/ResourceId' responses: '200': $ref: '#/components/responses/SuccessEnvelope' '404': $ref: '#/components/responses/NotFound' /subaccount/get-by-ref/{externalReference}: get: tags: - subaccount summary: Consultar subconta por referência externa operationId: getSubaccountByRef parameters: - name: externalReference in: path required: true schema: type: string responses: '200': $ref: '#/components/responses/SuccessEnvelope' '404': $ref: '#/components/responses/NotFound' /subaccount/list: get: tags: - subaccount summary: Listar subcontas operationId: listSubaccounts parameters: - name: page in: query schema: type: integer minimum: 1 - name: limit in: query schema: type: integer minimum: 1 maximum: 100 - name: status in: query schema: type: string enum: - ACTIVE - DISABLED responses: '200': $ref: '#/components/responses/SuccessEnvelope' '403': $ref: '#/components/responses/Forbidden' /subaccount/pricing: get: tags: - subaccount summary: Consultar taxas PIX da subconta operationId: getSubaccountPricing parameters: - name: id in: query schema: type: string - name: externalReference in: query schema: type: string responses: '200': $ref: '#/components/responses/SuccessEnvelope' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' /subaccount/update: post: tags: - subaccount summary: Atualizar subconta operationId: updateSubaccount requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateSubaccount' responses: '200': $ref: '#/components/responses/SuccessEnvelope' /subaccount/balance: get: tags: - subaccount summary: Saldo da subconta operationId: getSubaccountBalance parameters: - name: id in: query schema: type: string - name: externalReference in: query schema: type: string responses: '200': $ref: '#/components/responses/SuccessEnvelope' /subaccount/add-balance: post: tags: - subaccount summary: Adicionar saldo (main → subconta) operationId: addSubaccountBalance requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubaccountMovement' responses: '200': $ref: '#/components/responses/SuccessEnvelope' /subaccount/remove-balance: post: tags: - subaccount summary: Remover saldo (subconta → main) operationId: removeSubaccountBalance requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubaccountMovement' responses: '200': $ref: '#/components/responses/SuccessEnvelope' /subaccount/transfer: post: tags: - subaccount summary: Transferir entre subcontas operationId: transferSubaccount requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubaccountTransfer' responses: '200': $ref: '#/components/responses/SuccessEnvelope' /subaccount/lock: post: tags: - subaccount summary: Bloquear subconta operationId: lockSubaccount requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubaccountLock' responses: '200': $ref: '#/components/responses/SuccessEnvelope' /subaccount/unlock: post: tags: - subaccount summary: Desbloquear subconta operationId: unlockSubaccount requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubaccountIdBody' responses: '200': $ref: '#/components/responses/SuccessEnvelope' /subaccount/set-limits: post: tags: - subaccount summary: Definir limites da subconta operationId: setSubaccountLimits requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SetSubaccountLimits' responses: '200': $ref: '#/components/responses/SuccessEnvelope' /subaccount/set-pricing: post: tags: - subaccount summary: Taxas e lucro por operação operationId: setSubaccountPricing requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SetSubaccountPricing' responses: '200': $ref: '#/components/responses/SuccessEnvelope' /subaccount/portal/status: get: tags: - subaccount summary: Status do Portal Wallet description: >- Sem query params, lista todas as subcontas. Com id ou externalReference, retorna uma subconta. operationId: getSubaccountPortalStatus parameters: - name: id in: query schema: type: string - name: externalReference in: query schema: type: string responses: '200': $ref: '#/components/responses/SubaccountPortalStatusSuccess' /subaccount/portal/setup: post: tags: - subaccount summary: Configurar login do Portal Wallet operationId: setupSubaccountPortal requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubaccountPortalSetup' responses: '200': $ref: '#/components/responses/SubaccountPortalSetupSuccess' /subaccount/portal/update-email: post: tags: - subaccount summary: Alterar e-mail do operador do Portal Wallet operationId: updateSubaccountPortalEmail requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubaccountPortalUpdateEmail' responses: '200': $ref: '#/components/responses/SubaccountPortalUpdateEmailSuccess' /subaccount/portal/revoke: post: tags: - subaccount summary: Revogar acesso ao Portal Wallet operationId: revokeSubaccountPortal requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubaccountPortalTarget' responses: '200': $ref: '#/components/responses/SubaccountPortalRevokeSuccess' /subaccount/portal/reset-2fa: post: tags: - subaccount summary: Resetar 2FA do operador do Portal Wallet operationId: resetSubaccountPortal2fa requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubaccountPortalTarget' responses: '200': $ref: '#/components/responses/SubaccountPortalReset2faSuccess' /account/balance: get: tags: - account summary: Consultar saldo operationId: getAccountBalance responses: '200': $ref: '#/components/responses/AccountBalanceSuccess' '401': $ref: '#/components/responses/Unauthorized' /account/transactions: get: tags: - account summary: Listar transações (extrato) description: >- Todas as transações da conta. Mesmos filtros das rotas de listagem por produto. operationId: listAccountTransactions parameters: - $ref: '#/components/parameters/ListPage' - $ref: '#/components/parameters/ListPageSize' - $ref: '#/components/parameters/ListDateFrom' - $ref: '#/components/parameters/ListDateTo' - $ref: '#/components/parameters/ListStatus' - $ref: '#/components/parameters/ListExternalReference' - $ref: '#/components/parameters/ListSearch' - $ref: '#/components/parameters/ListSubaccountId' - $ref: '#/components/parameters/ListMerchantSubaccountId' - name: type in: query schema: type: string enum: - entrada - saida - name: method in: query schema: type: string enum: - PIX - Cartão - Boleto - Cripto - TED - Interna responses: '200': $ref: '#/components/responses/TransactionListSuccess' /meds/list: get: tags: - meds summary: Listar disputas MED description: Disputas MED do trilho PADRAO da conta. Paginação e filtros opcionais. operationId: listMeds parameters: - $ref: '#/components/parameters/ListPage' - $ref: '#/components/parameters/ListPageSize' - $ref: '#/components/parameters/ListDateFrom' - $ref: '#/components/parameters/ListDateTo' - name: status in: query schema: type: string enum: - OPEN - UNDER_REVIEW - ACCEPTED - REJECTED - CANCELED - EXPIRED - $ref: '#/components/parameters/ListSearch' responses: '200': $ref: '#/components/responses/MedListSuccess' /meds/get/{id}: get: tags: - meds summary: Consultar disputa MED description: ID interno, protocolo ou infractionId. operationId: getMed parameters: - $ref: '#/components/parameters/ResourceId' responses: '200': $ref: '#/components/responses/MedDisputeSuccess' '404': $ref: '#/components/responses/NotFound' /meds/{id}/evidence: post: tags: - meds summary: Enviar evidências MED description: > Enquanto `status` for OPEN. JSON ou multipart (`justification`, opcional `analysis`, `proofs`, arquivos `files`). operationId: submitMedEvidence parameters: - $ref: '#/components/parameters/ResourceId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SubmitMedEvidence' multipart/form-data: schema: type: object required: - justification properties: justification: type: string analysis: type: string enum: - aceito - rejeitado proofs: type: string description: JSON array de URLs em string. files: type: array items: type: string format: binary responses: '200': $ref: '#/components/responses/MedDisputeSuccess' '403': $ref: '#/components/responses/Forbidden' /webhooks/create: post: tags: - webhooks summary: Cadastrar endpoint de webhook description: >- Retorna `secret` (`whsec_...`) uma única vez. Endpoint fica vinculado à API key usada. operationId: createWebhook requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateWebhook' responses: '200': $ref: '#/components/responses/WebhookCreateSuccess' '403': $ref: '#/components/responses/Forbidden' /webhooks/list: get: tags: - webhooks summary: Listar webhooks operationId: listWebhooks responses: '200': $ref: '#/components/responses/WebhookListSuccess' /webhooks/get/{id}: get: tags: - webhooks summary: Consultar webhook operationId: getWebhook parameters: - $ref: '#/components/parameters/ResourceId' responses: '200': $ref: '#/components/responses/WebhookItemSuccess' '404': $ref: '#/components/responses/NotFound' /webhooks/update/{id}: patch: tags: - webhooks summary: Atualizar webhook operationId: updateWebhook parameters: - $ref: '#/components/parameters/ResourceId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateWebhook' responses: '200': $ref: '#/components/responses/WebhookItemSuccess' /webhooks/delete/{id}: delete: tags: - webhooks summary: Revogar webhook operationId: deleteWebhook parameters: - $ref: '#/components/parameters/ResourceId' responses: '200': $ref: '#/components/responses/WebhookItemSuccess' /payouts/create: post: tags: - payouts - pix summary: Criar saque PIX (alias) description: Idêntico a POST /transfer-pix/create. Permissão payouts/create. operationId: createPayout requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreatePixTransfer' responses: '200': $ref: '#/components/responses/PixTransferSuccess' /payouts/get/{id}: get: tags: - payouts - pix summary: Consultar saque PIX (alias) operationId: getPayout parameters: - $ref: '#/components/parameters/ResourceId' responses: '200': $ref: '#/components/responses/PixTransferSuccess' /payouts/list: get: tags: - payouts - pix summary: Listar saques PIX (alias) operationId: listPayouts parameters: - $ref: '#/components/parameters/ListPage' - $ref: '#/components/parameters/ListPageSize' - $ref: '#/components/parameters/ListStatus' - $ref: '#/components/parameters/ListDateFrom' - $ref: '#/components/parameters/ListDateTo' - $ref: '#/components/parameters/ListExternalReference' - $ref: '#/components/parameters/ListSearch' - $ref: '#/components/parameters/ListSubaccountId' responses: '200': $ref: '#/components/responses/TransactionListSuccess' /transfer-crypto-auto/create: post: tags: - crypto summary: Saque cripto automático description: Conversão automática de saldo BRL para envio on-chain. operationId: createCryptoTransferAuto requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateCryptoTransfer' responses: '200': $ref: '#/components/responses/CryptoTransactionSuccess' components: securitySchemes: apiKeyAuth: type: apiKey in: header name: X-API-Key description: Chave `gp_live_...` criada em Integrações → Chaves de API no dashboard. parameters: ResourceId: name: id in: path required: true schema: type: string description: ID do recurso (transação, cobrança, webhook, etc.) ListPage: name: page in: query schema: type: integer minimum: 1 default: 1 ListPageSize: name: pageSize in: query schema: type: integer minimum: 1 maximum: 100 default: 50 ListDateFrom: name: dateFrom in: query schema: type: string format: date-time ListDateTo: name: dateTo in: query schema: type: string format: date-time ListStatus: name: status in: query schema: type: string enum: - PENDING - PROCESSING - COMPLETED - FAILED - CANCELED - REVERSED ListExternalReference: name: externalReference in: query schema: type: string ListSearch: name: search in: query schema: type: string description: >- Busca parcial em id, description, externalReference, endToEndId, referenceId e pixKey. ListSubaccountId: name: subaccountId in: query schema: type: string description: > Filtra transações vinculadas à subconta merchant (PIX com subaccountId na criação, movimentações internas, MED/reembolso, etc.). Alias de merchantSubaccountId. Quando informado, o filtro de trilho PIX da API key é ignorado. ListMerchantSubaccountId: name: merchantSubaccountId in: query schema: type: string description: Mesmo filtro que subaccountId. schemas: SuccessEnvelope: type: object required: - success - message - data properties: success: type: boolean example: true message: type: string example: Operação concluída com sucesso data: type: object additionalProperties: true requestId: type: string PublicTransaction: type: object description: > Transação exposta na API pública após sanitização. Não inclui `provider`, `accountId`, `metadata`, `pixRail`, `direction`, `updatedAt` nem `providerStatus`. properties: id: type: string type: type: string description: Ex. PIX_IN, PIX_OUT, INTERNAL_TRANSFER_OUT, CRYPTO_IN. status: type: string enum: - PENDING - PROCESSING - COMPLETED - FAILED - CANCELED - REVERSED amount: type: number feeAmount: type: number netAmount: type: number coverFee: type: boolean emitFiscalInvoice: type: boolean description: Indica se a cobrança deve gerar nota fiscal ao ser paga. currency: type: string example: BRL countsTowardPixBalance: type: boolean description: Indica se a transação movimenta o saldo PIX GoatPay. settlementScope: type: string enum: - goatpay description: Escopo de liquidação/saldo da transação. description: type: string externalReference: type: string referenceId: type: string description: Identificador da operação no processador de pagamento. endToEndId: type: string pixKey: type: string pixKeyType: type: string payer: type: object description: >- Cliente/pagador da transação. Em PIX recebido após confirmação, `name` e `document` vêm do comprovante PIX Padrão. Em cobranças de link de pagamento, `email` e `phone` (e nome/documento do checkout quando ainda não houver pagamento confirmado) vêm do formulário do comprador. Presente em entradas (PIX, boleto, cartão, etc.) quando há dados identificáveis; ausente em saídas PIX e quando não há nenhum dado. properties: name: type: string nullable: true description: Nome do pagador (comprovante PIX ou checkout do link). document: type: string nullable: true description: CPF ou CNPJ do pagador (apenas dígitos). email: type: string nullable: true description: E-mail informado no checkout do link de pagamento. phone: type: string nullable: true description: Telefone informado no checkout do link de pagamento. recipient: type: object description: >- Favorecido (recebedor) da transferência PIX, com nome e documento confirmados na liquidação PIX (`creditorAccount`). Presente apenas em `PIX_OUT` após a liquidação; ausente em saídas pendentes, em PIX recebido e quando o favorecido não é confirmado. properties: name: type: string nullable: true description: Nome do favorecido confirmado pelo banco. document: type: string nullable: true description: CPF ou CNPJ do favorecido (apenas dígitos). subaccountId: type: string completedAt: type: string format: date-time expiresAt: type: string format: date-time createdAt: type: string format: date-time PublicPixDeposit: allOf: - $ref: '#/components/schemas/PublicTransaction' - type: object properties: copyPaste: type: string description: BR Code (copia e cola). qrCodeBase64: type: string qrcodeUrl: type: string format: uri split: type: object description: >- Presente na resposta de criação quando `splitUser` e `splitTax` são enviados. properties: userEmail: type: string format: email taxPercent: type: number estimatedSplitAmount: type: number PublicRefundDetail: type: object properties: status: type: string enum: - AVAILABLE - PROCESSING - COMPLETED - UNAVAILABLE refundId: type: string requestedAt: type: string format: date-time completedAt: type: string format: date-time debitNet: type: number depositNet: type: number transferFee: type: number nature: type: string enum: - ORIGINAL - RETIRADA description: type: string PublicPixRefund: allOf: - $ref: '#/components/schemas/PublicTransaction' - type: object properties: refund: $ref: '#/components/schemas/PublicRefundDetail' PublicCryptoTransaction: allOf: - $ref: '#/components/schemas/PublicTransaction' - type: object properties: payAddress: type: string payCurrency: type: string example: usdttrc20 payAmount: type: number payinExtraId: type: string cryptoNetwork: type: string payoutBatchId: type: string description: Identificador do lote de saque, quando disponível. requiresVerification: type: boolean description: >- Presente em transferências cripto que exigem confirmação adicional. PublicInternalTransfer: allOf: - $ref: '#/components/schemas/PublicTransaction' - type: object properties: transferKind: type: string enum: - internal recipientEmail: type: string format: email recipientName: type: string counterpartyName: type: string counterpartyAccountId: type: string pairId: type: string PublicPagedTransactions: type: object required: - items - page - pageSize - total - pages properties: items: type: array items: $ref: '#/components/schemas/PublicTransaction' page: type: integer pageSize: type: integer total: type: integer pages: type: integer PublicPagedPixDeposits: type: object required: - items - page - pageSize - total - pages properties: items: type: array items: $ref: '#/components/schemas/PublicPixDeposit' page: type: integer pageSize: type: integer total: type: integer pages: type: integer PublicPagedPixRefunds: type: object required: - items - page - pageSize - total - pages properties: items: type: array items: $ref: '#/components/schemas/PublicPixRefund' page: type: integer pageSize: type: integer total: type: integer pages: type: integer PublicAccountBalance: type: object properties: currency: type: string example: BRL availableAmount: type: number pendingAmount: type: number blockedAmount: type: number totalAmount: type: number status: type: string padrao: type: object properties: available: type: number pending: type: number withdrawable: type: number locked24h: type: number nextUnlockAt: type: string format: date-time PublicWebhookEndpoint: type: object properties: id: type: string url: type: string format: uri description: type: string events: type: array items: type: string status: type: string enum: - ACTIVE - DISABLED - PENDING_SECRET createdAt: type: string format: date-time PublicWebhookCreateData: type: object properties: item: $ref: '#/components/schemas/PublicWebhookEndpoint' secret: type: string description: Segredo `whsec_...` exibido apenas na criação ou rotação. example: whsec_abc123def456 PublicWebhookItemData: type: object properties: item: $ref: '#/components/schemas/PublicWebhookEndpoint' PublicWebhookListData: type: object properties: items: type: array items: $ref: '#/components/schemas/PublicWebhookEndpoint' PublicPagedMeds: type: object required: - items - page - pageSize - total - pages properties: items: type: array items: $ref: '#/components/schemas/PublicMedDispute' page: type: integer pageSize: type: integer total: type: integer pages: type: integer PublicMedDispute: type: object properties: id: type: string protocol: type: string transactionId: type: string status: type: string enum: - OPEN - UNDER_REVIEW - ACCEPTED - REJECTED - CANCELED - EXPIRED amount: type: number currency: type: string example: BRL reason: type: string infractionId: type: string description: >- Identificador da infração no processador (antes providerInfractionId). endToEndId: type: string openedAt: type: string format: date-time dueAt: type: string format: date-time resolvedAt: type: string format: date-time ErrorEnvelope: type: object required: - success - message - error properties: success: type: boolean example: false message: type: string example: Subconta inativa error: type: object properties: code: type: string example: Bad Request statusCode: type: integer example: 400 requestId: type: string example: req_abc123 CreateSubaccount: type: object required: - personType - fullName - cpf - birthDate - postalCode - externalReference properties: personType: type: string enum: - PF - PJ fullName: type: string maxLength: 200 description: Nome completo do titular (representante em PJ). cpf: type: string description: CPF com 11 dígitos (somente números ou formatado). birthDate: type: string format: date description: Data de nascimento (YYYY-MM-DD). filiation: type: string maxLength: 500 description: Opcional. Filiação (nome dos pais ou equivalente). monthlyIncome: type: number minimum: 0 description: Opcional. Renda mensal em reais. profession: type: string maxLength: 120 description: Opcional. Profissão. postalCode: type: string description: CEP com 8 dígitos. cnpj: type: string description: Obrigatório se personType=PJ. legalName: type: string maxLength: 200 description: Razão social (PJ). website: type: string maxLength: 500 description: Site da empresa (PJ). externalReference: type: string maxLength: 64 portalEmail: type: string format: email description: Opcional. E-mail de login no Portal Wallet (wallet.goatpay.com.br). portalPassword: type: string minLength: 8 description: Obrigatório se portalEmail for informado. Senha inicial do operador. name: type: string deprecated: true description: >- Ignorado; use fullName (PF) ou legalName (PJ). Resposta retorna name derivado. SubaccountPortalTarget: type: object description: Informe id ou externalReference da subconta. properties: id: type: string externalReference: type: string maxLength: 64 SubaccountPortalSetup: allOf: - $ref: '#/components/schemas/SubaccountPortalTarget' - type: object required: - email - password properties: email: type: string format: email password: type: string minLength: 8 SubaccountPortalUpdateEmail: allOf: - $ref: '#/components/schemas/SubaccountPortalTarget' - type: object required: - email properties: email: type: string format: email SubaccountIdBody: type: object required: - id properties: id: type: string UpdateSubaccount: type: object required: - id properties: id: type: string name: type: string maxLength: 120 status: type: string enum: - ACTIVE - DISABLED SubaccountMovement: type: object required: - id - amount properties: id: type: string amount: type: number exclusiveMinimum: 0 description: type: string maxLength: 200 externalReference: type: string maxLength: 64 SubaccountTransfer: type: object required: - fromSubaccountId - toSubaccountId - amount properties: fromSubaccountId: type: string toSubaccountId: type: string amount: type: number exclusiveMinimum: 0 description: type: string externalReference: type: string SubaccountLock: type: object required: - id - mode properties: id: type: string mode: type: string enum: - full - withdraw_only - deposit_only SetSubaccountLimits: type: object required: - id properties: id: type: string dailyLimit: type: number monthlyLimit: type: number perTransactionLimit: type: number Subaccount: type: object properties: id: type: string name: type: string externalReference: type: string status: type: string enum: - ACTIVE - DISABLED lockMode: type: string enum: - NONE - FULL - WITHDRAW_ONLY - DEPOSIT_ONLY balance: $ref: '#/components/schemas/SubaccountBalance' SubaccountBalance: type: object description: Saldo trilho PADRAO. properties: availablePadrao: type: number pendingPadrao: type: number lockedPadrao: type: number spendablePadrao: type: number SubaccountMovementResult: type: object properties: transactionId: type: string subaccountId: type: string amount: type: number SubaccountPricingResponse: type: object properties: rail: type: string example: PADRAO subaccountId: type: string lines: type: array items: $ref: '#/components/schemas/SubaccountPricingLineView' SubaccountPricingLineView: type: object properties: operation: type: string enum: - PIX_PADRAO_DEPOSIT - PIX_PADRAO_TRANSFER label: type: string mainPercentFee: type: number mainFixedFee: type: number extraPercentFee: type: number extraFixedFee: type: number totalPercentFee: type: number totalFixedFee: type: number useGlobal: type: boolean active: type: boolean SubaccountPricingLine: type: object required: - operation properties: operation: type: string enum: - PIX_PADRAO_DEPOSIT - PIX_PADRAO_TRANSFER extraPercentFee: type: number extraFixedFee: type: number useGlobal: type: boolean active: type: boolean SetSubaccountPricing: type: object required: - id - lines properties: id: type: string lines: type: array items: $ref: '#/components/schemas/SubaccountPricingLine' CreateStoreCustomer: type: object required: - name - email - document properties: name: type: string maxLength: 200 email: type: string format: email document: type: string description: CPF (11 dígitos) ou CNPJ (14), somente números. pattern: ^(\d{11}|\d{14})$ type: type: string enum: - PF - PJ - pf - pj status: type: string description: Ativo, Inativo, Bloqueado ou active/inactive/blocked phone: type: string maxLength: 20 whatsapp: type: string maxLength: 20 city: type: string maxLength: 120 state: type: string maxLength: 2 UpdateStoreCustomer: type: object properties: name: type: string email: type: string format: email document: type: string type: type: string enum: - PF - PJ - pf - pj status: type: string phone: type: string whatsapp: type: string city: type: string state: type: string PublicStoreCustomer: type: object properties: id: type: string name: type: string email: type: string document: type: string type: type: string enum: - PF - PJ status: type: string phone: type: string whatsapp: type: string city: type: string state: type: string transactions: type: integer volume: type: number createdAt: type: string format: date-time lastActivityAt: type: string format: date-time CreateStoreProduct: type: object required: - name properties: name: type: string maxLength: 120 sku: type: string description: type: string price: type: number minimum: 0.01 status: type: string enum: - ACTIVE - INACTIVE deliveries: type: array items: $ref: '#/components/schemas/ProductDelivery' ProductDelivery: type: object required: - type properties: type: type: string enum: - TEXT_INFINITE - TEXT_LINES - LINK richContent: type: string redirectUrl: type: string maxLength: 2048 linesText: type: string PublicStoreProduct: type: object properties: id: type: string name: type: string sku: type: string description: type: string price: type: - number - 'null' status: type: string deliveries: type: array items: $ref: '#/components/schemas/ProductDelivery' hasImage: type: boolean salesCount: type: integer createdAt: type: string format: date-time updatedAt: type: string format: date-time CreateStoreCoupon: type: object required: - code - discountType - discountValue properties: code: type: string maxLength: 32 discountType: type: string enum: - PERCENT - FIXED discountValue: type: number minimum: 0.01 maxUses: type: integer minimum: 1 expiresAt: type: string format: date-time productIds: type: array items: type: string paymentLinkIds: type: array items: type: string PublicStoreCoupon: type: object properties: id: type: string code: type: string discountType: type: string discountValue: type: number maxUses: type: integer uses: type: integer expiresAt: type: - string - 'null' format: date-time status: type: string productIds: type: array items: type: string paymentLinkIds: type: array items: type: string ValidateStoreCoupon: type: object required: - code - amount - paymentLinkId properties: code: type: string amount: type: number minimum: 0.01 paymentLinkId: type: string productId: type: string CouponValidateResult: type: object properties: couponId: type: string code: type: string discountType: type: string discountValue: type: number discountAmount: type: number amountOriginal: type: number amountFinal: type: number CreatePaymentLink: type: object required: - name - slug - allowedMethods properties: name: type: string slug: type: string description: type: string fixedAmount: type: number minimum: 0.01 allowedMethods: type: array minItems: 1 items: type: string enum: - PIX - CRYPTO requireName: type: boolean requireDocument: type: boolean requireEmail: type: boolean requirePhone: type: boolean customerMode: type: string enum: - NONE - OPTIONAL - REQUIRED payerCoversFee: type: boolean productIds: type: array items: type: string PaymentLinkCheckout: type: object required: - linkId - method properties: linkId: type: string method: type: string enum: - PIX - CRYPTO amount: type: number payerName: type: string payerDocument: type: string payerEmail: type: string payerPhone: type: string couponCode: type: string externalReference: type: string successUrl: type: string format: uri cancelUrl: type: string format: uri PublicPaymentLink: type: object properties: id: type: string name: type: string slug: type: string publicCode: type: string fixedAmount: type: - number - 'null' allowedMethods: type: array items: type: string status: type: string payPageUrl: type: string checkoutPath: type: string PaymentLinkCheckoutResult: type: object properties: sessionId: type: string sessionToken: type: string payCheckoutUrl: type: string paymentLinkId: type: string externalReference: type: string PublicPagedStoreList: type: object properties: items: type: array items: type: object page: type: integer pageSize: type: integer total: type: integer pages: type: integer CreatePixDeposit: type: object required: - amount - description properties: amount: type: number minimum: 1 maximum: 1000000 description: Valor em reais. Mínimo R$ 1,00 no trilho PADRAO. description: type: string minLength: 3 maxLength: 180 payerName: type: string maxLength: 120 payerDocument: type: string maxLength: 14 externalReference: type: string maxLength: 120 coverFee: type: boolean default: false description: Taxa fixa configurada no trilho PADRAO (ex. R$ 0,50 ou R$ 0,80). emitFiscalInvoice: type: boolean default: false description: >- Emite nota fiscal após pagamento confirmado (requer emissão fiscal automática ativa no dashboard). splitUser: type: string format: email description: E-mail GoatPay do parceiro no split interno. splitTax: type: number minimum: 0.01 maximum: 100 subaccountId: type: string description: >- ID da subconta merchant. Líquido credita na subconta; disponível apenas no trilho PADRAO (requer merchantSubaccountsPixEnabled). CreatePixRefund: type: object description: Informe `transactionId` ou `e2eId` (pelo menos um). properties: transactionId: type: string description: ID da cobrança PIX (depósito) na GoatPay. e2eId: type: string description: EndToEndId do PIX recebido. refundId: type: string minLength: 1 maxLength: 35 description: >- ID único da devolução no SPI (alfanumérico). Padrão — ID da transação. amount: type: number description: >- Valor bruto a devolver; deve ser igual ao depósito (estorno integral). nature: type: string enum: - ORIGINAL - RETIRADA default: ORIGINAL description: ORIGINAL (PIX padrão) ou RETIRADA (PIX saque/troco). description: type: string maxLength: 140 description: Texto opcional exibido ao pagador. subaccountId: type: string description: >- ID da subconta; estorno debita saldo e taxa da subconta quando o depósito pertence a ela. CreatePixTransfer: type: object required: - amount - description properties: amount: type: number minimum: 1 description: Valor em reais. Mínimo R$ 1,00 no trilho PADRAO. description: type: string minLength: 3 maxLength: 180 pixKey: type: string pixKeyType: type: string enum: - CPF - CNPJ - EMAIL - TELEFONE - CHAVE_ALEATORIA pixKeyOwnerDocument: type: string description: > CPF ou CNPJ do titular da chave (11 ou 14 dígitos, sem formatação). Campo opcional/legado; transferências por chave PIX não exigem mais CPF/CNPJ do titular. Em pagamentos por `pixCopyPaste`, o PSP pode inferir esse dado do BR Code quando disponível. pixCopyPaste: type: string description: BR Code para pagar QR de terceiros. externalReference: type: string coverFee: type: boolean default: true description: >- Taxa de saída conforme configuração da conta (ex. R$ 0,80 no PADRAO). subaccountId: type: string description: >- ID da subconta merchant. Débito no saldo da subconta; disponível apenas no trilho PADRAO (requer merchantSubaccountsPixEnabled). ScheduledTransferRecurrenceRule: type: object required: - interval properties: interval: type: string enum: - daily - weekly - monthly - custom_days time: type: string example: '09:00' description: Horário no fuso `timezone` (padrão America/Sao_Paulo). timezone: type: string default: America/Sao_Paulo dayOfWeek: type: integer minimum: 0 maximum: 6 description: 0=domingo … 6=sábado (recorrência semanal). dayOfMonth: type: integer minimum: 1 maximum: 31 description: Dia do mês (recorrência mensal). customDays: type: integer minimum: 1 maximum: 365 description: Intervalo em dias (quando interval=custom_days). ScheduledTransferPayload: type: object required: - method - amount properties: method: type: string enum: - pix_padrao - interna - cripto amount: type: number minimum: 0.01 coverFee: type: boolean default: true description: type: string pixRail: type: string enum: - PADRAO description: Herdado da API key quando omitido. pixKey: type: string pixKeyType: type: string enum: - CPF - CNPJ - EMAIL - TELEFONE - CHAVE_ALEATORIA pixKeyOwnerDocument: type: string recipientEmail: type: string format: email description: Transferência interna GoatPay. address: type: string description: Endereço on-chain (cripto). payCurrency: type: string description: Código da moeda/rede (cripto). extraId: type: string description: Memo/tag (cripto). subaccountId: type: string CreateScheduledTransfer: type: object required: - triggerType - payload properties: label: type: string maxLength: 120 triggerType: type: string enum: - ONCE - RECURRING - BALANCE_THRESHOLD description: | ONCE — data/hora única (`scheduledAt`). RECURRING — repetição (`recurrenceRule`). BALANCE_THRESHOLD — envia quando saldo ≥ `balanceThreshold`. payload: $ref: '#/components/schemas/ScheduledTransferPayload' coverFee: type: boolean default: true scheduledAt: type: string format: date-time description: Obrigatório para ONCE; deve ser no futuro. recurrenceRule: $ref: '#/components/schemas/ScheduledTransferRecurrenceRule' balanceThreshold: type: number minimum: 0 description: Saldo mínimo em reais (BALANCE_THRESHOLD). maxRuns: type: integer minimum: 1 maximum: 9999 description: Limite de execuções (RECURRING). contactId: type: string description: Contato salvo no dashboard (opcional). UpdateScheduledTransfer: type: object properties: label: type: string maxLength: 120 status: type: string enum: - ACTIVE - PAUSED scheduledAt: type: string format: date-time recurrenceRule: $ref: '#/components/schemas/ScheduledTransferRecurrenceRule' balanceThreshold: type: number minimum: 0 maxRuns: type: integer minimum: 1 maximum: 9999 PublicScheduledTransfer: type: object properties: id: type: string label: type: string amount: type: number method: type: string destination: type: string triggerType: type: string enum: - once - recurring - balance_threshold scheduleLabel: type: string nextRunAt: type: string lastRunAt: type: string runCount: type: integer status: type: string enum: - active - paused - completed - failed coverFee: type: boolean CreateInternalTransfer: type: object required: - amount - recipientEmail properties: amount: type: number minimum: 1 recipientEmail: type: string format: email description: type: string maxLength: 180 externalReference: type: string CreateCryptoDeposit: type: object required: - amount - payCurrency properties: amount: type: number minimum: 5 payCurrency: type: string description: Código da moeda/rede (`code` de GET /payment-crypto/currencies). example: usdttrc20 description: type: string externalReference: type: string coverFee: type: boolean default: false purpose: type: string enum: - gateway - topup default: gateway CreateCryptoTransfer: type: object required: - amount - address - payCurrency - description properties: amount: type: number minimum: 1 address: type: string payCurrency: type: string description: Código da moeda/rede (`code` de GET /payment-crypto/currencies). example: usdttrc20 extraId: type: string description: Memo / destination tag. description: type: string externalReference: type: string coverFee: type: boolean default: true CreateSubscription: type: object required: - method - amount - cycle - nextDueDate - customer properties: method: type: string enum: - BOLETO - CARD_CREDIT - PIX amount: type: number minimum: 0.01 cycle: type: string enum: - WEEKLY - BIWEEKLY - MONTHLY - BIMONTHLY - QUARTERLY - SEMIANNUALLY - YEARLY nextDueDate: type: string format: date customer: $ref: '#/components/schemas/PublicCustomer' description: type: string cardToken: type: string description: Token de cartão (cobranças seguintes) creditCard: $ref: '#/components/schemas/CreditCard' creditCardHolderInfo: $ref: '#/components/schemas/CreditCardHolderInfo' remoteIp: type: string description: IP do comprador (obrigatório em CARD_CREDIT) authorizeOnly: type: boolean CreateBilling: type: object required: - method - amount - customer properties: method: type: string enum: - BOLETO - CARD_CREDIT - CARD_DEBIT - CARD_VOUCHER - PIX amount: type: number minimum: 0.01 customer: $ref: '#/components/schemas/PublicCustomer' description: type: string dueDate: type: string format: date installmentCount: type: integer minimum: 1 maximum: 21 cardToken: type: string description: Token do cartão para reutilização em cobranças futuras. creditCard: $ref: '#/components/schemas/CreditCard' creditCardHolderInfo: $ref: '#/components/schemas/CreditCardHolderInfo' remoteIp: type: string description: IP do comprador (obrigatório em CARD_*) authorizeOnly: type: boolean externalReference: type: string TokenizeBillingCard: type: object required: - customer - creditCard - creditCardHolderInfo properties: customer: $ref: '#/components/schemas/PublicCustomer' creditCard: $ref: '#/components/schemas/CreditCard' creditCardHolderInfo: $ref: '#/components/schemas/CreditCardHolderInfo' remoteIp: type: string CreditCard: type: object required: - holderName - number - expiryMonth - expiryYear - ccv properties: holderName: type: string number: type: string expiryMonth: type: string expiryYear: type: string ccv: type: string CreditCardHolderInfo: type: object required: - name - email - cpfCnpj - postalCode - addressNumber - phone properties: name: type: string email: type: string format: email cpfCnpj: type: string postalCode: type: string addressNumber: type: string addressComplement: type: string phone: type: string mobilePhone: type: string RefundBilling: type: object required: - id properties: id: type: string description: paymentIntentId retornado no create amount: type: number minimum: 0.01 reason: type: string PublicCustomer: type: object required: - name - taxId properties: id: type: string description: ID no seu sistema (default taxId) name: type: string taxId: type: string description: CPF/CNPJ somente dígitos email: type: string format: email phone: type: string SubmitMedEvidence: type: object required: - justification properties: justification: type: string minLength: 10 maxLength: 2000 analysis: type: string enum: - aceito - rejeitado description: Posição da contestação (quando exigido pelo processador). proofs: type: array maxItems: 10 items: type: string description: URLs públicas de comprovantes (mínimo 1 quando exigido). CreateWebhook: type: object required: - url - description - events properties: url: type: string format: uri description: HTTPS obrigatório. description: type: string maxLength: 120 events: type: array minItems: 1 maxItems: 80 items: type: string enum: - payment.created - payment.paid - payment.failed - payment.refunded - payment.pix.expired - payment.crypto.created - payment.crypto.paid - payment.crypto.failed - payment.crypto.expired - transfer.created - transfer.crypto.completed - transfer.crypto.failed - transfer.completed - transfer.failed - med.created - med.updated - med.evidence_sent - webhook.test UpdateWebhook: type: object properties: url: type: string format: uri description: type: string events: type: array items: type: string status: type: string enum: - ACTIVE - DISABLED responses: SuccessEnvelope: description: Operação concluída. content: application/json: schema: $ref: '#/components/schemas/SuccessEnvelope' examples: default: summary: Sucesso value: success: true message: Operação concluída com sucesso data: {} requestId: req_abc123 SubaccountPortalSetupSuccess: description: Portal Wallet configurado. content: application/json: schema: $ref: '#/components/schemas/SuccessEnvelope' examples: default: value: success: true message: Portal Wallet configurado data: success: true mode: portal_ready requestId: req_abc123 SubaccountPortalUpdateEmailSuccess: description: E-mail do operador atualizado. content: application/json: schema: $ref: '#/components/schemas/SuccessEnvelope' examples: default: value: success: true message: E-mail do portal atualizado data: success: true requestId: req_abc123 SubaccountPortalRevokeSuccess: description: Acesso ao Portal Wallet revogado. content: application/json: schema: $ref: '#/components/schemas/SuccessEnvelope' examples: default: value: success: true message: Portal Wallet revogado data: success: true requestId: req_abc123 SubaccountPortalReset2faSuccess: description: 2FA do operador resetado. content: application/json: schema: $ref: '#/components/schemas/SuccessEnvelope' examples: default: value: success: true message: 2FA do portal resetado data: success: true requestId: req_abc123 SubaccountPortalStatusSuccess: description: Status do Portal Wallet. content: application/json: schema: $ref: '#/components/schemas/SuccessEnvelope' examples: default: value: success: true message: Status do portal data: subaccountId: clx_subconta subaccountName: Loja Parceiro portal: state: active email: operador@empresa.com emailVerified: true twoFactorEnabled: false lastLoginAt: '2026-06-08T14:22:00.000Z' requestId: req_abc123 PixDepositSuccess: description: Cobrança PIX criada ou consultada. content: application/json: schema: type: object required: - success - message - data properties: success: type: boolean example: true message: type: string data: $ref: '#/components/schemas/PublicPixDeposit' requestId: type: string examples: created: summary: Cobrança criada value: success: true message: Pagamento PIX criado com sucesso data: id: clx_transacao type: PIX_IN status: PENDING amount: 100 feeAmount: 0.5 netAmount: 99.5 coverFee: false currency: BRL countsTowardPixBalance: true settlementScope: goatpay description: Pedido 123 externalReference: pedido-123 referenceId: ref_pix_abc copyPaste: 000201010212... qrCodeBase64: data:image/png;base64,... qrcodeUrl: https://pay.goatpay.com.br/p/clx_transacao expiresAt: '2026-06-02T12:00:00.000Z' createdAt: '2026-06-01T12:00:00.000Z' requestId: req_abc123 paid: summary: Cobrança paga (com pagador) value: success: true message: Pagamento PIX encontrado data: id: clx_transacao type: PIX_IN status: COMPLETED amount: 100 feeAmount: 0.5 netAmount: 99.5 coverFee: false currency: BRL countsTowardPixBalance: true settlementScope: goatpay description: Pedido 123 externalReference: pedido-123 referenceId: ref_pix_abc endToEndId: E12345678202505301234567890123456 payer: name: João da Silva document: '12345678909' completedAt: '2026-06-01T12:05:00.000Z' createdAt: '2026-06-01T12:00:00.000Z' requestId: req_abc123 PixDepositListSuccess: description: Lista paginada de cobranças PIX. content: application/json: schema: type: object required: - success - message - data properties: success: type: boolean message: type: string data: $ref: '#/components/schemas/PublicPagedPixDeposits' requestId: type: string PixTransferSuccess: description: Transferência PIX criada ou consultada. content: application/json: schema: type: object required: - success - message - data properties: success: type: boolean message: type: string data: $ref: '#/components/schemas/PublicTransaction' requestId: type: string examples: created: summary: Saque criado value: success: true message: Transferência PIX criada com sucesso data: id: clx_pix_out type: PIX_OUT status: PROCESSING amount: 50 feeAmount: 2 netAmount: 52 coverFee: true currency: BRL countsTowardPixBalance: true settlementScope: goatpay description: Saque parceiro pixKey: '11999999999' pixKeyType: TELEFONE referenceId: ref_out_xyz createdAt: '2026-06-01T14:00:00.000Z' requestId: req_def456 completed: summary: Saque liquidado (com favorecido) value: success: true message: Transferência PIX encontrada data: id: clx_pix_out type: PIX_OUT status: COMPLETED amount: 50 feeAmount: 2 netAmount: 52 coverFee: true currency: BRL countsTowardPixBalance: true settlementScope: goatpay description: Saque parceiro pixKey: '11999999999' pixKeyType: TELEFONE referenceId: ref_out_xyz endToEndId: E12345678202505301234567890123456 recipient: name: Maria Recebedora document: '12345678909' completedAt: '2026-06-01T14:05:00.000Z' createdAt: '2026-06-01T14:00:00.000Z' requestId: req_def456 TransactionListSuccess: description: Lista paginada de transações. content: application/json: schema: type: object required: - success - message - data properties: success: type: boolean message: type: string data: $ref: '#/components/schemas/PublicPagedTransactions' requestId: type: string PixRefundSuccess: description: Reembolso PIX solicitado ou consultado. content: application/json: schema: type: object required: - success - message - data properties: success: type: boolean message: type: string data: $ref: '#/components/schemas/PublicPixRefund' requestId: type: string PixRefundListSuccess: description: Lista paginada de reembolsos PIX. content: application/json: schema: type: object required: - success - message - data properties: success: type: boolean message: type: string data: $ref: '#/components/schemas/PublicPagedPixRefunds' requestId: type: string AccountBalanceSuccess: description: Saldo da conta. content: application/json: schema: type: object required: - success - message - data properties: success: type: boolean message: type: string data: $ref: '#/components/schemas/PublicAccountBalance' requestId: type: string examples: balance: summary: Saldo consultado value: success: true message: Saldo consultado com sucesso data: currency: BRL availableAmount: 1000 pendingAmount: 50 blockedAmount: 0 totalAmount: 1050 status: ACTIVE padrao: available: 1000 pending: 50 withdrawable: 950 locked24h: 50 nextUnlockAt: '2026-06-02T10:00:00.000Z' requestId: req_bal001 CryptoTransactionSuccess: description: Transação cripto criada ou consultada. content: application/json: schema: type: object required: - success - message - data properties: success: type: boolean message: type: string data: $ref: '#/components/schemas/PublicCryptoTransaction' requestId: type: string ScheduledTransferSuccess: description: Programação de transferência criada, consultada ou atualizada. content: application/json: schema: type: object required: - success - message - data properties: success: type: boolean message: type: string data: $ref: '#/components/schemas/PublicScheduledTransfer' requestId: type: string ScheduledTransferListSuccess: description: Lista de programações de transferência. content: application/json: schema: type: object required: - success - message - data properties: success: type: boolean message: type: string data: type: object properties: items: type: array items: $ref: '#/components/schemas/PublicScheduledTransfer' requestId: type: string ScheduledTransferCancelSuccess: description: Programação cancelada. content: application/json: schema: type: object required: - success - message - data properties: success: type: boolean message: type: string data: type: object properties: id: type: string cancelled: type: boolean requestId: type: string InternalTransferSuccess: description: Transferência interna criada ou consultada. content: application/json: schema: type: object required: - success - message - data properties: success: type: boolean message: type: string data: $ref: '#/components/schemas/PublicInternalTransfer' requestId: type: string MedDisputeSuccess: description: Disputa MED consultada ou evidência enviada. content: application/json: schema: type: object required: - success - message - data properties: success: type: boolean message: type: string data: $ref: '#/components/schemas/PublicMedDispute' requestId: type: string MedListSuccess: description: Lista paginada de disputas MED. content: application/json: schema: type: object required: - success - message - data properties: success: type: boolean message: type: string data: $ref: '#/components/schemas/PublicPagedMeds' requestId: type: string WebhookCreateSuccess: description: Webhook cadastrado (secret exibido uma vez). content: application/json: schema: type: object required: - success - message - data properties: success: type: boolean message: type: string data: $ref: '#/components/schemas/PublicWebhookCreateData' requestId: type: string examples: created: summary: Endpoint criado value: success: true message: Webhook criado com sucesso data: item: id: clx_webhook url: https://api.exemplo.com/webhooks/goatpay description: Produção events: - payment.paid - transfer.completed status: ACTIVE createdAt: '2026-06-01T10:00:00.000Z' secret: whsec_abc123def456ghi789 requestId: req_wh001 StoreCustomerSuccess: description: Cliente criado, consultado ou atualizado. content: application/json: schema: type: object required: - success - message - data properties: success: type: boolean message: type: string data: $ref: '#/components/schemas/PublicStoreCustomer' requestId: type: string StoreProductSuccess: description: Produto criado, consultado ou atualizado. content: application/json: schema: type: object required: - success - message - data properties: success: type: boolean message: type: string data: $ref: '#/components/schemas/PublicStoreProduct' requestId: type: string StoreCouponSuccess: description: Cupom criado, consultado ou atualizado. content: application/json: schema: type: object required: - success - message - data properties: success: type: boolean message: type: string data: $ref: '#/components/schemas/PublicStoreCoupon' requestId: type: string StoreCouponValidateSuccess: description: Resultado da validação do cupom. content: application/json: schema: type: object required: - success - message - data properties: success: type: boolean message: type: string data: $ref: '#/components/schemas/CouponValidateResult' requestId: type: string PaymentLinkSuccess: description: Link de pagamento. content: application/json: schema: type: object required: - success - message - data properties: success: type: boolean message: type: string data: $ref: '#/components/schemas/PublicPaymentLink' requestId: type: string PaymentLinkCheckoutSuccess: description: Checkout iniciado. content: application/json: schema: type: object required: - success - message - data properties: success: type: boolean message: type: string data: $ref: '#/components/schemas/PaymentLinkCheckoutResult' requestId: type: string PaymentLinkSessionSuccess: description: Sessão de checkout (status do pagamento). content: application/json: schema: type: object required: - success - message - data properties: success: type: boolean message: type: string data: type: object requestId: type: string StoreListSuccess: description: Lista paginada (clientes, produtos, cupons ou links). content: application/json: schema: type: object required: - success - message - data properties: success: type: boolean message: type: string data: $ref: '#/components/schemas/PublicPagedStoreList' requestId: type: string StoreDeleteSuccess: description: Recurso excluído. content: application/json: schema: type: object required: - success - message - data properties: success: type: boolean message: type: string data: type: object properties: id: type: string deleted: type: boolean requestId: type: string WebhookListSuccess: description: Lista de endpoints de webhook (sem histórico de entregas). content: application/json: schema: type: object required: - success - message - data properties: success: type: boolean message: type: string data: $ref: '#/components/schemas/PublicWebhookListData' requestId: type: string examples: list: summary: Dois endpoints value: success: true message: Webhooks listados com sucesso data: items: - id: clx_webhook_a url: https://api.exemplo.com/hooks/a description: Produção events: - payment.paid status: ACTIVE createdAt: '2026-06-01T10:00:00.000Z' - id: clx_webhook_b url: https://api.exemplo.com/hooks/b description: Homologação events: - webhook.test status: DISABLED createdAt: '2026-05-20T08:00:00.000Z' requestId: req_wh002 WebhookItemSuccess: description: Webhook consultado, atualizado ou removido. content: application/json: schema: type: object required: - success - message - data properties: success: type: boolean message: type: string data: $ref: '#/components/schemas/PublicWebhookItemData' requestId: type: string Unauthorized: description: Chave ausente, inválida ou revogada. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' Forbidden: description: Chave sem permissão para este endpoint. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' NotFound: description: Recurso não encontrado. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' RateLimited: description: Limite de 100 requisições por minuto excedido. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope'