Skip to main content

Rejection reasons payin

One of the most likely reasons for receiving a status code 400 in response to a request is compliance validation. In this scenario, the status will be set to false, indicating that the request was not fulfilled. Additionally, additional details will be provided to facilitate understanding of the error.
Message Field: “Compliance validation error”HTTP code: 400

Data Object

Upon receiving this error code, review the details provided in the Data object to understand the nature of the restriction and take appropriate action to correct the request:
  • Code: Indicates the specific type of restriction that caused the error
  • Description: Provides a brief description of the reason for the error

Rejection Codes

Code: restriction_overdueDescription EN: Rejected due to document restrictionDescription PT-BR: Rejeição devido a restrição de documento
Code: restriction_underageDescription EN: Rejected due to document restriction underage Brazilian lawDescription PT-BR: Rejeição devido a restrição de documento menor de idade pela lei brasileira
Code: restriction_deceased_holderDescription EN: Rejected due to document restriction deceased holderDescription PT-BR: Rejeição devido a restrição de documento de falecido
Code: restriction_canceledDescription EN: Rejected due to document restriction canceled documentDescription PT-BR: Rejeição devido a restrição de documento cancelado
Code: restriction_unknownDescription EN: Rejected due to document restriction unknown documentDescription PT-BR: Rejeição devido a restrição de documento não encontrado na Receita Federal
Code: restriction_pending_regularizationDescription EN: Rejected due to document restriction pending of regularizationDescription PT-BR: Rejeição devido a restrição de documento pendente de atualização
Code: restriction_suspendedDescription EN: Rejected due to document restriction suspendedDescription PT-BR: Rejeição devido a restrição de documento suspenso
Code: restriction_partners_and_ownershipDescription EN: Rejected due to document restriction partners and ownershipDescription PT-BR: Rejeição devido a restrição de documento de sócios e titularidades
Code: restriction_judicial_blockDescription EN: Rejected due to document restriction judicial blockDescription PT-BR: Rejeição devido a restrição de documento bloqueio judicial
Code: restriction_cpf_irregularDescription EN: Rejected due to document restrictionDescription PT-BR: Rejeição devido a restrição de documento
Code: restriction_list_restrictDescription EN: Rejected due to document restrictionDescription PT-BR: Rejeição devido a restrição de documento
Code: restriction_pepDescription EN: Rejected due to document restriction PEP (Politically Exposed Person)Description PT-BR: Rejeição devido a restrição de documento PEP (Pessoa Politicamente Exposta)
Code: restriction_age_above_limitDescription EN: Rejected due to restriction age as per compliance policyDescription PT-BR: Rejeição devido a restrição de idade conforme política de conformidade
Code: restriction_ofacDescription EN: Rejected due to document restriction on OFAC listDescription PT-BR: Rejeição devido a restrição de documento na lista do OFAC
Code: restriction_interpolDescription EN: Rejected due to document restriction on INTERPOL listDescription PT-BR: Rejeição devido a restrição de documento na lista da INTERPOL
Code: restriction_onuDescription EN: Rejected due to document restriction on ONU listDescription PT-BR: Rejeição devido a restrição de documento na lista da ONU
Code: restriction_euroDescription EN: Rejected due to document restriction on EURO listDescription PT-BR: Rejeição devido a restrição de documento na lista da EURO

Error Response Example

{
  "status": false,
  "message": "Compliance validation error",
  "data": {
    "code": "restriction_underage",
    "description": "Rejected due to document restriction underage Brazilian law"
  }
}

Handling Rejection Errors

1

Identify the Error Code

Check the code field in the response to identify the specific restriction type.
2

Review the Description

Read the description field to understand the reason for rejection.
3

Take Corrective Action

Based on the error code, take appropriate action:
  • Update document information
  • Verify customer age and eligibility
  • Check compliance requirements
  • Contact support if needed
4

Retry the Request

After correcting the issue, retry the payin creation request.

Common Scenarios

Underage Customer

Code: restriction_underageSolution: Verify customer age. Brazilian law requires customers to be 18+ for financial transactions.

Invalid Document

Code: restriction_canceled or restriction_unknownSolution: Verify document number is correct and valid with Brazilian Federal Revenue.

PEP Restriction

Code: restriction_pepSolution: Additional compliance checks required for Politically Exposed Persons.

Judicial Block

Code: restriction_judicial_blockSolution: Document has judicial restrictions. Customer must resolve legal issues.

Best Practices

Validate Documents Early: Implement document validation before attempting to create a payin to provide better user experience.
Compliance Requirements: Always ensure customer documents are valid and comply with Brazilian regulations before processing transactions.
Error Handling: Implement proper error handling to gracefully inform customers about rejection reasons and guide them on next steps.

Integration Example

async function createChargeWithValidation(chargeData) {
  try {
    const response = await fetch(
      'https://api.sandbox.wepayout.com.br/v2/payin/payments',
      {
        method: 'POST',
        headers: {
          'Authorization': 'Bearer YOUR_TOKEN',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(chargeData)
      }
    );
    
    const data = await response.json();
    
    if (response.status === 400 && data.message === 'Compliance validation error') {
      // Handle compliance rejection
      const { code, description } = data.data;
      
      console.error(`Compliance Error: ${code}`);
      console.error(`Description: ${description}`);
      
      // Map error codes to user-friendly messages
      const userMessage = getUserFriendlyMessage(code);
      
      return {
        success: false,
        error: code,
        userMessage
      };
    }
    
    return {
      success: true,
      charge: data
    };
    
  } catch (error) {
    console.error('Error creating charge:', error);
    throw error;
  }
}

function getUserFriendlyMessage(code) {
  const messages = {
    'restriction_underage': 'Customer must be 18 years or older to complete this transaction.',
    'restriction_canceled': 'The provided document is invalid or canceled. Please verify the document number.',
    'restriction_unknown': 'The document could not be found in the Federal Revenue database. Please verify the document number.',
    'restriction_pep': 'Additional verification is required for this transaction. Please contact support.',
    'restriction_judicial_block': 'This document has judicial restrictions. Please resolve any legal issues before proceeding.',
    'restriction_deceased_holder': 'The document belongs to a deceased person and cannot be used.',
    'restriction_suspended': 'The document is currently suspended. Please regularize the document status.',
    'restriction_ofac': 'This document appears on the OFAC sanctions list.',
    'restriction_interpol': 'This document appears on the INTERPOL list.',
    'restriction_onu': 'This document appears on the UN sanctions list.'
  };
  
  return messages[code] || 'Transaction could not be completed due to compliance restrictions.';
}

// Usage
const result = await createChargeWithValidation({
  invoice: 'INV-001',
  payment_method: 'pix',
  amount: 5000,
  currency: 'BRL',
  country: 'BR',
  buyer: {
    name: 'Customer Name',
    email: '[email protected]',
    document: {
      type: 'CPF',
      number: '12345678900'
    }
  },
  pix: {
    expire_date: '2024-12-31T23:59:59'
  }
});

if (!result.success) {
  console.log('User Message:', result.userMessage);
}