POST /v1/submerchants HTTP/1.1
Host: api-global.fastpaybrasil.com
Authorization: Basic <base64 de "SUA_CHAVE_SECRETA:">
Content-Type: application/json
{
"legalName": "LOJA EXEMPLO LTDA",
"tradeName": "Loja Exemplo",
"companyTaxId": "11.222.333/0001-81",
"website": "https://loja.exemplo.com.br",
"averageMonthlyRevenue": 30000,
"averageOrderValue": 150,
"productType": "physical",
"contactEmail": "[email protected]",
"productDescription": "Roupas e acessórios femininos",
"softDescriptor": "LOJAEXEMPLO",
"address": {
"addressLine1": "Av. Paulista, 1000",
"addressLine2": "Sala 12",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"country": "BRA",
"postalCode": "01310100"
},
"phones": [
{
"type": "mobile",
"number": "+5511987654321"
}
],
"legalRepresentative": {
"fullName": "Ana Lima",
"dateOfBirth": "1988-04-12",
"nationality": "Brasileira",
"idNumber": "52998224725",
"issuingCountry": "BRA",
"email": "[email protected]",
"motherName": "Maria Lima",
"gender": "F",
"phones": [
{
"type": "mobile",
"number": "+5511987654321"
}
]
},
"additionalRepresentatives": [
{
"fullName": "Joao Silva",
"dateOfBirth": "1985-05-10",
"nationality": "Brasileira",
"idNumber": "11144477735",
"issuingCountry": "BRA",
"email": "[email protected]",
"motherName": "Joana Silva",
"gender": "M",
"phones": [
{
"type": "mobile",
"number": "+5511987654321"
}
]
}
],
"bankAccount": {
"bankCode": "001",
"agencyCode": "1234",
"accountNumber": "567890",
"accountDigit": "0",
"accountType": "checking",
"bankName": "Banco do Brasil",
"recipientName": "LOJA EXEMPLO LTDA",
"recipientDocument": "11222333000181"
},
"canAccessDashboard": true,
"user": {
"fullName": "Ana Lima",
"email": "[email protected]",
"phone": "+5511987654321"
},
"postbackUrl": "https://meusite.com.br/webhooks/finvia/conta"
}
curl -X POST "https://api-global.fastpaybrasil.com/v1/submerchants" \
-u "$FINVIA_API_KEY:" \
-H "Content-Type: application/json" \
-d '{
"legalName": "LOJA EXEMPLO LTDA",
"tradeName": "Loja Exemplo",
"companyTaxId": "11.222.333/0001-81",
"website": "https://loja.exemplo.com.br",
"averageMonthlyRevenue": 30000,
"averageOrderValue": 150,
"productType": "physical",
"contactEmail": "[email protected]",
"productDescription": "Roupas e acessórios femininos",
"softDescriptor": "LOJAEXEMPLO",
"address": {
"addressLine1": "Av. Paulista, 1000",
"addressLine2": "Sala 12",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"country": "BRA",
"postalCode": "01310100"
},
"phones": [{ "type": "mobile", "number": "+5511987654321" }],
"legalRepresentative": {
"fullName": "Ana Lima",
"dateOfBirth": "1988-04-12",
"nationality": "Brasileira",
"idNumber": "52998224725",
"issuingCountry": "BRA",
"email": "[email protected]",
"motherName": "Maria Lima",
"gender": "F",
"phones": [{ "type": "mobile", "number": "+5511987654321" }]
},
"additionalRepresentatives": [
{
"fullName": "Joao Silva",
"dateOfBirth": "1985-05-10",
"nationality": "Brasileira",
"idNumber": "11144477735",
"issuingCountry": "BRA",
"email": "[email protected]",
"motherName": "Joana Silva",
"gender": "M",
"phones": [{ "type": "mobile", "number": "+5511987654321" }]
}
],
"bankAccount": {
"bankCode": "001",
"agencyCode": "1234",
"accountNumber": "567890",
"accountDigit": "0",
"accountType": "checking",
"bankName": "Banco do Brasil",
"recipientName": "LOJA EXEMPLO LTDA",
"recipientDocument": "11222333000181"
},
"canAccessDashboard": true,
"user": {
"fullName": "Ana Lima",
"email": "[email protected]",
"phone": "+5511987654321"
},
"postbackUrl": "https://meusite.com.br/webhooks/finvia/conta"
}'
const auth = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');
const response = await fetch('https://api-global.fastpaybrasil.com/v1/submerchants', {
method: 'POST',
headers: {
Authorization: `Basic ${auth}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
legalName: 'LOJA EXEMPLO LTDA',
tradeName: 'Loja Exemplo',
companyTaxId: '11222333000181',
website: 'https://loja.exemplo.com.br',
averageMonthlyRevenue: 30000, // R$ 30.000,00 por mês
averageOrderValue: 150, // R$ 150,00 por pedido
productType: 'physical',
contactEmail: '[email protected]',
productDescription: 'Roupas e acessórios femininos',
address: {
addressLine1: 'Av. Paulista, 1000',
neighborhood: 'Bela Vista',
city: 'São Paulo',
state: 'SP',
country: 'BRA',
postalCode: '01310100',
},
phones: [{ type: 'mobile', number: '+5511987654321' }],
legalRepresentative: {
fullName: 'Ana Lima',
dateOfBirth: '1988-04-12',
nationality: 'Brasileira',
idNumber: '52998224725',
email: '[email protected]',
motherName: 'Maria Lima',
gender: 'F',
phones: [{ type: 'mobile', number: '+5511987654321' }],
},
bankAccount: {
bankCode: '001',
agencyCode: '1234',
accountNumber: '567890',
accountDigit: '0',
accountType: 'checking',
bankName: 'Banco do Brasil',
recipientName: 'LOJA EXEMPLO LTDA',
recipientDocument: '11222333000181',
},
canAccessDashboard: false,
}),
});
const result = await response.json();
if (response.status === 201) {
// Guarde result.id e os ids de result.legalRepresentatives
console.log(result.id, result.legalRepresentatives);
} else if (response.status === 409) {
// CNPJ já cadastrado: procure a subconta existente em vez de criar outra
} else {
console.error(response.status, result.message);
}
import os
import requests
payload = {
"legalName": "LOJA EXEMPLO LTDA",
"tradeName": "Loja Exemplo",
"companyTaxId": "11.222.333/0001-81",
"website": "https://loja.exemplo.com.br",
"averageMonthlyRevenue": 30000,
"averageOrderValue": 150,
"productType": "physical",
"contactEmail": "[email protected]",
"productDescription": "Roupas e acessórios femininos",
"softDescriptor": "LOJAEXEMPLO",
"address": {
"addressLine1": "Av. Paulista, 1000",
"addressLine2": "Sala 12",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"country": "BRA",
"postalCode": "01310100",
},
"phones": [
{
"type": "mobile",
"number": "+5511987654321",
},
],
"legalRepresentative": {
"fullName": "Ana Lima",
"dateOfBirth": "1988-04-12",
"nationality": "Brasileira",
"idNumber": "52998224725",
"issuingCountry": "BRA",
"email": "[email protected]",
"motherName": "Maria Lima",
"gender": "F",
"phones": [
{
"type": "mobile",
"number": "+5511987654321",
},
],
},
"additionalRepresentatives": [
{
"fullName": "Joao Silva",
"dateOfBirth": "1985-05-10",
"nationality": "Brasileira",
"idNumber": "11144477735",
"issuingCountry": "BRA",
"email": "[email protected]",
"motherName": "Joana Silva",
"gender": "M",
"phones": [
{
"type": "mobile",
"number": "+5511987654321",
},
],
},
],
"bankAccount": {
"bankCode": "001",
"agencyCode": "1234",
"accountNumber": "567890",
"accountDigit": "0",
"accountType": "checking",
"bankName": "Banco do Brasil",
"recipientName": "LOJA EXEMPLO LTDA",
"recipientDocument": "11222333000181",
},
"canAccessDashboard": True,
"user": {
"fullName": "Ana Lima",
"email": "[email protected]",
"phone": "+5511987654321",
},
"postbackUrl": "https://meusite.com.br/webhooks/finvia/conta",
}
response = requests.request(
"POST",
"https://api-global.fastpaybrasil.com/v1/submerchants",
auth=(os.environ["FINVIA_API_KEY"], ""),
json=payload,
timeout=30,
)
print(response.status_code)
if response.content:
print(response.json())
<?php
$payload = [
'legalName' => 'LOJA EXEMPLO LTDA',
'tradeName' => 'Loja Exemplo',
'companyTaxId' => '11.222.333/0001-81',
'website' => 'https://loja.exemplo.com.br',
'averageMonthlyRevenue' => 30000,
'averageOrderValue' => 150,
'productType' => 'physical',
'contactEmail' => '[email protected]',
'productDescription' => 'Roupas e acessórios femininos',
'softDescriptor' => 'LOJAEXEMPLO',
'address' => [
'addressLine1' => 'Av. Paulista, 1000',
'addressLine2' => 'Sala 12',
'neighborhood' => 'Bela Vista',
'city' => 'São Paulo',
'state' => 'SP',
'country' => 'BRA',
'postalCode' => '01310100',
],
'phones' => [
[
'type' => 'mobile',
'number' => '+5511987654321',
],
],
'legalRepresentative' => [
'fullName' => 'Ana Lima',
'dateOfBirth' => '1988-04-12',
'nationality' => 'Brasileira',
'idNumber' => '52998224725',
'issuingCountry' => 'BRA',
'email' => '[email protected]',
'motherName' => 'Maria Lima',
'gender' => 'F',
'phones' => [
[
'type' => 'mobile',
'number' => '+5511987654321',
],
],
],
'additionalRepresentatives' => [
[
'fullName' => 'Joao Silva',
'dateOfBirth' => '1985-05-10',
'nationality' => 'Brasileira',
'idNumber' => '11144477735',
'issuingCountry' => 'BRA',
'email' => '[email protected]',
'motherName' => 'Joana Silva',
'gender' => 'M',
'phones' => [
[
'type' => 'mobile',
'number' => '+5511987654321',
],
],
],
],
'bankAccount' => [
'bankCode' => '001',
'agencyCode' => '1234',
'accountNumber' => '567890',
'accountDigit' => '0',
'accountType' => 'checking',
'bankName' => 'Banco do Brasil',
'recipientName' => 'LOJA EXEMPLO LTDA',
'recipientDocument' => '11222333000181',
],
'canAccessDashboard' => true,
'user' => [
'fullName' => 'Ana Lima',
'email' => '[email protected]',
'phone' => '+5511987654321',
],
'postbackUrl' => 'https://meusite.com.br/webhooks/finvia/conta',
];
$ch = curl_init('https://api-global.fastpaybrasil.com/v1/submerchants');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':',
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode($payload),
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $status, PHP_EOL;
print_r(json_decode($body, true));
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Base64;
public class Exemplo {
public static void main(String[] args) throws Exception {
String credentials = Base64.getEncoder()
.encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes());
String payload = """
{
"legalName": "LOJA EXEMPLO LTDA",
"tradeName": "Loja Exemplo",
"companyTaxId": "11.222.333/0001-81",
"website": "https://loja.exemplo.com.br",
"averageMonthlyRevenue": 30000,
"averageOrderValue": 150,
"productType": "physical",
"contactEmail": "[email protected]",
"productDescription": "Roupas e acessórios femininos",
"softDescriptor": "LOJAEXEMPLO",
"address": {
"addressLine1": "Av. Paulista, 1000",
"addressLine2": "Sala 12",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"country": "BRA",
"postalCode": "01310100"
},
"phones": [
{
"type": "mobile",
"number": "+5511987654321"
}
],
"legalRepresentative": {
"fullName": "Ana Lima",
"dateOfBirth": "1988-04-12",
"nationality": "Brasileira",
"idNumber": "52998224725",
"issuingCountry": "BRA",
"email": "[email protected]",
"motherName": "Maria Lima",
"gender": "F",
"phones": [
{
"type": "mobile",
"number": "+5511987654321"
}
]
},
"additionalRepresentatives": [
{
"fullName": "Joao Silva",
"dateOfBirth": "1985-05-10",
"nationality": "Brasileira",
"idNumber": "11144477735",
"issuingCountry": "BRA",
"email": "[email protected]",
"motherName": "Joana Silva",
"gender": "M",
"phones": [
{
"type": "mobile",
"number": "+5511987654321"
}
]
}
],
"bankAccount": {
"bankCode": "001",
"agencyCode": "1234",
"accountNumber": "567890",
"accountDigit": "0",
"accountType": "checking",
"bankName": "Banco do Brasil",
"recipientName": "LOJA EXEMPLO LTDA",
"recipientDocument": "11222333000181"
},
"canAccessDashboard": true,
"user": {
"fullName": "Ana Lima",
"email": "[email protected]",
"phone": "+5511987654321"
},
"postbackUrl": "https://meusite.com.br/webhooks/finvia/conta"
}
""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api-global.fastpaybrasil.com/v1/submerchants"))
.header("Authorization", "Basic " + credentials)
.header("Content-Type", "application/json")
.method("POST", HttpRequest.BodyPublishers.ofString(payload))
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode());
System.out.println(response.body());
}
}
using System.Net.Http.Headers;
using System.Text;
var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY");
var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:"));
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials);
var payload = """
{
"legalName": "LOJA EXEMPLO LTDA",
"tradeName": "Loja Exemplo",
"companyTaxId": "11.222.333/0001-81",
"website": "https://loja.exemplo.com.br",
"averageMonthlyRevenue": 30000,
"averageOrderValue": 150,
"productType": "physical",
"contactEmail": "[email protected]",
"productDescription": "Roupas e acessórios femininos",
"softDescriptor": "LOJAEXEMPLO",
"address": {
"addressLine1": "Av. Paulista, 1000",
"addressLine2": "Sala 12",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"country": "BRA",
"postalCode": "01310100"
},
"phones": [
{
"type": "mobile",
"number": "+5511987654321"
}
],
"legalRepresentative": {
"fullName": "Ana Lima",
"dateOfBirth": "1988-04-12",
"nationality": "Brasileira",
"idNumber": "52998224725",
"issuingCountry": "BRA",
"email": "[email protected]",
"motherName": "Maria Lima",
"gender": "F",
"phones": [
{
"type": "mobile",
"number": "+5511987654321"
}
]
},
"additionalRepresentatives": [
{
"fullName": "Joao Silva",
"dateOfBirth": "1985-05-10",
"nationality": "Brasileira",
"idNumber": "11144477735",
"issuingCountry": "BRA",
"email": "[email protected]",
"motherName": "Joana Silva",
"gender": "M",
"phones": [
{
"type": "mobile",
"number": "+5511987654321"
}
]
}
],
"bankAccount": {
"bankCode": "001",
"agencyCode": "1234",
"accountNumber": "567890",
"accountDigit": "0",
"accountType": "checking",
"bankName": "Banco do Brasil",
"recipientName": "LOJA EXEMPLO LTDA",
"recipientDocument": "11222333000181"
},
"canAccessDashboard": true,
"user": {
"fullName": "Ana Lima",
"email": "[email protected]",
"phone": "+5511987654321"
},
"postbackUrl": "https://meusite.com.br/webhooks/finvia/conta"
}
""";
var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/submerchants");
request.Content = new StringContent(payload, Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main
import (
"fmt"
"io"
"net/http"
"os"
"strings"
)
func main() {
payload := strings.NewReader(`{
"legalName": "LOJA EXEMPLO LTDA",
"tradeName": "Loja Exemplo",
"companyTaxId": "11.222.333/0001-81",
"website": "https://loja.exemplo.com.br",
"averageMonthlyRevenue": 30000,
"averageOrderValue": 150,
"productType": "physical",
"contactEmail": "[email protected]",
"productDescription": "Roupas e acessórios femininos",
"softDescriptor": "LOJAEXEMPLO",
"address": {
"addressLine1": "Av. Paulista, 1000",
"addressLine2": "Sala 12",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"country": "BRA",
"postalCode": "01310100"
},
"phones": [
{
"type": "mobile",
"number": "+5511987654321"
}
],
"legalRepresentative": {
"fullName": "Ana Lima",
"dateOfBirth": "1988-04-12",
"nationality": "Brasileira",
"idNumber": "52998224725",
"issuingCountry": "BRA",
"email": "[email protected]",
"motherName": "Maria Lima",
"gender": "F",
"phones": [
{
"type": "mobile",
"number": "+5511987654321"
}
]
},
"additionalRepresentatives": [
{
"fullName": "Joao Silva",
"dateOfBirth": "1985-05-10",
"nationality": "Brasileira",
"idNumber": "11144477735",
"issuingCountry": "BRA",
"email": "[email protected]",
"motherName": "Joana Silva",
"gender": "M",
"phones": [
{
"type": "mobile",
"number": "+5511987654321"
}
]
}
],
"bankAccount": {
"bankCode": "001",
"agencyCode": "1234",
"accountNumber": "567890",
"accountDigit": "0",
"accountType": "checking",
"bankName": "Banco do Brasil",
"recipientName": "LOJA EXEMPLO LTDA",
"recipientDocument": "11222333000181"
},
"canAccessDashboard": true,
"user": {
"fullName": "Ana Lima",
"email": "[email protected]",
"phone": "+5511987654321"
},
"postbackUrl": "https://meusite.com.br/webhooks/finvia/conta"
}`)
req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/submerchants", payload)
if err != nil {
panic(err)
}
req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "")
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res.StatusCode)
fmt.Println(string(body))
}
require "json"
require "net/http"
require "uri"
uri = URI("https://api-global.fastpaybrasil.com/v1/submerchants")
request = Net::HTTP::Post.new(uri)
request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "")
request["Content-Type"] = "application/json"
request.body = JSON.generate({
"legalName" => "LOJA EXEMPLO LTDA",
"tradeName" => "Loja Exemplo",
"companyTaxId" => "11.222.333/0001-81",
"website" => "https://loja.exemplo.com.br",
"averageMonthlyRevenue" => 30000,
"averageOrderValue" => 150,
"productType" => "physical",
"contactEmail" => "[email protected]",
"productDescription" => "Roupas e acessórios femininos",
"softDescriptor" => "LOJAEXEMPLO",
"address" => {
"addressLine1" => "Av. Paulista, 1000",
"addressLine2" => "Sala 12",
"neighborhood" => "Bela Vista",
"city" => "São Paulo",
"state" => "SP",
"country" => "BRA",
"postalCode" => "01310100",
},
"phones" => [
{
"type" => "mobile",
"number" => "+5511987654321",
},
],
"legalRepresentative" => {
"fullName" => "Ana Lima",
"dateOfBirth" => "1988-04-12",
"nationality" => "Brasileira",
"idNumber" => "52998224725",
"issuingCountry" => "BRA",
"email" => "[email protected]",
"motherName" => "Maria Lima",
"gender" => "F",
"phones" => [
{
"type" => "mobile",
"number" => "+5511987654321",
},
],
},
"additionalRepresentatives" => [
{
"fullName" => "Joao Silva",
"dateOfBirth" => "1985-05-10",
"nationality" => "Brasileira",
"idNumber" => "11144477735",
"issuingCountry" => "BRA",
"email" => "[email protected]",
"motherName" => "Joana Silva",
"gender" => "M",
"phones" => [
{
"type" => "mobile",
"number" => "+5511987654321",
},
],
},
],
"bankAccount" => {
"bankCode" => "001",
"agencyCode" => "1234",
"accountNumber" => "567890",
"accountDigit" => "0",
"accountType" => "checking",
"bankName" => "Banco do Brasil",
"recipientName" => "LOJA EXEMPLO LTDA",
"recipientDocument" => "11222333000181",
},
"canAccessDashboard" => true,
"user" => {
"fullName" => "Ana Lima",
"email" => "[email protected]",
"phone" => "+5511987654321",
},
"postbackUrl" => "https://meusite.com.br/webhooks/finvia/conta",
})
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
puts response.code
puts response.body
{
"id": "36OO3bcGjhPjjF3tzrqOGcmQuKo",
"legalRepresentatives": [
{
"id": "2vorkEaaaBbbCccDddEeeFffGgg",
"fullName": "Ana Lima",
"isPrimary": true
},
{
"id": "2vorkEbbbCccDddEeeFffGggHhh",
"fullName": "Joao Silva",
"isPrimary": false
}
]
}
{
"statusCode": 400,
"message": ["address.country must be a valid ISO31661 Alpha3 code"],
"error": "Bad Request"
}
{ "statusCode": 403, "message": "Fast Connect not enabled." }
{
"statusCode": 409,
"message": "Já existe um cadastro com este CNPJ. Consulte o registro existente ou acione o time de Risco.",
"error": "Conflict"
}
Connect
Criar subconta
Cadastra uma subconta ligada à sua conta master, com dados da empresa, representante legal, sócios e conta bancária.
POST
/
v1
/
submerchants
POST /v1/submerchants HTTP/1.1
Host: api-global.fastpaybrasil.com
Authorization: Basic <base64 de "SUA_CHAVE_SECRETA:">
Content-Type: application/json
{
"legalName": "LOJA EXEMPLO LTDA",
"tradeName": "Loja Exemplo",
"companyTaxId": "11.222.333/0001-81",
"website": "https://loja.exemplo.com.br",
"averageMonthlyRevenue": 30000,
"averageOrderValue": 150,
"productType": "physical",
"contactEmail": "[email protected]",
"productDescription": "Roupas e acessórios femininos",
"softDescriptor": "LOJAEXEMPLO",
"address": {
"addressLine1": "Av. Paulista, 1000",
"addressLine2": "Sala 12",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"country": "BRA",
"postalCode": "01310100"
},
"phones": [
{
"type": "mobile",
"number": "+5511987654321"
}
],
"legalRepresentative": {
"fullName": "Ana Lima",
"dateOfBirth": "1988-04-12",
"nationality": "Brasileira",
"idNumber": "52998224725",
"issuingCountry": "BRA",
"email": "[email protected]",
"motherName": "Maria Lima",
"gender": "F",
"phones": [
{
"type": "mobile",
"number": "+5511987654321"
}
]
},
"additionalRepresentatives": [
{
"fullName": "Joao Silva",
"dateOfBirth": "1985-05-10",
"nationality": "Brasileira",
"idNumber": "11144477735",
"issuingCountry": "BRA",
"email": "[email protected]",
"motherName": "Joana Silva",
"gender": "M",
"phones": [
{
"type": "mobile",
"number": "+5511987654321"
}
]
}
],
"bankAccount": {
"bankCode": "001",
"agencyCode": "1234",
"accountNumber": "567890",
"accountDigit": "0",
"accountType": "checking",
"bankName": "Banco do Brasil",
"recipientName": "LOJA EXEMPLO LTDA",
"recipientDocument": "11222333000181"
},
"canAccessDashboard": true,
"user": {
"fullName": "Ana Lima",
"email": "[email protected]",
"phone": "+5511987654321"
},
"postbackUrl": "https://meusite.com.br/webhooks/finvia/conta"
}
curl -X POST "https://api-global.fastpaybrasil.com/v1/submerchants" \
-u "$FINVIA_API_KEY:" \
-H "Content-Type: application/json" \
-d '{
"legalName": "LOJA EXEMPLO LTDA",
"tradeName": "Loja Exemplo",
"companyTaxId": "11.222.333/0001-81",
"website": "https://loja.exemplo.com.br",
"averageMonthlyRevenue": 30000,
"averageOrderValue": 150,
"productType": "physical",
"contactEmail": "[email protected]",
"productDescription": "Roupas e acessórios femininos",
"softDescriptor": "LOJAEXEMPLO",
"address": {
"addressLine1": "Av. Paulista, 1000",
"addressLine2": "Sala 12",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"country": "BRA",
"postalCode": "01310100"
},
"phones": [{ "type": "mobile", "number": "+5511987654321" }],
"legalRepresentative": {
"fullName": "Ana Lima",
"dateOfBirth": "1988-04-12",
"nationality": "Brasileira",
"idNumber": "52998224725",
"issuingCountry": "BRA",
"email": "[email protected]",
"motherName": "Maria Lima",
"gender": "F",
"phones": [{ "type": "mobile", "number": "+5511987654321" }]
},
"additionalRepresentatives": [
{
"fullName": "Joao Silva",
"dateOfBirth": "1985-05-10",
"nationality": "Brasileira",
"idNumber": "11144477735",
"issuingCountry": "BRA",
"email": "[email protected]",
"motherName": "Joana Silva",
"gender": "M",
"phones": [{ "type": "mobile", "number": "+5511987654321" }]
}
],
"bankAccount": {
"bankCode": "001",
"agencyCode": "1234",
"accountNumber": "567890",
"accountDigit": "0",
"accountType": "checking",
"bankName": "Banco do Brasil",
"recipientName": "LOJA EXEMPLO LTDA",
"recipientDocument": "11222333000181"
},
"canAccessDashboard": true,
"user": {
"fullName": "Ana Lima",
"email": "[email protected]",
"phone": "+5511987654321"
},
"postbackUrl": "https://meusite.com.br/webhooks/finvia/conta"
}'
const auth = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');
const response = await fetch('https://api-global.fastpaybrasil.com/v1/submerchants', {
method: 'POST',
headers: {
Authorization: `Basic ${auth}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
legalName: 'LOJA EXEMPLO LTDA',
tradeName: 'Loja Exemplo',
companyTaxId: '11222333000181',
website: 'https://loja.exemplo.com.br',
averageMonthlyRevenue: 30000, // R$ 30.000,00 por mês
averageOrderValue: 150, // R$ 150,00 por pedido
productType: 'physical',
contactEmail: '[email protected]',
productDescription: 'Roupas e acessórios femininos',
address: {
addressLine1: 'Av. Paulista, 1000',
neighborhood: 'Bela Vista',
city: 'São Paulo',
state: 'SP',
country: 'BRA',
postalCode: '01310100',
},
phones: [{ type: 'mobile', number: '+5511987654321' }],
legalRepresentative: {
fullName: 'Ana Lima',
dateOfBirth: '1988-04-12',
nationality: 'Brasileira',
idNumber: '52998224725',
email: '[email protected]',
motherName: 'Maria Lima',
gender: 'F',
phones: [{ type: 'mobile', number: '+5511987654321' }],
},
bankAccount: {
bankCode: '001',
agencyCode: '1234',
accountNumber: '567890',
accountDigit: '0',
accountType: 'checking',
bankName: 'Banco do Brasil',
recipientName: 'LOJA EXEMPLO LTDA',
recipientDocument: '11222333000181',
},
canAccessDashboard: false,
}),
});
const result = await response.json();
if (response.status === 201) {
// Guarde result.id e os ids de result.legalRepresentatives
console.log(result.id, result.legalRepresentatives);
} else if (response.status === 409) {
// CNPJ já cadastrado: procure a subconta existente em vez de criar outra
} else {
console.error(response.status, result.message);
}
import os
import requests
payload = {
"legalName": "LOJA EXEMPLO LTDA",
"tradeName": "Loja Exemplo",
"companyTaxId": "11.222.333/0001-81",
"website": "https://loja.exemplo.com.br",
"averageMonthlyRevenue": 30000,
"averageOrderValue": 150,
"productType": "physical",
"contactEmail": "[email protected]",
"productDescription": "Roupas e acessórios femininos",
"softDescriptor": "LOJAEXEMPLO",
"address": {
"addressLine1": "Av. Paulista, 1000",
"addressLine2": "Sala 12",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"country": "BRA",
"postalCode": "01310100",
},
"phones": [
{
"type": "mobile",
"number": "+5511987654321",
},
],
"legalRepresentative": {
"fullName": "Ana Lima",
"dateOfBirth": "1988-04-12",
"nationality": "Brasileira",
"idNumber": "52998224725",
"issuingCountry": "BRA",
"email": "[email protected]",
"motherName": "Maria Lima",
"gender": "F",
"phones": [
{
"type": "mobile",
"number": "+5511987654321",
},
],
},
"additionalRepresentatives": [
{
"fullName": "Joao Silva",
"dateOfBirth": "1985-05-10",
"nationality": "Brasileira",
"idNumber": "11144477735",
"issuingCountry": "BRA",
"email": "[email protected]",
"motherName": "Joana Silva",
"gender": "M",
"phones": [
{
"type": "mobile",
"number": "+5511987654321",
},
],
},
],
"bankAccount": {
"bankCode": "001",
"agencyCode": "1234",
"accountNumber": "567890",
"accountDigit": "0",
"accountType": "checking",
"bankName": "Banco do Brasil",
"recipientName": "LOJA EXEMPLO LTDA",
"recipientDocument": "11222333000181",
},
"canAccessDashboard": True,
"user": {
"fullName": "Ana Lima",
"email": "[email protected]",
"phone": "+5511987654321",
},
"postbackUrl": "https://meusite.com.br/webhooks/finvia/conta",
}
response = requests.request(
"POST",
"https://api-global.fastpaybrasil.com/v1/submerchants",
auth=(os.environ["FINVIA_API_KEY"], ""),
json=payload,
timeout=30,
)
print(response.status_code)
if response.content:
print(response.json())
<?php
$payload = [
'legalName' => 'LOJA EXEMPLO LTDA',
'tradeName' => 'Loja Exemplo',
'companyTaxId' => '11.222.333/0001-81',
'website' => 'https://loja.exemplo.com.br',
'averageMonthlyRevenue' => 30000,
'averageOrderValue' => 150,
'productType' => 'physical',
'contactEmail' => '[email protected]',
'productDescription' => 'Roupas e acessórios femininos',
'softDescriptor' => 'LOJAEXEMPLO',
'address' => [
'addressLine1' => 'Av. Paulista, 1000',
'addressLine2' => 'Sala 12',
'neighborhood' => 'Bela Vista',
'city' => 'São Paulo',
'state' => 'SP',
'country' => 'BRA',
'postalCode' => '01310100',
],
'phones' => [
[
'type' => 'mobile',
'number' => '+5511987654321',
],
],
'legalRepresentative' => [
'fullName' => 'Ana Lima',
'dateOfBirth' => '1988-04-12',
'nationality' => 'Brasileira',
'idNumber' => '52998224725',
'issuingCountry' => 'BRA',
'email' => '[email protected]',
'motherName' => 'Maria Lima',
'gender' => 'F',
'phones' => [
[
'type' => 'mobile',
'number' => '+5511987654321',
],
],
],
'additionalRepresentatives' => [
[
'fullName' => 'Joao Silva',
'dateOfBirth' => '1985-05-10',
'nationality' => 'Brasileira',
'idNumber' => '11144477735',
'issuingCountry' => 'BRA',
'email' => '[email protected]',
'motherName' => 'Joana Silva',
'gender' => 'M',
'phones' => [
[
'type' => 'mobile',
'number' => '+5511987654321',
],
],
],
],
'bankAccount' => [
'bankCode' => '001',
'agencyCode' => '1234',
'accountNumber' => '567890',
'accountDigit' => '0',
'accountType' => 'checking',
'bankName' => 'Banco do Brasil',
'recipientName' => 'LOJA EXEMPLO LTDA',
'recipientDocument' => '11222333000181',
],
'canAccessDashboard' => true,
'user' => [
'fullName' => 'Ana Lima',
'email' => '[email protected]',
'phone' => '+5511987654321',
],
'postbackUrl' => 'https://meusite.com.br/webhooks/finvia/conta',
];
$ch = curl_init('https://api-global.fastpaybrasil.com/v1/submerchants');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':',
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode($payload),
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $status, PHP_EOL;
print_r(json_decode($body, true));
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Base64;
public class Exemplo {
public static void main(String[] args) throws Exception {
String credentials = Base64.getEncoder()
.encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes());
String payload = """
{
"legalName": "LOJA EXEMPLO LTDA",
"tradeName": "Loja Exemplo",
"companyTaxId": "11.222.333/0001-81",
"website": "https://loja.exemplo.com.br",
"averageMonthlyRevenue": 30000,
"averageOrderValue": 150,
"productType": "physical",
"contactEmail": "[email protected]",
"productDescription": "Roupas e acessórios femininos",
"softDescriptor": "LOJAEXEMPLO",
"address": {
"addressLine1": "Av. Paulista, 1000",
"addressLine2": "Sala 12",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"country": "BRA",
"postalCode": "01310100"
},
"phones": [
{
"type": "mobile",
"number": "+5511987654321"
}
],
"legalRepresentative": {
"fullName": "Ana Lima",
"dateOfBirth": "1988-04-12",
"nationality": "Brasileira",
"idNumber": "52998224725",
"issuingCountry": "BRA",
"email": "[email protected]",
"motherName": "Maria Lima",
"gender": "F",
"phones": [
{
"type": "mobile",
"number": "+5511987654321"
}
]
},
"additionalRepresentatives": [
{
"fullName": "Joao Silva",
"dateOfBirth": "1985-05-10",
"nationality": "Brasileira",
"idNumber": "11144477735",
"issuingCountry": "BRA",
"email": "[email protected]",
"motherName": "Joana Silva",
"gender": "M",
"phones": [
{
"type": "mobile",
"number": "+5511987654321"
}
]
}
],
"bankAccount": {
"bankCode": "001",
"agencyCode": "1234",
"accountNumber": "567890",
"accountDigit": "0",
"accountType": "checking",
"bankName": "Banco do Brasil",
"recipientName": "LOJA EXEMPLO LTDA",
"recipientDocument": "11222333000181"
},
"canAccessDashboard": true,
"user": {
"fullName": "Ana Lima",
"email": "[email protected]",
"phone": "+5511987654321"
},
"postbackUrl": "https://meusite.com.br/webhooks/finvia/conta"
}
""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api-global.fastpaybrasil.com/v1/submerchants"))
.header("Authorization", "Basic " + credentials)
.header("Content-Type", "application/json")
.method("POST", HttpRequest.BodyPublishers.ofString(payload))
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode());
System.out.println(response.body());
}
}
using System.Net.Http.Headers;
using System.Text;
var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY");
var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:"));
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials);
var payload = """
{
"legalName": "LOJA EXEMPLO LTDA",
"tradeName": "Loja Exemplo",
"companyTaxId": "11.222.333/0001-81",
"website": "https://loja.exemplo.com.br",
"averageMonthlyRevenue": 30000,
"averageOrderValue": 150,
"productType": "physical",
"contactEmail": "[email protected]",
"productDescription": "Roupas e acessórios femininos",
"softDescriptor": "LOJAEXEMPLO",
"address": {
"addressLine1": "Av. Paulista, 1000",
"addressLine2": "Sala 12",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"country": "BRA",
"postalCode": "01310100"
},
"phones": [
{
"type": "mobile",
"number": "+5511987654321"
}
],
"legalRepresentative": {
"fullName": "Ana Lima",
"dateOfBirth": "1988-04-12",
"nationality": "Brasileira",
"idNumber": "52998224725",
"issuingCountry": "BRA",
"email": "[email protected]",
"motherName": "Maria Lima",
"gender": "F",
"phones": [
{
"type": "mobile",
"number": "+5511987654321"
}
]
},
"additionalRepresentatives": [
{
"fullName": "Joao Silva",
"dateOfBirth": "1985-05-10",
"nationality": "Brasileira",
"idNumber": "11144477735",
"issuingCountry": "BRA",
"email": "[email protected]",
"motherName": "Joana Silva",
"gender": "M",
"phones": [
{
"type": "mobile",
"number": "+5511987654321"
}
]
}
],
"bankAccount": {
"bankCode": "001",
"agencyCode": "1234",
"accountNumber": "567890",
"accountDigit": "0",
"accountType": "checking",
"bankName": "Banco do Brasil",
"recipientName": "LOJA EXEMPLO LTDA",
"recipientDocument": "11222333000181"
},
"canAccessDashboard": true,
"user": {
"fullName": "Ana Lima",
"email": "[email protected]",
"phone": "+5511987654321"
},
"postbackUrl": "https://meusite.com.br/webhooks/finvia/conta"
}
""";
var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/submerchants");
request.Content = new StringContent(payload, Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main
import (
"fmt"
"io"
"net/http"
"os"
"strings"
)
func main() {
payload := strings.NewReader(`{
"legalName": "LOJA EXEMPLO LTDA",
"tradeName": "Loja Exemplo",
"companyTaxId": "11.222.333/0001-81",
"website": "https://loja.exemplo.com.br",
"averageMonthlyRevenue": 30000,
"averageOrderValue": 150,
"productType": "physical",
"contactEmail": "[email protected]",
"productDescription": "Roupas e acessórios femininos",
"softDescriptor": "LOJAEXEMPLO",
"address": {
"addressLine1": "Av. Paulista, 1000",
"addressLine2": "Sala 12",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"country": "BRA",
"postalCode": "01310100"
},
"phones": [
{
"type": "mobile",
"number": "+5511987654321"
}
],
"legalRepresentative": {
"fullName": "Ana Lima",
"dateOfBirth": "1988-04-12",
"nationality": "Brasileira",
"idNumber": "52998224725",
"issuingCountry": "BRA",
"email": "[email protected]",
"motherName": "Maria Lima",
"gender": "F",
"phones": [
{
"type": "mobile",
"number": "+5511987654321"
}
]
},
"additionalRepresentatives": [
{
"fullName": "Joao Silva",
"dateOfBirth": "1985-05-10",
"nationality": "Brasileira",
"idNumber": "11144477735",
"issuingCountry": "BRA",
"email": "[email protected]",
"motherName": "Joana Silva",
"gender": "M",
"phones": [
{
"type": "mobile",
"number": "+5511987654321"
}
]
}
],
"bankAccount": {
"bankCode": "001",
"agencyCode": "1234",
"accountNumber": "567890",
"accountDigit": "0",
"accountType": "checking",
"bankName": "Banco do Brasil",
"recipientName": "LOJA EXEMPLO LTDA",
"recipientDocument": "11222333000181"
},
"canAccessDashboard": true,
"user": {
"fullName": "Ana Lima",
"email": "[email protected]",
"phone": "+5511987654321"
},
"postbackUrl": "https://meusite.com.br/webhooks/finvia/conta"
}`)
req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/submerchants", payload)
if err != nil {
panic(err)
}
req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "")
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res.StatusCode)
fmt.Println(string(body))
}
require "json"
require "net/http"
require "uri"
uri = URI("https://api-global.fastpaybrasil.com/v1/submerchants")
request = Net::HTTP::Post.new(uri)
request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "")
request["Content-Type"] = "application/json"
request.body = JSON.generate({
"legalName" => "LOJA EXEMPLO LTDA",
"tradeName" => "Loja Exemplo",
"companyTaxId" => "11.222.333/0001-81",
"website" => "https://loja.exemplo.com.br",
"averageMonthlyRevenue" => 30000,
"averageOrderValue" => 150,
"productType" => "physical",
"contactEmail" => "[email protected]",
"productDescription" => "Roupas e acessórios femininos",
"softDescriptor" => "LOJAEXEMPLO",
"address" => {
"addressLine1" => "Av. Paulista, 1000",
"addressLine2" => "Sala 12",
"neighborhood" => "Bela Vista",
"city" => "São Paulo",
"state" => "SP",
"country" => "BRA",
"postalCode" => "01310100",
},
"phones" => [
{
"type" => "mobile",
"number" => "+5511987654321",
},
],
"legalRepresentative" => {
"fullName" => "Ana Lima",
"dateOfBirth" => "1988-04-12",
"nationality" => "Brasileira",
"idNumber" => "52998224725",
"issuingCountry" => "BRA",
"email" => "[email protected]",
"motherName" => "Maria Lima",
"gender" => "F",
"phones" => [
{
"type" => "mobile",
"number" => "+5511987654321",
},
],
},
"additionalRepresentatives" => [
{
"fullName" => "Joao Silva",
"dateOfBirth" => "1985-05-10",
"nationality" => "Brasileira",
"idNumber" => "11144477735",
"issuingCountry" => "BRA",
"email" => "[email protected]",
"motherName" => "Joana Silva",
"gender" => "M",
"phones" => [
{
"type" => "mobile",
"number" => "+5511987654321",
},
],
},
],
"bankAccount" => {
"bankCode" => "001",
"agencyCode" => "1234",
"accountNumber" => "567890",
"accountDigit" => "0",
"accountType" => "checking",
"bankName" => "Banco do Brasil",
"recipientName" => "LOJA EXEMPLO LTDA",
"recipientDocument" => "11222333000181",
},
"canAccessDashboard" => true,
"user" => {
"fullName" => "Ana Lima",
"email" => "[email protected]",
"phone" => "+5511987654321",
},
"postbackUrl" => "https://meusite.com.br/webhooks/finvia/conta",
})
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
puts response.code
puts response.body
{
"id": "36OO3bcGjhPjjF3tzrqOGcmQuKo",
"legalRepresentatives": [
{
"id": "2vorkEaaaBbbCccDddEeeFffGgg",
"fullName": "Ana Lima",
"isPrimary": true
},
{
"id": "2vorkEbbbCccDddEeeFffGggHhh",
"fullName": "Joao Silva",
"isPrimary": false
}
]
}
{
"statusCode": 400,
"message": ["address.country must be a valid ISO31661 Alpha3 code"],
"error": "Bad Request"
}
{ "statusCode": 403, "message": "Fast Connect not enabled." }
{
"statusCode": 409,
"message": "Já existe um cadastro com este CNPJ. Consulte o registro existente ou acione o time de Risco.",
"error": "Conflict"
}
Esta rota cria uma subconta (SubMerchant) da Finvia vinculada à sua conta master (MerchantMaster) no Connect. É o primeiro passo para colocar um vendedor, franqueado ou parceiro para receber pagamentos dentro da sua plataforma. A subconta nasce em análise (
Todos os campos de país da subconta usam ISO 3166-1 alpha-3:
As mensagens misturam português e inglês. Trate o erro pelo código HTTP e use a mensagem para registro ou exibição.
pending) e só pode transacionar depois de aprovada no credenciamento (KYC, a verificação de identidade da empresa e dos sócios).
Quando usar
| Situação | Como usar esta rota |
|---|---|
| Vendedor novo se cadastra na sua plataforma | Envie os dados da empresa, o representante legal e a conta bancária |
| Empresa com mais de um sócio | Envie também additionalRepresentatives e guarde os id devolvidos em legalRepresentatives |
| O vendedor vai usar o painel da Finvia | canAccessDashboard: true e o objeto user |
| O vendedor só vai operar pelo seu sistema | canAccessDashboard: false, sem user |
| Consultar uma subconta já criada | Use Consultar subconta |
Antes de chamar
- O módulo Connect precisa estar habilitado pela Finvia na sua conta master. Sem isso, a resposta é
403Fast Connect not enabled.. - Autentique com a chave secreta (
sk_) da conta master (Credenciais e ambientes). - Pré-valide o cadastro do lojista do seu lado antes de enviar, como pedem as Regras de credenciamento.
- Tenha em mãos os dados da empresa, do representante legal (e dos demais sócios, se houver) e da conta bancária de recebimento.
- Os documentos (cartão CNPJ, contrato social, documento com foto e selfie) não vão nesta chamada. Eles são enviados depois, com o
iddevolvido aqui (Sócios e documentos).
Para o negócio: na criação, a subconta recebe uma cópia das taxas e configurações vigentes da conta master. Depois disso, as taxas da subconta são independentes: mudar as taxas da master não altera as das subcontas já criadas. As taxas de cada subconta podem ser consultadas em Taxas e dados da subconta.
Corpo da requisição
Campos obrigatórios:legalName, tradeName, companyTaxId, website, averageMonthlyRevenue, averageOrderValue, productType, legalRepresentative, contactEmail, productDescription, address, phones, bankAccount e canAccessDashboard.
Dados da empresa
CNPJ da empresa, com ou sem máscara. Quando
address.country é BRA, precisa ser um CPF ou CNPJ com dígito verificador válido. O valor é gravado só com dígitos. Ex.: 11.222.333/0001-81.Site da empresa (formato
uri). Informe a URL onde estão os produtos ou serviços que serão vendidos: ela é conferida no credenciamento. Ex.: https://loja.exemplo.com.br.E-mail de contato da empresa. Ex.:
[email protected].Nome que aparece na fatura do cartão do cliente. Máximo de 40 caracteres (
maxLength 40). Ex.: LOJAEXEMPLO.Endereço da empresa. O país define as regras dos outros campos (veja a tabela abaixo).
Show propriedades
Show propriedades
Logradouro e número, separados por vírgula, com o número no fim. Ex.:
Av. Paulista, 1000. O número é extraído desse formato para o credenciamento nas adquirentes. Sem vírgula e número no fim, ele pode ser enviado como “S/N”.Complemento (apartamento, sala, bloco, andar). Opcional; se omitido, é gravado vazio. Ex.:
Sala 12.Ponto de referência do endereço. Opcional, até 255 caracteres. Ex.:
Próximo à estação Trianon-Masp.País, em ISO 3166-1 alpha-3 (três letras maiúsculas, padrão
^[A-Z]{3}$). Ex.: BRA. O formato alpha-2 (BR) é recusado com 400.Regras que dependem do país
| Campo | Quando o país do endereço é BRA |
|---|---|
companyTaxId | CPF ou CNPJ com dígito verificador válido |
address.state | UF válida (ex.: SP) |
address.postalCode | CEP com 8 dígitos |
address.neighborhood | Obrigatório |
idNumber do representante e dos sócios | CPF válido quando issuingCountry é BRA ou não é enviado |
address.country, address.country do representante e dos sócios, e issuingCountry. A validação não diferencia maiúsculas de minúsculas, mas o valor é gravado como foi enviado: envie sempre em maiúsculas.
Representante legal e sócios
Representante legal da empresa. É sempre o representante principal da subconta (
isPrimary: true), e os documentos de pessoa enviados sem indicar um sócio ficam ligados a ele.Show propriedades
Show propriedades
Número do documento. Precisa ser um CPF válido quando
issuingCountry é BRA ou não é enviado. Ex.: 52998224725.E-mail. Ex.:
[email protected].Endereço próprio do representante. Opcional: sem ele, o representante usa o endereço da empresa. Quando enviado,
country é obrigatório.Show propriedades
Show propriedades
Sócios adicionais da empresa (opcional). Cada item tem o mesmo formato do
legalRepresentative, com as mesmas regras de país e de CPF. O legalRepresentative continua obrigatório e é sempre o representante legal; os adicionais são cadastrados como sócios. Os documentos dos sócios não vão neste corpo: depois da criação, use os id devolvidos em legalRepresentatives para enviar os documentos de cada sócio com token de upload.O campo
referencePoint só é gravado no endereço da empresa. No endereço próprio do representante ou de um sócio ele é aceito, mas descartado.Conta bancária
Conta bancária da subconta. Todos os campos são obrigatórios, exceto
routingNumber.Show propriedades
Show propriedades
CPF ou CNPJ do titular da conta, validado pelos dígitos verificadores. Ex.:
11222333000181.companyTaxId, idNumber (do representante e dos sócios) e bankAccount.recipientDocument são validados pelos dígitos verificadores. Os números dos exemplos desta página são válidos só para teste de formato: na sua integração, envie os documentos reais do lojista.Acesso ao painel e notificações
Usuário que vai acessar o painel. Obrigatório quando
canAccessDashboard é true. Quando o objeto é enviado, os três campos são obrigatórios. Se o e-mail já tiver usuário cadastrado, a resposta é 400 Email already registered.Show propriedades
Show propriedades
E-mail do usuário. Ex.:
[email protected].URL (formato
uri) para receber os avisos de mudança de status da subconta. Opcional. Ex.: https://meusite.com.br/webhooks/finvia/conta.A URL fica salva nas configurações da subconta. Para alterá-la depois, fale com o suporte. Sem postbackUrl, a subconta usa a URL de aviso de status da conta master, se a master tiver uma. Esta URL não recebe eventos de cobrança. O aviso vem sem envelope, em camelCase, com merchantId, status, date e, quando o status é rejected ou correcting, rejectionReason. Veja Webhooks de conta.Respostas
A resposta201 traz só o id da subconta e os representantes criados. Para ver o cadastro completo, use Consultar subconta.
Identificador da subconta criada. Ex.:
36OO3bcGjhPjjF3tzrqOGcmQuKo. Guarde este valor: ele é usado para enviar documentos, consultar a subconta, obter as chaves de API e pedir saques.Representantes criados: o representante legal primeiro (
isPrimary: true) e depois os sócios adicionais, na ordem enviada. Use os id dos itens com isPrimary: false para enviar os documentos de cada sócio.| HTTP | Significado | Corpo |
|---|---|---|
201 | Subconta criada | id, legalRepresentatives |
400 | Corpo inválido, com message em lista | {"statusCode": 400, "message": ["bankAccount.bankCode should not be empty"], "error": "Bad Request"} |
400 | E-mail do usuário do painel já cadastrado (com canAccessDashboard: true) | {"statusCode": 400, "message": "Email already registered", "error": "Bad Request"} |
401 | Chave ausente ou inválida | {"statusCode": 401, "message": "Unauthorized"} |
403 | Connect não habilitado na conta master | {"statusCode": 403, "message": "Fast Connect not enabled."} |
409 | CNPJ já cadastrado em outra subconta da mesma master (em qualquer status) ou igual ao CNPJ da própria master | {"statusCode": 409, "message": "Já existe um cadastro com este CNPJ. Consulte o registro existente ou acione o time de Risco.", "error": "Conflict"} |
A criação deu certo quando a resposta é
201 com um id. A subconta começa em análise (pending) e só pode transacionar quando chegar a active.Depois de criar
1
Envie os documentos
Use Enviar documentos para os documentos da empresa e do representante legal. Para cada sócio adicional, gere um token de upload com o
id dele. A lista de documentos exigidos está em Regras de credenciamento.2
Acompanhe a análise
Receba os avisos de status no
postbackUrl e consulte a subconta com Consultar subconta. Se o status for correcting, corrija os dados ou documentos pedidos.3
Obtenha as chaves
Com a subconta
active, busque as chaves dela em Chaves de API da subconta para criar cobranças em nome do vendedor.Exemplos por caso de uso
- Sócio único, sem painel
- Dois sócios, com painel
Vendedor que opera só pela sua plataforma. O representante usa o endereço da empresa.
{
"legalName": "LOJA EXEMPLO LTDA",
"tradeName": "Loja Exemplo",
"companyTaxId": "11.222.333/0001-81",
"website": "https://loja.exemplo.com.br",
"averageMonthlyRevenue": 30000,
"averageOrderValue": 150,
"productType": "physical",
"contactEmail": "[email protected]",
"productDescription": "Roupas e acessórios femininos",
"softDescriptor": "LOJAEXEMPLO",
"address": {
"addressLine1": "Av. Paulista, 1000",
"addressLine2": "Sala 12",
"referencePoint": "Próximo à estação Trianon-Masp",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"country": "BRA",
"postalCode": "01310100"
},
"phones": [{ "type": "mobile", "number": "+5511987654321" }],
"legalRepresentative": {
"fullName": "Ana Lima",
"dateOfBirth": "1988-04-12",
"nationality": "Brasileira",
"idNumber": "52998224725",
"idType": "cpf",
"issuingCountry": "BRA",
"email": "[email protected]",
"motherName": "Maria Lima",
"gender": "F",
"phones": [{ "type": "mobile", "number": "+5511987654321" }]
},
"bankAccount": {
"bankCode": "001",
"agencyCode": "1234",
"accountNumber": "567890",
"accountDigit": "0",
"accountType": "checking",
"bankName": "Banco do Brasil",
"recipientName": "LOJA EXEMPLO LTDA",
"recipientDocument": "11222333000181"
},
"canAccessDashboard": false,
"postbackUrl": "https://meusite.com.br/webhooks/finvia/conta"
}
Empresa com um sócio adicional, que tem endereço próprio. O vendedor também terá acesso ao painel da Finvia.Na resposta, o item com
{
"legalName": "LOJA EXEMPLO LTDA",
"tradeName": "Loja Exemplo",
"companyTaxId": "11222333000181",
"website": "https://loja.exemplo.com.br",
"averageMonthlyRevenue": 12000,
"averageOrderValue": 100,
"productType": "both",
"contactEmail": "[email protected]",
"productDescription": "Peças de cerâmica e aulas online",
"address": {
"addressLine1": "Av. Paulista, 1000",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"country": "BRA",
"postalCode": "01310100"
},
"phones": [{ "type": "mobile", "number": "+5511987654321" }],
"legalRepresentative": {
"fullName": "Ana Lima",
"dateOfBirth": "1988-04-12",
"nationality": "Brasileira",
"idNumber": "52998224725",
"email": "[email protected]",
"motherName": "Maria Lima",
"gender": "F",
"phones": [{ "type": "mobile", "number": "+5511987654321" }]
},
"additionalRepresentatives": [
{
"fullName": "Joao Silva",
"dateOfBirth": "1985-05-10",
"nationality": "Brasileira",
"idNumber": "11144477735",
"idType": "cpf",
"issuingCountry": "BRA",
"email": "[email protected]",
"motherName": "Joana Silva",
"gender": "M",
"address": {
"addressLine1": "Rua Augusta, 500",
"addressLine2": "Apto 31",
"neighborhood": "Consolação",
"city": "São Paulo",
"state": "SP",
"country": "BRA",
"postalCode": "01305000"
},
"phones": [{ "type": "mobile", "number": "+5511987654321" }]
}
],
"bankAccount": {
"bankCode": "001",
"agencyCode": "1234",
"accountNumber": "567890",
"accountDigit": "0",
"accountType": "checking",
"bankName": "Banco do Brasil",
"recipientName": "LOJA EXEMPLO LTDA",
"recipientDocument": "11222333000181"
},
"canAccessDashboard": true,
"user": {
"fullName": "Ana Lima",
"email": "[email protected]",
"phone": "+5511987654321"
}
}
isPrimary: false é o sócio Joao Silva. Use o id dele ao gerar o token de upload dos documentos pessoais dele.Erros comuns
| Sintoma | Causa | Como resolver |
|---|---|---|
400 address.country must be a valid ISO31661 Alpha3 code | País enviado em alpha-2 (BR) | Envie BRA |
400 no companyTaxId ou no idNumber | CNPJ ou CPF com dígito verificador inválido, com país BRA | Confira os documentos do lojista e dos sócios |
400 no CEP, na UF ou no bairro | Com país BRA, o CEP precisa ter 8 dígitos, a UF precisa ser válida e o bairro é obrigatório | Corrija o endereço |
400 com canAccessDashboard: true | Objeto user ausente ou incompleto, ou user.phone fora do E.164 | Envie user com fullName, email e phone (ex.: +5511987654321) |
400 Email already registered | Já existe usuário do painel com esse e-mail | Use outro e-mail em user.email |
409 com a mensagem de CNPJ já cadastrado | O CNPJ já existe em outra subconta sua, em qualquer status, ou é o CNPJ da master | Consulte a subconta existente em Listar subcontas com companyTaxId |
| Número do endereço chega como “S/N” na adquirente | addressLine1 sem vírgula e número no fim | Envie no formato Av. Paulista, 1000 |
| Documentos do sócio ficaram no representante legal | Upload feito sem indicar o sócio | Use o fluxo com token informando o legalRepresentativeId do sócio |
POST /v1/submerchants HTTP/1.1
Host: api-global.fastpaybrasil.com
Authorization: Basic <base64 de "SUA_CHAVE_SECRETA:">
Content-Type: application/json
{
"legalName": "LOJA EXEMPLO LTDA",
"tradeName": "Loja Exemplo",
"companyTaxId": "11.222.333/0001-81",
"website": "https://loja.exemplo.com.br",
"averageMonthlyRevenue": 30000,
"averageOrderValue": 150,
"productType": "physical",
"contactEmail": "[email protected]",
"productDescription": "Roupas e acessórios femininos",
"softDescriptor": "LOJAEXEMPLO",
"address": {
"addressLine1": "Av. Paulista, 1000",
"addressLine2": "Sala 12",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"country": "BRA",
"postalCode": "01310100"
},
"phones": [
{
"type": "mobile",
"number": "+5511987654321"
}
],
"legalRepresentative": {
"fullName": "Ana Lima",
"dateOfBirth": "1988-04-12",
"nationality": "Brasileira",
"idNumber": "52998224725",
"issuingCountry": "BRA",
"email": "[email protected]",
"motherName": "Maria Lima",
"gender": "F",
"phones": [
{
"type": "mobile",
"number": "+5511987654321"
}
]
},
"additionalRepresentatives": [
{
"fullName": "Joao Silva",
"dateOfBirth": "1985-05-10",
"nationality": "Brasileira",
"idNumber": "11144477735",
"issuingCountry": "BRA",
"email": "[email protected]",
"motherName": "Joana Silva",
"gender": "M",
"phones": [
{
"type": "mobile",
"number": "+5511987654321"
}
]
}
],
"bankAccount": {
"bankCode": "001",
"agencyCode": "1234",
"accountNumber": "567890",
"accountDigit": "0",
"accountType": "checking",
"bankName": "Banco do Brasil",
"recipientName": "LOJA EXEMPLO LTDA",
"recipientDocument": "11222333000181"
},
"canAccessDashboard": true,
"user": {
"fullName": "Ana Lima",
"email": "[email protected]",
"phone": "+5511987654321"
},
"postbackUrl": "https://meusite.com.br/webhooks/finvia/conta"
}
curl -X POST "https://api-global.fastpaybrasil.com/v1/submerchants" \
-u "$FINVIA_API_KEY:" \
-H "Content-Type: application/json" \
-d '{
"legalName": "LOJA EXEMPLO LTDA",
"tradeName": "Loja Exemplo",
"companyTaxId": "11.222.333/0001-81",
"website": "https://loja.exemplo.com.br",
"averageMonthlyRevenue": 30000,
"averageOrderValue": 150,
"productType": "physical",
"contactEmail": "[email protected]",
"productDescription": "Roupas e acessórios femininos",
"softDescriptor": "LOJAEXEMPLO",
"address": {
"addressLine1": "Av. Paulista, 1000",
"addressLine2": "Sala 12",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"country": "BRA",
"postalCode": "01310100"
},
"phones": [{ "type": "mobile", "number": "+5511987654321" }],
"legalRepresentative": {
"fullName": "Ana Lima",
"dateOfBirth": "1988-04-12",
"nationality": "Brasileira",
"idNumber": "52998224725",
"issuingCountry": "BRA",
"email": "[email protected]",
"motherName": "Maria Lima",
"gender": "F",
"phones": [{ "type": "mobile", "number": "+5511987654321" }]
},
"additionalRepresentatives": [
{
"fullName": "Joao Silva",
"dateOfBirth": "1985-05-10",
"nationality": "Brasileira",
"idNumber": "11144477735",
"issuingCountry": "BRA",
"email": "[email protected]",
"motherName": "Joana Silva",
"gender": "M",
"phones": [{ "type": "mobile", "number": "+5511987654321" }]
}
],
"bankAccount": {
"bankCode": "001",
"agencyCode": "1234",
"accountNumber": "567890",
"accountDigit": "0",
"accountType": "checking",
"bankName": "Banco do Brasil",
"recipientName": "LOJA EXEMPLO LTDA",
"recipientDocument": "11222333000181"
},
"canAccessDashboard": true,
"user": {
"fullName": "Ana Lima",
"email": "[email protected]",
"phone": "+5511987654321"
},
"postbackUrl": "https://meusite.com.br/webhooks/finvia/conta"
}'
const auth = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');
const response = await fetch('https://api-global.fastpaybrasil.com/v1/submerchants', {
method: 'POST',
headers: {
Authorization: `Basic ${auth}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
legalName: 'LOJA EXEMPLO LTDA',
tradeName: 'Loja Exemplo',
companyTaxId: '11222333000181',
website: 'https://loja.exemplo.com.br',
averageMonthlyRevenue: 30000, // R$ 30.000,00 por mês
averageOrderValue: 150, // R$ 150,00 por pedido
productType: 'physical',
contactEmail: '[email protected]',
productDescription: 'Roupas e acessórios femininos',
address: {
addressLine1: 'Av. Paulista, 1000',
neighborhood: 'Bela Vista',
city: 'São Paulo',
state: 'SP',
country: 'BRA',
postalCode: '01310100',
},
phones: [{ type: 'mobile', number: '+5511987654321' }],
legalRepresentative: {
fullName: 'Ana Lima',
dateOfBirth: '1988-04-12',
nationality: 'Brasileira',
idNumber: '52998224725',
email: '[email protected]',
motherName: 'Maria Lima',
gender: 'F',
phones: [{ type: 'mobile', number: '+5511987654321' }],
},
bankAccount: {
bankCode: '001',
agencyCode: '1234',
accountNumber: '567890',
accountDigit: '0',
accountType: 'checking',
bankName: 'Banco do Brasil',
recipientName: 'LOJA EXEMPLO LTDA',
recipientDocument: '11222333000181',
},
canAccessDashboard: false,
}),
});
const result = await response.json();
if (response.status === 201) {
// Guarde result.id e os ids de result.legalRepresentatives
console.log(result.id, result.legalRepresentatives);
} else if (response.status === 409) {
// CNPJ já cadastrado: procure a subconta existente em vez de criar outra
} else {
console.error(response.status, result.message);
}
import os
import requests
payload = {
"legalName": "LOJA EXEMPLO LTDA",
"tradeName": "Loja Exemplo",
"companyTaxId": "11.222.333/0001-81",
"website": "https://loja.exemplo.com.br",
"averageMonthlyRevenue": 30000,
"averageOrderValue": 150,
"productType": "physical",
"contactEmail": "[email protected]",
"productDescription": "Roupas e acessórios femininos",
"softDescriptor": "LOJAEXEMPLO",
"address": {
"addressLine1": "Av. Paulista, 1000",
"addressLine2": "Sala 12",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"country": "BRA",
"postalCode": "01310100",
},
"phones": [
{
"type": "mobile",
"number": "+5511987654321",
},
],
"legalRepresentative": {
"fullName": "Ana Lima",
"dateOfBirth": "1988-04-12",
"nationality": "Brasileira",
"idNumber": "52998224725",
"issuingCountry": "BRA",
"email": "[email protected]",
"motherName": "Maria Lima",
"gender": "F",
"phones": [
{
"type": "mobile",
"number": "+5511987654321",
},
],
},
"additionalRepresentatives": [
{
"fullName": "Joao Silva",
"dateOfBirth": "1985-05-10",
"nationality": "Brasileira",
"idNumber": "11144477735",
"issuingCountry": "BRA",
"email": "[email protected]",
"motherName": "Joana Silva",
"gender": "M",
"phones": [
{
"type": "mobile",
"number": "+5511987654321",
},
],
},
],
"bankAccount": {
"bankCode": "001",
"agencyCode": "1234",
"accountNumber": "567890",
"accountDigit": "0",
"accountType": "checking",
"bankName": "Banco do Brasil",
"recipientName": "LOJA EXEMPLO LTDA",
"recipientDocument": "11222333000181",
},
"canAccessDashboard": True,
"user": {
"fullName": "Ana Lima",
"email": "[email protected]",
"phone": "+5511987654321",
},
"postbackUrl": "https://meusite.com.br/webhooks/finvia/conta",
}
response = requests.request(
"POST",
"https://api-global.fastpaybrasil.com/v1/submerchants",
auth=(os.environ["FINVIA_API_KEY"], ""),
json=payload,
timeout=30,
)
print(response.status_code)
if response.content:
print(response.json())
<?php
$payload = [
'legalName' => 'LOJA EXEMPLO LTDA',
'tradeName' => 'Loja Exemplo',
'companyTaxId' => '11.222.333/0001-81',
'website' => 'https://loja.exemplo.com.br',
'averageMonthlyRevenue' => 30000,
'averageOrderValue' => 150,
'productType' => 'physical',
'contactEmail' => '[email protected]',
'productDescription' => 'Roupas e acessórios femininos',
'softDescriptor' => 'LOJAEXEMPLO',
'address' => [
'addressLine1' => 'Av. Paulista, 1000',
'addressLine2' => 'Sala 12',
'neighborhood' => 'Bela Vista',
'city' => 'São Paulo',
'state' => 'SP',
'country' => 'BRA',
'postalCode' => '01310100',
],
'phones' => [
[
'type' => 'mobile',
'number' => '+5511987654321',
],
],
'legalRepresentative' => [
'fullName' => 'Ana Lima',
'dateOfBirth' => '1988-04-12',
'nationality' => 'Brasileira',
'idNumber' => '52998224725',
'issuingCountry' => 'BRA',
'email' => '[email protected]',
'motherName' => 'Maria Lima',
'gender' => 'F',
'phones' => [
[
'type' => 'mobile',
'number' => '+5511987654321',
],
],
],
'additionalRepresentatives' => [
[
'fullName' => 'Joao Silva',
'dateOfBirth' => '1985-05-10',
'nationality' => 'Brasileira',
'idNumber' => '11144477735',
'issuingCountry' => 'BRA',
'email' => '[email protected]',
'motherName' => 'Joana Silva',
'gender' => 'M',
'phones' => [
[
'type' => 'mobile',
'number' => '+5511987654321',
],
],
],
],
'bankAccount' => [
'bankCode' => '001',
'agencyCode' => '1234',
'accountNumber' => '567890',
'accountDigit' => '0',
'accountType' => 'checking',
'bankName' => 'Banco do Brasil',
'recipientName' => 'LOJA EXEMPLO LTDA',
'recipientDocument' => '11222333000181',
],
'canAccessDashboard' => true,
'user' => [
'fullName' => 'Ana Lima',
'email' => '[email protected]',
'phone' => '+5511987654321',
],
'postbackUrl' => 'https://meusite.com.br/webhooks/finvia/conta',
];
$ch = curl_init('https://api-global.fastpaybrasil.com/v1/submerchants');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':',
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode($payload),
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo $status, PHP_EOL;
print_r(json_decode($body, true));
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Base64;
public class Exemplo {
public static void main(String[] args) throws Exception {
String credentials = Base64.getEncoder()
.encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes());
String payload = """
{
"legalName": "LOJA EXEMPLO LTDA",
"tradeName": "Loja Exemplo",
"companyTaxId": "11.222.333/0001-81",
"website": "https://loja.exemplo.com.br",
"averageMonthlyRevenue": 30000,
"averageOrderValue": 150,
"productType": "physical",
"contactEmail": "[email protected]",
"productDescription": "Roupas e acessórios femininos",
"softDescriptor": "LOJAEXEMPLO",
"address": {
"addressLine1": "Av. Paulista, 1000",
"addressLine2": "Sala 12",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"country": "BRA",
"postalCode": "01310100"
},
"phones": [
{
"type": "mobile",
"number": "+5511987654321"
}
],
"legalRepresentative": {
"fullName": "Ana Lima",
"dateOfBirth": "1988-04-12",
"nationality": "Brasileira",
"idNumber": "52998224725",
"issuingCountry": "BRA",
"email": "[email protected]",
"motherName": "Maria Lima",
"gender": "F",
"phones": [
{
"type": "mobile",
"number": "+5511987654321"
}
]
},
"additionalRepresentatives": [
{
"fullName": "Joao Silva",
"dateOfBirth": "1985-05-10",
"nationality": "Brasileira",
"idNumber": "11144477735",
"issuingCountry": "BRA",
"email": "[email protected]",
"motherName": "Joana Silva",
"gender": "M",
"phones": [
{
"type": "mobile",
"number": "+5511987654321"
}
]
}
],
"bankAccount": {
"bankCode": "001",
"agencyCode": "1234",
"accountNumber": "567890",
"accountDigit": "0",
"accountType": "checking",
"bankName": "Banco do Brasil",
"recipientName": "LOJA EXEMPLO LTDA",
"recipientDocument": "11222333000181"
},
"canAccessDashboard": true,
"user": {
"fullName": "Ana Lima",
"email": "[email protected]",
"phone": "+5511987654321"
},
"postbackUrl": "https://meusite.com.br/webhooks/finvia/conta"
}
""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api-global.fastpaybrasil.com/v1/submerchants"))
.header("Authorization", "Basic " + credentials)
.header("Content-Type", "application/json")
.method("POST", HttpRequest.BodyPublishers.ofString(payload))
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode());
System.out.println(response.body());
}
}
using System.Net.Http.Headers;
using System.Text;
var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY");
var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:"));
using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials);
var payload = """
{
"legalName": "LOJA EXEMPLO LTDA",
"tradeName": "Loja Exemplo",
"companyTaxId": "11.222.333/0001-81",
"website": "https://loja.exemplo.com.br",
"averageMonthlyRevenue": 30000,
"averageOrderValue": 150,
"productType": "physical",
"contactEmail": "[email protected]",
"productDescription": "Roupas e acessórios femininos",
"softDescriptor": "LOJAEXEMPLO",
"address": {
"addressLine1": "Av. Paulista, 1000",
"addressLine2": "Sala 12",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"country": "BRA",
"postalCode": "01310100"
},
"phones": [
{
"type": "mobile",
"number": "+5511987654321"
}
],
"legalRepresentative": {
"fullName": "Ana Lima",
"dateOfBirth": "1988-04-12",
"nationality": "Brasileira",
"idNumber": "52998224725",
"issuingCountry": "BRA",
"email": "[email protected]",
"motherName": "Maria Lima",
"gender": "F",
"phones": [
{
"type": "mobile",
"number": "+5511987654321"
}
]
},
"additionalRepresentatives": [
{
"fullName": "Joao Silva",
"dateOfBirth": "1985-05-10",
"nationality": "Brasileira",
"idNumber": "11144477735",
"issuingCountry": "BRA",
"email": "[email protected]",
"motherName": "Joana Silva",
"gender": "M",
"phones": [
{
"type": "mobile",
"number": "+5511987654321"
}
]
}
],
"bankAccount": {
"bankCode": "001",
"agencyCode": "1234",
"accountNumber": "567890",
"accountDigit": "0",
"accountType": "checking",
"bankName": "Banco do Brasil",
"recipientName": "LOJA EXEMPLO LTDA",
"recipientDocument": "11222333000181"
},
"canAccessDashboard": true,
"user": {
"fullName": "Ana Lima",
"email": "[email protected]",
"phone": "+5511987654321"
},
"postbackUrl": "https://meusite.com.br/webhooks/finvia/conta"
}
""";
var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/submerchants");
request.Content = new StringContent(payload, Encoding.UTF8, "application/json");
var response = await client.SendAsync(request);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main
import (
"fmt"
"io"
"net/http"
"os"
"strings"
)
func main() {
payload := strings.NewReader(`{
"legalName": "LOJA EXEMPLO LTDA",
"tradeName": "Loja Exemplo",
"companyTaxId": "11.222.333/0001-81",
"website": "https://loja.exemplo.com.br",
"averageMonthlyRevenue": 30000,
"averageOrderValue": 150,
"productType": "physical",
"contactEmail": "[email protected]",
"productDescription": "Roupas e acessórios femininos",
"softDescriptor": "LOJAEXEMPLO",
"address": {
"addressLine1": "Av. Paulista, 1000",
"addressLine2": "Sala 12",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"country": "BRA",
"postalCode": "01310100"
},
"phones": [
{
"type": "mobile",
"number": "+5511987654321"
}
],
"legalRepresentative": {
"fullName": "Ana Lima",
"dateOfBirth": "1988-04-12",
"nationality": "Brasileira",
"idNumber": "52998224725",
"issuingCountry": "BRA",
"email": "[email protected]",
"motherName": "Maria Lima",
"gender": "F",
"phones": [
{
"type": "mobile",
"number": "+5511987654321"
}
]
},
"additionalRepresentatives": [
{
"fullName": "Joao Silva",
"dateOfBirth": "1985-05-10",
"nationality": "Brasileira",
"idNumber": "11144477735",
"issuingCountry": "BRA",
"email": "[email protected]",
"motherName": "Joana Silva",
"gender": "M",
"phones": [
{
"type": "mobile",
"number": "+5511987654321"
}
]
}
],
"bankAccount": {
"bankCode": "001",
"agencyCode": "1234",
"accountNumber": "567890",
"accountDigit": "0",
"accountType": "checking",
"bankName": "Banco do Brasil",
"recipientName": "LOJA EXEMPLO LTDA",
"recipientDocument": "11222333000181"
},
"canAccessDashboard": true,
"user": {
"fullName": "Ana Lima",
"email": "[email protected]",
"phone": "+5511987654321"
},
"postbackUrl": "https://meusite.com.br/webhooks/finvia/conta"
}`)
req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/submerchants", payload)
if err != nil {
panic(err)
}
req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "")
req.Header.Set("Content-Type", "application/json")
res, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(res.StatusCode)
fmt.Println(string(body))
}
require "json"
require "net/http"
require "uri"
uri = URI("https://api-global.fastpaybrasil.com/v1/submerchants")
request = Net::HTTP::Post.new(uri)
request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "")
request["Content-Type"] = "application/json"
request.body = JSON.generate({
"legalName" => "LOJA EXEMPLO LTDA",
"tradeName" => "Loja Exemplo",
"companyTaxId" => "11.222.333/0001-81",
"website" => "https://loja.exemplo.com.br",
"averageMonthlyRevenue" => 30000,
"averageOrderValue" => 150,
"productType" => "physical",
"contactEmail" => "[email protected]",
"productDescription" => "Roupas e acessórios femininos",
"softDescriptor" => "LOJAEXEMPLO",
"address" => {
"addressLine1" => "Av. Paulista, 1000",
"addressLine2" => "Sala 12",
"neighborhood" => "Bela Vista",
"city" => "São Paulo",
"state" => "SP",
"country" => "BRA",
"postalCode" => "01310100",
},
"phones" => [
{
"type" => "mobile",
"number" => "+5511987654321",
},
],
"legalRepresentative" => {
"fullName" => "Ana Lima",
"dateOfBirth" => "1988-04-12",
"nationality" => "Brasileira",
"idNumber" => "52998224725",
"issuingCountry" => "BRA",
"email" => "[email protected]",
"motherName" => "Maria Lima",
"gender" => "F",
"phones" => [
{
"type" => "mobile",
"number" => "+5511987654321",
},
],
},
"additionalRepresentatives" => [
{
"fullName" => "Joao Silva",
"dateOfBirth" => "1985-05-10",
"nationality" => "Brasileira",
"idNumber" => "11144477735",
"issuingCountry" => "BRA",
"email" => "[email protected]",
"motherName" => "Joana Silva",
"gender" => "M",
"phones" => [
{
"type" => "mobile",
"number" => "+5511987654321",
},
],
},
],
"bankAccount" => {
"bankCode" => "001",
"agencyCode" => "1234",
"accountNumber" => "567890",
"accountDigit" => "0",
"accountType" => "checking",
"bankName" => "Banco do Brasil",
"recipientName" => "LOJA EXEMPLO LTDA",
"recipientDocument" => "11222333000181",
},
"canAccessDashboard" => true,
"user" => {
"fullName" => "Ana Lima",
"email" => "[email protected]",
"phone" => "+5511987654321",
},
"postbackUrl" => "https://meusite.com.br/webhooks/finvia/conta",
})
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
puts response.code
puts response.body
{
"id": "36OO3bcGjhPjjF3tzrqOGcmQuKo",
"legalRepresentatives": [
{
"id": "2vorkEaaaBbbCccDddEeeFffGgg",
"fullName": "Ana Lima",
"isPrimary": true
},
{
"id": "2vorkEbbbCccDddEeeFffGggHhh",
"fullName": "Joao Silva",
"isPrimary": false
}
]
}
{
"statusCode": 400,
"message": ["address.country must be a valid ISO31661 Alpha3 code"],
"error": "Bad Request"
}
{ "statusCode": 403, "message": "Fast Connect not enabled." }
{
"statusCode": 409,
"message": "Já existe um cadastro com este CNPJ. Consulte o registro existente ou acione o time de Risco.",
"error": "Conflict"
}
Veja também
Subcontas e KYC
Cadastro e credenciamento passo a passo.
Regras de credenciamento
Documentos exigidos, motivos de recusa e MCCs não aceitos.
Sócios e documentos
Documentos de cada sócio com token de upload.
Webhooks de conta
Avisos de mudança de status.

