Visão Geral

A API de Checkout permite criar links de pagamento personalizados. Seus clientes podem acessar o link e completar a compra de forma segura.

Todo valor monetário da API é em centavos inteiros, em campos terminados em Cents. 15000 é R$ 150,00.

Ao usar productIds, o preço vem do catálogo e não do seu payload: não há como o cliente forjar o valor cobrado.

Endpoints

Método	Endpoint	Auth	Descrição
`POST`	`/api/sdk/checkout/create-link`	🔒 SDK	Criar link de checkout
`GET`	`/api/sdk/checkout/:token`	🌐 Público	Buscar sessão

Apenas create-link requer autenticação via API Keys. Os endpoints com :token são públicos — o token funciona como autenticação.

Criar Link de Checkout

POST /api/sdk/checkout/create-link

Body

Campo	Tipo	Obrigatório	Descrição
`productIds`	`string[]`	❌*	IDs dos produtos da loja
`items`	`array`	❌*	Itens customizados
`items[].title`	`string`	✅	Título do item (max 200)
`items[].priceCents`	`integer`	✅	Preço unitário em centavos inteiros. `15000` é R$ 150,00
`items[].quantity`	`number`	❌	Quantidade (padrão: 1, max: 9999)
`items[].image`	`string`	❌	URL da imagem
`items[].description`	`string`	❌	Descrição (max 1000)
`items[].sku`	`string`	❌	SKU do item
`successUrl`	`string`	❌	URL de redirecionamento após sucesso
`cancelUrl`	`string`	❌	URL de redirecionamento se cancelar
`customer`	`object`	❌	Pré-preencher dados do cliente
`customer.email`	`string`	❌	Email
`customer.name`	`string`	❌	Nome
`customer.phone`	`string`	❌	Telefone
`currency`	`string`	❌	Moeda (padrão: `BRL`)
`expiresIn`	`number`	❌	Expiração em minutos (5 a 10080)
`shippingCents`	`integer`	❌	Valor do frete em centavos inteiros
`couponCode`	`string`	❌	Código de cupom (max 50)
`metadata`	`object`	❌	Metadados (max 4KB)

Você deve enviar productIds OU items, não ambos. Máximo de 50 itens por checkout.

Exemplo com Produtos

curl -X POST "https://api.plasmacheckout.com/api/sdk/checkout/create-link" \
  -H "X-PLASMA-Public-Key: pk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "X-PLASMA-Secret-Key: sk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "productIds": ["cm5abc123def456ghi789", "cm5abc123def456ghi790"],
    "successUrl": "https://meusite.com/obrigado",
    "cancelUrl": "https://meusite.com/carrinho",
    "expiresIn": 60
  }'

const response = await fetch(
  'https://api.plasmacheckout.com/api/sdk/checkout/create-link',
  {
    method: 'POST',
    headers: {
      'X-PLASMA-Public-Key': 'pk_live_xxxxxxxxxxxxxxxxxxxx',
      'X-PLASMA-Secret-Key': 'sk_live_xxxxxxxxxxxxxxxxxxxx',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      productIds: ['cm5abc123def456ghi789', 'cm5abc123def456ghi790'],
      successUrl: 'https://meusite.com/obrigado',
      cancelUrl: 'https://meusite.com/carrinho',
      expiresIn: 60  // 60 minutos = 1 hora
    })
  }
);

const { data } = await response.json();
console.log(data.checkoutUrl);  // URL para redirecionar o cliente

Exemplo com Itens Customizados

curl -X POST "https://api.plasmacheckout.com/api/sdk/checkout/create-link" \
  -H "X-PLASMA-Public-Key: pk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "X-PLASMA-Secret-Key: sk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "title": "Consultoria 1 hora",
        "priceCents": 15000,
        "quantity": 1
      },
      {
        "title": "Material de apoio",
        "priceCents": 5000,
        "quantity": 1
      }
    ],
    "customer": {
      "email": "cliente@email.com",
      "name": "João Silva"
    },
    "successUrl": "https://meusite.com/obrigado",
    "metadata": {
      "clienteId": "123",
      "origem": "landing-page"
    }
  }'

Resposta (201 Created)

{
  "data": {
    "id": "cm5session123abc456",
    "token": "ck_lm7abc123xyz",
    "status": "pending",
    "checkoutUrl": "https://checkout.plasmacheckout.com/c/ck_lm7abc123xyz",
    "items": [...],
    "totals": {
      "subtotalCents": 20000,
      "shippingCents": 0,
      "discountCents": 0,
      "totalCents": 20000
    },
    "currency": "BRL",
    "customer": {
      "email": "cliente@email.com",
      "name": "João Silva",
      "phone": null
    },
    "urls": {
      "success": "https://meusite.com/obrigado",
      "cancel": null
    },
    "environment": "live",
    "expiresAt": "2025-01-15T11:00:00Z",
    "createdAt": "2025-01-15T10:00:00Z"
  }
}

Buscar Sessão de Checkout

GET /api/sdk/checkout/:token

Este endpoint é público e pode ser usado no frontend para exibir os detalhes do checkout.

Exemplo

curl -X GET "https://api.plasmacheckout.com/api/sdk/checkout/ck_lm7abc123xyz"

Resposta

{
  "data": {
    "id": "cm5session123abc456",
    "token": "ck_lm7abc123xyz",
    "status": "pending",
    "checkoutUrl": "https://checkout.plasmacheckout.com/c/ck_lm7abc123xyz",
    "items": [
      {
        "title": "Camiseta Premium",
        "priceCents": 7990,
        "quantity": 2,
        "image": "https://..."
      }
    ],
    "totals": {
      "subtotalCents": 15980,
      "shippingCents": 1500,
      "discountCents": 0,
      "totalCents": 17480
    },
    "currency": "BRL",
    "customer": {
      "email": "cliente@email.com",
      "name": null,
      "phone": null
    },
    "expiresAt": "2025-01-15T11:00:00Z",
    "createdAt": "2025-01-15T10:00:00Z"
  }
}

Valor	Tempo
Mínimo	5 minutos
Padrão	1440 minutos (24 horas)
Máximo	10080 minutos (7 dias)

{
  "expiresIn": 60
}

O valor é em minutos, não em segundos. 60 = 1 hora, 1440 = 24 horas.

Moedas Suportadas

Código	Moeda
`BRL`	Real Brasileiro
`USD`	Dólar Americano
`EUR`	Euro
`ARS`	Peso Argentino
`CLP`	Peso Chileno
`COP`	Peso Colombiano
`MXN`	Peso Mexicano
`PEN`	Sol Peruano
`UYU`	Peso Uruguaio

Integração Frontend

Botão de Compra

BotaoComprar.jsx

function BotaoComprar({ produtoId }) {
  const [loading, setLoading] = useState(false);

  async function handleComprar() {
    setLoading(true);
    
    const response = await fetch('/api/criar-checkout', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ produtoId })
    });
    
    const { checkoutUrl } = await response.json();
    
    // Redireciona para o checkout
    window.location.href = checkoutUrl;
  }

  return (
    <button onClick={handleComprar} disabled={loading}>
      {loading ? 'Carregando...' : 'Comprar Agora'}
    </button>
  );
}

Backend (Next.js API Route)

app/api/criar-checkout/route.ts

import { NextResponse } from 'next/server';

export async function POST(request: Request) {
  const { produtoId } = await request.json();

  const response = await fetch(
    'https://api.plasmacheckout.com/api/sdk/checkout/create-link',
    {
      method: 'POST',
      headers: {
        'X-PLASMA-Public-Key': process.env.PLASMA_PUBLIC_KEY!,
        'X-PLASMA-Secret-Key': process.env.PLASMA_SECRET_KEY!,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        productIds: [produtoId],
        successUrl: `${process.env.NEXT_PUBLIC_URL}/obrigado`,
        cancelUrl: `${process.env.NEXT_PUBLIC_URL}/produtos`
      })
    }
  );

  const result = await response.json();
  
  return NextResponse.json({ 
    checkoutUrl: result.data.checkoutUrl 
  });
}

Nunca exponha suas API Keys no frontend. Use uma API Route no backend para intermediar.

Erros Comuns

Código	Erro	Solução
`400`	`VALIDATION_ERROR`	Envie `productIds` ou `items`, não ambos
`400`	`INVALID_EXPIRATION`	`expiresIn` deve ser entre 5 e 10080 minutos
`400`	`INVALID_CURRENCY`	Use uma moeda suportada
`400`	`TOO_MANY_ITEMS`	Máximo 50 itens por checkout
`400`	`INVALID_METADATA`	Metadata deve ser objeto com max 4KB
`404`	`NOT_FOUND`	Loja não encontrada

Webhooks Disparados

Quando o cliente finaliza o pagamento na página de checkout hospedada do Plasma Checkout, nós enviamos notificações em tempo real para os endpoints de webhook cadastrados na sua loja:

checkout.completed — Disparado assim que a sessão de checkout é concluída com sucesso pelo cliente.
order.created — Disparado quando o pedido é gerado no banco de dados.
order.paid — Disparado quando o gateway de pagamento confirma o recebimento do valor (PIX, Cartão ou Boleto).
order.cancelled — Disparado caso o pedido seja cancelado pelo gateway.
order.refunded — Disparado caso o pedido seja reembolsado.

Checkout

Visão Geral

Endpoints

Criar Link de Checkout

Body

Exemplo com Produtos

Exemplo com Itens Customizados

Resposta (201 Created)

Buscar Sessão de Checkout

Exemplo

Resposta

Fluxo do Checkout

Criar Link

Redirecionar Cliente

Cliente Completa

Webhook

Redirecionamento

Expiração