Skip to content

Cobrança com Cartão de Crédito ​

Processe pagamentos com cartão de crédito diretamente, com suporte a parcelamento e 3DS.

Fluxo de Pagamento ​

  1. Obter chave pública
  2. Criptografar dados do cartão
  3. Criar cobrança
  4. Processar pagamento

GET /api/charge/credit-card/public-key ​

Obtém a chave pública para criptografar dados do cartão.

Endpoint ​

GET https://api.divipay.com.br/api/charge/credit-card/public-key

Headers ​

HeaderValorObrigatório
AuthorizationBearerSim

Exemplo de Requisição ​

bash
curl -X GET https://api.divipay.com.br/api/charge/credit-card/public-key \
  -H "Authorization: Bearer SEU_TOKEN"

Resposta ​

json
{
  "public_key": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...",
  "created_at": 1699113600
}

GET /api/charge/credit-card/session ​

Obtém sessão 3DS para cartão de débito.

Endpoint ​

GET https://api.divipay.com.br/api/charge/credit-card/session

Resposta ​

json
{
  "session": "abc123xyz789",
  "env": "production"
}

POST /api/charge/credit-card ​

Cria uma cobrança com cartão de crédito.

Endpoint ​

POST https://api.divipay.com.br/api/charge/credit-card

Body Parameters ​

CampoTipoDescriçãoObrigatório
amountnumberValor da cobrançaSim
descriptionstringDescrição (máx. 15 caracteres)Sim
referenceIdstringID de referênciaSim
callbackUrlstringURL para webhookSim
installmentsnumberNúmero de parcelas (padrão 1)Sim
customerIdstringID da subcontaNão
feenumberTaxa fixaNão
cardobjectDados do cartãoSim
clientobjectDados do clienteSim
itensarrayLista de itensSim
shippingobjectEndereço de cobrançaSim

referenceId não é idempotente

O referenceId não é único e não evita duplicidade: reenviar a mesma requisição gera uma nova cobrança/tentativa. Controle retentativas do seu lado. Idempotência automática só existe na Cobrança em Lote (header Idempotency-Key).

Objeto Card ​

CampoTipoDescriçãoObrigatório
cardNumberstringNúmero do cartãoSim*
holderstringNome no cartãoSim*
expirationDatestringValidade (MM/AAAA)Sim*
securityCodestringCVVSim
cardTokenstringToken de cartão salvoNão
encryptedCardstringCartão criptografadoSim
antiFraudIdstringID antifraudeSim
threedsTokenstringToken 3DS (débito)Não

*Obrigatório se não usar cardToken

Objeto Client ​

CampoTipoDescriçãoObrigatório
namestringNome do cliente (máx. 255 caracteres)Sim
documentstringCPF ou CNPJ (somente números)Sim
phonestringTelefone com DDD (somente números)Sim
emailstringE-mail do cliente (máx. 255 caracteres)Não
ipstringIP do clienteNão
fingerprintstringFingerprint do dispositivo para antifraude (repassado à adquirente como identificador de dispositivo). OpcionalNão

Objeto Shipping ​

CampoTipoDescriçãoObrigatório
zipCodestringCEP (somente números, 8 dígitos)Sim
streetstringLogradouro (máx. 100 caracteres)Sim
numberstringNúmero (máx. 15 caracteres)Sim
complementstringComplemento (máx. 100 caracteres)Sim
districtstringBairro (máx. 100 caracteres)Sim
citystringCidade (máx. 100 caracteres)Sim
statestringEstado (2 caracteres, ex: SP)Sim

Exemplo de Requisição ​

bash
curl -X POST https://api.divipay.com.br/api/charge/credit-card \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 200.00,
    "description": "Compra Online",
    "referenceId": "order-789",
    "callbackUrl": "https://seusite.com/webhook",
    "installments": 3,
    "card": {
      "cardNumber": "4111111111111111",
      "holder": "JOAO SILVA",
      "expirationDate": "12/2025",
      "securityCode": "123",
      "encryptedCard": "encrypted_data_here",
      "antiFraudId": "antifraud_id_here"
    },
    "client": {
      "name": "João Silva",
      "document": "12345678901",
      "email": "joao@email.com",
      "phone": "11999999999",
      "ip": "203.0.113.10"
    },
    "itens": [
      {
        "name": "Produto Digital",
        "quantity": 1,
        "unitPrice": 200.00,
        "feePercent": 0
      }
    ],
    "shipping": {
      "zipCode": "01001000",
      "street": "Rua Exemplo",
      "number": "123",
      "complement": "Apto 45",
      "district": "Centro",
      "city": "São Paulo",
      "state": "SP"
    }
  }'
javascript
// 1. Obter chave pública
const keyResponse = await fetch(
  'https://api.divipay.com.br/api/charge/credit-card/public-key',
  {
    headers: { 'Authorization': `Bearer ${token}` }
  }
);
const { public_key } = await keyResponse.json();

// 2. Criptografar cartão (use biblioteca de criptografia)
const encryptedCard = encryptCardData(cardData, public_key);

// 3. Criar cobrança
const response = await fetch(
  'https://api.divipay.com.br/api/charge/credit-card',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      amount: 200.00,
      description: 'Compra Online',
      referenceId: 'order-789',
      callbackUrl: 'https://seusite.com/webhook',
      installments: 3,
      card: {
        cardNumber: '4111111111111111',
        holder: 'JOAO SILVA',
        expirationDate: '12/2025',
        securityCode: '123',
        encryptedCard: encryptedCard,
        antiFraudId: generateAntiFraudId()
      },
      client: {
        name: 'João Silva',
        document: '12345678901',
        email: 'joao@email.com',
        phone: '11999999999',
        ip: '203.0.113.10'
      },
      itens: [
        {
          name: 'Produto Digital',
          quantity: 1,
          unitPrice: 200.00,
          feePercent: 0
        }
      ],
      shipping: {
        zipCode: '01001000',
        street: 'Rua Exemplo',
        number: '123',
        complement: 'Apto 45',
        district: 'Centro',
        city: 'São Paulo',
        state: 'SP'
      }
    })
  }
);

const charge = await response.json();

Resposta de Sucesso ​

Status: 201 Created

json
{
  "id": "2f11b9f1-0c50-4cf3-a7dd-5df6d355a289",
  "status": "PAID",
  "amount": 200.00,
  "payedAt": "2024-11-04T15:30:00.000Z",
  "customerId": null,
  "cardToken": "card_token_xyz789",
  "nsu": "123456",
  "authorizationCode": "ABC123",
  "proofOfSale": "789456",
  "returnCode": "00",
  "returnMessage": "Transação aprovada"
}

Status da Transação ​

StatusDescrição
PENDINGAguardando processamento
PAIDPagamento aprovado
CANCELEDPagamento recusado

Códigos de Retorno ​

CódigoMensagem
00Transação aprovada
05Não autorizada
51Saldo insuficiente
57Cartão bloqueado
78Cartão não desbloqueado

Salvar Cartão ​

POST /api/charge/credit-card/save-card ​

Salva um cartão para uso futuro.

bash
curl -X POST https://api.divipay.com.br/api/charge/credit-card/save-card \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cardNumber": "4111111111111111",
    "holder": "JOAO SILVA",
    "expirationDate": "12/2025",
    "securityCode": "123"
  }'

Resposta:

json
{
  "customerId": "5a4c2b18-8f01-49cc-9e3d-2b3b7f1d4e66",
  "cardToken": "card_token_xyz789"
}

Usar Cartão Salvo ​

javascript
{
  "card": {
    "cardToken": "card_token_xyz789",
    "securityCode": "123"
  }
  // ... outros campos
}

Deletar Cartão ​

DELETE /api/charge/credit-card/save-card/ ​

bash
curl -X DELETE https://api.divipay.com.br/api/charge/credit-card/save-card/card_token_xyz789 \
  -H "Authorization: Bearer SEU_TOKEN"

Parcelamento ​

Configure o número de parcelas:

javascript
{
  "amount": 300.00,
  "installments": 6,  // 6x de R$ 50,00
  // ... outros campos
}

ATENÇÃO

  • Nesta rota o valor cobrado é exatamente o amount enviado — a API não acrescenta a taxa de parcelamento automaticamente. Para repassar a taxa ao portador, envie o amount já com o valor final (o feeType do link de checkout não se aplica aqui).
  • Verifique as taxas de parcelamento com sua conta DiviPay.

Exemplo Completo ​

javascript
class CreditCardPayment {
  constructor(token) {
    this.token = token;
    this.apiUrl = 'https://api.divipay.com.br';
  }

  async getPublicKey() {
    const response = await fetch(
      `${this.apiUrl}/api/charge/credit-card/public-key`,
      {
        headers: { 'Authorization': `Bearer ${this.token}` }
      }
    );
    const data = await response.json();
    return data.public_key;
  }

  encryptCard(cardData, publicKey) {
    // Implementar criptografia RSA
    // Use biblioteca como node-rsa ou jsencrypt
    const encrypted = /* criptografar com publicKey */;
    return encrypted;
  }

  async processPayment(paymentData) {
    try {
      // 1. Obter chave pública
      const publicKey = await this.getPublicKey();

      // 2. Criptografar cartão
      const encryptedCard = this.encryptCard(
        paymentData.card,
        publicKey
      );

      // 3. Criar cobrança
      const response = await fetch(
        `${this.apiUrl}/api/charge/credit-card`,
        {
          method: 'POST',
          headers: {
            'Authorization': `Bearer ${this.token}`,
            'Content-Type': 'application/json'
          },
          body: JSON.stringify({
            ...paymentData,
            card: {
              ...paymentData.card,
              encryptedCard,
              antiFraudId: this.generateAntiFraudId()
            }
          })
        }
      );

      if (!response.ok) {
        const error = await response.json();
        throw new Error(error.message);
      }

      const charge = await response.json();

      // 4. Verificar status
      if (charge.status === 'PAID') {
        console.log('✅ Pagamento aprovado!');
        console.log('NSU:', charge.nsu);
        console.log('Autorização:', charge.authorizationCode);
        return charge;
      } else {
        console.log('❌ Pagamento recusado');
        console.log('Motivo:', charge.returnMessage);
        throw new Error(charge.returnMessage);
      }

    } catch (error) {
      console.error('Erro ao processar pagamento:', error);
      throw error;
    }
  }

  generateAntiFraudId() {
    // Gerar ID único para antifraude
    return `af_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
  }
}

// Uso
const payment = new CreditCardPayment(token);

const charge = await payment.processPayment({
  amount: 200.00,
  description: 'Compra Online',
  referenceId: 'order-789',
  callbackUrl: 'https://seusite.com/webhook',
  installments: 3,
  card: {
    cardNumber: '4111111111111111',
    holder: 'JOAO SILVA',
    expirationDate: '12/2025',
    securityCode: '123'
  },
  client: {
    name: 'João Silva',
    document: '12345678901',
    email: 'joao@email.com',
    phone: '11999999999',
    ip: '203.0.113.10'
  },
  itens: [
    {
      name: 'Produto Digital',
      quantity: 1,
      unitPrice: 200.00
    }
  ],
  shipping: {
    zipCode: '01001000',
    street: 'Rua Exemplo',
    number: '123',
    complement: 'Apto 45',
    district: 'Centro',
    city: 'São Paulo',
    state: 'SP'
  }
});

Segurança ​

IMPORTANTE

  • Nunca armazene dados completos do cartão
  • Sempre use HTTPS
  • Criptografe dados sensíveis
  • Implemente 3DS para débito
  • Use tokens para pagamentos recorrentes

Próximos Passos ​

Documentação da API DiviPay