Cartão de crédito

Criar cobrança

Como autorizar uma cobrança de cartão de crédito, à vista ou parcelada, com cartão aberto ou token.

A chave da API de cartão vai no header X-API-KEY. A URL base é entregue pela BW na habilitação do meio. Nos exemplos, BASE representa essa URL.

POST /v2/payment

Cartão de crédito usa PaymentMethod "2". O valor da venda é a soma de Products (UnitPrice × Quantity), em reais.

Com cartão tokenizado, envie só PaymentObject.Token. Sem token, envie titular, número, validade (MM/YYYY) e código de segurança. O nome impresso aceita até 25 caracteres.

A autorização sai do seu backend. O navegador do pagador não chama este endpoint.

cURL

curl --request POST \
  --url 'BASE/v2/payment' \
  --header 'X-API-KEY: SUA_CHAVE' \
  --header 'content-type: application/json' \
  --data '{ ... }'

Body JSON

{
  "IsSandbox": false,
  "Application": "Loja BW",
  "Vendor": "João da Silva",
  "CallbackUrl": "https://callbacks.exemplo.com.br/api/notify",
  "PaymentMethod": "2",
  "Reference": "PEDIDO-1042",
  "IpAddress": "200.200.200.200",
  "Customer": {
    "Name": "Maria Silva",
    "Identity": "12345678909",
    "Phone": "51999999999",
    "Email": "maria@exemplo.com",
    "Address": {
      "ZipCode": "90160090",
      "Street": "Rua Beck",
      "Number": "56",
      "Complement": "Sala 1",
      "District": "Menino Deus",
      "CityName": "Porto Alegre",
      "StateInitials": "RS",
      "CountryName": "Brasil"
    }
  },
  "Products": [
    {
      "Code": "001",
      "Description": "Serviço",
      "UnitPrice": 150.35,
      "Quantity": 1
    }
  ],
  "PaymentObject": {
    "Holder": "MARIA SILVA",
    "CardNumber": "5105105105105100",
    "ExpirationDate": "12/2028",
    "SecurityCode": "123",
    "InstallmentQuantity": 1
  }
}

Campos do cartão

Campo	Uso
IsSandbox	true no ambiente de teste, false em produção.
Application	Nome da aplicação que originou a venda.
Vendor	Vendedor vinculado à transação.
CallbackUrl	URL que recebe as mudanças de status.
Reference	Seu identificador da venda.
IpAddress	IP v4 ou v6 do comprador.
Customer	Nome, documento, telefone, e-mail e endereço.
Products	Itens com código, descrição, preço unitário e quantidade.
PaymentObject.InstallmentQuantity	Número de parcelas.
PaymentObject.IsPreAuthorization	true reserva o limite e não captura. A captura precisa ocorrer em até 15 dias corridos. Não combine com split.
PaymentObject.IsApplyInterest	true quando a venda cobra juros do comprador.
PaymentObject.InterestRate	Percentual de juros aplicado à compra.
PaymentObject.Token	Token do cofre, no lugar dos dados abertos do cartão.
PaymentObject.ExternalAuthentication	Retorno do 3DS: Cavv, Xid, Eci, Version e ReferenceId.
VisitorID	Identificador gerado pelo script de antifraude.
ShouldUseAntiFraud	false pula a análise. O risco de chargeback fica com o estabelecimento. O painel precisa estar em análise por transação.

O documento do cliente passa a aceitar CNPJ alfanumérico quando a Receita Federal emitir esse formato. Revise máscaras e validações do checkout para não recusar letras.

Resposta

JSON

{
  "ResponseDetail": {
    "IdTransaction": 1049946,
    "Token": "36d8f360-6019-49f4-9cf4-3d8d198817e8",
    "Description": "O seu pagamento foi autorizado pela operadora do cartão de crédito.",
    "Tid": "020006495642",
    "AuthorizationCode": "205340",
    "Status": 3,
    "Message": "Pagamento Autorizado",
    "CreditCard": {
      "CardNumber": "402400******3191",
      "Brand": 1,
      "Installments": 1
    }
  },
  "HasError": false
}

Status 3 é autorizado. Guarde IdTransaction para captura, estorno e consulta de chargeback. O número do cartão volta mascarado.