Skip to main content

​
Account Opening Process

This guide walks you through the complete process of opening a new account in WEpayments.

​
Prerequisites

Before you begin, make sure you have:
  • Valid API credentials
  • Business information ready
  • Legal representative details
  • Required documentation

​
Step 1: Prepare Business Information

Gather all required information about the business:

​
Business Details

{
  "business_name": "Example Company Ltd",
  "document": "12345678000190",
  "email": "[email protected]",
  "phone": "+5511999999999"
}

​
Address Information

{
  "address": {
    "street": "Main Street",
    "number": "123",
    "complement": "Suite 456",
    "neighborhood": "Downtown",
    "city": "São Paulo",
    "state": "SP",
    "postal_code": "01234567",
    "country": "BR"
  }
}

​
Representative Details

{
  "representative": {
    "name": "John Doe",
    "document": "12345678900",
    "email": "[email protected]",
    "phone": "+5511988888888",
    "birth_date": "1990-01-15"
  }
}

​
Step 2: Submit Account Opening Request

Make a POST request to create the account: 
const response = await fetch('https://api.wepayments.com/v1/account/opening', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    business_name: 'Example Company Ltd',
    document: '12345678000190',
    email: '[email protected]',
    phone: '+5511999999999',
    address: {
      street: 'Main Street',
      number: '123',
      complement: 'Suite 456',
      neighborhood: 'Downtown',
      city: 'São Paulo',
      state: 'SP',
      postal_code: '01234567',
      country: 'BR'
    },
    representative: {
      name: 'John Doe',
      document: '12345678900',
      email: '[email protected]',
      phone: '+5511988888888',
      birth_date: '1990-01-15'
    }
  })
});

const data = await response.json();
console.log('Account ID:', data.data.account_id);

​
Expected Response

{
  "success": true,
  "data": {
    "account_id": "acc_1234567890",
    "status": "pending",
    "created_at": "2024-01-15T10:30:00Z"
  }
}
Important: Save the account_id returned in the response. You’ll need it to track the account status.

​
Step 3: Set Up Webhook Notifications

Register a webhook to receive real-time updates about the account status: 
const webhookResponse = await fetch('https://api.wepayments.com/v1/account/webhook', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://your-domain.com/webhooks/onboarding',
    events: ['onboarding']
  })
});

​
Step 4: Monitor Account Status

You’ll receive webhook notifications as the account moves through the verification process:
1

Pending → Under Review

Compliance team starts reviewing the account
2

Under Review → Approved/Rejected

Final decision is made

​
Webhook Notification Example

{
  "event": "onboarding",
  "event_id": "evt_1234567890",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "account_id": "acc_1234567890",
    "status": "approved",
    "previous_status": "under_review",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

​
Common Issues & Solutions

Error: "Invalid document number"Solution: Ensure the document number is valid and properly formatted. For Brazil:
  • CNPJ: 14 digits
  • CPF: 11 digits
Error: "Missing required field: [field_name]"Solution: Check that all required fields are included in your request. Review the API documentation for the complete list.
Error: "Invalid address format"Solution: Ensure postal code and state code are in the correct format for the country.
Error: "Account already exists for this document"Solution: Check if an account with this document number already exists. Each document can only have one account.

​
Timeline

Typical account opening timeline:
StageDurationDescription
SubmissionInstantAPI request processed
Pending1-2 hoursInitial validation
Under Review2-5 business daysCompliance review
DecisionSame dayApproval or rejection
Timeline may vary based on the completeness of documentation and complexity of the business structure.

​
Next Steps

Webhook Integration

Set up webhook notifications

API Reference

View complete API documentation