Skip to main content
POST
/
refunds
/
create
curl -X POST 'https://api.goatpay.com.br/v1/refunds/create' \
  -H 'X-API-Key: gp_live_SUA_CHAVE' \
  -H 'Content-Type: application/json' \
  -d '{ "transactionId": "clx_pix_in", "refundId": "devolucao-pedido-123", "amount": 100, "nature": "ORIGINAL", "description": "Estorno pedido #123" }'

{
  "success": true,
  "message": "Reembolso PIX solicitado com sucesso",
  "data": {
    "id": "clx_pix_in",
    "type": "PIX_IN",
    "status": "PROCESSING",
    "amount": 100,
    "feeAmount": 8.5,
    "netAmount": 91.5,
    "coverFee": false,
    "currency": "BRL",
    "description": "Pedido 123",
    "externalReference": "pedido-123",
    "referenceId": "txid_dep_abc",
    "endToEndId": "E12345678202505301234567890123456",
    "createdAt": "2026-06-01T12:00:00.000Z",
    "refund": {
      "status": "PROCESSING",
      "refundId": "devolucao-pedido-123",
      "requestedAt": "2026-06-02T10:00:00.000Z",
      "completedAt": null,
      "nature": "ORIGINAL",
      "description": "Estorno pedido #123"
    }
  },
  "requestId": "req_abc123"
}

curl -X POST 'https://api.goatpay.com.br/v1/refunds/create' \
  -H 'X-API-Key: gp_live_SUA_CHAVE' \
  -H 'Content-Type: application/json' \
  -d '{ "transactionId": "clx_pix_in", "refundId": "devolucao-pedido-123", "amount": 100, "nature": "ORIGINAL", "description": "Estorno pedido #123" }'

{
  "success": true,
  "message": "Reembolso PIX solicitado com sucesso",
  "data": {
    "id": "clx_pix_in",
    "type": "PIX_IN",
    "status": "PROCESSING",
    "amount": 100,
    "feeAmount": 8.5,
    "netAmount": 91.5,
    "coverFee": false,
    "currency": "BRL",
    "description": "Pedido 123",
    "externalReference": "pedido-123",
    "referenceId": "txid_dep_abc",
    "endToEndId": "E12345678202505301234567890123456",
    "createdAt": "2026-06-01T12:00:00.000Z",
    "refund": {
      "status": "PROCESSING",
      "refundId": "devolucao-pedido-123",
      "requestedAt": "2026-06-02T10:00:00.000Z",
      "completedAt": null,
      "nature": "ORIGINAL",
      "description": "Estorno pedido #123"
    }
  },
  "requestId": "req_abc123"
}

​
Corpo da requisição

​
transactionId
string
ID da cobrança PIX (depósito) na GoatPay. Obrigatório se não enviar e2eId.
​
e2eId
string
EndToEndId do PIX recebido (alternativa ao transactionId).
​
refundId
string
ID único da devolução (1–35 alfanuméricos). Padrão: ID da transação.
​
amount
number
Valor bruto a devolver — deve ser igual ao depósito (estorno integral).
​
nature
string
ORIGINAL (PIX padrão) ou RETIRADA (PIX saque/troco). Padrão ORIGINAL.
​
description
string
Texto opcional para o pagador (máx. 140 caracteres).
​
subaccountId
string
ID da subconta merchant. Quando o depósito foi creditado na subconta, informe este campo: o estorno debita o saldo da subconta (líquido retido + taxa PIX saída da subconta). O depósito deve pertencer à subconta.
Disponível no trilho PADRÃO. Estorno integral do depósito. Depósitos em subconta exigem saldo na subconta (não na conta principal).

Authorizations

​
X-API-Key
string
header
required

Chave gp_live_... criada em Integrações → Chaves de API no dashboard.

Body

application/json

Informe transactionId ou e2eId (pelo menos um).

​
transactionId
string

ID da cobrança PIX (depósito) na GoatPay.

​
e2eId
string

EndToEndId do PIX recebido.

​
refundId
string

ID único da devolução no SPI (alfanumérico). Padrão — ID da transação.

Required string length: 1 - 35
​
amount
number

Valor bruto a devolver; deve ser igual ao depósito (estorno integral).

​
nature
enum<string>
default:ORIGINAL

ORIGINAL (PIX padrão) ou RETIRADA (PIX saque/troco).

Available options:
ORIGINAL,
RETIRADA
​
description
string

Texto opcional exibido ao pagador.

Maximum string length: 140
​
subaccountId
string

ID da subconta; estorno debita saldo e taxa da subconta quando o depósito pertence a ela.

Response

Reembolso PIX solicitado ou consultado.

​
success
boolean
required
​
message
string
required
​
data
object
required

Transação exposta na API pública após sanitização. Não inclui provider, accountId, metadata, pixRail, direction, updatedAt nem providerStatus.

​
requestId
string