Pagamentos online por cartão de crédito

A API de pagamentos da CDX Pay permite que o e-commerce do seu estabelecimento cobre cartão de crédito sem que o número do cartão passe pelo seu servidor. O cartão é digitado em campos seguros embutidos na sua página, o navegador recebe um token de uso único, e o seu servidor cobra com esse token pela API /v1.

O que a API faz

• Crédito à vista e parcelado, de 1 a 18 parcelas.
• Pré-autorização com captura posterior, total ou parcial, dentro da janela de captura.
• Estorno total e parcial de um pagamento capturado, e cancelamento de uma pré-autorização.
• Cartão salvo: troque um token por um cartão guardado no cofre do provedor e cobre de novo sem pedir o cartão ao comprador.
• Webhook a cada mudança de status do pagamento, assinado com HMAC-SHA256.
• Idempotência em toda operação que movimenta dinheiro, para você repetir uma requisição com segurança depois de uma falha de rede.

O que a API não faz

• Pix, boleto e cartão de débito não são suportados.
• A API não recebe o número do cartão, a validade nem o CVV. Eles vão do navegador direto para os campos seguros do SDK de tokenização.

Como a integração funciona

1. O seu servidor lê a configuração pública de tokenização em GET /v1/capabilities (Tokenização do cartão).
2. A sua página monta os campos seguros do cartão com o SDK @malga/tokenization e obtém um token_id de uso único.
3. O seu servidor cria o pagamento com POST /v1/payments, enviando o token_id e os dados do comprador (Pagamentos).
4. O seu endpoint recebe o evento payment.status_changed a cada mudança de status (Webhook).

navegador do comprador ──(cartão)──▶ campos seguros do SDK ──▶ token_id
           │ token_id
           ▼
servidor do e-commerce ──(Authorization: Bearer, Idempotency-Key)──▶ API /v1 da CDX Pay
           ▲
           └──── webhook payment.status_changed (X-WebPayments-Signature)

Por onde começar

Todos os valores são em centavos, como inteiros (15000 = R$ 150,00), e a moeda é o real (BRL). Todos os exemplos desta documentação usam dados de teste.