POST /v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document/upload-token HTTP/1.1
Host: api-global.fastpaybrasil.com
Authorization: Basic <base64 de "SUA_CHAVE_SECRETA:">
Content-Type: application/json
{
"legalRepresentativeId": "2vorkEbbbCccDddEeeFffGggHhh"
}
curl -X POST "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document/upload-token" \
-u "$FINVIA_API_KEY:" \
-H "Content-Type: application/json" \
-d '{ "legalRepresentativeId": "2vorkEbbbCccDddEeeFffGggHhh" }'
const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');
const merchantId = '36OO3bcGjhPjjF3tzrqOGcmQuKo';
const response = await fetch(
`https://api-global.fastpaybrasil.com/v1/submerchants/${merchantId}/document/upload-token`,
{
method: 'POST',
headers: {
Authorization: `Basic ${credentials}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ legalRepresentativeId: '2vorkEbbbCccDddEeeFffGggHhh' }),
},
);
const { token, expiresIn } = await response.json();
// Entregue apenas o token ao front-end; ele vale por expiresIn segundos
import os
import requests
payload = {
"legalRepresentativeId": "2vorkEbbbCccDddEeeFffGggHhh",
}
response = requests.request(
"POST",
"https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document/upload-token",
auth=(os.environ["FINVIA_API_KEY"], ""),
json=payload,
timeout=30,
)
print(response.status_code)
if response.content:
print(response.json())
<?php
$payload = [
'legalRepresentativeId' => '2vorkEbbbCccDddEeeFffGggHhh',
];
$ch = curl_init('https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document/upload-token');
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 = """
{
"legalRepresentativeId": "2vorkEbbbCccDddEeeFffGggHhh"
}
""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document/upload-token"))
.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 = """
{
"legalRepresentativeId": "2vorkEbbbCccDddEeeFffGggHhh"
}
""";
var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document/upload-token");
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(`{
"legalRepresentativeId": "2vorkEbbbCccDddEeeFffGggHhh"
}`)
req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document/upload-token", 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/36OO3bcGjhPjjF3tzrqOGcmQuKo/document/upload-token")
request = Net::HTTP::Post.new(uri)
request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "")
request["Content-Type"] = "application/json"
request.body = JSON.generate({
"legalRepresentativeId" => "2vorkEbbbCccDddEeeFffGggHhh",
})
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
puts response.code
puts response.body
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresIn": 300
}
{ "statusCode": 401, "message": "Unauthorized" }
{ "statusCode": 404, "message": "Representante legal não encontrado" }
Connect
Criar token de upload
Emite um token de curta duração para enviar documentos da subconta sem expor a chave secreta, com vínculo opcional a um sócio.
POST
/
v1
/
submerchants
/
{merchantId}
/
document
/
upload-token
POST /v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document/upload-token HTTP/1.1
Host: api-global.fastpaybrasil.com
Authorization: Basic <base64 de "SUA_CHAVE_SECRETA:">
Content-Type: application/json
{
"legalRepresentativeId": "2vorkEbbbCccDddEeeFffGggHhh"
}
curl -X POST "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document/upload-token" \
-u "$FINVIA_API_KEY:" \
-H "Content-Type: application/json" \
-d '{ "legalRepresentativeId": "2vorkEbbbCccDddEeeFffGggHhh" }'
const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');
const merchantId = '36OO3bcGjhPjjF3tzrqOGcmQuKo';
const response = await fetch(
`https://api-global.fastpaybrasil.com/v1/submerchants/${merchantId}/document/upload-token`,
{
method: 'POST',
headers: {
Authorization: `Basic ${credentials}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ legalRepresentativeId: '2vorkEbbbCccDddEeeFffGggHhh' }),
},
);
const { token, expiresIn } = await response.json();
// Entregue apenas o token ao front-end; ele vale por expiresIn segundos
import os
import requests
payload = {
"legalRepresentativeId": "2vorkEbbbCccDddEeeFffGggHhh",
}
response = requests.request(
"POST",
"https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document/upload-token",
auth=(os.environ["FINVIA_API_KEY"], ""),
json=payload,
timeout=30,
)
print(response.status_code)
if response.content:
print(response.json())
<?php
$payload = [
'legalRepresentativeId' => '2vorkEbbbCccDddEeeFffGggHhh',
];
$ch = curl_init('https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document/upload-token');
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 = """
{
"legalRepresentativeId": "2vorkEbbbCccDddEeeFffGggHhh"
}
""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document/upload-token"))
.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 = """
{
"legalRepresentativeId": "2vorkEbbbCccDddEeeFffGggHhh"
}
""";
var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document/upload-token");
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(`{
"legalRepresentativeId": "2vorkEbbbCccDddEeeFffGggHhh"
}`)
req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document/upload-token", 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/36OO3bcGjhPjjF3tzrqOGcmQuKo/document/upload-token")
request = Net::HTTP::Post.new(uri)
request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "")
request["Content-Type"] = "application/json"
request.body = JSON.generate({
"legalRepresentativeId" => "2vorkEbbbCccDddEeeFffGggHhh",
})
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
puts response.code
puts response.body
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresIn": 300
}
{ "statusCode": 401, "message": "Unauthorized" }
{ "statusCode": 404, "message": "Representante legal não encontrado" }
Esta rota gera um token de upload: uma credencial temporária, válida por 5 minutos, que só serve para enviar documentos de uma subconta em
POST /v1/document-uploads. Com ele, o upload pode sair direto do navegador do vendedor, sem que a chave secreta saia do seu servidor. É também o único caminho para enviar os documentos pessoais de um sócio adicional.
Quando usar
| Situação | Como usar esta rota |
|---|---|
| Documentos pessoais de um sócio adicional | Envie o legalRepresentativeId do sócio |
| Tela de upload no navegador do vendedor | Gere o token no seu servidor e entregue só o token ao front-end |
| Reenviar o documento de um sócio específico | Gere um token novo com o legalRepresentativeId dele e reenvie o arquivo |
| Documentos do representante legal ou da empresa | Sem corpo (vincula ao representante legal), ou use Enviar documentos |
Antes de chamar
- Tenha o
idda subconta, devolvido em Criar subconta. - Para um sócio, tenha o
iddele: vem emlegalRepresentativesna resposta da criação (itens comisPrimary: false) ou em Listar representantes. - Autentique com a chave secreta (
sk_) da conta master, sempre no servidor (Credenciais e ambientes).
Parâmetros de caminho
Corpo da requisição
Formatoapplication/json. O corpo é opcional.
Sócio ao qual os documentos de pessoa (
responsible_document_front, responsible_document_back, selfie_with_document) serão vinculados. Precisa pertencer à subconta; caso contrário, a resposta é 404. Quando omitido, os documentos ficam no representante legal. Ex.: 2vorkEbbbCccDddEeeFffGggHhh.O
legalRepresentativeId só afeta documentos de pessoa. Documentos de empresa (cnpj_card, social_contract, irs_letter) valem para a subconta como um todo, com ou sem sócio no token.Respostas
Token de upload. Use no cabeçalho
Authorization: Bearer da chamada POST /v1/document-uploads. Ex.: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....| HTTP | Significado | Corpo |
|---|---|---|
201 | Token emitido | token, expiresIn |
401 | Credencial inválida | {"statusCode": 401, "message": "Unauthorized"} |
404 | Representante legal não encontrado (não pertence à subconta) | {"statusCode": 404, "message": "Representante legal não encontrado"} |
O token expira em 300 segundos (5 minutos) e é de uso único. Gere o token no momento do envio. Token vencido é recusado com
401 “Token de upload inválido ou expirado”; token já usado, com 403 “Token de upload expirado ou já utilizado”. Nos dois casos, gere outro token.Para o desenvolvedor: a subconta e o sócio ficam gravados dentro do token. O front-end recebe só o token e não consegue trocar de subconta ou de sócio. Gere um token por sócio: um token emitido para Bruno vincula os documentos de pessoa a Bruno, mesmo que o arquivo seja de outra pessoa.
Para o negócio: com o token, cada sócio pode enviar os próprios documentos por um link ou tela do seu sistema, e a chave secreta da sua conta continua guardada no servidor.
Erros comuns
| Sintoma | Causa | Como resolver |
|---|---|---|
404 “Representante legal não encontrado” | legalRepresentativeId de outra subconta ou inexistente | Confira os ids com Listar representantes para esse merchantId |
401 | Chave ausente, inválida ou mal codificada no Basic | Codifique chave: em Base64 (com os dois-pontos no fim) |
Upload recusado com 401 minutos depois | Token vencido (300 segundos) | Gere um token novo logo antes do envio |
Segundo upload recusado com 403 | O token é de uso único | Gere um token para cada envio |
| Documentos do sócio aparecem no representante legal | Token emitido sem legalRepresentativeId | Envie o id do sócio no corpo |
POST /v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document/upload-token HTTP/1.1
Host: api-global.fastpaybrasil.com
Authorization: Basic <base64 de "SUA_CHAVE_SECRETA:">
Content-Type: application/json
{
"legalRepresentativeId": "2vorkEbbbCccDddEeeFffGggHhh"
}
curl -X POST "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document/upload-token" \
-u "$FINVIA_API_KEY:" \
-H "Content-Type: application/json" \
-d '{ "legalRepresentativeId": "2vorkEbbbCccDddEeeFffGggHhh" }'
const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');
const merchantId = '36OO3bcGjhPjjF3tzrqOGcmQuKo';
const response = await fetch(
`https://api-global.fastpaybrasil.com/v1/submerchants/${merchantId}/document/upload-token`,
{
method: 'POST',
headers: {
Authorization: `Basic ${credentials}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ legalRepresentativeId: '2vorkEbbbCccDddEeeFffGggHhh' }),
},
);
const { token, expiresIn } = await response.json();
// Entregue apenas o token ao front-end; ele vale por expiresIn segundos
import os
import requests
payload = {
"legalRepresentativeId": "2vorkEbbbCccDddEeeFffGggHhh",
}
response = requests.request(
"POST",
"https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document/upload-token",
auth=(os.environ["FINVIA_API_KEY"], ""),
json=payload,
timeout=30,
)
print(response.status_code)
if response.content:
print(response.json())
<?php
$payload = [
'legalRepresentativeId' => '2vorkEbbbCccDddEeeFffGggHhh',
];
$ch = curl_init('https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document/upload-token');
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 = """
{
"legalRepresentativeId": "2vorkEbbbCccDddEeeFffGggHhh"
}
""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document/upload-token"))
.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 = """
{
"legalRepresentativeId": "2vorkEbbbCccDddEeeFffGggHhh"
}
""";
var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document/upload-token");
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(`{
"legalRepresentativeId": "2vorkEbbbCccDddEeeFffGggHhh"
}`)
req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/submerchants/36OO3bcGjhPjjF3tzrqOGcmQuKo/document/upload-token", 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/36OO3bcGjhPjjF3tzrqOGcmQuKo/document/upload-token")
request = Net::HTTP::Post.new(uri)
request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "")
request["Content-Type"] = "application/json"
request.body = JSON.generate({
"legalRepresentativeId" => "2vorkEbbbCccDddEeeFffGggHhh",
})
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
puts response.code
puts response.body
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"expiresIn": 300
}
{ "statusCode": 401, "message": "Unauthorized" }
{ "statusCode": 404, "message": "Representante legal não encontrado" }
Veja também
Enviar documentos com token
Upload usando o token gerado aqui.
Sócios e documentos
Fluxo completo de documentos por sócio.
Listar representantes
Ids dos sócios e status dos documentos.
Criar subconta
Cadastro com sócios adicionais.

