Montar o seu próprio checkout

Se preferir coletar os dados na sua interface, use as rotas abaixo com o payment_link_guid. São públicas — não usam token.

Passo	Etapa	Rota
1	Chave	GET /api/v1/public-key — chave pública RSA (PEM)
2	Link	GET /api/v1/checkout-links/:guid — dados do link
3	Pagador	PATCH /api/v1/checkout-links/:guid/payer — dados pessoais
4	Endereço	PATCH /api/v1/checkout-links/:guid/address — endereço do pagador
5	Pagamento	PUT /api/v1/checkout-links/:guid/pay — cartão criptografado, conclui

aviso

O GUID é o segredo que protege esse fluxo. Trate-o como credencial.

Passo 1 — Chave pública

GET/api/v1/public-keyPúblico

{
  "status": "success",
  "data": {
    "publicKey": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...\n-----END PUBLIC KEY-----\n"
  }
}

RSA 2048, formato PEM. A chave não muda a cada pagamento — busque uma vez e mantenha em cache. A mesma chave serve para todos os campos encryptedCardData desta API: link de pagamento, criação de assinatura, ativação de assinatura e troca de cartão.

Padding: PKCS#1 v1.5

Cifre com RSAES-PKCS1-v1_5. OAEP-SHA256 devolve 400 Dados de cartão criptografados inválidos.

O conteúdo cifrado é sempre este JSON:

Campo	Descrição
credit_card	Número do cartão. Espaços e hífens são removidos pelo servidor
card_holder_name	Nome do titular como impresso no cartão
exp	Validade no formato MM/YYYY
cvv	Código de segurança

Exemplo em Python

import base64, json
from cryptography.hazmat.primitives import serialization
from cryptography.hazmat.primitives.asymmetric import padding

chave = serialization.load_pem_public_key(pem.encode())
dados = json.dumps({
    "credit_card": "4111111111111111",
    "card_holder_name": "JOAO DA SILVA",
    "exp": "12/2028",
    "cvv": "123",
}, separators=(",", ":")).encode()
encrypted_card_data = base64.b64encode(chave.encrypt(dados, padding.PKCS1v15())).decode()

Exemplo em Node

const crypto = require("crypto");
const dados = Buffer.from(JSON.stringify({
  credit_card: "4111111111111111",
  card_holder_name: "JOAO DA SILVA",
  exp: "12/2028",
  cvv: "123",
}));
const encryptedCardData = crypto.publicEncrypt(
  { key: pem, padding: crypto.constants.RSA_PKCS1_PADDING },
  dados,
).toString("base64");

Passo 2 — Carregar o link

GET/api/v1/checkout-links/:guidPúblico

{
  "status": "success",
  "data": {
    "guid": "0a798f92-72ef-4809-9a6a-b318f067c2ee",
    "value": 990,
    "description": "Produto XYZ",
    "numberOfInstallments": 1,
    "merchantName": "Loja Homolog Pag",
    "merchantDocument": "11444777000161",
    "status": 1,
    "isCheckoutClosed": false,
    "expiresAt": "2026-10-07T12:49:13Z",
    "payerName": "Joao da Silva",
    "email": "[email protected]",
    "document": "52998224725",
    "mobile": "11999999999",
    "zipcode": "01310100",
    "street": "Av Paulista",
    "addressNumber": "1000",
    "neighborhood": "Bela Vista",
    "city": "Sao Paulo",
    "state": "SP",
    "complement": "",
    "reference": ""
  }
}

Campo	Descrição
merchantName / merchantDocument	Razão social e CNPJ do lojista
payerName	Nome do pagador — o payer_name da criação ou do passo 3
isCheckoutClosed	true quando o link já foi pago, cancelado ou expirou

Depois do pagamento a resposta ganha nsu, paymentTransactionGuid e paymentDate. Um GUID inexistente devolve 404 em JSON.

Passo 3 — Dados do pagador

PATCH/api/v1/checkout-links/:guid/payerPúblico

{
  "payer_name": "Joao da Silva",
  "document": "52998224725",
  "email": "[email protected]",
  "mobile": "11999999999"
}

Campo	Tipo	Obrigatório	Descrição
payer_name	string	Sim	Nome do pagador. Máx. 20 caracteres. merchant_name é aceito como alias
document	string	Sim	CPF ou CNPJ, com dígito verificador válido. Somente dígitos
email	string	Sim	E-mail do pagador. Máx. 100 caracteres
mobile	string	Sim	Telefone do pagador. Máx. 20 caracteres

Dígito verificador inválido devolve 400 dados inválidos no checkout: documento inválido.

Passo 4 — Endereço do pagador

PATCH/api/v1/checkout-links/:guid/addressPúblico

{
  "cep": "01310100",
  "street": "Av Paulista",
  "number": "1000",
  "neighborhood": "Bela Vista",
  "city": "Sao Paulo",
  "state": "SP",
  "complement": "Sala 12"
}

Campo	Tipo	Obrigatório	Descrição
cep	string	Sim	CEP com 8 dígitos, somente dígitos
street	string	Sim	Logradouro. Máx. 100 caracteres
number	string	Sim	Número. Máx. 20 caracteres
neighborhood	string	Sim	Bairro. Máx. 100 caracteres
city	string	Sim	Cidade. Máx. 100 caracteres
state	string	Sim	UF com 2 letras
complement	string	Não	Complemento. Máx. 50 caracteres
reference	string	Não	Ponto de referência. Máx. 50 caracteres

Passo 5 — Concluir o pagamento

PUT/api/v1/checkout-links/:guid/payPúblico

{ "encrypted_card_data": "base64_da_criptografia_RSA..." }

O campo também é aceito como encryptedCardData.

Resposta 200

{
  "status": "success",
  "data": { "payment_link_id": 18, "status": 4, "outcome": "approved" }
}

Campo	Descrição
status	Status numérico do link. 4 = Confirmado, 7 = Negado
outcome	"approved" ou "denied", em minúsculas. É o campo para decidir

Como na seção Pré-captura com cartão de crédito, 200 não significa aprovação: confira outcome. Um link negado aceita nova tentativa com outro cartão. Repetir a chamada num link já pago devolve 409 Checkout encerrado.