Skip to main content
GET
https://api.sandbox.wepayout.com.br
/
v1
/
payin
/
payments
/
payin-refund
/
{refundId}
Get Unique Refund
curl --request GET \
  --url https://api.sandbox.wepayout.com.br/v1/payin/payments/payin-refund/{refundId} \
  --header 'Authorization: Bearer <token>'
{
  "id": 12345,
  "payin_id": 32457,
  "status_id": 4,
  "user": {
    "id": 1,
    "name": "Admin User"
  },
  "name": "PAID",
  "notification": "string",
  "created_at": "2024-06-12T23:10:00.000000Z",
  "end_to_end_id": "E1805820220621234567890AB1C2",
  "reason": "Customer requested refund",
  "wallet_error_code": null,
  "notification_url": "https://client.callback.com/notify-payin",
  "updated_at": "2024-06-12T23:15:00.000000Z",
  "refund_amount": 5000,
  "status_history": [
    {
      "id": 1,
      "status_id": 2,
      "name": "REQUESTED",
      "notification": "Refund requested",
      "created_at": "2024-06-12T23:10:00.000000Z",
      "end_to_end_id": null
    },
    {
      "id": 2,
      "status_id": 4,
      "name": "PAID",
      "notification": "Refund completed",
      "created_at": "2024-06-12T23:15:00.000000Z",
      "end_to_end_id": "E1805820220621234567890AB1C2"
    }
  ]
}

​
Get Unique Refund

Returns the refund using its unique identifier.

​
Path Parameters

​
refundId
integer
required
The unique ID of the refund to retrieve.Example: 1234

​
Response

​
id
integer
Refund ID.
​
payin_id
integer
ID of the payin (payin) that was refunded.
​
status_id
integer
Current status of the refund.Status codes:
  • 2: REQUESTED
  • 4: PAID (refund completed)
  • 5: ERROR
​
user
object
User object.
​
status_id
integer
Refund status ID.
​
name
string
Refund status name.
​
notification
string
Notification message.
​
created_at
string
Creation date time.
​
end_to_end_id
string
End-to-end ID (Pix transaction identifier).
​
reason
string
Reason for the refund.
​
wallet_error_code
string
Wallet error code (if applicable).
​
notification_url
string
Payin where notification will be sent.
​
created_at
string
Creation date time.
​
updated_at
string
Update date time.
​
refund_amount
integer
Refund value in cents.
​
status_history
array
Array of status history.

​
Request Example

curl --request GET \
  --url https://api.sandbox.wepayout.com.br/v1/payin/payments/payin-refund/1234 \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer 123'

{
  "id": 12345,
  "payin_id": 32457,
  "status_id": 4,
  "user": {
    "id": 1,
    "name": "Admin User"
  },
  "name": "PAID",
  "notification": "string",
  "created_at": "2024-06-12T23:10:00.000000Z",
  "end_to_end_id": "E1805820220621234567890AB1C2",
  "reason": "Customer requested refund",
  "wallet_error_code": null,
  "notification_url": "https://client.callback.com/notify-payin",
  "updated_at": "2024-06-12T23:15:00.000000Z",
  "refund_amount": 5000,
  "status_history": [
    {
      "id": 1,
      "status_id": 2,
      "name": "REQUESTED",
      "notification": "Refund requested",
      "created_at": "2024-06-12T23:10:00.000000Z",
      "end_to_end_id": null
    },
    {
      "id": 2,
      "status_id": 4,
      "name": "PAID",
      "notification": "Refund completed",
      "created_at": "2024-06-12T23:15:00.000000Z",
      "end_to_end_id": "E1805820220621234567890AB1C2"
    }
  ]
}

​
Use Cases

Monitor the status of a refund:
async function checkRefundStatus(refundId) {
  const refund = await getRefund(refundId);
  
  const statusMap = {
    2: 'REQUESTED - Refund is being processed',
    4: 'PAID - Refund completed successfully',
    5: 'ERROR - Refund failed'
  };
  
  console.log(`Refund ${refundId}:`);
  console.log(`Status: ${statusMap[refund.status_id]}`);
  console.log(`Amount: R$ ${refund.refund_amount / 100}`);
  console.log(`Reason: ${refund.reason}`);
  
  return refund.status_id === 4;
}
View the complete history of a refund:
async function trackRefundHistory(refundId) {
  const refund = await getRefund(refundId);
  
  console.log(`Refund history for ID ${refundId}:`);
  refund.status_history.forEach(history => {
    console.log(`${history.created_at}: ${history.name} - ${history.notification}`);
  });
  
  return refund.status_history;
}
Check if a refund has been completed:
async function verifyRefundCompletion(refundId) {
  const refund = await getRefund(refundId);
  
  const isCompleted = refund.status_id === 4;
  const hasFailed = refund.status_id === 5;
  
  if (isCompleted) {
    console.log(`Refund completed successfully`);
    console.log(`End-to-end ID: ${refund.end_to_end_id}`);
    return true;
  }
  
  if (hasFailed) {
    console.log(`Refund failed`);
    console.log(`Error: ${refund.wallet_error_code}`);
    return false;
  }
  
  console.log(`Refund still processing`);
  return null;
}
Retrieve refund details for accounting reconciliation:
async function getRefundForReconciliation(refundId) {
  const refund = await getRefund(refundId);
  
  return {
    refundId: refund.id,
    payinId: refund.payin_id,
    amount: refund.refund_amount / 100,
    status: refund.name,
    endToEndId: refund.end_to_end_id,
    reason: refund.reason,
    createdAt: refund.created_at,
    completedAt: refund.updated_at,
    user: refund.user.name
  };
}

// Usage
const reconciliation = await getRefundForReconciliation(1234);
console.log('Reconciliation data:', reconciliation);
Check status of multiple refunds:
async function monitorRefunds(refundIds) {
  const results = [];
  
  for (const refundId of refundIds) {
    try {
      const refund = await getRefund(refundId);
      results.push({
        id: refundId,
        status: refund.name,
        amount: refund.refund_amount,
        completed: refund.status_id === 4
      });
    } catch (error) {
      results.push({
        id: refundId,
        error: error.message
      });
    }
  }
  
  return results;
}

// Usage
const refundIds = [1234, 1235, 1236];
const statuses = await monitorRefunds(refundIds);
console.log('Refund statuses:', statuses);

​
Status Codes

Status IDStatus NameDescription
2REQUESTEDRefund has been requested and is being processed
4PAIDRefund has been completed successfully
5ERRORRefund has failed

​
Best Practices

Status History: Use the status_history array to track the complete timeline of the refund process.
End-to-End ID: The end_to_end_id is only available after the refund is completed (status = PAID). Use it for Pix transaction tracking.
Error Handling: Always check the wallet_error_code field when status is ERROR to understand why the refund failed.

​
Integration Example

class RefundService {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = 'https://api.sandbox.wepayout.com.br/v1';
  }
  
  async getRefund(refundId) {
    const response = await fetch(
      `${this.baseUrl}/payin/payments/payin-refund/${refundId}`,
      {
        headers: {
          'Authorization': `Bearer ${this.apiKey}`,
          'Accept': 'application/json'
        }
      }
    );
    
    if (!response.ok) {
      throw new Error(`Failed to get refund: ${response.statusText}`);
    }
    
    return await response.json();
  }
  
  async waitForRefundCompletion(refundId, maxAttempts = 20, intervalMs = 5000) {
    for (let i = 0; i < maxAttempts; i++) {
      const refund = await this.getRefund(refundId);
      
      if (refund.status_id === 4) {
        return {
          success: true,
          refund,
          message: 'Refund completed successfully'
        };
      }
      
      if (refund.status_id === 5) {
        return {
          success: false,
          refund,
          message: 'Refund failed',
          error: refund.wallet_error_code
        };
      }
      
      // Still processing, wait before next check
      await new Promise(resolve => setTimeout(resolve, intervalMs));
    }
    
    return {
      success: false,
      message: 'Timeout waiting for refund completion'
    };
  }
  
  async getRefundsByPayin(payinId) {
    // This would require getting the payin first and accessing its refunds array
    // Placeholder for demonstration
    throw new Error('Not implemented - use Get Unique Charge endpoint to get refunds');
  }
}

// Usage
const refundService = new RefundService('YOUR_API_KEY');

// Get refund details
const refund = await refundService.getRefund(1234);
console.log('Refund:', refund);

// Wait for refund to complete
const result = await refundService.waitForRefundCompletion(1234);
if (result.success) {
  console.log('Refund completed:', result.refund.end_to_end_id);
} else {
  console.error('Refund failed:', result.message);
}