Cartão de crédito

Em breve. O pagamento com cartão de crédito ainda não está disponível na Bob. Esta página descreve como vai funcionar quando lançar — por enquanto, use PIX.

A Bob Payments também vai processar cartão de crédito. Para a maioria das integrações, você usará o checkout hospedado ou o SDK embutível da Bob. Eles carregam os campos seguros, tokenizam o cartão, conduzem 3DS e gerenciam o processamento internamente.

Para aceitar cartão no checkout, o cartão deve ser tokenizado no navegador pelo pacote de checkout da Bob (@bobpayments/checkout-sdk). A sua aplicação e a API só recebem um token seguro — PAN, CVV e validade nunca passam pela API Bob. Veja o SDK Checkout e a Referência.

Escolha o nível de integração

Nível	Quando usar
Checkout hospedado	Caminho padrão. Você cria uma sessão e redireciona o comprador para a `checkoutUrl`.
SDK embutível	Use quando você já tem uma página própria e quer montar o checkout da Bob dentro dela.
API direta	Use apenas em integrações avançadas que já possuem tokenização, conformidade e tratamento de 3DS próprios.

Fluxo recomendado

Cartão
  -> Bob Checkout ou @bobpayments/checkout-sdk
  -> tokenização segura
  -> API Bob
  -> processamento interno da Bob

O número do cartão, CVV e validade nunca passam pela API Bob. O comprador não vê detalhes do processamento interno.

Nunca envie cartão bruto para a API Bob. Payloads com PAN, CVV ou validade devem continuar sendo rejeitados.

Checkout hospedado

Para aceitar cartão no checkout hospedado, envie credit_card em paymentMethods:

curl -X POST https://api.payments.bob.company/api/v1/checkout-sessions/ \
  -H "Authorization: Bearer $BOB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amountCents": 25000,
    "items": [{ "name": "Assinatura Pro", "quantity": 1, "unitAmountCents": 25000 }],
    "paymentMethods": ["credit_card", "pix"],
    "successUrl": "https://loja.example.com/obrigado",
    "webhookUrl": "https://loja.example.com/webhooks/bob",
    "webhookVersion": "v2"
  }'

A sessão aceita credit_card quando o método está habilitado no projeto. Caso contrário, a API informa que o método não está disponível.

SDK embutível

Use o SDK embutível quando você quer manter o comprador no seu site, mas não quer implementar os campos seguros, a tokenização, o 3DS ou o fallback.

import { BobCheckout } from '@bobpayments/checkout-sdk';

<BobCheckout
  sessionToken={checkoutToken}
  onSuccess={(payment) => navigate(`/orders/${payment.id}`)}
  onError={(error) => showError(error)}
/>

Ou monte o checkout em uma página sem React:

const checkout = await BobCheckout.create({
  sessionToken: checkoutToken,
});

checkout.mount('#bob-payment');

O SDK gerencia os campos seguros, cria um identificador seguro de método de pagamento, envia o token para a API Bob e conduz 3DS quando necessário. O lojista não precisa importar bibliotecas adicionais.

SDK Checkout

Veja como embutir o checkout da Bob no seu site.

API direta avançada

Use a API direta com cartão somente quando você já possui sua própria implementação de tokenização e autenticação 3DS. Nesse modo, o frontend cria um identificador seguro de método de pagamento (pm_...) e envia para a Bob apenas esse token, junto com paymentMethod: "credit_card". O pm_... deve existir apenas em memória durante a tentativa. Não salve esse valor em logs, analytics, URL ou banco do checkout.

Processamento e fallback

Para cartão, a Bob gerencia as tentativas e o fallback internamente. O comprador recebe uma única resposta final e não vê detalhes do processamento. Quando o pagamento exigir ação do comprador, como autenticação 3DS, o checkout deve mostrar a autenticação segura, abrir a URL retornada e consultar o status ao voltar. Mostre sucesso somente quando a sessão ou transação estiver PAID/paid.

Estados públicos

Status	Significado
`paid`	Pagamento aprovado
`waiting_payment`	Aguardando autenticação 3DS ou confirmação assíncrona
`failed`	O processamento não foi concluído
`pending`	Pagamento criado, mas ainda sem confirmação final

Use webhook e/ou consulta de status para confirmar o desfecho financeiro. Não considere apenas o HTTP 201 como confirmação de pagamento.

O que você configura

No seu lado, a configuração é feita pelo Dashboard:

Habilite cartão para o projeto, quando necessário.
Use o checkout hospedado ou o SDK Checkout para coletar o cartão.
Configure o webhook da Bob para receber a confirmação do pagamento.

A Bob gerencia o processamento do cartão, a reconciliação e os detalhes internos da operação. Você não precisa enviar credenciais de provedores de pagamento para a sua aplicação.

Nunca envie credenciais secretas nem dados brutos do cartão para o navegador, para a API Bob ou para repositórios.

Primeiros passos

Conceitos principais

Formas de integração

Webhooks

Usando a Bob

Fundamentos da API

Escolha o nível de integração

Fluxo recomendado

Checkout hospedado

SDK embutível

SDK Checkout

API direta avançada

Processamento e fallback

Estados públicos

O que você configura

Próximos passos

SDK Checkout

Transação de cartão

​Escolha o nível de integração

​Fluxo recomendado

​Checkout hospedado

​SDK embutível

SDK Checkout

​API direta avançada

​Processamento e fallback

​Estados públicos

​O que você configura

​Próximos passos

SDK Checkout

Transação de cartão

Escolha o nível de integração

Fluxo recomendado

Checkout hospedado

SDK embutível

API direta avançada

Processamento e fallback

Estados públicos

O que você configura

Próximos passos