POST /v1/customers HTTP/1.1
Host: api-global.fastpaybrasil.com
Authorization: Basic <base64 de "SUA_CHAVE_SECRETA:">
Content-Type: application/json
{
"name": "Joao Silva",
"email": "[email protected]",
"documentId": "52998224725",
"documentType": "cpf",
"phoneNumber": "+5511987654321"
}
curl -X POST "https://api-global.fastpaybrasil.com/v1/customers" \
-u "$FINVIA_API_KEY:" \
-H "Content-Type: application/json" \
-d '{
"name": "Joao Silva",
"email": "[email protected]",
"documentId": "52998224725",
"documentType": "cpf",
"phoneNumber": "+5511987654321"
}'
const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');
const response = await fetch('https://api-global.fastpaybrasil.com/v1/customers', {
method: 'POST',
headers: {
Authorization: `Basic ${credentials}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
name: 'Maria Souza',
email: '[email protected]',
documentId: '11222333000181',
documentType: 'cnpj',
}),
});
const { id } = await response.json();
import os
import requests
payload = {
"name": "Joao Silva",
"email": "[email protected]",
"documentId": "52998224725",
"documentType": "cpf",
"phoneNumber": "+5511987654321",
}
response = requests.request(
"POST",
"https://api-global.fastpaybrasil.com/v1/customers",
auth=(os.environ["FINVIA_API_KEY"], ""),
json=payload,
timeout=30,
)
print(response.status_code)
if response.content:
print(response.json())
<?php
$payload = [
'name' => 'Joao Silva',
'email' => '[email protected]',
'documentId' => '52998224725',
'documentType' => 'cpf',
'phoneNumber' => '+5511987654321',
];
$ch = curl_init('https://api-global.fastpaybrasil.com/v1/customers');
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 = """
{
"name": "Joao Silva",
"email": "[email protected]",
"documentId": "52998224725",
"documentType": "cpf",
"phoneNumber": "+5511987654321"
}
""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api-global.fastpaybrasil.com/v1/customers"))
.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 = """
{
"name": "Joao Silva",
"email": "[email protected]",
"documentId": "52998224725",
"documentType": "cpf",
"phoneNumber": "+5511987654321"
}
""";
var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/customers");
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(`{
"name": "Joao Silva",
"email": "[email protected]",
"documentId": "52998224725",
"documentType": "cpf",
"phoneNumber": "+5511987654321"
}`)
req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/customers", 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/customers")
request = Net::HTTP::Post.new(uri)
request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "")
request["Content-Type"] = "application/json"
request.body = JSON.generate({
"name" => "Joao Silva",
"email" => "[email protected]",
"documentId" => "52998224725",
"documentType" => "cpf",
"phoneNumber" => "+5511987654321",
})
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
puts response.code
puts response.body
{
"id": "2RhQg9M7ZCg3X3nMb9W1kX8Q"
}
{
"statusCode": 401,
"message": "Unauthorized"
}
{
"message": "Acesso negado",
"error": "Forbidden",
"statusCode": 403
}
Clientes
Criar um cliente
Cadastra o comprador com nome, e-mail e documento para usar depois em cobranças, cartões salvos e assinaturas.
POST
/
v1
/
customers
POST /v1/customers HTTP/1.1
Host: api-global.fastpaybrasil.com
Authorization: Basic <base64 de "SUA_CHAVE_SECRETA:">
Content-Type: application/json
{
"name": "Joao Silva",
"email": "[email protected]",
"documentId": "52998224725",
"documentType": "cpf",
"phoneNumber": "+5511987654321"
}
curl -X POST "https://api-global.fastpaybrasil.com/v1/customers" \
-u "$FINVIA_API_KEY:" \
-H "Content-Type: application/json" \
-d '{
"name": "Joao Silva",
"email": "[email protected]",
"documentId": "52998224725",
"documentType": "cpf",
"phoneNumber": "+5511987654321"
}'
const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');
const response = await fetch('https://api-global.fastpaybrasil.com/v1/customers', {
method: 'POST',
headers: {
Authorization: `Basic ${credentials}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
name: 'Maria Souza',
email: '[email protected]',
documentId: '11222333000181',
documentType: 'cnpj',
}),
});
const { id } = await response.json();
import os
import requests
payload = {
"name": "Joao Silva",
"email": "[email protected]",
"documentId": "52998224725",
"documentType": "cpf",
"phoneNumber": "+5511987654321",
}
response = requests.request(
"POST",
"https://api-global.fastpaybrasil.com/v1/customers",
auth=(os.environ["FINVIA_API_KEY"], ""),
json=payload,
timeout=30,
)
print(response.status_code)
if response.content:
print(response.json())
<?php
$payload = [
'name' => 'Joao Silva',
'email' => '[email protected]',
'documentId' => '52998224725',
'documentType' => 'cpf',
'phoneNumber' => '+5511987654321',
];
$ch = curl_init('https://api-global.fastpaybrasil.com/v1/customers');
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 = """
{
"name": "Joao Silva",
"email": "[email protected]",
"documentId": "52998224725",
"documentType": "cpf",
"phoneNumber": "+5511987654321"
}
""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api-global.fastpaybrasil.com/v1/customers"))
.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 = """
{
"name": "Joao Silva",
"email": "[email protected]",
"documentId": "52998224725",
"documentType": "cpf",
"phoneNumber": "+5511987654321"
}
""";
var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/customers");
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(`{
"name": "Joao Silva",
"email": "[email protected]",
"documentId": "52998224725",
"documentType": "cpf",
"phoneNumber": "+5511987654321"
}`)
req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/customers", 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/customers")
request = Net::HTTP::Post.new(uri)
request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "")
request["Content-Type"] = "application/json"
request.body = JSON.generate({
"name" => "Joao Silva",
"email" => "[email protected]",
"documentId" => "52998224725",
"documentType" => "cpf",
"phoneNumber" => "+5511987654321",
})
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
puts response.code
puts response.body
{
"id": "2RhQg9M7ZCg3X3nMb9W1kX8Q"
}
{
"statusCode": 401,
"message": "Unauthorized"
}
{
"message": "Acesso negado",
"error": "Forbidden",
"statusCode": 403
}
Esta rota cadastra um cliente (objeto
A resposta traz só o
customer), a pessoa ou empresa que paga. O cadastro devolve um id que você guarda no seu sistema e reutiliza: para registrar o cartão no cofre, para criar uma assinatura ou para cobrar sem reenviar os dados pessoais a cada venda.
Quando usar
| Situação | Como usar esta rota |
|---|---|
| Fluxo de assinatura com cartão registrado antes (cards-first) | Crie o cliente, depois registre o cartão com o id devolvido |
| Cadastro feito no seu site antes da primeira compra | Crie o cliente no momento do cadastro e guarde o id junto do usuário |
| Recompra com um clique | Cliente criado aqui + cartão salvo + cobrança com cardTokenId |
| Venda avulsa sem cadastro prévio | Não é preciso chamar esta rota: Criar cobrança aceita name e email e cria ou localiza o cliente |
Antes de chamar
- Tenha uma chave secreta (
sk_) válida. A chave herda as permissões do usuário que a gerou, e esta rota devolve403quando a chave não tem permissão (Credenciais e ambientes). - Confira se o cliente já existe com Listar clientes filtrando por
emailoudocumentId, para não duplicar o cadastro. - Se o cliente vai ter cartão salvo ou assinatura, colete e-mail e CPF ou CNPJ. Sem esses dois dados, o cartão não pode ser salvo.
O documento não pode ser alterado depois: Atualizar cliente muda só nome, e-mail e telefone. Para registrar cartão (em
POST /v1/cards ou no cartão enviado direto em POST /v1/subscriptions), o cliente precisa ter e-mail e CPF ou CNPJ. O tipo é deduzido pela quantidade de dígitos de documentId: 11 dígitos é CPF e 14 é CNPJ. Qualquer outro documento (passaporte, RG) conta como cliente sem documento, e o cartão é recusado com 400.Corpo da requisição
Campos obrigatórios:name, email, documentId e documentType.
E-mail do cliente (formato
email). Ex.: [email protected].Número do documento de identificação. Ex.:
52998224725 (CPF, 11 dígitos) ou 11222333000181 (CNPJ, 14 dígitos).Tipo do documento. Use
cpf ou cnpj. Para salvar cartão, o que conta é a quantidade de dígitos de documentId, e não o valor deste campo.Para o desenvolvedor: envie o
documentId como string, sem pontos, barras ou traços, como nos exemplos (52998224725). Guarde o id da resposta na tabela de usuários do seu sistema: ele é a chave para todas as operações seguintes com esse cliente.Respostas
Identificador único do cliente criado. Ex.:
2RhQg9M7ZCg3X3nMb9W1kX8Q. Use em customerId ao registrar um cartão ou criar uma assinatura, e em customer.id ao criar uma cobrança.id. Para ver o cadastro completo, use Consultar cliente.
| HTTP | Significado | Corpo |
|---|---|---|
201 | Cliente criado | {"id": "..."} |
401 | Credencial inválida | {"statusCode": 401, "message": "Unauthorized"} |
403 | Sem permissão | { "message": "Acesso negado", "error": "Forbidden", "statusCode": 403 } |
Para o negócio: ter o cliente cadastrado com CPF ou CNPJ e e-mail é a condição para oferecer recompra com cartão salvo e cobrança recorrente. Se o seu produto tem assinatura, peça esses dados já no cadastro do site ou do aplicativo, assim o cliente não precisa preencher nada a mais no momento da contratação.
Erros comuns
| Sintoma | Causa | Como resolver |
|---|---|---|
401 Unauthorized | Chave ausente, inválida ou mal codificada | Codifique em Base64 a chave seguida de : |
403 Forbidden | A chave herda as permissões do usuário que a gerou, e esse usuário não tem acesso à rota | Gere a chave com um usuário que tenha a permissão (para integração, use Owner ou Manager) |
| Registro de cartão recusado para o cliente | Cliente sem e-mail ou com documento que não tem 11 nem 14 dígitos | Cadastre o cliente com e-mail e CPF ou CNPJ |
| Documento cadastrado errado | O documento não muda depois da criação | Crie um novo cliente com o documento correto |
| Mesmo cliente cadastrado mais de uma vez | Criação sem verificar se já existia | Antes de criar, consulte Listar clientes com email ou documentId |
POST /v1/customers HTTP/1.1
Host: api-global.fastpaybrasil.com
Authorization: Basic <base64 de "SUA_CHAVE_SECRETA:">
Content-Type: application/json
{
"name": "Joao Silva",
"email": "[email protected]",
"documentId": "52998224725",
"documentType": "cpf",
"phoneNumber": "+5511987654321"
}
curl -X POST "https://api-global.fastpaybrasil.com/v1/customers" \
-u "$FINVIA_API_KEY:" \
-H "Content-Type: application/json" \
-d '{
"name": "Joao Silva",
"email": "[email protected]",
"documentId": "52998224725",
"documentType": "cpf",
"phoneNumber": "+5511987654321"
}'
const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');
const response = await fetch('https://api-global.fastpaybrasil.com/v1/customers', {
method: 'POST',
headers: {
Authorization: `Basic ${credentials}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
name: 'Maria Souza',
email: '[email protected]',
documentId: '11222333000181',
documentType: 'cnpj',
}),
});
const { id } = await response.json();
import os
import requests
payload = {
"name": "Joao Silva",
"email": "[email protected]",
"documentId": "52998224725",
"documentType": "cpf",
"phoneNumber": "+5511987654321",
}
response = requests.request(
"POST",
"https://api-global.fastpaybrasil.com/v1/customers",
auth=(os.environ["FINVIA_API_KEY"], ""),
json=payload,
timeout=30,
)
print(response.status_code)
if response.content:
print(response.json())
<?php
$payload = [
'name' => 'Joao Silva',
'email' => '[email protected]',
'documentId' => '52998224725',
'documentType' => 'cpf',
'phoneNumber' => '+5511987654321',
];
$ch = curl_init('https://api-global.fastpaybrasil.com/v1/customers');
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 = """
{
"name": "Joao Silva",
"email": "[email protected]",
"documentId": "52998224725",
"documentType": "cpf",
"phoneNumber": "+5511987654321"
}
""";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api-global.fastpaybrasil.com/v1/customers"))
.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 = """
{
"name": "Joao Silva",
"email": "[email protected]",
"documentId": "52998224725",
"documentType": "cpf",
"phoneNumber": "+5511987654321"
}
""";
var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/customers");
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(`{
"name": "Joao Silva",
"email": "[email protected]",
"documentId": "52998224725",
"documentType": "cpf",
"phoneNumber": "+5511987654321"
}`)
req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/customers", 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/customers")
request = Net::HTTP::Post.new(uri)
request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "")
request["Content-Type"] = "application/json"
request.body = JSON.generate({
"name" => "Joao Silva",
"email" => "[email protected]",
"documentId" => "52998224725",
"documentType" => "cpf",
"phoneNumber" => "+5511987654321",
})
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
http.request(request)
end
puts response.code
puts response.body
{
"id": "2RhQg9M7ZCg3X3nMb9W1kX8Q"
}
{
"statusCode": 401,
"message": "Unauthorized"
}
{
"message": "Acesso negado",
"error": "Forbidden",
"statusCode": 403
}
Veja também
Guia de clientes
Quando cadastrar e como reaproveitar o cliente.
Registrar cartão
Próximo passo do fluxo cards-first.
Cofre de cartões
Como os cartões ficam guardados e são reutilizados.
Visão geral de assinaturas
Cliente, plano e cartão na cobrança recorrente.

