Skip to main content
DELETE
https://api.sandbox.wepayout.com.br
/
v1
/
payin
/
payments
/
{cashInId}
/
request-cancel
Cancel Charge
curl --request DELETE \
  --url https://api.sandbox.wepayout.com.br/v1/payin/payments/{cashInId}/request-cancel \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "cashInId": "<string>"
}
'
{
  "status": true,
  "data": {
    "message": "Cancellation request submitted successfully"
  }
}

Cancel Charge

Request the cancellation of Payins of type boleto or pix.

Eligibility

Cancellation Restrictions:
  • Only Payins with status = created can be canceled
  • Payin in any other status cannot be canceled

Minimum Time Before Cancellation

  • pix: at least 5 minutes after creation
  • boleto: at least 30 minutes after creation

Behavior After Cancellation Request

  • pix: canceled instantly
  • boleto: requires at least 1 day to move from drop_requested to canceled, since the process depends on confirmation from the payment processor

Path Parameters

cashInId
string
required
The ID of the payin (charge) to cancel.Example: 32458

Request Body

cashInId
string
required
The ID of the payin to cancel (must match the path parameter).

Response

status
boolean
Indicates if the cancellation request was successful.
data
object
Response data object.

Request Example

curl --request DELETE \
  --url https://api.sandbox.wepayout.com.br/v1/payin/payments/32457/request-cancel \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer 123' \
  --header 'Content-Type: application/json' \
  --data '{
    "cashInId": "32457"
  }'
{
  "status": true,
  "data": {
    "message": "Cancellation request submitted successfully"
  }
}

Use Cases

Cancel a Pix charge that hasn’t been paid yet:
async function cancelPixCharge(chargeId) {
  // First, check if the charge is eligible for cancellation
  const charge = await getChargeById(chargeId);
  
  if (charge.payment_method !== 'pix') {
    throw new Error('Not a Pix charge');
  }
  
  if (charge.status.id !== 1) {
    throw new Error('Charge status must be "created" to cancel');
  }
  
  // Check if 5 minutes have passed since creation
  const createdAt = new Date(charge.created_at);
  const now = new Date();
  const minutesPassed = (now - createdAt) / 1000 / 60;
  
  if (minutesPassed < 5) {
    throw new Error('Must wait at least 5 minutes before canceling Pix');
  }
  
  // Cancel the charge
  const result = await cancelCharge(chargeId);
  return result;
}
Cancel a Boleto charge that hasn’t been paid:
async function cancelBoletoCharge(chargeId) {
  const charge = await getChargeById(chargeId);
  
  if (charge.payment_method !== 'boleto') {
    throw new Error('Not a Boleto charge');
  }
  
  if (charge.status.id !== 1) {
    throw new Error('Charge status must be "created" to cancel');
  }
  
  // Check if 30 minutes have passed since creation
  const createdAt = new Date(charge.created_at);
  const now = new Date();
  const minutesPassed = (now - createdAt) / 1000 / 60;
  
  if (minutesPassed < 30) {
    throw new Error('Must wait at least 30 minutes before canceling Boleto');
  }
  
  // Cancel the charge
  const result = await cancelCharge(chargeId);
  
  console.log('Boleto cancellation requested.');
  console.log('Note: It may take at least 1 day for the status to change to "canceled"');
  
  return result;
}
Cancel multiple charges at once:
async function batchCancelCharges(chargeIds) {
  const results = [];
  
  for (const chargeId of chargeIds) {
    try {
      const result = await cancelCharge(chargeId);
      results.push({
        chargeId,
        success: true,
        result
      });
    } catch (error) {
      results.push({
        chargeId,
        success: false,
        error: error.message
      });
    }
    
    // Add delay to avoid rate limiting
    await new Promise(resolve => setTimeout(resolve, 100));
  }
  
  return results;
}

// Usage
const chargesToCancel = [32457, 32458, 32459];
const results = await batchCancelCharges(chargesToCancel);
console.log('Cancellation results:', results);
Automatically cancel charges that have expired:
async function autoCancelExpiredCharges() {
  // Get all charges with status "created"
  const charges = await fetch(
    'https://api.sandbox.wepayout.com.br/v2/payin/payments?status_id=1',
    {
      headers: {
        'Authorization': 'Bearer 123',
        'Accept': 'application/json'
      }
    }
  ).then(r => r.json());
  
  const now = new Date();
  const canceledCharges = [];
  
  for (const charge of charges.data) {
    const createdAt = new Date(charge.created_at);
    const minutesPassed = (now - createdAt) / 1000 / 60;
    
    // Check if charge is eligible for cancellation
    const minMinutes = charge.payment_method === 'pix' ? 5 : 30;
    
    if (minutesPassed >= minMinutes) {
      try {
        await cancelCharge(charge.id);
        canceledCharges.push(charge.id);
      } catch (error) {
        console.error(`Failed to cancel charge ${charge.id}:`, error);
      }
    }
  }
  
  return canceledCharges;
}
Cancel a charge with full validation:
async function cancelChargeWithValidation(chargeId) {
  // Get charge details
  const charge = await getChargeById(chargeId);
  
  // Validation checks
  const validations = {
    statusCheck: charge.status.id === 1,
    paymentMethodCheck: ['pix', 'boleto'].includes(charge.payment_method),
    timeCheck: false
  };
  
  // Check minimum time
  const createdAt = new Date(charge.created_at);
  const now = new Date();
  const minutesPassed = (now - createdAt) / 1000 / 60;
  
  if (charge.payment_method === 'pix') {
    validations.timeCheck = minutesPassed >= 5;
  } else if (charge.payment_method === 'boleto') {
    validations.timeCheck = minutesPassed >= 30;
  }
  
  // Check all validations
  if (!validations.statusCheck) {
    throw new Error('Charge status must be "created"');
  }
  
  if (!validations.paymentMethodCheck) {
    throw new Error('Only pix and boleto charges can be canceled');
  }
  
  if (!validations.timeCheck) {
    const minTime = charge.payment_method === 'pix' ? 5 : 30;
    throw new Error(`Must wait at least ${minTime} minutes before canceling`);
  }
  
  // All validations passed, cancel the charge
  const result = await cancelCharge(chargeId);
  
  return {
    success: true,
    chargeId,
    paymentMethod: charge.payment_method,
    result
  };
}

Important Notes

Pix Cancellation: Pix charges are canceled instantly once the request is made.
Boleto Cancellation: Boleto charges require at least 1 day to move from drop_requested to canceled status, as the process depends on confirmation from the payment processor.
Time Requirements: Always check that the minimum time has passed before attempting to cancel:
  • Pix: 5 minutes
  • Boleto: 30 minutes

Status Flow

Pix Cancellation Flow

Created → (cancel request) → Canceled (instant)

Boleto Cancellation Flow

Created → (cancel request) → Drop Requested → (1+ day) → Canceled

Error Handling

Common errors when canceling charges:
ErrorCauseSolution
Status not “created”Charge has already been paid or canceledCannot cancel
Time requirement not metTried to cancel too soon after creationWait for minimum time
Invalid charge IDCharge doesn’t existVerify the charge ID
Payment method not supportedTrying to cancel unsupported payment typeOnly pix and boleto can be canceled