Criar assinatura

curl --request POST \
  --url https://api.uvvipay.com.br/v1/subscriptions \
  --header 'Content-Type: application/json' \
  --header 'client-id: <api-key>' \
  --header 'client-secret: <api-key>' \
  --data '
{
  "subscription_plan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "grace_period_days": 3,
  "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "payment_methods": {
    "number": "4111111111111111",
    "holder_name": "JOAO DA SILVA",
    "security_code": "123",
    "expiration_month": 12,
    "expiration_year": 2030,
    "type": "credit_card",
    "main_payment_method": true
  },
  "transaction_idempotency_id": "sub-create-0001",
  "trial_duration": 1,
  "trial_unit": "DAY"
}
'

import requests

url = "https://api.uvvipay.com.br/v1/subscriptions"

payload = {
    "subscription_plan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "grace_period_days": 3,
    "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "payment_methods": {
        "number": "4111111111111111",
        "holder_name": "JOAO DA SILVA",
        "security_code": "123",
        "expiration_month": 12,
        "expiration_year": 2030,
        "type": "credit_card",
        "main_payment_method": True
    },
    "transaction_idempotency_id": "sub-create-0001",
    "trial_duration": 1,
    "trial_unit": "DAY"
}
headers = {
    "client-id": "<api-key>",
    "client-secret": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'client-id': '<api-key>',
    'client-secret': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    subscription_plan_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    grace_period_days: 3,
    customer_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    payment_methods: {
      number: '4111111111111111',
      holder_name: 'JOAO DA SILVA',
      security_code: '123',
      expiration_month: 12,
      expiration_year: 2030,
      type: 'credit_card',
      main_payment_method: true
    },
    transaction_idempotency_id: 'sub-create-0001',
    trial_duration: 1,
    trial_unit: 'DAY'
  })
};

fetch('https://api.uvvipay.com.br/v1/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://api.uvvipay.com.br/v1/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([
    'subscription_plan_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'grace_period_days' => 3,
    'customer_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'payment_methods' => [
        'number' => '4111111111111111',
        'holder_name' => 'JOAO DA SILVA',
        'security_code' => '123',
        'expiration_month' => 12,
        'expiration_year' => 2030,
        'type' => 'credit_card',
        'main_payment_method' => true
    ],
    'transaction_idempotency_id' => 'sub-create-0001',
    'trial_duration' => 1,
    'trial_unit' => 'DAY'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "client-id: <api-key>",
    "client-secret: <api-key>"
  ],
]);

$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://api.uvvipay.com.br/v1/subscriptions"

	payload := strings.NewReader("{\n  \"subscription_plan_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"grace_period_days\": 3,\n  \"customer_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"payment_methods\": {\n    \"number\": \"4111111111111111\",\n    \"holder_name\": \"JOAO DA SILVA\",\n    \"security_code\": \"123\",\n    \"expiration_month\": 12,\n    \"expiration_year\": 2030,\n    \"type\": \"credit_card\",\n    \"main_payment_method\": true\n  },\n  \"transaction_idempotency_id\": \"sub-create-0001\",\n  \"trial_duration\": 1,\n  \"trial_unit\": \"DAY\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("client-id", "<api-key>")
	req.Header.Add("client-secret", "<api-key>")
	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://api.uvvipay.com.br/v1/subscriptions")
  .header("client-id", "<api-key>")
  .header("client-secret", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"subscription_plan_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"grace_period_days\": 3,\n  \"customer_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"payment_methods\": {\n    \"number\": \"4111111111111111\",\n    \"holder_name\": \"JOAO DA SILVA\",\n    \"security_code\": \"123\",\n    \"expiration_month\": 12,\n    \"expiration_year\": 2030,\n    \"type\": \"credit_card\",\n    \"main_payment_method\": true\n  },\n  \"transaction_idempotency_id\": \"sub-create-0001\",\n  \"trial_duration\": 1,\n  \"trial_unit\": \"DAY\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.uvvipay.com.br/v1/subscriptions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["client-id"] = '<api-key>'
request["client-secret"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"subscription_plan_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"grace_period_days\": 3,\n  \"customer_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"payment_methods\": {\n    \"number\": \"4111111111111111\",\n    \"holder_name\": \"JOAO DA SILVA\",\n    \"security_code\": \"123\",\n    \"expiration_month\": 12,\n    \"expiration_year\": 2030,\n    \"type\": \"credit_card\",\n    \"main_payment_method\": true\n  },\n  \"transaction_idempotency_id\": \"sub-create-0001\",\n  \"trial_duration\": 1,\n  \"trial_unit\": \"DAY\"\n}"

response = http.request(request)
puts response.read_body

{
  "subscription_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "invoice_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "subscription_status": "ACTIVE",
  "invoice_status": "<string>",
  "charge_status": "pending",
  "transaction_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "failure_code": "<string>",
  "failure_message": "<string>",
  "pix": {
    "qrcode": "<string>"
  }
}

{
  "code": "UVV154293",
  "message": "Nao foi possivel processar pagamento. Verifique os dados e tente novamente."
}

{
  "code": "UVV154158",
  "message": "Nao foi possivel processar pagamento. Verifique os dados e tente novamente."
}

{
  "code": "UVV154640",
  "message": "Nao foi possivel processar pagamento. Verifique os dados e tente novamente."
}

{
  "code": "UVV154524",
  "message": "Nao foi possivel processar a cobranca. Tente novamente."
}

POST

subscriptions

Criar assinatura

curl --request POST \
  --url https://api.uvvipay.com.br/v1/subscriptions \
  --header 'Content-Type: application/json' \
  --header 'client-id: <api-key>' \
  --header 'client-secret: <api-key>' \
  --data '
{
  "subscription_plan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "grace_period_days": 3,
  "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "payment_methods": {
    "number": "4111111111111111",
    "holder_name": "JOAO DA SILVA",
    "security_code": "123",
    "expiration_month": 12,
    "expiration_year": 2030,
    "type": "credit_card",
    "main_payment_method": true
  },
  "transaction_idempotency_id": "sub-create-0001",
  "trial_duration": 1,
  "trial_unit": "DAY"
}
'

import requests

url = "https://api.uvvipay.com.br/v1/subscriptions"

payload = {
    "subscription_plan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "grace_period_days": 3,
    "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "payment_methods": {
        "number": "4111111111111111",
        "holder_name": "JOAO DA SILVA",
        "security_code": "123",
        "expiration_month": 12,
        "expiration_year": 2030,
        "type": "credit_card",
        "main_payment_method": True
    },
    "transaction_idempotency_id": "sub-create-0001",
    "trial_duration": 1,
    "trial_unit": "DAY"
}
headers = {
    "client-id": "<api-key>",
    "client-secret": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'client-id': '<api-key>',
    'client-secret': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    subscription_plan_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    grace_period_days: 3,
    customer_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    payment_methods: {
      number: '4111111111111111',
      holder_name: 'JOAO DA SILVA',
      security_code: '123',
      expiration_month: 12,
      expiration_year: 2030,
      type: 'credit_card',
      main_payment_method: true
    },
    transaction_idempotency_id: 'sub-create-0001',
    trial_duration: 1,
    trial_unit: 'DAY'
  })
};

fetch('https://api.uvvipay.com.br/v1/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://api.uvvipay.com.br/v1/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([
    'subscription_plan_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'grace_period_days' => 3,
    'customer_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'payment_methods' => [
        'number' => '4111111111111111',
        'holder_name' => 'JOAO DA SILVA',
        'security_code' => '123',
        'expiration_month' => 12,
        'expiration_year' => 2030,
        'type' => 'credit_card',
        'main_payment_method' => true
    ],
    'transaction_idempotency_id' => 'sub-create-0001',
    'trial_duration' => 1,
    'trial_unit' => 'DAY'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "client-id: <api-key>",
    "client-secret: <api-key>"
  ],
]);

$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://api.uvvipay.com.br/v1/subscriptions"

	payload := strings.NewReader("{\n  \"subscription_plan_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"grace_period_days\": 3,\n  \"customer_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"payment_methods\": {\n    \"number\": \"4111111111111111\",\n    \"holder_name\": \"JOAO DA SILVA\",\n    \"security_code\": \"123\",\n    \"expiration_month\": 12,\n    \"expiration_year\": 2030,\n    \"type\": \"credit_card\",\n    \"main_payment_method\": true\n  },\n  \"transaction_idempotency_id\": \"sub-create-0001\",\n  \"trial_duration\": 1,\n  \"trial_unit\": \"DAY\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("client-id", "<api-key>")
	req.Header.Add("client-secret", "<api-key>")
	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://api.uvvipay.com.br/v1/subscriptions")
  .header("client-id", "<api-key>")
  .header("client-secret", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"subscription_plan_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"grace_period_days\": 3,\n  \"customer_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"payment_methods\": {\n    \"number\": \"4111111111111111\",\n    \"holder_name\": \"JOAO DA SILVA\",\n    \"security_code\": \"123\",\n    \"expiration_month\": 12,\n    \"expiration_year\": 2030,\n    \"type\": \"credit_card\",\n    \"main_payment_method\": true\n  },\n  \"transaction_idempotency_id\": \"sub-create-0001\",\n  \"trial_duration\": 1,\n  \"trial_unit\": \"DAY\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.uvvipay.com.br/v1/subscriptions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["client-id"] = '<api-key>'
request["client-secret"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"subscription_plan_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"grace_period_days\": 3,\n  \"customer_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"payment_methods\": {\n    \"number\": \"4111111111111111\",\n    \"holder_name\": \"JOAO DA SILVA\",\n    \"security_code\": \"123\",\n    \"expiration_month\": 12,\n    \"expiration_year\": 2030,\n    \"type\": \"credit_card\",\n    \"main_payment_method\": true\n  },\n  \"transaction_idempotency_id\": \"sub-create-0001\",\n  \"trial_duration\": 1,\n  \"trial_unit\": \"DAY\"\n}"

response = http.request(request)
puts response.read_body

{
  "subscription_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "customer_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "invoice_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "subscription_status": "ACTIVE",
  "invoice_status": "<string>",
  "charge_status": "pending",
  "transaction_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "failure_code": "<string>",
  "failure_message": "<string>",
  "pix": {
    "qrcode": "<string>"
  }
}

{
  "code": "UVV154293",
  "message": "Nao foi possivel processar pagamento. Verifique os dados e tente novamente."
}

{
  "code": "UVV154158",
  "message": "Nao foi possivel processar pagamento. Verifique os dados e tente novamente."
}

{
  "code": "UVV154640",
  "message": "Nao foi possivel processar pagamento. Verifique os dados e tente novamente."
}

{
  "code": "UVV154524",
  "message": "Nao foi possivel processar a cobranca. Tente novamente."
}

Assina um cliente em um plano. Crie o plano primeiro. Se não houver trial, a primeira cobrança acontece neste request. Com trial, a assinatura entra em TRIAL e ninguém é cobrado ainda. O limite é 20 requisições por minuto. Se passar disso, a API responde 429. Cada transaction_idempotency_id precisa ser único por operação. Use o mesmo valor só em retries idempotentes dessa operação. Os campos da resposta vêm em snake_case (subscription_id, subscription_status, …). Em trial, trial_unit só aceita DAY.

Método de pagamento

Use credit_card ou pix em payment_methods. Para PIX, envie pix_type em minúsculo: immediate (padrão) ou automatic. scheduled não é aceito. A resposta devolve pix_type no mesmo formato. Se for PIX sem trial, a resposta traz pix.qrcode. A assinatura fica PENDING até o cliente pagar. ATENÇÃO: envie dados de cartão só do seu backend.

Cliente

Envie o cliente de um jeito só: customer_id ou o bloco customer. Se mandar os dois, ou nenhum, a API responde 400.

Campo	Quando usar	O que a API faz
`customer_id`	O cliente já está na sua conta	Usa esse cliente na assinatura
`customer`	Primeira assinatura do cliente	Cria o cadastro, ou reaproveita o que já existe pelo `external_customer_id`

Você encontra o customer_id em:

id de POST /v1/customers;
customer_id da resposta de uma assinatura anterior;
id de GET /v1/customers;
id de GET /v1/customers/{customerId}.

Cliente já cadastrado

{
  "subscription_plan_id": "550e8400-e29b-41d4-a716-446655440000",
  "grace_period_days": 3,
  "customer_id": "660e8400-e29b-41d4-a716-446655440000",
  "payment_methods": {
    "type": "pix",
    "main_payment_method": true
  },
  "transaction_idempotency_id": "sub-create-0002"
}

Se o customer_id não existir na sua conta, a API responde 404 / UVV154225. NOTA: com customer_id, a API não olha nome, e-mail, telefone nem documento. Por isso UVV154640 e UVV154718 não aparecem. O cadastro também fica como está.

Idempotência

Se você repetir a chamada, envie o mesmo payload. Isso inclui o jeito de identificar o cliente.

Primeira chamada	Nova chamada com o mesmo `transaction_idempotency_id`	Resultado
`customer_id`	mesmo `customer_id`	retorna a mesma assinatura
`customer`	mesmo bloco `customer`	retorna a mesma assinatura
`customer`	`customer_id` do cliente criado	`409` / `UVV154862`

Endereço em Pix Automático

O endereço no bloco customer é opcional. Se enviar address, preencha todos os campos: zip_code, street, street_number, neighborhood, city, state e country. Se faltar algum, a API responde 400. Pix Automático (pix_type: automatic) precisa de endereço completo. Sem isso, a API responde 422 / UVV154361 e a assinatura não é criada.

Se você enviou	A API usa o endereço
`customer_id`	Do cadastro
`customer`	Do bloco `address` do request

ATENÇÃO: sem endereço, Pix Automático não roda. Cadastre o endereço antes, ou envie customer com address. PIX imediato e cartão não pedem endereço.

Dados do cliente no bloco `customer`

external_customer_id e documento (número e tipo) são únicos na sua conta.

mesmo external_customer_id com nome, e-mail, telefone ou documento diferente → 422 / UVV154640;
mesmo documento com outro external_customer_id → 422 / UVV154718.

Sucesso (`201`)

No 201, você vê como ficou a assinatura, a fatura e a cobrança. Vale para cartão pago, trial e PIX esperando pagamento. Exemplo de PIX sem trial:

{
  "subscription_id": "550e8400-e29b-41d4-a716-446655440000",
  "customer_id": "660e8400-e29b-41d4-a716-446655440000",
  "invoice_id": "770e8400-e29b-41d4-a716-446655440000",
  "subscription_status": "PENDING",
  "invoice_status": "open",
  "charge_status": "pending",
  "transaction_id": "880e8400-e29b-41d4-a716-446655440000",
  "failure_code": null,
  "failure_message": null,
  "pix_type": "immediate",
  "pix": {
    "qrcode": "00020126..."
  }
}

Recusa na primeira cobrança (`422` / `UVV154147`)

Mesmo com recusa, a assinatura existe (PAST_DUE, fatura open). A API responde 422, não 201.

{
  "code": "UVV154147",
  "message": "Nao foi possivel processar o pagamento. Verifique os dados e tente novamente.",
  "subscription_id": "...",
  "customer_id": "...",
  "invoice_id": "...",
  "transaction_id": "...",
  "failure_code": "issuer_declined",
  "failure_message": "Recusa do banco emissor"
}

transaction_id só vem se a tentativa recusada gerou um id. customer_id vem se a assinatura foi criada. Guarde esse valor. Em um retry idempotente, repita a mesma forma de identificação do cliente usada no request original. Se o request original usou customer, envie customer de novo. Se usou customer_id, envie o mesmo customer_id. Isso mantém o payload idêntico. Para uma nova operação, use outro transaction_idempotency_id. Nesse caso, a API trata o request como uma nova criação. Se o mesmo cliente já tiver uma assinatura nesse plano, a API pode responder 409 / UVV154158. Estes códigos não trazem ids: UVV154817, UVV154293, UVV154225, UVV154640, UVV154718. Para repetir a cobrança da mesma assinatura, reenvie o mesmo POST, com o mesmo transaction_idempotency_id e o mesmo payload. A API não abre outra assinatura. Se a fatura ainda estiver open, ela tenta cobrar de novo.

Erros

O code tem o formato UVV154 mais 3 dígitos. Use esse valor para tratar o erro no seu sistema. Corpo padrão:

{
  "code": "UVV154293",
  "message": "Nao foi possivel processar pagamento. Verifique os dados e tente novamente."
}

HTTP	`code`	Quando
`400`	-	Payload inválido. Sem `code` UVV
`404`	`UVV154817`, `UVV154225`	Recurso não encontrado
`404`	`UVV154293`	Plano não encontrado
`409`	`UVV154158`, `UVV154972`, `UVV154785`, `UVV154431`, `UVV154862`	Conflito. Ex.: o cliente já tem assinatura neste plano, ou o retry veio com payload diferente
`422`	`UVV154640`, `UVV154306`, `UVV154718`, `UVV154839`	Dados do cliente ou do cartão recusados
`422`	`UVV154069`	Dados da cobrança inválidos. O body pode trazer ids
`422`	`UVV154147`	Recusa na primeira cobrança. O body traz ids
`422`	`UVV154591`	Limite de tentativas de cobrança. O body traz ids
`422`	`UVV154208`	Intervalo do plano não aceito para Pix Automático (`DAILY`, `CUSTOM`, `ONE_TIME`)
`422`	`UVV154361`	Endereço incompleto para Pix Automático
`422`	`UVV154490`	Trial de Pix Automático deve terminar no mínimo em 3 dias
`429`	-	Limite de 20 requisições por minuto
`500`	`UVV154524`	Falha ao processar a cobrança. Tente de novo. O body pode trazer ids

Authorizations

client-id

string

header

required

client-secret

string

header

required

Headers

client-id

string

required

ID público da credencial do merchant

client-secret

string

required

Secret da credencial do merchant

Body

application/json

Option 1
Option 2

subscription_plan_id

string<uuid>

required

UUID de um plano ACTIVE criado antes via POST /v1/subscriptions/plan. Define valor, moeda e cadência da assinatura.

grace_period_days

integer

required

Dias de tolerância após falha de cobrança antes do cancelamento terminal.

Required range: x >= 0

Example:

3

customer_id

string<uuid>

required

UUID de um cliente já existente na organização. Use no lugar de customer para reaproveitar o cliente sem reenviar os dados. Envie customer_id ou customer, nunca os dois.

payment_methods

object

required

Método de pagamento (credit_card com PAN ou pix).

Option 1
Option 2

Show child attributes

transaction_idempotency_id

string

required

Chave de idempotência da criação (scope subscription_create)

Example:

"sub-create-0001"

trial_duration

integer | null

Duração do trial desta assinatura. Sobrescreve o trial padrão do plano quando informado.

Required range: x >= 0

trial_unit

enum<string> | null

Unidade do trial desta assinatura. Apenas DAY é aceito.

Available options:

DAY

customer

object

Dados do cliente. Reaproveitado por external_customer_id quando já existir. Envie customer_id ou customer, nunca os dois. Endereço completo é exigido apenas em pix_type: automatic, que responde 422 (UVV154069) sem ele.

Show child attributes

Response

Assinatura criada. Sem trial, a primeira cobranca e sincrona: cartao pago → ACTIVE; PIX aguardando pagamento → PENDING com pix.qrcode; trial → TRIAL sem cobranca. Decline de negocio na cobranca sync responde 422 (UVV154147), nao 201.

subscription_id

string<uuid>

Identificador da assinatura criada.

customer_id

string<uuid>

Identificador do cliente vinculado.

invoice_id

string<uuid>

Identificador da primeira invoice.

subscription_status

enum<string>

Status da assinatura após o create (ACTIVE se paid; PENDING se PIX waiting_payment; PAST_DUE se decline; TRIAL se trial).

Available options:

ACTIVE,

PENDING,

TRIAL,

PAST_DUE,

CANCELLED

Example:

"ACTIVE"

invoice_status

string | null

Status da invoice após a cobrança sync (ou open no trial/PIX pendente).

charge_status

enum<string> | null

Status da tentativa de cobrança. Null no trial (sem cobrança no create). pending para PIX aguardando pagamento.

Available options:

pending,

succeeded,

failed

transaction_id

string<uuid> | null

ID da transação quando a cobrança gerou pagamento.

failure_code

string | null

Categoria pública de recusa em decline (ex.: issuer_declined). Null quando paid/trial/PIX pendente.

failure_message

string | null

Rótulo público da recusa. Null quando paid/trial/PIX pendente.

pix

object | null

Presente quando a primeira cobrança PIX foi gerada e aguarda pagamento.

Show child attributes

​Método de pagamento

​Cliente

​Cliente já cadastrado

​Idempotência

​Endereço em Pix Automático

​Dados do cliente no bloco customer

​Sucesso (201)

​Recusa na primeira cobrança (422 / UVV154147)

​Erros

Authorizations

Headers

Body

Response

Método de pagamento

Cliente

Cliente já cadastrado

Idempotência

Endereço em Pix Automático

Dados do cliente no bloco `customer`

Sucesso (`201`)

Recusa na primeira cobrança (`422` / `UVV154147`)

Erros