Account Opening Request

curl --request POST \
  --url https://api.sandbox.wepayout.com.br/v2/register/companies \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "legal_name": "<string>",
  "trade_name": "<string>",
  "tax_id": "<string>",
  "website": "<string>",
  "parent_id": 123,
  "contacts": {
    "name": "<string>",
    "email": "<string>",
    "phone": "<string>",
    "role": "<string>",
    "tax_id": "<string>"
  },
  "address": {
    "city": "<string>",
    "state": "<string>",
    "country": "<string>",
    "zip_code": "<string>",
    "street": "<string>",
    "number": "<string>",
    "complement": "<string>"
  },
  "segment": {
    "id": 123
  }
}
'

import requests

url = "https://api.sandbox.wepayout.com.br/v2/register/companies"

payload = {
    "legal_name": "<string>",
    "trade_name": "<string>",
    "tax_id": "<string>",
    "website": "<string>",
    "parent_id": 123,
    "contacts": {
        "name": "<string>",
        "email": "<string>",
        "phone": "<string>",
        "role": "<string>",
        "tax_id": "<string>"
    },
    "address": {
        "city": "<string>",
        "state": "<string>",
        "country": "<string>",
        "zip_code": "<string>",
        "street": "<string>",
        "number": "<string>",
        "complement": "<string>"
    },
    "segment": { "id": 123 }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    legal_name: '<string>',
    trade_name: '<string>',
    tax_id: '<string>',
    website: '<string>',
    parent_id: 123,
    contacts: {
      name: '<string>',
      email: '<string>',
      phone: '<string>',
      role: '<string>',
      tax_id: '<string>'
    },
    address: {
      city: '<string>',
      state: '<string>',
      country: '<string>',
      zip_code: '<string>',
      street: '<string>',
      number: '<string>',
      complement: '<string>'
    },
    segment: {id: 123}
  })
};

fetch('https://api.sandbox.wepayout.com.br/v2/register/companies', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.wepayout.com.br/v2/register/companies",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'legal_name' => '<string>',
    'trade_name' => '<string>',
    'tax_id' => '<string>',
    'website' => '<string>',
    'parent_id' => 123,
    'contacts' => [
        'name' => '<string>',
        'email' => '<string>',
        'phone' => '<string>',
        'role' => '<string>',
        'tax_id' => '<string>'
    ],
    'address' => [
        'city' => '<string>',
        'state' => '<string>',
        'country' => '<string>',
        'zip_code' => '<string>',
        'street' => '<string>',
        'number' => '<string>',
        'complement' => '<string>'
    ],
    'segment' => [
        'id' => 123
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sandbox.wepayout.com.br/v2/register/companies"

	payload := strings.NewReader("{\n  \"legal_name\": \"<string>\",\n  \"trade_name\": \"<string>\",\n  \"tax_id\": \"<string>\",\n  \"website\": \"<string>\",\n  \"parent_id\": 123,\n  \"contacts\": {\n    \"name\": \"<string>\",\n    \"email\": \"<string>\",\n    \"phone\": \"<string>\",\n    \"role\": \"<string>\",\n    \"tax_id\": \"<string>\"\n  },\n  \"address\": {\n    \"city\": \"<string>\",\n    \"state\": \"<string>\",\n    \"country\": \"<string>\",\n    \"zip_code\": \"<string>\",\n    \"street\": \"<string>\",\n    \"number\": \"<string>\",\n    \"complement\": \"<string>\"\n  },\n  \"segment\": {\n    \"id\": 123\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sandbox.wepayout.com.br/v2/register/companies")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"legal_name\": \"<string>\",\n  \"trade_name\": \"<string>\",\n  \"tax_id\": \"<string>\",\n  \"website\": \"<string>\",\n  \"parent_id\": 123,\n  \"contacts\": {\n    \"name\": \"<string>\",\n    \"email\": \"<string>\",\n    \"phone\": \"<string>\",\n    \"role\": \"<string>\",\n    \"tax_id\": \"<string>\"\n  },\n  \"address\": {\n    \"city\": \"<string>\",\n    \"state\": \"<string>\",\n    \"country\": \"<string>\",\n    \"zip_code\": \"<string>\",\n    \"street\": \"<string>\",\n    \"number\": \"<string>\",\n    \"complement\": \"<string>\"\n  },\n  \"segment\": {\n    \"id\": 123\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.wepayout.com.br/v2/register/companies")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"legal_name\": \"<string>\",\n  \"trade_name\": \"<string>\",\n  \"tax_id\": \"<string>\",\n  \"website\": \"<string>\",\n  \"parent_id\": 123,\n  \"contacts\": {\n    \"name\": \"<string>\",\n    \"email\": \"<string>\",\n    \"phone\": \"<string>\",\n    \"role\": \"<string>\",\n    \"tax_id\": \"<string>\"\n  },\n  \"address\": {\n    \"city\": \"<string>\",\n    \"state\": \"<string>\",\n    \"country\": \"<string>\",\n    \"zip_code\": \"<string>\",\n    \"street\": \"<string>\",\n    \"number\": \"<string>\",\n    \"complement\": \"<string>\"\n  },\n  \"segment\": {\n    \"id\": 123\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "339074a8-1834-49c5-af94-4a044248d88d",
  "status": "pending"
}

{
  "error_code": "validation",
  "error_description": "Validation error",
  "fields": {
    "legal_name": ["The legal name field is required."],
    "tax_id": ["The tax id must be a valid CNPJ."],
    "contacts.0.email": ["The contact e-mail field must be a valid email address."]
  }
}

POST

companies

Account Opening Request

curl --request POST \
  --url https://api.sandbox.wepayout.com.br/v2/register/companies \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "legal_name": "<string>",
  "trade_name": "<string>",
  "tax_id": "<string>",
  "website": "<string>",
  "parent_id": 123,
  "contacts": {
    "name": "<string>",
    "email": "<string>",
    "phone": "<string>",
    "role": "<string>",
    "tax_id": "<string>"
  },
  "address": {
    "city": "<string>",
    "state": "<string>",
    "country": "<string>",
    "zip_code": "<string>",
    "street": "<string>",
    "number": "<string>",
    "complement": "<string>"
  },
  "segment": {
    "id": 123
  }
}
'

import requests

url = "https://api.sandbox.wepayout.com.br/v2/register/companies"

payload = {
    "legal_name": "<string>",
    "trade_name": "<string>",
    "tax_id": "<string>",
    "website": "<string>",
    "parent_id": 123,
    "contacts": {
        "name": "<string>",
        "email": "<string>",
        "phone": "<string>",
        "role": "<string>",
        "tax_id": "<string>"
    },
    "address": {
        "city": "<string>",
        "state": "<string>",
        "country": "<string>",
        "zip_code": "<string>",
        "street": "<string>",
        "number": "<string>",
        "complement": "<string>"
    },
    "segment": { "id": 123 }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    legal_name: '<string>',
    trade_name: '<string>',
    tax_id: '<string>',
    website: '<string>',
    parent_id: 123,
    contacts: {
      name: '<string>',
      email: '<string>',
      phone: '<string>',
      role: '<string>',
      tax_id: '<string>'
    },
    address: {
      city: '<string>',
      state: '<string>',
      country: '<string>',
      zip_code: '<string>',
      street: '<string>',
      number: '<string>',
      complement: '<string>'
    },
    segment: {id: 123}
  })
};

fetch('https://api.sandbox.wepayout.com.br/v2/register/companies', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.wepayout.com.br/v2/register/companies",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'legal_name' => '<string>',
    'trade_name' => '<string>',
    'tax_id' => '<string>',
    'website' => '<string>',
    'parent_id' => 123,
    'contacts' => [
        'name' => '<string>',
        'email' => '<string>',
        'phone' => '<string>',
        'role' => '<string>',
        'tax_id' => '<string>'
    ],
    'address' => [
        'city' => '<string>',
        'state' => '<string>',
        'country' => '<string>',
        'zip_code' => '<string>',
        'street' => '<string>',
        'number' => '<string>',
        'complement' => '<string>'
    ],
    'segment' => [
        'id' => 123
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sandbox.wepayout.com.br/v2/register/companies"

	payload := strings.NewReader("{\n  \"legal_name\": \"<string>\",\n  \"trade_name\": \"<string>\",\n  \"tax_id\": \"<string>\",\n  \"website\": \"<string>\",\n  \"parent_id\": 123,\n  \"contacts\": {\n    \"name\": \"<string>\",\n    \"email\": \"<string>\",\n    \"phone\": \"<string>\",\n    \"role\": \"<string>\",\n    \"tax_id\": \"<string>\"\n  },\n  \"address\": {\n    \"city\": \"<string>\",\n    \"state\": \"<string>\",\n    \"country\": \"<string>\",\n    \"zip_code\": \"<string>\",\n    \"street\": \"<string>\",\n    \"number\": \"<string>\",\n    \"complement\": \"<string>\"\n  },\n  \"segment\": {\n    \"id\": 123\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.sandbox.wepayout.com.br/v2/register/companies")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"legal_name\": \"<string>\",\n  \"trade_name\": \"<string>\",\n  \"tax_id\": \"<string>\",\n  \"website\": \"<string>\",\n  \"parent_id\": 123,\n  \"contacts\": {\n    \"name\": \"<string>\",\n    \"email\": \"<string>\",\n    \"phone\": \"<string>\",\n    \"role\": \"<string>\",\n    \"tax_id\": \"<string>\"\n  },\n  \"address\": {\n    \"city\": \"<string>\",\n    \"state\": \"<string>\",\n    \"country\": \"<string>\",\n    \"zip_code\": \"<string>\",\n    \"street\": \"<string>\",\n    \"number\": \"<string>\",\n    \"complement\": \"<string>\"\n  },\n  \"segment\": {\n    \"id\": 123\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.sandbox.wepayout.com.br/v2/register/companies")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"legal_name\": \"<string>\",\n  \"trade_name\": \"<string>\",\n  \"tax_id\": \"<string>\",\n  \"website\": \"<string>\",\n  \"parent_id\": 123,\n  \"contacts\": {\n    \"name\": \"<string>\",\n    \"email\": \"<string>\",\n    \"phone\": \"<string>\",\n    \"role\": \"<string>\",\n    \"tax_id\": \"<string>\"\n  },\n  \"address\": {\n    \"city\": \"<string>\",\n    \"state\": \"<string>\",\n    \"country\": \"<string>\",\n    \"zip_code\": \"<string>\",\n    \"street\": \"<string>\",\n    \"number\": \"<string>\",\n    \"complement\": \"<string>\"\n  },\n  \"segment\": {\n    \"id\": 123\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "id": "339074a8-1834-49c5-af94-4a044248d88d",
  "status": "pending"
}

{
  "error_code": "validation",
  "error_description": "Validation error",
  "fields": {
    "legal_name": ["The legal name field is required."],
    "tax_id": ["The tax id must be a valid CNPJ."],
    "contacts.0.email": ["The contact e-mail field must be a valid email address."]
  }
}

Allowed Roles

Role	Required
administrator	✓
legal_representative	✓
financial	✗
commercial	✗

Request Body

string

required

Official registered name of the company as it appears in legal documents.

Min: 1 character
Max: 150 characters
Example: Company X LTDA

string

required

Common or commercial name used by the company in business operations.

Min: 1 character
Max: 150 characters
Example: Company X

string

required

Company’s tax identification number (CNPJ for Brazilian companies), without formatting.

If country = BR: exactly 14 characters (valid CNPJ), in either format issued by the Receita Federal:
- numeric — 14 digits, e.g. 12345678000199;
- alphanumeric (issued since July 2026) — letters and digits in the first 12 positions, the 2 check digits always numeric, e.g. 12ABC34501DE35.
If country ≠ BR: max 50 characters
Letters are normalized to upper case, and the mask separators (., / and -) are removed before validation — so 12.abc.345/01de-35 is stored as 12ABC34501DE35. The expected format is still the unformatted one.
Must be unique per parent — a parent cannot have two solicitations with the same tax_id, compared on the normalized value.
Example: 12345678000199

string

required

Company’s website.

Max: 255 characters
Accepted as free text: the API checks only the length, not the URL format.
Example: https://www.companyx.com

integer

Identifier of the merchant (level 1 in the account hierarchy) the solicitation will be created under. When omitted, your own company is used as the parent — which must itself be a merchant. A master/holding account (level 0) has no implicit merchant and must provide a parent_id.The parent_id must belong to your accessible companies and be a merchant; otherwise the request fails with 422.

Example: 1024

array[object]

required

List of individuals associated with the company, such as administrators, legal representatives, or other relevant roles.

Show Contact Object

string

required

Full name of the contact person.

Min: 1 character
Max: 120 characters
Example: João Silva

string

required

Contact’s professional email address.

Max: 100 characters
Example: joao.silva@companyx.com

string

required

Contact’s phone number, including country and area code.

Max: 15 characters
Example: 5511999999999

string

required

Role of the contact person within the company. Must be one of the allowed roles.

Allowed values: administrator, legal_representative, financial, commercial
Example: administrator

string

required

Personal tax identification number of the contact (CPF for Brazil), without formatting.

If country = BR: max 11 characters (valid CPF)
If country ≠ BR: max 30 characters
Example: 12345678909

object

required

Company’s main business address.

Show Address Object

string

required

City where the company is located.

Max: 40 characters
Example: São Paulo

string

required

State or province where the company is located (ISO code preferred).

Max: 4 characters
Example: SP

string

required

Country code where the company is registered (ISO 3166-1 alpha-2 format).

Max: 4 characters
Example: BR

string

required

Postal code of the company address, without formatting.

Max: 12 characters
Example: 01001000

string

required

Street name of the company address.

Max: 80 characters
Example: Av. Paulista

string

Street number of the company address.

Max: 10 characters
Example: 1000

string

Additional address details, such as suite, floor, or unit.

Max: 80 characters
Example: Conjunto 12

object

Optional business segment to associate with the company at creation time. When omitted, the company is created without a segment.

Show Segment Object

integer

Unique identifier of the segment. Must reference an existing segment, otherwise the request fails with 422 Unprocessable Entity.

Example: 7

To obtain a valid segment.id, call the List Segments endpoint (GET /v2/register/segments) and use the id of the desired segment. You can also fetch a single segment with GET /v2/register/segments?id={id} to confirm it exists before sending it.

Response

On a 422, fields maps each rejected field to its messages. The key is the path of the field in the payload you sent — tax_id, address.city, contacts.0.email — so you can show the message next to the input that caused it. Messages follow the language of the authenticated user.

string

Unique identifier of the corporate subaccount opening request.

Format: UUID
Example: 339074a8-1834-49c5-af94-4a044248d88d

string

Current status of the onboarding request.

Default: pending

{
  "id": "339074a8-1834-49c5-af94-4a044248d88d",
  "status": "pending"
}

{
  "error_code": "validation",
  "error_description": "Validation error",
  "fields": {
    "legal_name": ["The legal name field is required."],
    "tax_id": ["The tax id must be a valid CNPJ."],
    "contacts.0.email": ["The contact e-mail field must be a valid email address."]
  }
}

Setup Webhook

Configure webhook notifications for onboarding events

Update Webhook

Update existing webhook configuration

List Segments

Retrieve segment IDs to associate with a company

Account

Banks

Payin

Payout

KYC

Markup

Account Opening Request

Allowed Roles

Request Body

Response

Setup Webhook

Update Webhook

List Segments

​Allowed Roles

​Request Body

​Response

​Related Resources

Setup Webhook

Update Webhook

List Segments

Allowed Roles

Request Body

Response

Related Resources