Criar assinatura

curl --request POST \
  --url https://api.uvvipay.com.br/v1/recurrency/subscription \
  --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": {
    "external_customer_id": "customer-ext-0001",
    "name": "<string>",
    "email": "jsmith@example.com",
    "phone": "11987654321",
    "address": {
      "street": "<string>",
      "street_number": "<string>",
      "zip_code": "<string>",
      "city": "<string>",
      "state": "<string>",
      "country": "BR",
      "neighborhood": "<string>"
    },
    "document": {
      "number": "12345678901"
    }
  },
  "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/recurrency/subscription"

payload = {
    "subscription_plan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "grace_period_days": 3,
    "customer": {
        "external_customer_id": "customer-ext-0001",
        "name": "<string>",
        "email": "jsmith@example.com",
        "phone": "11987654321",
        "address": {
            "street": "<string>",
            "street_number": "<string>",
            "zip_code": "<string>",
            "city": "<string>",
            "state": "<string>",
            "country": "BR",
            "neighborhood": "<string>"
        },
        "document": { "number": "12345678901" }
    },
    "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: {
      external_customer_id: 'customer-ext-0001',
      name: '<string>',
      email: 'jsmith@example.com',
      phone: '11987654321',
      address: {
        street: '<string>',
        street_number: '<string>',
        zip_code: '<string>',
        city: '<string>',
        state: '<string>',
        country: 'BR',
        neighborhood: '<string>'
      },
      document: {number: '12345678901'}
    },
    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/recurrency/subscription', 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/recurrency/subscription",
  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' => [
        'external_customer_id' => 'customer-ext-0001',
        'name' => '<string>',
        'email' => 'jsmith@example.com',
        'phone' => '11987654321',
        'address' => [
                'street' => '<string>',
                'street_number' => '<string>',
                'zip_code' => '<string>',
                'city' => '<string>',
                'state' => '<string>',
                'country' => 'BR',
                'neighborhood' => '<string>'
        ],
        'document' => [
                'number' => '12345678901'
        ]
    ],
    '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/recurrency/subscription"

	payload := strings.NewReader("{\n  \"subscription_plan_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"grace_period_days\": 3,\n  \"customer\": {\n    \"external_customer_id\": \"customer-ext-0001\",\n    \"name\": \"<string>\",\n    \"email\": \"jsmith@example.com\",\n    \"phone\": \"11987654321\",\n    \"address\": {\n      \"street\": \"<string>\",\n      \"street_number\": \"<string>\",\n      \"zip_code\": \"<string>\",\n      \"city\": \"<string>\",\n      \"state\": \"<string>\",\n      \"country\": \"BR\",\n      \"neighborhood\": \"<string>\"\n    },\n    \"document\": {\n      \"number\": \"12345678901\"\n    }\n  },\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/recurrency/subscription")
  .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\": {\n    \"external_customer_id\": \"customer-ext-0001\",\n    \"name\": \"<string>\",\n    \"email\": \"jsmith@example.com\",\n    \"phone\": \"11987654321\",\n    \"address\": {\n      \"street\": \"<string>\",\n      \"street_number\": \"<string>\",\n      \"zip_code\": \"<string>\",\n      \"city\": \"<string>\",\n      \"state\": \"<string>\",\n      \"country\": \"BR\",\n      \"neighborhood\": \"<string>\"\n    },\n    \"document\": {\n      \"number\": \"12345678901\"\n    }\n  },\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/recurrency/subscription")

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\": {\n    \"external_customer_id\": \"customer-ext-0001\",\n    \"name\": \"<string>\",\n    \"email\": \"jsmith@example.com\",\n    \"phone\": \"11987654321\",\n    \"address\": {\n      \"street\": \"<string>\",\n      \"street_number\": \"<string>\",\n      \"zip_code\": \"<string>\",\n      \"city\": \"<string>\",\n      \"state\": \"<string>\",\n      \"country\": \"BR\",\n      \"neighborhood\": \"<string>\"\n    },\n    \"document\": {\n      \"number\": \"12345678901\"\n    }\n  },\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>",
  "transaction_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "failure_code": "<string>",
  "failure_message": "<string>",
  "pix": {
    "qrcode": "<string>"
  }
}

{
  "code": "UVV154069",
  "message": "Nao foi possivel validar os dados da cobranca. Verifique os dados e tente novamente."
}

{
  "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

recurrency

subscription

Criar assinatura

curl --request POST \
  --url https://api.uvvipay.com.br/v1/recurrency/subscription \
  --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": {
    "external_customer_id": "customer-ext-0001",
    "name": "<string>",
    "email": "jsmith@example.com",
    "phone": "11987654321",
    "address": {
      "street": "<string>",
      "street_number": "<string>",
      "zip_code": "<string>",
      "city": "<string>",
      "state": "<string>",
      "country": "BR",
      "neighborhood": "<string>"
    },
    "document": {
      "number": "12345678901"
    }
  },
  "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/recurrency/subscription"

payload = {
    "subscription_plan_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "grace_period_days": 3,
    "customer": {
        "external_customer_id": "customer-ext-0001",
        "name": "<string>",
        "email": "jsmith@example.com",
        "phone": "11987654321",
        "address": {
            "street": "<string>",
            "street_number": "<string>",
            "zip_code": "<string>",
            "city": "<string>",
            "state": "<string>",
            "country": "BR",
            "neighborhood": "<string>"
        },
        "document": { "number": "12345678901" }
    },
    "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: {
      external_customer_id: 'customer-ext-0001',
      name: '<string>',
      email: 'jsmith@example.com',
      phone: '11987654321',
      address: {
        street: '<string>',
        street_number: '<string>',
        zip_code: '<string>',
        city: '<string>',
        state: '<string>',
        country: 'BR',
        neighborhood: '<string>'
      },
      document: {number: '12345678901'}
    },
    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/recurrency/subscription', 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/recurrency/subscription",
  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' => [
        'external_customer_id' => 'customer-ext-0001',
        'name' => '<string>',
        'email' => 'jsmith@example.com',
        'phone' => '11987654321',
        'address' => [
                'street' => '<string>',
                'street_number' => '<string>',
                'zip_code' => '<string>',
                'city' => '<string>',
                'state' => '<string>',
                'country' => 'BR',
                'neighborhood' => '<string>'
        ],
        'document' => [
                'number' => '12345678901'
        ]
    ],
    '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/recurrency/subscription"

	payload := strings.NewReader("{\n  \"subscription_plan_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"grace_period_days\": 3,\n  \"customer\": {\n    \"external_customer_id\": \"customer-ext-0001\",\n    \"name\": \"<string>\",\n    \"email\": \"jsmith@example.com\",\n    \"phone\": \"11987654321\",\n    \"address\": {\n      \"street\": \"<string>\",\n      \"street_number\": \"<string>\",\n      \"zip_code\": \"<string>\",\n      \"city\": \"<string>\",\n      \"state\": \"<string>\",\n      \"country\": \"BR\",\n      \"neighborhood\": \"<string>\"\n    },\n    \"document\": {\n      \"number\": \"12345678901\"\n    }\n  },\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/recurrency/subscription")
  .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\": {\n    \"external_customer_id\": \"customer-ext-0001\",\n    \"name\": \"<string>\",\n    \"email\": \"jsmith@example.com\",\n    \"phone\": \"11987654321\",\n    \"address\": {\n      \"street\": \"<string>\",\n      \"street_number\": \"<string>\",\n      \"zip_code\": \"<string>\",\n      \"city\": \"<string>\",\n      \"state\": \"<string>\",\n      \"country\": \"BR\",\n      \"neighborhood\": \"<string>\"\n    },\n    \"document\": {\n      \"number\": \"12345678901\"\n    }\n  },\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/recurrency/subscription")

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\": {\n    \"external_customer_id\": \"customer-ext-0001\",\n    \"name\": \"<string>\",\n    \"email\": \"jsmith@example.com\",\n    \"phone\": \"11987654321\",\n    \"address\": {\n      \"street\": \"<string>\",\n      \"street_number\": \"<string>\",\n      \"zip_code\": \"<string>\",\n      \"city\": \"<string>\",\n      \"state\": \"<string>\",\n      \"country\": \"BR\",\n      \"neighborhood\": \"<string>\"\n    },\n    \"document\": {\n      \"number\": \"12345678901\"\n    }\n  },\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>",
  "transaction_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "failure_code": "<string>",
  "failure_message": "<string>",
  "pix": {
    "qrcode": "<string>"
  }
}

{
  "code": "UVV154069",
  "message": "Nao foi possivel validar os dados da cobranca. Verifique os dados e tente novamente."
}

{
  "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."
}

Cria uma nova assinatura. Sem trial (PENDING), a primeira cobrança roda no mesmo request. Paid → 201. Decline de negócio → 422 (UVV154147) com subscription_id / invoice_id. Com trial (TRIAL), não há cobrança no create. O endpoint é limitado a 20 requisições por minuto por rastreador do throttler (credencial/IP). Em excesso, a API responde 429. payment_methods aceita credit_card (PAN) ou pix. Sem trial e com PIX, a resposta inclui pix.qrcode e a assinatura permanece PENDING até o pagamento. A resposta HTTP do create usa snake_case (subscription_id, subscription_status, …). trial_unit aceita apenas DAY. transaction_idempotency_id deve ser único por organização.

Resposta de sucesso (`201`)

Inclui status da assinatura/invoice/cobrança quando a cobrança sync é paga, quando é trial sem cobrança, ou quando é PIX aguardando pagamento. Exemplo 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": {
    "qrcode": "00020126..."
  }
}

Declínio na cobrança sync (`422` / `UVV154147`)

A assinatura é criada (PAST_DUE, invoice OPEN), mas a API não devolve 201 com falha embutida. Body:

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

transaction_id é público e só entra no body quando a adquirente devolveu um id na tentativa recusada. Recuperação: reenvie o mesmo POST com o mesmo transaction_idempotency_id e o mesmo payload de negócio. O backend cria o próximo charge attempt e cobra de novo (retries manuais via POST não aplicam o limite da fila automática). Não há retry automático na fila para a primeira cobrança (auto_charge=false).

Erros de negócio e cobrança

Corpo padrão:

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

HTTP	`code`	`message`
`404`	`UVV154817`, `UVV154293`	Nao foi possivel processar pagamento. Verifique os dados e tente novamente.
`409`	`UVV154158`, `UVV154972`, `UVV154785`, `UVV154431`, `UVV154862`	Nao foi possivel processar pagamento. Verifique os dados e tente novamente.
`422`	`UVV154640`, `UVV154306`, `UVV154718`	Nao foi possivel processar pagamento. Verifique os dados e tente novamente.
`400`	`UVV154069`	Nao foi possivel validar os dados da cobranca. Verifique os dados e tente novamente. (+ ids)
`429`	—	Rate limit do create (20 req / 60s)
`500`	`UVV154524`	Nao foi possivel processar a cobranca. Tente novamente. (+ ids)
`422`	`UVV154147`	Nao foi possivel processar o pagamento. Verifique os dados e tente novamente. (+ ids)
`422`	`UVV154591`	Limite de tentativas de cobranca atingido. Atualize o metodo de pagamento ou contate o suporte. (+ ids)

Os codes são opacos no formato UVV154 + 3 dígitos. Use-os para branching programático.

Customer

external_customer_id e documento (número + tipo) são únicos por organização. No create de assinatura:

mesmo external_customer_id com nome/email/telefone/documento divergente → 422 / UVV154640 (CUSTOMER_DATA_MISMATCH);
mesmo documento (número + tipo) com external_customer_id diferente → 422 / UVV154718 (EXTERNAL_CUSTOMER_ID_MISMATCH).

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

subscription_plan_id

string<uuid>

required

UUID de um plano ACTIVE criado antes via POST /v1/recurrency/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

object

required

Dados do cliente. Reaproveitado por external_customer_id quando já existir.

Show child attributes

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

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

​Resposta de sucesso (201)

​Declínio na cobrança sync (422 / UVV154147)

​Erros de negócio e cobrança

​Customer

Authorizations

Headers

Body

Response

Resposta de sucesso (`201`)

Declínio na cobrança sync (`422` / `UVV154147`)

Erros de negócio e cobrança

Customer