Cartão de Crédito
Processe pagamentos com cartão de crédito com parcelamento, estorno e retentativa. Os dados do cartão são tokenizados no navegador do pagador — eles nunca trafegam pelo seu servidor.
POST
/v1/charges/cardCria uma cobrança de cartão de crédito com captura automática
1. Tokenização no seu frontend
Antes de chamar a API, gere o paymentToken no navegador do pagador com a ActivePayments.js. Você não precisa saber qual adquirente processa o cartão da sua conta nem cadastrar o seu domínio em lugar nenhum: basta a sua public key. Os dados do cartão vão do navegador direto para o processador — não passam pelo seu servidor nem pelo nosso.
ActivePayments.js
<!-- 1. No <head> da página de pagamento -->
<script src="https://activepayments.com.br/v1/js"></script>
<script>
// 2. Sua PUBLIC KEY (Credenciais de API). Nunca use o secret no navegador.
ActivePayments.setPublicKey('ActivePayments_pk_xxxxxxxxxxxx');
// 3. Ao clicar em "Pagar": gera o token com os dados que o pagador digitou
async function pagar() {
try {
const card = await ActivePayments.encrypt({
number: '4111111111111111',
holderName: 'JOAO SILVA',
expMonth: 5, // 1 a 12
expYear: 2031, // 4 dígitos (ou 2)
cvv: '123',
});
// card.token → envie como paymentToken
// card.brand → "Visa", "Mastercard"... (envie como cardBrand)
// card.cardMask → "XXXXXXXXXXXX1111" (envie como cardMask)
await fetch('/seu-backend/pagar', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ paymentToken: card.token, cardBrand: card.brand, cardMask: card.cardMask }),
});
// 4. O SEU servidor chama POST /v1/charges/card com a API Key (public + secret)
} catch (e) {
alert(e.message); // ex.: "Número do cartão inválido."
}
}
</script>| Método | Descrição |
|---|---|
ActivePayments.setPublicKey(publicKey) | A public key da sua API Key (ActivePayments_pk_...). Chame uma vez, ao carregar a página |
ActivePayments.encrypt(card) | card: number, holderName, expMonth, expYear, cvv. Retorna uma Promise com token, brand, last4 e cardMask. Rejeita com mensagem em português pronta para o pagador (ex.: Número do cartão inválido., Cartão vencido.) |
Nunca envie o número do cartão para a APIO token é de uso único e expira em poucos minutos: gere um novo a cada tentativa de pagamento e envie ao seu servidor só o
token. Quem chama POST /v1/charges/card é o seu servidor, com a API Key completa.2. Parâmetros da Requisição
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
amount | number | Sim | Valor total em reais (ex: 150.00) |
paymentToken | string | Sim | token retornado por ActivePayments.encrypt() |
cardMask | string | Não | Máscara do cartão (ex: XXXXXXXXXXXX0087) — o cardMask da ActivePayments.js |
cardBrand | string | Não | Bandeira (ex: Visa) — o brand da ActivePayments.js |
installments | number | Não | Número de parcelas (1-12, default 1). Consulte as opções em GET /v1/card/installments |
cardHolder | string | Sim | Nome impresso no cartão (MAIÚSCULAS) |
customerName | string | Sim | Nome completo do pagador |
customerDocument | string | Sim | CPF ou CNPJ do pagador (apenas números) |
customerEmail | string | Não | E-mail do pagador |
customerPhone | string | Não | Telefone do pagador (apenas números) |
street / number / district / city / state / zipCode | string | Não | Endereço de cobrança (opcional — melhora a taxa de aprovação) |
externalReference | string | Não | Identificador externo (ex: ID do pedido no seu sistema) |
postbackUrl | string | Não | URL de callback para notificações desta cobrança |
Ciclo de Status
| Status (criação) | Significado |
|---|---|
RELEASE | Aprovada e capturada — o resultado do cartão é síncrono na maioria dos casos |
PENDING | Em análise pelo emissor — o resultado final chega via webhook (card.approved / card.refused) |
FAILED | Recusada — veja card.refusalReason; se card.retryAllowed = true, é possível retentar |
Na consulta (GET /v1/charges/:id) o status vem em lowercase: paid, pending, failed, refunded, chargedback. A resposta inclui o bloco card com brand, lastDigits, installments e refundedAmount.
Endpoints auxiliares
| Endpoint | Descrição |
|---|---|
GET /v1/card/installments?brand=visa&total=150.00 | Opções de parcelamento com juros. Bandeiras: visa, mastercard, amex, elo |
POST /v1/charges/card/:id/refund | Estorno. Sem body = total (até 360 dias); com { "amount": 50.00 } = parcial (até 90 dias). O líquido é revertido pró-rata do seu saldo |
POST /v1/charges/card/:id/retry | Retentativa de cobrança recusada com um novo paymentToken (a mesma cobrança é reaproveitada). Só quando a recusa veio com card.retryAllowed = true; com false ou null, crie uma nova cobrança com um novo token |
Resposta do estorno parcial (HTTP 200)
{
"success": true,
"data": {
"chargeId": "e19b0dae-2a0a-4e6d-9ab7-2298c58c9b62",
"externalId": "123456789",
"refundedAmount": "50.00",
"totalRefunded": "50.00",
"status": "RELEASE"
}
}Liberação do saldoO valor líquido de vendas no cartão fica em saldo a liberar por um período configurado na plataforma (padrão D+30), com opção de antecipação mediante taxa.
Próximo passoConfigure os Webhooks para receber
card.approved, card.refused, card.refunded e card.chargeback.