Criar assinatura
curl --request POST \
--url https://sandbox.4seletpay.com.br/api/v2/subscriptions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"code": "plano-anual-123",
"description": "Plano de teste",
"interval": "week",
"interval_count": 2,
"max_invoices": 12,
"customer": {
"name": "João Silva",
"email": "joao@exemplo.com.br",
"phone": {
"ddi": 55,
"ddd": 11,
"number": "999999999"
},
"document": {
"type": "cpf",
"number": "12345678909"
}
},
"items": [
{
"code": "SKU-SUB",
"description": "Assinatura",
"quantity": 1,
"amount": 10000
}
],
"payment": {
"type": "card",
"card": {
"number": "4111111111111111",
"holder_name": "João Silva",
"exp_month": "12",
"exp_year": "2030",
"cvc": "123",
"installments": 1
}
},
"discounts": [
{
"type": "fixed",
"value": 1000,
"invoice_number": 1
}
],
"increments": [
{
"type": "percentage",
"value": 10,
"invoice_number": 2
}
]
}
'import requests
url = "https://sandbox.4seletpay.com.br/api/v2/subscriptions"
payload = {
"code": "plano-anual-123",
"description": "Plano de teste",
"interval": "week",
"interval_count": 2,
"max_invoices": 12,
"customer": {
"name": "João Silva",
"email": "joao@exemplo.com.br",
"phone": {
"ddi": 55,
"ddd": 11,
"number": "999999999"
},
"document": {
"type": "cpf",
"number": "12345678909"
}
},
"items": [
{
"code": "SKU-SUB",
"description": "Assinatura",
"quantity": 1,
"amount": 10000
}
],
"payment": {
"type": "card",
"card": {
"number": "4111111111111111",
"holder_name": "João Silva",
"exp_month": "12",
"exp_year": "2030",
"cvc": "123",
"installments": 1
}
},
"discounts": [
{
"type": "fixed",
"value": 1000,
"invoice_number": 1
}
],
"increments": [
{
"type": "percentage",
"value": 10,
"invoice_number": 2
}
]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
code: 'plano-anual-123',
description: 'Plano de teste',
interval: 'week',
interval_count: 2,
max_invoices: 12,
customer: {
name: 'João Silva',
email: 'joao@exemplo.com.br',
phone: {ddi: 55, ddd: 11, number: '999999999'},
document: {type: 'cpf', number: '12345678909'}
},
items: [{code: 'SKU-SUB', description: 'Assinatura', quantity: 1, amount: 10000}],
payment: {
type: 'card',
card: {
number: '4111111111111111',
holder_name: 'João Silva',
exp_month: '12',
exp_year: '2030',
cvc: '123',
installments: 1
}
},
discounts: [{type: 'fixed', value: 1000, invoice_number: 1}],
increments: [{type: 'percentage', value: 10, invoice_number: 2}]
})
};
fetch('https://sandbox.4seletpay.com.br/api/v2/subscriptions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://sandbox.4seletpay.com.br/api/v2/subscriptions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'code' => 'plano-anual-123',
'description' => 'Plano de teste',
'interval' => 'week',
'interval_count' => 2,
'max_invoices' => 12,
'customer' => [
'name' => 'João Silva',
'email' => 'joao@exemplo.com.br',
'phone' => [
'ddi' => 55,
'ddd' => 11,
'number' => '999999999'
],
'document' => [
'type' => 'cpf',
'number' => '12345678909'
]
],
'items' => [
[
'code' => 'SKU-SUB',
'description' => 'Assinatura',
'quantity' => 1,
'amount' => 10000
]
],
'payment' => [
'type' => 'card',
'card' => [
'number' => '4111111111111111',
'holder_name' => 'João Silva',
'exp_month' => '12',
'exp_year' => '2030',
'cvc' => '123',
'installments' => 1
]
],
'discounts' => [
[
'type' => 'fixed',
'value' => 1000,
'invoice_number' => 1
]
],
'increments' => [
[
'type' => 'percentage',
'value' => 10,
'invoice_number' => 2
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://sandbox.4seletpay.com.br/api/v2/subscriptions"
payload := strings.NewReader("{\n \"code\": \"plano-anual-123\",\n \"description\": \"Plano de teste\",\n \"interval\": \"week\",\n \"interval_count\": 2,\n \"max_invoices\": 12,\n \"customer\": {\n \"name\": \"João Silva\",\n \"email\": \"joao@exemplo.com.br\",\n \"phone\": {\n \"ddi\": 55,\n \"ddd\": 11,\n \"number\": \"999999999\"\n },\n \"document\": {\n \"type\": \"cpf\",\n \"number\": \"12345678909\"\n }\n },\n \"items\": [\n {\n \"code\": \"SKU-SUB\",\n \"description\": \"Assinatura\",\n \"quantity\": 1,\n \"amount\": 10000\n }\n ],\n \"payment\": {\n \"type\": \"card\",\n \"card\": {\n \"number\": \"4111111111111111\",\n \"holder_name\": \"João Silva\",\n \"exp_month\": \"12\",\n \"exp_year\": \"2030\",\n \"cvc\": \"123\",\n \"installments\": 1\n }\n },\n \"discounts\": [\n {\n \"type\": \"fixed\",\n \"value\": 1000,\n \"invoice_number\": 1\n }\n ],\n \"increments\": [\n {\n \"type\": \"percentage\",\n \"value\": 10,\n \"invoice_number\": 2\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://sandbox.4seletpay.com.br/api/v2/subscriptions")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"code\": \"plano-anual-123\",\n \"description\": \"Plano de teste\",\n \"interval\": \"week\",\n \"interval_count\": 2,\n \"max_invoices\": 12,\n \"customer\": {\n \"name\": \"João Silva\",\n \"email\": \"joao@exemplo.com.br\",\n \"phone\": {\n \"ddi\": 55,\n \"ddd\": 11,\n \"number\": \"999999999\"\n },\n \"document\": {\n \"type\": \"cpf\",\n \"number\": \"12345678909\"\n }\n },\n \"items\": [\n {\n \"code\": \"SKU-SUB\",\n \"description\": \"Assinatura\",\n \"quantity\": 1,\n \"amount\": 10000\n }\n ],\n \"payment\": {\n \"type\": \"card\",\n \"card\": {\n \"number\": \"4111111111111111\",\n \"holder_name\": \"João Silva\",\n \"exp_month\": \"12\",\n \"exp_year\": \"2030\",\n \"cvc\": \"123\",\n \"installments\": 1\n }\n },\n \"discounts\": [\n {\n \"type\": \"fixed\",\n \"value\": 1000,\n \"invoice_number\": 1\n }\n ],\n \"increments\": [\n {\n \"type\": \"percentage\",\n \"value\": 10,\n \"invoice_number\": 2\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://sandbox.4seletpay.com.br/api/v2/subscriptions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"code\": \"plano-anual-123\",\n \"description\": \"Plano de teste\",\n \"interval\": \"week\",\n \"interval_count\": 2,\n \"max_invoices\": 12,\n \"customer\": {\n \"name\": \"João Silva\",\n \"email\": \"joao@exemplo.com.br\",\n \"phone\": {\n \"ddi\": 55,\n \"ddd\": 11,\n \"number\": \"999999999\"\n },\n \"document\": {\n \"type\": \"cpf\",\n \"number\": \"12345678909\"\n }\n },\n \"items\": [\n {\n \"code\": \"SKU-SUB\",\n \"description\": \"Assinatura\",\n \"quantity\": 1,\n \"amount\": 10000\n }\n ],\n \"payment\": {\n \"type\": \"card\",\n \"card\": {\n \"number\": \"4111111111111111\",\n \"holder_name\": \"João Silva\",\n \"exp_month\": \"12\",\n \"exp_year\": \"2030\",\n \"cvc\": \"123\",\n \"installments\": 1\n }\n },\n \"discounts\": [\n {\n \"type\": \"fixed\",\n \"value\": 1000,\n \"invoice_number\": 1\n }\n ],\n \"increments\": [\n {\n \"type\": \"percentage\",\n \"value\": 10,\n \"invoice_number\": 2\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"id": "sub_4Hn8Qw2Rt6Yp1Zx3",
"object": "subscription",
"code": "plano-anual-123",
"status": "incomplete",
"currency": "brl",
"description": "Plano de teste",
"interval": "week",
"interval_count": 2,
"billing_type": "prepaid",
"amount": 10000,
"items": [
{
"code": "SKU-SUB",
"description": "Assinatura",
"quantity": 1,
"amount": 10000
}
],
"discounts": [
{
"type": "fixed",
"value": 1000,
"invoice_number": 1
}
],
"increments": [
{
"type": "percentage",
"value": 10,
"invoice_number": 2
}
],
"max_invoices": 12,
"invoices_paid": 0,
"minimum_price": null,
"payment_method": {
"type": "card",
"installments": 1,
"card": {
"token": "9b2f5c8e-3a1d-4f7b-8c6e-2d9a1b4c5e6f",
"brand": "visa",
"last_four": "1111",
"holder_name": "João Silva"
}
},
"statement_descriptor": null,
"start_at": "2026-09-14T00:00:00-03:00",
"next_billing_at": "2026-09-28T00:00:00-03:00",
"created_at": "2026-09-14T12:00:00-03:00",
"customer": {
"name": "João Silva",
"email": "joao@exemplo.com.br"
},
"latest_invoice": {
"id": "719305",
"object": "invoice",
"subscription": "sub_4Hn8Qw2Rt6Yp1Zx3",
"number": 1,
"status": "processing",
"currency": "brl",
"amount": 9000,
"attempts": 1,
"items": [
{
"code": "SKU-SUB",
"description": "Assinatura",
"quantity": 1,
"amount": 10000
}
],
"discounts": [
{
"type": "fixed",
"value": 1000,
"invoice_number": 1
}
],
"increments": [],
"payments": [
{
"id": "cha_8Kq2Lm9XvB3nT7pZ",
"object": "payment_intent",
"status": "processing",
"amount": 9000,
"amount_refunded": 0,
"currency": "brl",
"payment_method_details": {
"type": "card",
"card": {
"brand": "visa",
"last_four": "1111",
"holder_name": "João Silva"
}
}
}
],
"next_action": null,
"created_at": "2026-09-14T12:00:00-03:00"
},
"metadata": {}
}
Assinaturas
Criar assinatura
Cria uma assinatura recorrente. Sem start_at, a primeira fatura é cobrada na criação e vem em latest_invoice. Com start_at futuro, a assinatura fica scheduled e nada é cobrado agora. Se a primeira fatura for recusada, a resposta é 402 e a assinatura fica incomplete_expired.
Intervalo. interval é day ou week, com interval_count. Não existe mês de calendário: uma cobrança “mensal” é day × 30 e a data desliza em relação ao dia do mês. O intervalo total não pode passar de 365 dias.
Regras. Valores fixos de discounts e increments são inteiros em centavos; descontos percentuais vão até 100. split não pode ser combinado com descontos ou acréscimos. minimum_price é aceito e devolvido, mas ainda não é aplicado na cobrança. Não existe webhook de assinatura criada: a primeira fatura vem na própria resposta.
POST
/
v2
/
subscriptions
Criar assinatura
curl --request POST \
--url https://sandbox.4seletpay.com.br/api/v2/subscriptions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"code": "plano-anual-123",
"description": "Plano de teste",
"interval": "week",
"interval_count": 2,
"max_invoices": 12,
"customer": {
"name": "João Silva",
"email": "joao@exemplo.com.br",
"phone": {
"ddi": 55,
"ddd": 11,
"number": "999999999"
},
"document": {
"type": "cpf",
"number": "12345678909"
}
},
"items": [
{
"code": "SKU-SUB",
"description": "Assinatura",
"quantity": 1,
"amount": 10000
}
],
"payment": {
"type": "card",
"card": {
"number": "4111111111111111",
"holder_name": "João Silva",
"exp_month": "12",
"exp_year": "2030",
"cvc": "123",
"installments": 1
}
},
"discounts": [
{
"type": "fixed",
"value": 1000,
"invoice_number": 1
}
],
"increments": [
{
"type": "percentage",
"value": 10,
"invoice_number": 2
}
]
}
'import requests
url = "https://sandbox.4seletpay.com.br/api/v2/subscriptions"
payload = {
"code": "plano-anual-123",
"description": "Plano de teste",
"interval": "week",
"interval_count": 2,
"max_invoices": 12,
"customer": {
"name": "João Silva",
"email": "joao@exemplo.com.br",
"phone": {
"ddi": 55,
"ddd": 11,
"number": "999999999"
},
"document": {
"type": "cpf",
"number": "12345678909"
}
},
"items": [
{
"code": "SKU-SUB",
"description": "Assinatura",
"quantity": 1,
"amount": 10000
}
],
"payment": {
"type": "card",
"card": {
"number": "4111111111111111",
"holder_name": "João Silva",
"exp_month": "12",
"exp_year": "2030",
"cvc": "123",
"installments": 1
}
},
"discounts": [
{
"type": "fixed",
"value": 1000,
"invoice_number": 1
}
],
"increments": [
{
"type": "percentage",
"value": 10,
"invoice_number": 2
}
]
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
code: 'plano-anual-123',
description: 'Plano de teste',
interval: 'week',
interval_count: 2,
max_invoices: 12,
customer: {
name: 'João Silva',
email: 'joao@exemplo.com.br',
phone: {ddi: 55, ddd: 11, number: '999999999'},
document: {type: 'cpf', number: '12345678909'}
},
items: [{code: 'SKU-SUB', description: 'Assinatura', quantity: 1, amount: 10000}],
payment: {
type: 'card',
card: {
number: '4111111111111111',
holder_name: 'João Silva',
exp_month: '12',
exp_year: '2030',
cvc: '123',
installments: 1
}
},
discounts: [{type: 'fixed', value: 1000, invoice_number: 1}],
increments: [{type: 'percentage', value: 10, invoice_number: 2}]
})
};
fetch('https://sandbox.4seletpay.com.br/api/v2/subscriptions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://sandbox.4seletpay.com.br/api/v2/subscriptions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'code' => 'plano-anual-123',
'description' => 'Plano de teste',
'interval' => 'week',
'interval_count' => 2,
'max_invoices' => 12,
'customer' => [
'name' => 'João Silva',
'email' => 'joao@exemplo.com.br',
'phone' => [
'ddi' => 55,
'ddd' => 11,
'number' => '999999999'
],
'document' => [
'type' => 'cpf',
'number' => '12345678909'
]
],
'items' => [
[
'code' => 'SKU-SUB',
'description' => 'Assinatura',
'quantity' => 1,
'amount' => 10000
]
],
'payment' => [
'type' => 'card',
'card' => [
'number' => '4111111111111111',
'holder_name' => 'João Silva',
'exp_month' => '12',
'exp_year' => '2030',
'cvc' => '123',
'installments' => 1
]
],
'discounts' => [
[
'type' => 'fixed',
'value' => 1000,
'invoice_number' => 1
]
],
'increments' => [
[
'type' => 'percentage',
'value' => 10,
'invoice_number' => 2
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://sandbox.4seletpay.com.br/api/v2/subscriptions"
payload := strings.NewReader("{\n \"code\": \"plano-anual-123\",\n \"description\": \"Plano de teste\",\n \"interval\": \"week\",\n \"interval_count\": 2,\n \"max_invoices\": 12,\n \"customer\": {\n \"name\": \"João Silva\",\n \"email\": \"joao@exemplo.com.br\",\n \"phone\": {\n \"ddi\": 55,\n \"ddd\": 11,\n \"number\": \"999999999\"\n },\n \"document\": {\n \"type\": \"cpf\",\n \"number\": \"12345678909\"\n }\n },\n \"items\": [\n {\n \"code\": \"SKU-SUB\",\n \"description\": \"Assinatura\",\n \"quantity\": 1,\n \"amount\": 10000\n }\n ],\n \"payment\": {\n \"type\": \"card\",\n \"card\": {\n \"number\": \"4111111111111111\",\n \"holder_name\": \"João Silva\",\n \"exp_month\": \"12\",\n \"exp_year\": \"2030\",\n \"cvc\": \"123\",\n \"installments\": 1\n }\n },\n \"discounts\": [\n {\n \"type\": \"fixed\",\n \"value\": 1000,\n \"invoice_number\": 1\n }\n ],\n \"increments\": [\n {\n \"type\": \"percentage\",\n \"value\": 10,\n \"invoice_number\": 2\n }\n ]\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://sandbox.4seletpay.com.br/api/v2/subscriptions")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"code\": \"plano-anual-123\",\n \"description\": \"Plano de teste\",\n \"interval\": \"week\",\n \"interval_count\": 2,\n \"max_invoices\": 12,\n \"customer\": {\n \"name\": \"João Silva\",\n \"email\": \"joao@exemplo.com.br\",\n \"phone\": {\n \"ddi\": 55,\n \"ddd\": 11,\n \"number\": \"999999999\"\n },\n \"document\": {\n \"type\": \"cpf\",\n \"number\": \"12345678909\"\n }\n },\n \"items\": [\n {\n \"code\": \"SKU-SUB\",\n \"description\": \"Assinatura\",\n \"quantity\": 1,\n \"amount\": 10000\n }\n ],\n \"payment\": {\n \"type\": \"card\",\n \"card\": {\n \"number\": \"4111111111111111\",\n \"holder_name\": \"João Silva\",\n \"exp_month\": \"12\",\n \"exp_year\": \"2030\",\n \"cvc\": \"123\",\n \"installments\": 1\n }\n },\n \"discounts\": [\n {\n \"type\": \"fixed\",\n \"value\": 1000,\n \"invoice_number\": 1\n }\n ],\n \"increments\": [\n {\n \"type\": \"percentage\",\n \"value\": 10,\n \"invoice_number\": 2\n }\n ]\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://sandbox.4seletpay.com.br/api/v2/subscriptions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"code\": \"plano-anual-123\",\n \"description\": \"Plano de teste\",\n \"interval\": \"week\",\n \"interval_count\": 2,\n \"max_invoices\": 12,\n \"customer\": {\n \"name\": \"João Silva\",\n \"email\": \"joao@exemplo.com.br\",\n \"phone\": {\n \"ddi\": 55,\n \"ddd\": 11,\n \"number\": \"999999999\"\n },\n \"document\": {\n \"type\": \"cpf\",\n \"number\": \"12345678909\"\n }\n },\n \"items\": [\n {\n \"code\": \"SKU-SUB\",\n \"description\": \"Assinatura\",\n \"quantity\": 1,\n \"amount\": 10000\n }\n ],\n \"payment\": {\n \"type\": \"card\",\n \"card\": {\n \"number\": \"4111111111111111\",\n \"holder_name\": \"João Silva\",\n \"exp_month\": \"12\",\n \"exp_year\": \"2030\",\n \"cvc\": \"123\",\n \"installments\": 1\n }\n },\n \"discounts\": [\n {\n \"type\": \"fixed\",\n \"value\": 1000,\n \"invoice_number\": 1\n }\n ],\n \"increments\": [\n {\n \"type\": \"percentage\",\n \"value\": 10,\n \"invoice_number\": 2\n }\n ]\n}"
response = http.request(request)
puts response.read_body{
"id": "sub_4Hn8Qw2Rt6Yp1Zx3",
"object": "subscription",
"code": "plano-anual-123",
"status": "incomplete",
"currency": "brl",
"description": "Plano de teste",
"interval": "week",
"interval_count": 2,
"billing_type": "prepaid",
"amount": 10000,
"items": [
{
"code": "SKU-SUB",
"description": "Assinatura",
"quantity": 1,
"amount": 10000
}
],
"discounts": [
{
"type": "fixed",
"value": 1000,
"invoice_number": 1
}
],
"increments": [
{
"type": "percentage",
"value": 10,
"invoice_number": 2
}
],
"max_invoices": 12,
"invoices_paid": 0,
"minimum_price": null,
"payment_method": {
"type": "card",
"installments": 1,
"card": {
"token": "9b2f5c8e-3a1d-4f7b-8c6e-2d9a1b4c5e6f",
"brand": "visa",
"last_four": "1111",
"holder_name": "João Silva"
}
},
"statement_descriptor": null,
"start_at": "2026-09-14T00:00:00-03:00",
"next_billing_at": "2026-09-28T00:00:00-03:00",
"created_at": "2026-09-14T12:00:00-03:00",
"customer": {
"name": "João Silva",
"email": "joao@exemplo.com.br"
},
"latest_invoice": {
"id": "719305",
"object": "invoice",
"subscription": "sub_4Hn8Qw2Rt6Yp1Zx3",
"number": 1,
"status": "processing",
"currency": "brl",
"amount": 9000,
"attempts": 1,
"items": [
{
"code": "SKU-SUB",
"description": "Assinatura",
"quantity": 1,
"amount": 10000
}
],
"discounts": [
{
"type": "fixed",
"value": 1000,
"invoice_number": 1
}
],
"increments": [],
"payments": [
{
"id": "cha_8Kq2Lm9XvB3nT7pZ",
"object": "payment_intent",
"status": "processing",
"amount": 9000,
"amount_refunded": 0,
"currency": "brl",
"payment_method_details": {
"type": "card",
"card": {
"brand": "visa",
"last_four": "1111",
"holder_name": "João Silva"
}
}
}
],
"next_action": null,
"created_at": "2026-09-14T12:00:00-03:00"
},
"metadata": {}
}
201 não significa pago. Sem start_at, a primeira fatura é cobrada na criação e volta em latest_invoice. Com cartão, ela costuma ficar em processing até a confirmação; com PIX, fica em requires_action com o QR Code em latest_invoice.next_action. Se a primeira fatura for recusada, a resposta é 402 com a assinatura em incomplete_expired e o motivo em latest_invoice.failure_reason.Todos os valores são em centavos (
10000 = R$ 100,00). O intervalo é interval (day ou week) × interval_count, com no máximo 365 dias. Não existe mês de calendário: uma assinatura “mensal” é day × 30 e a data de cobrança desliza em relação ao calendário. Veja Intervalo de cobrança.Com
start_at (a partir de amanhã), a assinatura nasce scheduled e nada é cobrado na criação.Para usar um cartão salvo, envie
payment.card.token com o id retornado por POST /v2/cards. Sem token, envie number, holder_name, exp_month, exp_year e cvc.O campo
minimum_price é aceito e devolvido, mas não é aplicado na cobrança das faturas.Esta rota passa pelo bloqueio de clientes (
403 customer_blocked) e pelo limite por comprador (429 rate_limit_exceeded). Envie o header Idempotency-Key para reenviar com segurança. Veja Idempotência e limites.Authorizations
Chave de API (secret key) da conta, no formato sk_live_... (produção) ou sk_test_... (Dev mode). Envie no header Authorization: Bearer <chave>. Autentica todas as rotas da API v2 e as rotas de Análise de Fraude. A chave identifica a conta, então a API v2 não usa o header account. Uma chave só é aceita no ambiente em que foi criada. Gere a sua no dashboard em Configurações → Chaves de API.
Headers
Chave de idempotência opcional e recomendada. Tem até 128 caracteres e vale por 24 horas, por conta. A mesma chave com o mesmo corpo devolve a resposta original (mesmo status e mesmo corpo), sem processar de novo. Só respostas 2xx ficam guardadas: depois de um erro, a mesma chave pode ser reutilizada. A mesma chave com um corpo diferente retorna 422 (idempotency_key_conflict), uma requisição original ainda em andamento retorna 409 (idempotency_key_in_use) e uma chave com mais de 128 caracteres retorna 400 (idempotency_key_invalid).
Maximum string length:
128Example:
"pedido-1024-tentativa-1"
Body
application/json
Unidade do intervalo entre cobranças. Não existe mês de calendário: para uma cobrança mensal, use day com interval_count: 30 — a data desliza em relação ao dia do mês.
Available options:
day, week Example:
"week"
Quantidade de unidades entre cobranças. O intervalo total não pode passar de 365 dias
Required range:
x >= 1Example:
2
Dados do comprador da assinatura
Show child attributes
Show child attributes
Minimum array length:
1Show child attributes
Show child attributes
Show child attributes
Show child attributes
Código da assinatura na sua integração
Maximum string length:
255Example:
"plano-anual-123"
Maximum string length:
255Example:
"Plano de teste"
Available options:
BRL, USD Available options:
prepaid Data da primeira cobrança, a partir de amanhã. Sem start_at, a primeira fatura é cobrada na criação.
Example:
"2026-09-20"
Número máximo de faturas. Ao pagar a última, a assinatura fica completed
Required range:
x >= 1Example:
12
Aceito e devolvido pela API, mas ainda não é aplicado na cobrança
Required range:
x >= 0Texto na fatura do cartão
Maximum string length:
50Show child attributes
Show child attributes
Show child attributes
Show child attributes
Divisão de cada fatura entre recebedores. A soma de split[].amount precisa ser igual ao total dos itens. Exatamente um recebedor com options.charge_processing_fee: true, ao menos um com options.charge_remainder_fee: true e ao menos um com options.liable: true. Cada receiver_code (até 32 caracteres) precisa pertencer à conta e estar ativo ou com ativação pendente. Não pode ser combinado com discounts ou increments.
Required array length:
1 - 10 elementsShow child attributes
Show child attributes
Pula a análise de fraude. Exige permissão da conta — sem ela, a requisição retorna 422 (fraud_bypass_not_allowed). Todo pulo precisa de um motivo, que fica registrado.
Show child attributes
Show child attributes
Response
Assinatura criada. Com cobrança imediata, o status fica incomplete até a primeira fatura ser paga (a confirmação chega por webhook invoice.paid). Com start_at futuro, fica scheduled.
Assinatura. incomplete: a primeira fatura ainda não foi paga. incomplete_expired: a primeira fatura foi recusada. scheduled: a primeira cobrança está agendada (start_at). active: em dia. past_due: fatura em atraso. suspended: suspensa. canceled: cancelada. completed: todas as faturas previstas foram pagas.
Example:
"sub_4Hn8Qw2Rt6Yp1Zx3"
Available options:
subscription Example:
"plano-anual-123"
Available options:
incomplete, incomplete_expired, scheduled, active, past_due, suspended, canceled, completed Example:
"brl"
Available options:
day, week Available options:
prepaid Total dos itens, em centavos, sem descontos ou acréscimos
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Quantidade de faturas pagas
Aceito e devolvido pela API, mas ainda não é aplicado na cobrança
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Fatura de um ciclo da assinatura. processing: em processamento. requires_action: PIX aguardando pagamento ou verificação por código (veja next_action). paid: paga. failed: recusada (veja failure_reason). canceled: cancelada. refunded e partially_refunded: estornada. chargeback: contestada.
Show child attributes
Show child attributes