Criar sessão de checkout

POST/api/v1/bank/wallet/checkout/Bearer Token

---

Cabeçalhos da requisição

Cabeçalho	Valor	Obrigatório
Authorization	Bearer {A55_ACCESS_TOKEN}	Sim
Content-Type	application/json	Sim
Idempotency-Key	UUID v4	Recomendado

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
wallet_uuid	string (UUID)	Sim	Carteira que recebe os fundos
merchant_id	string (UUID)	Sim	Identificador do estabelecimento
amount	number	Sim	Valor total da cobrança (ex.: 250.00)
currency	string	Sim	Código de moeda ISO 4217
description	string	Sim	Descrição da cobrança exibida na página de checkout
redirect_url	string	Sim	URL de redirecionamento após a conclusão do pagamento
cancel_url	string	Não	URL de redirecionamento se o pagador cancelar
due_date	string	Sim	Data de expiração YYYY-MM-DD
payer_email	string	Não	Preencher previamente o e-mail do pagador na página de checkout
allowed_methods	array	Não	Restringir métodos de pagamento (ex.: ["credit_card", "pix"])
max_installments	integer	Não	Máximo de parcelas permitidas (padrão: configuração da carteira)
webhook_url	string	Não	Substituir a URL de webhook padrão
reference_external_id	string	Não	Seu ID de pedido interno
is_checkout	boolean	Não	true (padrão para este endpoint)

---

Campos da resposta

Campo	Tipo	Descrição
checkout_uuid	string	Identificador único da sessão de checkout
checkout_url	string	URL da página de checkout hospedada — redirecione o pagador para cá
status	string	active — sessão pronta para pagamento
amount	number	Valor do checkout
currency	string	Código da moeda
expires_at	string	Expiração da sessão ISO 8601
charge_uuid	string	Criado quando o pagador conclui o pagamento

---

Códigos de status HTTP

Status	Descrição
200	Sessão de checkout criada
400	Corpo da requisição inválido ou campos obrigatórios ausentes
401	Token Bearer inválido ou expirado
403	Permissões insuficientes para esta carteira
404	Carteira ou estabelecimento não encontrado
422	Erro de validação (moeda inválida, valor inválido)
429	Limite de requisições excedido
500	Erro interno do servidor — tente novamente com backoff exponencial

---

Exemplos de código

cURL

curl -s -X POST https://core-manager.a55.tech/api/v1/bank/wallet/checkout/ \
  -H "Authorization: Bearer $A55_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 990e8400-e29b-41d4-a716-446655440004" \
  -d '{
    "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "merchant_id": "11111111-1111-1111-1111-111111111111",
    "amount": 250.00,
    "currency": "BRL",
    "description": "Premium Plan — Monthly",
    "redirect_url": "https://your-app.com/payment/success",
    "cancel_url": "https://your-app.com/payment/cancel",
    "due_date": "2026-12-31",
    "payer_email": "maria@example.com",
    "allowed_methods": ["credit_card", "pix"],
    "max_installments": 6,
    "webhook_url": "https://your-app.com/webhooks/a55",
    "reference_external_id": "ORDER-2048"
  }'

Python

import requests
import os

token = os.environ["A55_ACCESS_TOKEN"]
base = os.environ.get("A55_API_URL", "https://core-manager.a55.tech")

try:
    response = requests.post(
        f"{base}/api/v1/bank/wallet/checkout/",
        json={
            "wallet_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
            "merchant_id": "11111111-1111-1111-1111-111111111111",
            "amount": 250.00,
            "currency": "BRL",
            "description": "Premium Plan — Monthly",
            "redirect_url": "https://your-app.com/payment/success",
            "cancel_url": "https://your-app.com/payment/cancel",
            "due_date": "2026-12-31",
            "payer_email": "maria@example.com",
            "allowed_methods": ["credit_card", "pix"],
            "max_installments": 6,
            "webhook_url": "https://your-app.com/webhooks/a55",
            "reference_external_id": "ORDER-2048",
        },
        headers={
            "Authorization": f"Bearer {token}",
            "Content-Type": "application/json",
            "Idempotency-Key": "990e8400-e29b-41d4-a716-446655440004",
        },
    )
    response.raise_for_status()
    checkout = response.json()
    print(f"Checkout URL: {checkout['checkout_url']}")
    print(f"Session: {checkout['checkout_uuid']} — Expires: {checkout['expires_at']}")
except requests.exceptions.HTTPError as e:
    print(f"HTTP {e.response.status_code}: {e.response.json()}")
except requests.exceptions.RequestException as e:
    print(f"Request failed: {e}")

Node.js

const token = process.env.A55_ACCESS_TOKEN;
const base = process.env.A55_API_URL || "https://core-manager.a55.tech";

try {
  const response = await fetch(`${base}/api/v1/bank/wallet/checkout/`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json",
      "Idempotency-Key": "990e8400-e29b-41d4-a716-446655440004",
    },
    body: JSON.stringify({
      wallet_uuid: "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      merchant_id: "11111111-1111-1111-1111-111111111111",
      amount: 250.00,
      currency: "BRL",
      description: "Premium Plan — Monthly",
      redirect_url: "https://your-app.com/payment/success",
      cancel_url: "https://your-app.com/payment/cancel",
      due_date: "2026-12-31",
      payer_email: "maria@example.com",
      allowed_methods: ["credit_card", "pix"],
      max_installments: 6,
      webhook_url: "https://your-app.com/webhooks/a55",
      reference_external_id: "ORDER-2048",
    }),
  });

  if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
  const checkout = await response.json();
  console.log(`Checkout URL: ${checkout.checkout_url}`);
  console.log(`Session: ${checkout.checkout_uuid} — Expires: ${checkout.expires_at}`);
} catch (error) {
  console.error("Checkout creation failed:", error.message);
}

---

Exemplo de resposta de erro

{
  "status": "error",
  "message": [
    {
      "code": "INVALID_REDIRECT_URL",
      "source": "validation",
      "description": "redirect_url must be a valid HTTPS URL"
    }
  ]
}

---

Link de pagamento →Crie links de pagamento reutilizáveis para compartilhamento.Consultar cobrança →Verifique o status da cobrança após a conclusão do checkout.Webhooks →Receba uma notificação quando o checkout for pago.