Criar cobrança Cartão

curl -X POST https://api.abacatepay.com/v2/transparents/create \
  -H "Authorization: Bearer $ABACATEPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "CARD",
    "data": {
      "amount": 4700,
      "cardToken": "dev_card_4242",
      "customer": {
        "name": "Maria Silva",
        "email": "maria@exemplo.com",
        "taxId": "529.982.247-25",
        "cellphone": "(11) 99999-9999"
      }
    }
  }'

{
  "data": {
    "id": "card_Wk3aD8sPq1XyZ7mN2bVc4LtR",
    "amount": 4700,
    "status": "APPROVED",
    "devMode": true,
    "cardToken": "dev_card_4242",
    "brand": "VISA",
    "lastFour": "4242",
    "receiptUrl": null,
    "createdAt": "2026-10-12T14:20:31.512Z",
    "updatedAt": "2026-10-12T14:20:31.512Z",
    "metadata": {}
  },
  "success": true,
  "error": null
}

{
  "data": null,
  "success": false,
  "error": "Não foi possível processar o pagamento com este cartão"
}

POST

transparents

create

curl -X POST https://api.abacatepay.com/v2/transparents/create \
  -H "Authorization: Bearer $ABACATEPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "CARD",
    "data": {
      "amount": 4700,
      "cardToken": "dev_card_4242",
      "customer": {
        "name": "Maria Silva",
        "email": "maria@exemplo.com",
        "taxId": "529.982.247-25",
        "cellphone": "(11) 99999-9999"
      }
    }
  }'

{
  "data": {
    "id": "card_Wk3aD8sPq1XyZ7mN2bVc4LtR",
    "amount": 4700,
    "status": "APPROVED",
    "devMode": true,
    "cardToken": "dev_card_4242",
    "brand": "VISA",
    "lastFour": "4242",
    "receiptUrl": null,
    "createdAt": "2026-10-12T14:20:31.512Z",
    "updatedAt": "2026-10-12T14:20:31.512Z",
    "metadata": {}
  },
  "success": true,
  "error": null
}

{
  "data": null,
  "success": false,
  "error": "Não foi possível processar o pagamento com este cartão"
}

Requer a permissão TRANSPARENT:CREATE.

Cria uma cobrança de cartão de crédito no checkout transparente. O cartão é informado de um destes dois jeitos:

Campo	Quando usar
`data.token`	Primeira compra: o cliente acabou de digitar o cartão e o abacatepay.js gerou o token `ctok_`
`data.cardToken`	Cobranças seguintes do mesmo cartão, sem o cliente presente. Veja Cobrar de novo um cartão salvo

Primeira integração? Siga o passo a passo do checkout transparente. Esta página é a referência dos campos.

Corpo da requisição

string

required

Sempre "CARD".

object

required

Dados da cobrança. Envie token ou cardToken, nunca os dois. Campos fora desta lista (como description e externalId) são ignorados na cobrança de cartão.

Hide campos de data

integer

required

Valor total em centavos, a partir de 100 (R$ 1,00). Com token, precisa ser igual ao amount usado no AbacatePay.create. Com cardToken, pode ser qualquer valor.

string

Token ctok_... gerado pelo tokenize() do abacatepay.js. Vale 60 segundos e uma única cobrança.

string

Token permanente do cartão, devolvido em uma cobrança anterior (texto de até 200 caracteres). Cobra o mesmo cartão sem o cliente presente e sem 3DS.

integer

default:"1"

Número de parcelas, de 1 (à vista) a 12. Cada parcela precisa ter pelo menos R$ 10,00: 3x exige amount de pelo menos 3000.

object

required

Dados do cliente. Todos os campos são obrigatórios.

Hide campos de customer

string

required

Nome do cliente, até 150 caracteres.

string

required

E-mail válido, até 150 caracteres.

string

required

CPF ou CNPJ válido, com ou sem máscara.

string

required

Celular, de 8 a 20 caracteres.

object

Seus dados de referência, devolvidos na resposta. Todos os valores precisam ser texto: { "pedidoId": "123" }, não { "pedidoId": 123 }.

Exemplos de requisição

Primeira compra (token)
Cartão salvo (cardToken)
Parcelado

{
  "method": "CARD",
  "data": {
    "amount": 10000,
    "token": "ctok_9fK2mQ7xLp4vR8sT1wYz3nBc",
    "customer": {
      "name": "Maria Silva",
      "email": "maria@exemplo.com",
      "taxId": "529.982.247-25",
      "cellphone": "(11) 99999-9999"
    },
    "metadata": { "pedidoId": "pedido-123" }
  }
}

{
  "method": "CARD",
  "data": {
    "amount": 4700,
    "cardToken": "dev_card_4242",
    "customer": {
      "name": "Maria Silva",
      "email": "maria@exemplo.com",
      "taxId": "529.982.247-25",
      "cellphone": "(11) 99999-9999"
    }
  }
}

{
  "method": "CARD",
  "data": {
    "amount": 30000,
    "installmentCount": 3,
    "token": "ctok_9fK2mQ7xLp4vR8sT1wYz3nBc",
    "customer": {
      "name": "Maria Silva",
      "email": "maria@exemplo.com",
      "taxId": "529.982.247-25",
      "cellphone": "(11) 99999-9999"
    }
  }
}

Para testar no terminal, use um cardToken de Dev mode, como o dev_card_4242 da sua primeira compra de teste: o ctok_ vale só 60 segundos. Exemplos completos em Node.js e Python estão no guia do cartão salvo.

Resposta

object

A cobrança criada.

Hide campos de data

string

ID da cobrança (card_...). Use para consultar e reembolsar.

integer

Valor total da venda, em centavos. No parcelado, é o total e não a parcela.

string

Situação da cobrança. Veja Status.

boolean

true quando criada com chave de Dev mode.

string

Token permanente do cartão. Guarde para cobrar de novo. No Dev mode vem como dev_card_ + os 4 últimos dígitos; em produção é um identificador sem formato fixo: guarde exatamente como veio.

string

Bandeira do cartão, como VISA ou MASTERCARD.

string

Últimos 4 dígitos do cartão.

integer

Só no parcelado: número de parcelas.

integer

Só no parcelado: valor da primeira parcela, em centavos. As demais podem variar em centavos por arredondamento.

integer

Só no parcelado: sempre 1 nesta resposta.

string

Só no parcelado: ID do parcelamento (cinst_...).

string | null

Comprovante. Vem null na criação.

string

Data de criação (ISO 8601).

string

Data da última atualização (ISO 8601).

string

Não se aplica a cartão. Ignore.

object

O que você enviou em data.metadata.

boolean

true quando a cobrança foi criada.

string | null

Mensagem de erro, ou null. Veja Erros.

No parcelado, a resposta traz os campos de parcela:

{
  "data": {
    "id": "card_Lr8pN3vKq2XwT6yB9mZc1HdS",
    "amount": 30000,
    "status": "APPROVED",
    "devMode": true,
    "cardToken": "dev_card_4242",
    "brand": "VISA",
    "lastFour": "4242",
    "installmentCount": 3,
    "installmentAmount": 10000,
    "installmentNumber": 1,
    "installmentGroupId": "cinst_Qe5tY7uI9oP1aS3dF5gH7jK9",
    "receiptUrl": null,
    "createdAt": "2026-10-12T14:25:02.118Z",
    "updatedAt": "2026-10-12T14:25:02.118Z",
    "metadata": {}
  },
  "success": true,
  "error": null
}

Status

`status`	Significado
`APPROVED`	Aprovada. Pode liberar o pedido
`PENDING`	O banco ainda não respondeu. Espere o webhook `transparent.completed`
`PAID`	O valor da venda foi repassado pela adquirente. Acontece depois da aprovação, sem ação sua
`FAILED`	Recusada. Na criação, a recusa volta como erro; o status aparece na consulta e na listagem
`REFUNDED`	Reembolsada
`UNDER_DISPUTE`	Contestada pelo titular do cartão (chargeback)

Erros

Erros voltam com success: false e a mensagem em error. Os mais comuns:

Não foi possível processar o pagamento com este cartão (400): o cartão foi recusado. A mensagem é a mesma para qualquer motivo, de propósito. Peça outro cartão.
Invalid or expired card token (400): o ctok_ passou de 60 segundos, já foi usado, é de outra loja ou de outro ambiente. Gere outro com tokenize().
amount does not match the tokenized amount (400): o amount é diferente do usado no AbacatePay.create. O token foi gasto: gere outro.
Card token not found (400): o cardToken não existe nesta loja e neste ambiente.
Provide exactly one of token (ctok_) or cardToken (400): faltou o cartão, ou foram enviados os dois.
customer.taxId must be a valid CPF or CNPJ (400): CPF ou CNPJ inválido.
amount must be at least 2000 cents for 2 installments (400): parcela abaixo de R$ 10,00. O número muda conforme as parcelas.
CARD_TRANSPARENTS is not available for this store (400): sua conta ainda não tem cartão liberado. Fale com o suporte.
Card payments are temporarily unavailable. Please try again later. (400): pagamentos com cartão suspensos temporariamente. Tente mais tarde.
Unauthorized (401): faltou o header Authorization: Bearer <chave de API>.
Invalid or inactive API key (401): chave de API errada ou revogada.
Insufficient permissions (401): a chave de API não tem a permissão TRANSPARENT:CREATE.
Erro de validação (422): um campo está faltando ou no formato errado, e a mensagem diz qual. Por exemplo: Property 'data.customer.cellphone' is missing, Property 'data.customer.email' should be email, Expected property 'data.metadata.pedidoId' to be string but found: 123 (valor de metadata que não é texto) ou Property 'method' should be one of: 'PIX', 'BOLETO', 'CARD'.

Timeout ou erro de rede não é recusa. A cobrança pode ter sido aprovada mesmo sem resposta. Não repita na hora: com cardToken, repetir pode cobrar o cliente duas vezes. Consulte a listagem ou espere o webhook antes de tentar de novo.

Consultar, listar e reembolsar

Consultar uma cobrança: GET /v2/transparents/get?id=card_... devolve o mesmo formato da resposta acima. Permissão TRANSPARENT:READ.
Listar só as de cartão: GET /v2/transparents/list?method=CARD. Veja Listar.
Reembolsar: POST /v2/transparents/refund com { "id": "card_..." }. Veja Reembolsar.
Ser avisado da aprovação: webhook transparent.completed. Veja os eventos do checkout transparente.

A rota GET /v2/transparents/check é só para PIX. Para cartão, use GET /v2/transparents/get.

curl -X POST https://api.abacatepay.com/v2/transparents/create \
  -H "Authorization: Bearer $ABACATEPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "CARD",
    "data": {
      "amount": 4700,
      "cardToken": "dev_card_4242",
      "customer": {
        "name": "Maria Silva",
        "email": "maria@exemplo.com",
        "taxId": "529.982.247-25",
        "cellphone": "(11) 99999-9999"
      }
    }
  }'

{
  "data": {
    "id": "card_Wk3aD8sPq1XyZ7mN2bVc4LtR",
    "amount": 4700,
    "status": "APPROVED",
    "devMode": true,
    "cardToken": "dev_card_4242",
    "brand": "VISA",
    "lastFour": "4242",
    "receiptUrl": null,
    "createdAt": "2026-10-12T14:20:31.512Z",
    "updatedAt": "2026-10-12T14:20:31.512Z",
    "metadata": {}
  },
  "success": true,
  "error": null
}

{
  "data": null,
  "success": false,
  "error": "Não foi possível processar o pagamento com este cartão"
}

Introdução

Cobrar com Checkout

Links de pagamento

Clientes

Checkout Transparente

Cupons

Produtos

Webhooks

Assinaturas

Saques

PIX

Extrato

Loja

Public MRR

Criar cobrança Cartão

Corpo da requisição

Exemplos de requisição

Resposta

Status

Erros

Consultar, listar e reembolsar

​Corpo da requisição

​Exemplos de requisição

​Resposta

​Status

​Erros

​Consultar, listar e reembolsar

Corpo da requisição

Exemplos de requisição

Resposta

Status

Erros

Consultar, listar e reembolsar