POST /v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document HTTP/1.1
Host: api-global.fastpaybrasil.com
Authorization: Basic <base64 de "SUA_CHAVE_SECRETA:">
Content-Type: multipart/form-data; boundary=----FinviaBoundary
------FinviaBoundary
Content-Disposition: form-data; name="cnpj_card"; filename="cartao-cnpj.pdf"
<conteúdo de cartao-cnpj.pdf>
------FinviaBoundary
Content-Disposition: form-data; name="social_contract"; filename="contrato-social.pdf"
<conteúdo de contrato-social.pdf>
------FinviaBoundary
Content-Disposition: form-data; name="responsible_document_front"; filename="rg-frente.jpg"
<conteúdo de rg-frente.jpg>
------FinviaBoundary
Content-Disposition: form-data; name="responsible_document_back"; filename="rg-verso.jpg"
<conteúdo de rg-verso.jpg>
------FinviaBoundary
Content-Disposition: form-data; name="selfie_with_document"; filename="selfie.jpg"
<conteúdo de selfie.jpg>
------FinviaBoundary--
curl -X POST "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document" \
-u "$FINVIA_API_KEY:" \
-F "cnpj_card=@./cartao-cnpj.pdf" \
-F "social_contract=@./contrato-social.pdf" \
-F "responsible_document_front=@./rg-frente.jpg" \
-F "responsible_document_back=@./rg-verso.jpg" \
-F "selfie_with_document=@./selfie.jpg"
import { readFile } from 'node:fs/promises';
const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');
const id = '36OO3bcGjhPjjF3tzrqOGcmQuKo';
const form = new FormData();
form.append('cnpj_card', new Blob([await readFile('./cartao-cnpj.pdf')], { type: 'application/pdf' }), 'cartao-cnpj.pdf');
form.append('social_contract', new Blob([await readFile('./contrato-social.pdf')], { type: 'application/pdf' }), 'contrato-social.pdf');
form.append('responsible_document_front', new Blob([await readFile('./rg-frente.jpg')], { type: 'image/jpeg' }), 'rg-frente.jpg');
form.append('responsible_document_back', new Blob([await readFile('./rg-verso.jpg')], { type: 'image/jpeg' }), 'rg-verso.jpg');
form.append('selfie_with_document', new Blob([await readFile('./selfie.jpg')], { type: 'image/jpeg' }), 'selfie.jpg');
// Não defina Content-Type: o fetch monta o boundary do multipart
const response = await fetch(`https://api-global.fastpaybrasil.com/v1/submerchants/${id}/document`, {
method: 'POST',
headers: { Authorization: `Basic ${credentials}` },
body: form,
});
if (response.status !== 201) {
console.error(await response.json());
}
import os
import requests
files = {
"cnpj_card": open("./cartao-cnpj.pdf", "rb"),
"social_contract": open("./contrato-social.pdf", "rb"),
"responsible_document_front": open("./rg-frente.jpg", "rb"),
"responsible_document_back": open("./rg-verso.jpg", "rb"),
"selfie_with_document": open("./selfie.jpg", "rb"),
}
response = requests.request(
"POST",
"https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document",
auth=(os.environ["FINVIA_API_KEY"], ""),
files=files,
timeout=30,
)
print(response.status_code)
if response.content:
print(response.json())
<?php
$ch = curl_init('https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':',
CURLOPT_POSTFIELDS => [
'cnpj_card' => new CURLFile('./cartao-cnpj.pdf', null, 'cartao-cnpj.pdf'),
'social_contract' => new CURLFile('./contrato-social.pdf', null, 'contrato-social.pdf'),
'responsible_document_front' => new CURLFile('./rg-frente.jpg', null, 'rg-frente.jpg'),
'responsible_document_back' => new CURLFile('./rg-verso.jpg', null, 'rg-verso.jpg'),
'selfie_with_document' => new CURLFile('./selfie.jpg', null, 'selfie.jpg'),
],
]);
$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;
import java.io.ByteArrayOutputStream;
import java.nio.file.Files;
import java.nio.file.Path;
public class Exemplo {
public static void main(String[] args) throws Exception {
String credentials = Base64.getEncoder()
.encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes());
String boundary = "FinviaBoundary";
ByteArrayOutputStream form = new ByteArrayOutputStream();
String[][] files = {
{"cnpj_card", "./cartao-cnpj.pdf"},
{"social_contract", "./contrato-social.pdf"},
{"responsible_document_front", "./rg-frente.jpg"},
{"responsible_document_back", "./rg-verso.jpg"},
{"selfie_with_document", "./selfie.jpg"},
};
for (String[] file : files) {
Path path = Path.of(file[1]);
form.write(("--" + boundary + "\r\n"
+ "Content-Disposition: form-data; name=\"" + file[0] + "\"; filename=\""
+ path.getFileName() + "\"\r\n"
+ "Content-Type: application/octet-stream\r\n\r\n").getBytes());
form.write(Files.readAllBytes(path));
form.write("\r\n".getBytes());
}
form.write(("--" + boundary + "--\r\n").getBytes());
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document"))
.header("Authorization", "Basic " + credentials)
.header("Content-Type", "multipart/form-data; boundary=" + boundary)
.method("POST", HttpRequest.BodyPublishers.ofByteArray(form.toByteArray()))
.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);
using var form = new MultipartFormDataContent();
form.Add(new ByteArrayContent(File.ReadAllBytes("./cartao-cnpj.pdf")), "cnpj_card", "cartao-cnpj.pdf");
form.Add(new ByteArrayContent(File.ReadAllBytes("./contrato-social.pdf")), "social_contract", "contrato-social.pdf");
form.Add(new ByteArrayContent(File.ReadAllBytes("./rg-frente.jpg")), "responsible_document_front", "rg-frente.jpg");
form.Add(new ByteArrayContent(File.ReadAllBytes("./rg-verso.jpg")), "responsible_document_back", "rg-verso.jpg");
form.Add(new ByteArrayContent(File.ReadAllBytes("./selfie.jpg")), "selfie_with_document", "selfie.jpg");
var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document");
request.Content = form;
var response = await client.SendAsync(request);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main
import (
"bytes"
"fmt"
"io"
"mime/multipart"
"net/http"
"os"
"path/filepath"
)
func main() {
var form bytes.Buffer
writer := multipart.NewWriter(&form)
files := [][2]string{
{"cnpj_card", "./cartao-cnpj.pdf"},
{"social_contract", "./contrato-social.pdf"},
{"responsible_document_front", "./rg-frente.jpg"},
{"responsible_document_back", "./rg-verso.jpg"},
{"selfie_with_document", "./selfie.jpg"},
}
for _, file := range files {
part, err := writer.CreateFormFile(file[0], filepath.Base(file[1]))
if err != nil {
panic(err)
}
content, err := os.ReadFile(file[1])
if err != nil {
panic(err)
}
part.Write(content)
}
writer.Close()
req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document", &form)
if err != nil {
panic(err)
}
req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "")
req.Header.Set("Content-Type", writer.FormDataContentType())
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 "net/http"
require "uri"
uri = URI("https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document")
request = Net::HTTP::Post.new(uri)
request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "")
request.set_form(
[
["cnpj_card", File.open("./cartao-cnpj.pdf")],
["social_contract", File.open("./contrato-social.pdf")],
["responsible_document_front", File.open("./rg-frente.jpg")],
["responsible_document_back", File.open("./rg-verso.jpg")],
["selfie_with_document", File.open("./selfie.jpg")],
],
"multipart/form-data"
)
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
puts response.code
puts response.body
(sem corpo)
{ "statusCode": 400, "message": "Invalid document name", "error": "Bad Request" }
{ "statusCode": 401, "message": "Unauthorized" }
{ "statusCode": 422, "message": "Unprocessable Entity" }
Connect
Enviar documentos da subconta
Envia os documentos da empresa e do representante legal para a análise de credenciamento da subconta.
POST
/
v1
/
submerchants
/
{id}
/
document
POST /v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document HTTP/1.1
Host: api-global.fastpaybrasil.com
Authorization: Basic <base64 de "SUA_CHAVE_SECRETA:">
Content-Type: multipart/form-data; boundary=----FinviaBoundary
------FinviaBoundary
Content-Disposition: form-data; name="cnpj_card"; filename="cartao-cnpj.pdf"
<conteúdo de cartao-cnpj.pdf>
------FinviaBoundary
Content-Disposition: form-data; name="social_contract"; filename="contrato-social.pdf"
<conteúdo de contrato-social.pdf>
------FinviaBoundary
Content-Disposition: form-data; name="responsible_document_front"; filename="rg-frente.jpg"
<conteúdo de rg-frente.jpg>
------FinviaBoundary
Content-Disposition: form-data; name="responsible_document_back"; filename="rg-verso.jpg"
<conteúdo de rg-verso.jpg>
------FinviaBoundary
Content-Disposition: form-data; name="selfie_with_document"; filename="selfie.jpg"
<conteúdo de selfie.jpg>
------FinviaBoundary--
curl -X POST "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document" \
-u "$FINVIA_API_KEY:" \
-F "cnpj_card=@./cartao-cnpj.pdf" \
-F "social_contract=@./contrato-social.pdf" \
-F "responsible_document_front=@./rg-frente.jpg" \
-F "responsible_document_back=@./rg-verso.jpg" \
-F "selfie_with_document=@./selfie.jpg"
import { readFile } from 'node:fs/promises';
const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');
const id = '36OO3bcGjhPjjF3tzrqOGcmQuKo';
const form = new FormData();
form.append('cnpj_card', new Blob([await readFile('./cartao-cnpj.pdf')], { type: 'application/pdf' }), 'cartao-cnpj.pdf');
form.append('social_contract', new Blob([await readFile('./contrato-social.pdf')], { type: 'application/pdf' }), 'contrato-social.pdf');
form.append('responsible_document_front', new Blob([await readFile('./rg-frente.jpg')], { type: 'image/jpeg' }), 'rg-frente.jpg');
form.append('responsible_document_back', new Blob([await readFile('./rg-verso.jpg')], { type: 'image/jpeg' }), 'rg-verso.jpg');
form.append('selfie_with_document', new Blob([await readFile('./selfie.jpg')], { type: 'image/jpeg' }), 'selfie.jpg');
// Não defina Content-Type: o fetch monta o boundary do multipart
const response = await fetch(`https://api-global.fastpaybrasil.com/v1/submerchants/${id}/document`, {
method: 'POST',
headers: { Authorization: `Basic ${credentials}` },
body: form,
});
if (response.status !== 201) {
console.error(await response.json());
}
import os
import requests
files = {
"cnpj_card": open("./cartao-cnpj.pdf", "rb"),
"social_contract": open("./contrato-social.pdf", "rb"),
"responsible_document_front": open("./rg-frente.jpg", "rb"),
"responsible_document_back": open("./rg-verso.jpg", "rb"),
"selfie_with_document": open("./selfie.jpg", "rb"),
}
response = requests.request(
"POST",
"https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document",
auth=(os.environ["FINVIA_API_KEY"], ""),
files=files,
timeout=30,
)
print(response.status_code)
if response.content:
print(response.json())
<?php
$ch = curl_init('https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':',
CURLOPT_POSTFIELDS => [
'cnpj_card' => new CURLFile('./cartao-cnpj.pdf', null, 'cartao-cnpj.pdf'),
'social_contract' => new CURLFile('./contrato-social.pdf', null, 'contrato-social.pdf'),
'responsible_document_front' => new CURLFile('./rg-frente.jpg', null, 'rg-frente.jpg'),
'responsible_document_back' => new CURLFile('./rg-verso.jpg', null, 'rg-verso.jpg'),
'selfie_with_document' => new CURLFile('./selfie.jpg', null, 'selfie.jpg'),
],
]);
$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;
import java.io.ByteArrayOutputStream;
import java.nio.file.Files;
import java.nio.file.Path;
public class Exemplo {
public static void main(String[] args) throws Exception {
String credentials = Base64.getEncoder()
.encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes());
String boundary = "FinviaBoundary";
ByteArrayOutputStream form = new ByteArrayOutputStream();
String[][] files = {
{"cnpj_card", "./cartao-cnpj.pdf"},
{"social_contract", "./contrato-social.pdf"},
{"responsible_document_front", "./rg-frente.jpg"},
{"responsible_document_back", "./rg-verso.jpg"},
{"selfie_with_document", "./selfie.jpg"},
};
for (String[] file : files) {
Path path = Path.of(file[1]);
form.write(("--" + boundary + "\r\n"
+ "Content-Disposition: form-data; name=\"" + file[0] + "\"; filename=\""
+ path.getFileName() + "\"\r\n"
+ "Content-Type: application/octet-stream\r\n\r\n").getBytes());
form.write(Files.readAllBytes(path));
form.write("\r\n".getBytes());
}
form.write(("--" + boundary + "--\r\n").getBytes());
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document"))
.header("Authorization", "Basic " + credentials)
.header("Content-Type", "multipart/form-data; boundary=" + boundary)
.method("POST", HttpRequest.BodyPublishers.ofByteArray(form.toByteArray()))
.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);
using var form = new MultipartFormDataContent();
form.Add(new ByteArrayContent(File.ReadAllBytes("./cartao-cnpj.pdf")), "cnpj_card", "cartao-cnpj.pdf");
form.Add(new ByteArrayContent(File.ReadAllBytes("./contrato-social.pdf")), "social_contract", "contrato-social.pdf");
form.Add(new ByteArrayContent(File.ReadAllBytes("./rg-frente.jpg")), "responsible_document_front", "rg-frente.jpg");
form.Add(new ByteArrayContent(File.ReadAllBytes("./rg-verso.jpg")), "responsible_document_back", "rg-verso.jpg");
form.Add(new ByteArrayContent(File.ReadAllBytes("./selfie.jpg")), "selfie_with_document", "selfie.jpg");
var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document");
request.Content = form;
var response = await client.SendAsync(request);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main
import (
"bytes"
"fmt"
"io"
"mime/multipart"
"net/http"
"os"
"path/filepath"
)
func main() {
var form bytes.Buffer
writer := multipart.NewWriter(&form)
files := [][2]string{
{"cnpj_card", "./cartao-cnpj.pdf"},
{"social_contract", "./contrato-social.pdf"},
{"responsible_document_front", "./rg-frente.jpg"},
{"responsible_document_back", "./rg-verso.jpg"},
{"selfie_with_document", "./selfie.jpg"},
}
for _, file := range files {
part, err := writer.CreateFormFile(file[0], filepath.Base(file[1]))
if err != nil {
panic(err)
}
content, err := os.ReadFile(file[1])
if err != nil {
panic(err)
}
part.Write(content)
}
writer.Close()
req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document", &form)
if err != nil {
panic(err)
}
req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "")
req.Header.Set("Content-Type", writer.FormDataContentType())
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 "net/http"
require "uri"
uri = URI("https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document")
request = Net::HTTP::Post.new(uri)
request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "")
request.set_form(
[
["cnpj_card", File.open("./cartao-cnpj.pdf")],
["social_contract", File.open("./contrato-social.pdf")],
["responsible_document_front", File.open("./rg-frente.jpg")],
["responsible_document_back", File.open("./rg-verso.jpg")],
["selfie_with_document", File.open("./selfie.jpg")],
],
"multipart/form-data"
)
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
puts response.code
puts response.body
(sem corpo)
{ "statusCode": 400, "message": "Invalid document name", "error": "Bad Request" }
{ "statusCode": 401, "message": "Unauthorized" }
{ "statusCode": 422, "message": "Unprocessable Entity" }
Depois de criar a subconta, a Finvia precisa dos documentos da empresa e do representante legal para fazer o credenciamento (KYC). Esta rota recebe esses arquivos direto do seu servidor, autenticada com a chave secreta da conta master. Os documentos de pessoa enviados aqui ficam sempre ligados ao representante legal (principal).
Qualquer outro nome de campo é recusado com
Esta rota usa o corpo de erro padrão (
Quando usar
| Situação | Rota indicada |
|---|---|
| Subconta com um único representante, upload feito pelo seu servidor | Esta rota |
Documentos de empresa (cnpj_card, social_contract, irs_letter) | Esta rota ou o fluxo com token: valem para a subconta como um todo |
| Documentos pessoais de um sócio adicional | Criar token de upload com o legalRepresentativeId do sócio e Enviar documentos com token |
| Upload feito do navegador do vendedor, sem expor a chave secreta | Fluxo com token |
Se a subconta tem só um representante (sem
additionalRepresentatives), esta rota é tudo o que você precisa. Integrações que já usam esta rota continuam funcionando sem mudança.Antes de chamar
- Tenha o
idda subconta, devolvido em Criar subconta. - Autentique com a chave secreta (
sk_) da conta master (Credenciais e ambientes). - Os arquivos precisam estar em JPEG, JPG, PNG, GIF, BMP, WEBP ou PDF, com no máximo 50 MB cada.
- Envie antes da aprovação: depois que a subconta é aprovada, novos uploads são bloqueados (
422). - Confira quais documentos o credenciamento exige em Regras de credenciamento.
Parâmetros de caminho
Corpo da requisição
Formatomultipart/form-data, obrigatório. O nome de cada campo é o tipo do documento. Nenhum campo é obrigatório sozinho, mas a requisição precisa ter pelo menos um arquivo (minProperties: 1). Você pode enviar vários documentos na mesma chamada ou um por chamada.
Frente do documento de identificação do representante legal (tipo
string, formato binary). Documento de pessoa.Verso do documento de identificação do representante legal (tipo
string, formato binary). Documento de pessoa.Selfie do representante legal segurando o documento (tipo
string, formato binary). Documento de pessoa.IRS letter, usada no fluxo de cadastro de LLC (tipo
string, formato binary). Documento de empresa.| Documento | Campo | Vinculado a |
|---|---|---|
| Cartão CNPJ | cnpj_card | Subconta |
| Contrato social | social_contract | Subconta |
| IRS letter (LLC) | irs_letter | Subconta |
| Documento, frente | responsible_document_front | Representante legal |
| Documento, verso | responsible_document_back | Representante legal |
| Selfie com documento | selfie_with_document | Representante legal |
400 Invalid document name. Não há campo para o certificado de MEI: para enviar esse documento, fale com o suporte da Finvia.
Esta rota não diferencia sócios. Documentos de pessoa enviados aqui sempre ficam no representante legal. Se você enviar aqui a identidade de um sócio adicional, ela será registrada como documento do representante principal. Para sócios, use o fluxo com token.
Respostas
A resposta201 não tem corpo. O sucesso é indicado pelo código HTTP.
| HTTP | Significado | Corpo |
|---|---|---|
201 | Documentos enviados | Sem conteúdo |
400 | Tipo de arquivo não aceito, arquivo acima de 50 MB ou nenhum arquivo | Mensagem padrão de validação. Ex.: Validation failed (current file type is text/plain, expected type is ...) ou File is required |
400 | Nome de campo fora da lista | {"statusCode": 400, "message": "Invalid document name", "error": "Bad Request"} |
400 | Subconta que não pertence à conta master | {"statusCode": 400, "message": "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."} |
422 | Subconta já aprovada: os documentos não podem mais ser alterados | {"statusCode": 422, "message": "Unprocessable Entity"} |
statusCode, message, error), sem os códigos próprios da rota com token. Trate o erro pelo código HTTP.
Cada arquivo foi aceito quando a resposta é
201. Para conferir os documentos de pessoa e o status de análise de cada um, use Listar representantes com include=documents.Para o negócio: no roteiro de homologação, o cenário FC-02 pede um envio por tipo: contrato social, cartão CNPJ, documento do responsável (frente e verso) e selfie com documento. Peça esses arquivos ao vendedor já no cadastro, para enviar tudo logo depois de criar a subconta.
Erros comuns
| Sintoma | Causa | Como resolver |
|---|---|---|
400 Validation failed (...) | Formato fora da lista aceita (ex.: HEIC, DOCX) ou arquivo acima de 50 MB | Converta para JPEG, PNG ou PDF e reduza o tamanho |
400 File is required | Requisição sem arquivo | Envie pelo menos um dos seis campos |
400 Invalid document name | Nome de campo fora da lista (ex.: mei_certificate) | Use um dos seis nomes desta página |
422 Unprocessable Entity | Subconta já aprovada | Fale com a Finvia se precisar atualizar documentos |
| Documento do sócio ficou no representante principal | Rota direta usada para sócio adicional | Use o fluxo com token e o legalRepresentativeId do sócio |
POST /v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document HTTP/1.1
Host: api-global.fastpaybrasil.com
Authorization: Basic <base64 de "SUA_CHAVE_SECRETA:">
Content-Type: multipart/form-data; boundary=----FinviaBoundary
------FinviaBoundary
Content-Disposition: form-data; name="cnpj_card"; filename="cartao-cnpj.pdf"
<conteúdo de cartao-cnpj.pdf>
------FinviaBoundary
Content-Disposition: form-data; name="social_contract"; filename="contrato-social.pdf"
<conteúdo de contrato-social.pdf>
------FinviaBoundary
Content-Disposition: form-data; name="responsible_document_front"; filename="rg-frente.jpg"
<conteúdo de rg-frente.jpg>
------FinviaBoundary
Content-Disposition: form-data; name="responsible_document_back"; filename="rg-verso.jpg"
<conteúdo de rg-verso.jpg>
------FinviaBoundary
Content-Disposition: form-data; name="selfie_with_document"; filename="selfie.jpg"
<conteúdo de selfie.jpg>
------FinviaBoundary--
curl -X POST "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document" \
-u "$FINVIA_API_KEY:" \
-F "cnpj_card=@./cartao-cnpj.pdf" \
-F "social_contract=@./contrato-social.pdf" \
-F "responsible_document_front=@./rg-frente.jpg" \
-F "responsible_document_back=@./rg-verso.jpg" \
-F "selfie_with_document=@./selfie.jpg"
import { readFile } from 'node:fs/promises';
const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');
const id = '36OO3bcGjhPjjF3tzrqOGcmQuKo';
const form = new FormData();
form.append('cnpj_card', new Blob([await readFile('./cartao-cnpj.pdf')], { type: 'application/pdf' }), 'cartao-cnpj.pdf');
form.append('social_contract', new Blob([await readFile('./contrato-social.pdf')], { type: 'application/pdf' }), 'contrato-social.pdf');
form.append('responsible_document_front', new Blob([await readFile('./rg-frente.jpg')], { type: 'image/jpeg' }), 'rg-frente.jpg');
form.append('responsible_document_back', new Blob([await readFile('./rg-verso.jpg')], { type: 'image/jpeg' }), 'rg-verso.jpg');
form.append('selfie_with_document', new Blob([await readFile('./selfie.jpg')], { type: 'image/jpeg' }), 'selfie.jpg');
// Não defina Content-Type: o fetch monta o boundary do multipart
const response = await fetch(`https://api-global.fastpaybrasil.com/v1/submerchants/${id}/document`, {
method: 'POST',
headers: { Authorization: `Basic ${credentials}` },
body: form,
});
if (response.status !== 201) {
console.error(await response.json());
}
import os
import requests
files = {
"cnpj_card": open("./cartao-cnpj.pdf", "rb"),
"social_contract": open("./contrato-social.pdf", "rb"),
"responsible_document_front": open("./rg-frente.jpg", "rb"),
"responsible_document_back": open("./rg-verso.jpg", "rb"),
"selfie_with_document": open("./selfie.jpg", "rb"),
}
response = requests.request(
"POST",
"https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document",
auth=(os.environ["FINVIA_API_KEY"], ""),
files=files,
timeout=30,
)
print(response.status_code)
if response.content:
print(response.json())
<?php
$ch = curl_init('https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document');
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':',
CURLOPT_POSTFIELDS => [
'cnpj_card' => new CURLFile('./cartao-cnpj.pdf', null, 'cartao-cnpj.pdf'),
'social_contract' => new CURLFile('./contrato-social.pdf', null, 'contrato-social.pdf'),
'responsible_document_front' => new CURLFile('./rg-frente.jpg', null, 'rg-frente.jpg'),
'responsible_document_back' => new CURLFile('./rg-verso.jpg', null, 'rg-verso.jpg'),
'selfie_with_document' => new CURLFile('./selfie.jpg', null, 'selfie.jpg'),
],
]);
$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;
import java.io.ByteArrayOutputStream;
import java.nio.file.Files;
import java.nio.file.Path;
public class Exemplo {
public static void main(String[] args) throws Exception {
String credentials = Base64.getEncoder()
.encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes());
String boundary = "FinviaBoundary";
ByteArrayOutputStream form = new ByteArrayOutputStream();
String[][] files = {
{"cnpj_card", "./cartao-cnpj.pdf"},
{"social_contract", "./contrato-social.pdf"},
{"responsible_document_front", "./rg-frente.jpg"},
{"responsible_document_back", "./rg-verso.jpg"},
{"selfie_with_document", "./selfie.jpg"},
};
for (String[] file : files) {
Path path = Path.of(file[1]);
form.write(("--" + boundary + "\r\n"
+ "Content-Disposition: form-data; name=\"" + file[0] + "\"; filename=\""
+ path.getFileName() + "\"\r\n"
+ "Content-Type: application/octet-stream\r\n\r\n").getBytes());
form.write(Files.readAllBytes(path));
form.write("\r\n".getBytes());
}
form.write(("--" + boundary + "--\r\n").getBytes());
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document"))
.header("Authorization", "Basic " + credentials)
.header("Content-Type", "multipart/form-data; boundary=" + boundary)
.method("POST", HttpRequest.BodyPublishers.ofByteArray(form.toByteArray()))
.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);
using var form = new MultipartFormDataContent();
form.Add(new ByteArrayContent(File.ReadAllBytes("./cartao-cnpj.pdf")), "cnpj_card", "cartao-cnpj.pdf");
form.Add(new ByteArrayContent(File.ReadAllBytes("./contrato-social.pdf")), "social_contract", "contrato-social.pdf");
form.Add(new ByteArrayContent(File.ReadAllBytes("./rg-frente.jpg")), "responsible_document_front", "rg-frente.jpg");
form.Add(new ByteArrayContent(File.ReadAllBytes("./rg-verso.jpg")), "responsible_document_back", "rg-verso.jpg");
form.Add(new ByteArrayContent(File.ReadAllBytes("./selfie.jpg")), "selfie_with_document", "selfie.jpg");
var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document");
request.Content = form;
var response = await client.SendAsync(request);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());
package main
import (
"bytes"
"fmt"
"io"
"mime/multipart"
"net/http"
"os"
"path/filepath"
)
func main() {
var form bytes.Buffer
writer := multipart.NewWriter(&form)
files := [][2]string{
{"cnpj_card", "./cartao-cnpj.pdf"},
{"social_contract", "./contrato-social.pdf"},
{"responsible_document_front", "./rg-frente.jpg"},
{"responsible_document_back", "./rg-verso.jpg"},
{"selfie_with_document", "./selfie.jpg"},
}
for _, file := range files {
part, err := writer.CreateFormFile(file[0], filepath.Base(file[1]))
if err != nil {
panic(err)
}
content, err := os.ReadFile(file[1])
if err != nil {
panic(err)
}
part.Write(content)
}
writer.Close()
req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document", &form)
if err != nil {
panic(err)
}
req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "")
req.Header.Set("Content-Type", writer.FormDataContentType())
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 "net/http"
require "uri"
uri = URI("https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document")
request = Net::HTTP::Post.new(uri)
request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "")
request.set_form(
[
["cnpj_card", File.open("./cartao-cnpj.pdf")],
["social_contract", File.open("./contrato-social.pdf")],
["responsible_document_front", File.open("./rg-frente.jpg")],
["responsible_document_back", File.open("./rg-verso.jpg")],
["selfie_with_document", File.open("./selfie.jpg")],
],
"multipart/form-data"
)
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
puts response.code
puts response.body
(sem corpo)
{ "statusCode": 400, "message": "Invalid document name", "error": "Bad Request" }
{ "statusCode": 401, "message": "Unauthorized" }
{ "statusCode": 422, "message": "Unprocessable Entity" }
Veja também
Sócios e documentos
Quando usar a rota direta e quando usar o token.
Criar token de upload
Token para sócios e uploads pelo navegador.
Listar representantes
Status de análise de cada documento.
Subcontas e KYC
Fluxo completo de credenciamento.

