Cartão de crédito

A API de cartão da PulsePag usa a base oficial https://api.pulsepag.com e trabalha com autenticação Bearer JWT. O endpoint principal é POST /api/v1/card/payments e aceita pagamento à vista, parcelado, fluxo com 3DS e callback white-label do seu projeto.

1) Autenticação

Gere o JWT primeiro e use o token nas rotas de cartão.

curl -X POST 'https://api.pulsepag.com/api/auth/login' \
  --header 'Content-Type: application/json' \
  --data '{
    "client_id": "seu_client_id",
    "client_secret": "seu_client_secret"
  }'

{
  "token": "SEU_JWT"
}

2) Endpoint principal

3) Exemplo de criação

curl -X POST 'https://api.pulsepag.com/api/v1/card/payments' \
  --header 'Authorization: Bearer SEU_JWT' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 50.00,
    "description": "Pedido #1024",
    "externalReference": "pedido_1024",
    "installmentCount": 1,
    "dueDate": "2026-04-17",
    "global": false,
    "clientCallbackUrl": "https://seusistema.com/webhooks/card",
    "payer": {
      "name": "Lucas Teixeira",
      "email": "lucas@example.com",
      "phone": "11999999999",
      "document": "36188196841"
    },
    "creditCard": {
      "holderName": "LUCAS TEIXEIRA",
      "number": "4111111111111111",
      "expiryMonth": "08",
      "expiryYear": "2029",
      "ccv": "123",
      "holderDocument": "36188196841",
      "currency": "BRL"
    },
    "items": [
      {
        "title": "Plano Premium",
        "quantity": 1,
        "amount": 50.00,
        "tangible": false,
        "externalRef": "item_1024"
      }
    ],
    "metadata": {
      "order_id": "1024",
      "source": "checkout-web"
    }
  }'

Resposta de exemplo

{
  "message": "Pagamento criado com sucesso.",
  "data": {
    "id": 152,
    "status": "PENDING",
    "amount": 50.00,
    "netValue": 42.04,
    "brand": "VISA",
    "last4": "1111",
    "invoiceUrl": null,
    "receiptUrl": null,
    "provider": "witetec",
    "providerReferences": {
      "transactionId": "022d7383-2b95-4f75-be4b-fbba37ba50ae",
      "customerId": "82eb9fdf-06f5-4f9b-9a64-51714d0dfa00",
      "cardId": "e42df45b-61cc-4e9d-939c-b52956cf01c6"
    }
  }
}

4) Status possíveis

• PENDING: transação criada e aguardando confirmação.
• PROCESSING: pagamento em análise/processamento.
• COMPLETED: pagamento aprovado.
• FAILED: pagamento recusado ou falhado.
• REFUNDED: venda estornada.
• CHARGEDBACK: venda contestada/estornada por chargeback.

5) Consulta da venda

curl -X GET 'https://api.pulsepag.com/api/v1/card/payments/152' \
  --header 'Authorization: Bearer SEU_JWT'

6) 3DS e tokenização no frontend

Para 3DS, carregue o módulo de segurança no frontend, inicialize a chave pública fixa do ambiente e envie o resultado ao seu backend. A sua integração deve falar com a PulsePag sempre pelo backend.

<script src="https://api.paysharkgateway.com.br/v1/js"></script>

const publicKey = "pk_j8iPqjurYkTDxHjXsJqAQnhvmU-Ar9AnrBU8GcPYWfdO4I9R";

const moduleName = window["ShieldHelper"].getModuleName();
const module = window[moduleName];
await module.setPublicKey(publicKey);

const settingsResponse = await fetch(
  `https://api.paysharkgateway.com.br/api/v1/js/get3dsSettings?publicKey=${publicKey}`
);
const settings = await settingsResponse.json();

const amountInCents = window["ShieldHelper"].convertDecimalToCents(50, "BRL");

await window["ShieldHelper"].prepareThreeDS({
  amount: amountInCents,
  installments: 1,
  currency: "BRL",
});

const token = await module.encrypt({
  number: "4111111111111111",
  holderName: "LUCAS TEIXEIRA",
  expMonth: 8,
  expYear: 2029,
  cvv: "123"
});

Depois de gerar o token e o contexto 3DS, envie a transação do seu backend para a PulsePag com creditCard preenchido e, se aplicável, também creditCardToken, creditCard.sessionId e creditCard.threeDS.

{
  "amount": 50.00,
  "installmentCount": 1,
  "dueDate": "2026-04-17",
  "payer": {
    "name": "Lucas Teixeira",
    "email": "lucas@example.com",
    "phone": "11999999999",
    "document": "36188196841"
  },
  "creditCardToken": "tok_exemplo_123",
  "creditCard": {
    "holderName": "LUCAS TEIXEIRA",
    "number": "4111111111111111",
    "expiryMonth": "08",
    "expiryYear": "2029",
    "ccv": "123",
    "holderDocument": "36188196841",
    "sessionId": "sessao_3ds_123",
    "currency": "BRL",
    "threeDS": {
      "cavv": "AAABBBCCC123456789",
      "xid": "XID123456789",
      "eci": "05",
      "version": "2.1.0",
      "referenceId": "REF987654321"
    }
  }
}

7) Callback do seu projeto

Se você enviar clientCallbackUrl, a PulsePag fará o POST para a URL informada quando houver atualização relevante da venda.

POST https://seusistema.com/webhooks/card
Content-Type: application/json

{
  "id": 152,
  "type": "Card",
  "status": "COMPLETED",
  "amount": 50.00,
  "netValue": 42.04,
  "brand": "VISA",
  "last4": "1111",
  "provider": "WITETEC",
  "providerTransactionId": "022d7383-2b95-4f75-be4b-fbba37ba50ae",
  "providerCustomerId": "82eb9fdf-06f5-4f9b-9a64-51714d0dfa00",
  "providerStatus": "PAID",
  "eventType": "PAYMENT_UPDATED",
  "externalReference": "pedido_1024",
  "updatedAt": "2026-04-17T20:15:30.000Z",
  "note": "status_updated"
}

8) Boas práticas

• Não armazene PAN, CVV ou dados sensíveis do cartão no seu backend.
• Envie a transação sempre pelo backend. O frontend deve apenas coletar/tokenizar.
• Use externalReference para reconciliar pedidos.
• Trate a venda como concluída somente após status COMPLETED.
• Configure sua clientCallbackUrl e mantenha consulta por ID como fallback.