Skip to main content
POST
/
refunds
/
invoice
/
{invoiceId}
curl -X POST "https://api.gates2b.com/refunds/invoice/123" \
  -H "Authorization: Bearer {seu-token}" \
  -H "Content-Type: application/json" \
  -d '{
    "value": 50.00,
    "reason": "Produto com defeito"
  }'

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "invoice": {
    "id": 123,
    "transaction_pix_id": "NOX152OM61MC0REP3F7HMQYI7U14QU85",
    "amount_final": 100.0,
    "status": "REFUND_REQUESTED",
    "med_amount": 0
  },
  "user": {
    "id": 456,
    "name": "Joao Silva",
    "email": "joao@empresa.com"
  },
  "gateway": "PIX",
  "transaction_id": "NOX152OM61MC0REP3F7HMQYI7U14QU85",
  "amount": 50.0,
  "reason": "Produto com defeito",
  "status": "REFUND_IN_PROGRESS",
  "external_refund_id": "",
  "created_at": "2025-09-24T14:30:15.123Z",
  "updated_at": "2025-09-24T14:30:15.123Z"
}
​
Authorization
string
required
The Bearer authentication token is required to access this endpoint.
​
invoiceId
string
required
Invoice (sale) ID for which the refund will be requested.
​
value
number
Specific refund amount. If not provided, a full refund for the received sale amount will be processed.
​
reason
string
Refund reason. Optional field for internal tracking.

​
Response

​
id
string
Unique identifier of the created refund.
​
invoice
object
Sale data related to the refund.
​
user
object
Data for the user who requested the refund.
​
gateway
string
Gateway used to process the refund (e.g., PIX, IUGU).
​
transaction_id
string
ID of the original transaction being refunded.
​
amount
number
Requested refund amount.
​
reason
string
Refund reason provided in the request.
​
status
string
Current refund status. Possible values: - REFUND_IN_PROGRESS: Refund in progress - REFUND_COMPLETED: Refund completed - REFUND_FAILED: Refund failed - REFUND_CANCELLED: Refund canceled
​
external_refund_id
string
External refund ID provided by the gateway.
​
created_at
string
Refund creation date and time.
​
updated_at
string
Refund last update date and time.
curl -X POST "https://api.gates2b.com/refunds/invoice/123" \
  -H "Authorization: Bearer {seu-token}" \
  -H "Content-Type: application/json" \
  -d '{
    "value": 50.00,
    "reason": "Produto com defeito"
  }'

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "invoice": {
    "id": 123,
    "transaction_pix_id": "NOX152OM61MC0REP3F7HMQYI7U14QU85",
    "amount_final": 100.0,
    "status": "REFUND_REQUESTED",
    "med_amount": 0
  },
  "user": {
    "id": 456,
    "name": "Joao Silva",
    "email": "joao@empresa.com"
  },
  "gateway": "PIX",
  "transaction_id": "NOX152OM61MC0REP3F7HMQYI7U14QU85",
  "amount": 50.0,
  "reason": "Produto com defeito",
  "status": "REFUND_IN_PROGRESS",
  "external_refund_id": "",
  "created_at": "2025-09-24T14:30:15.123Z",
  "updated_at": "2025-09-24T14:30:15.123Z"
}

​
Important Notes

​
Partial vs Full Refund

  • Partial Refund: When value is provided, the system processes a refund for the specified amount
  • Full Refund: When value is not provided, the system automatically calculates the total available amount for refund (received amount + MED amount)

​
Validations

  1. Available Balance: The system checks whether there is enough balance to process the refund
  2. Invoice Status: The invoice must be in a valid status for refund (cannot already be refunded)
  3. Maximum Amount: The refund amount cannot exceed the total amount received in the sale

​
Processing Flow

  1. Creation: The refund is created with status REFUND_IN_PROGRESS
  2. Processing: The system sends the request to the payment gateway
  3. Completion: Once processed by the gateway, the status is updated via internal webhook
  4. Settlement: The amount is debited from the user’s available balance

​
HTTP Status Codes

  • 201: Refund created successfully
  • 400: Invalid data or business restrictions
  • 401: Invalid authentication token
  • 404: Invoice not found
  • 500: Internal server error