API amigável para programadores
A API da Cardflo foi projetada a pensar nos programadores, priorizando a facilidade de uso, documentação abrangente e funcionalidade robusta. Isso garante um processo de integração suave, permitindo que a sua equipa implemente e gira soluções de pagamento rapidamente.
Concentre-se na inovação, não nos desafios de integração.
- Categoria
- Programador
- Funcionalidades
- 10
- Disponível em
- Todos os planos
A visão geral
Uma API amigável para programadores serve como a interface principal entre a infraestrutura digital de um comerciante e o ecossistema de pagamentos mais amplo. No setor B2B, isso significa fornecer endpoints RESTful que permitem a execução programática de autorizações, capturas e reembolsos.
A arquitetura deve contabilizar estruturas de dados complexas exigidas por transações Card-Not-Present, incluindo metadados 3DS e detalhes de compra de Nível 2 ou Nível 3.
Um design de API eficaz prioriza pedidos idempotentes para evitar transações duplicadas e utiliza códigos de status HTTP padrão para comunicar o estado de um pedido.
Além do simples processamento de pagamentos, essas interfaces facilitam a gestão de agendamentos de faturamento recorrente, armazenamento de credenciais tokenizadas e a recuperação de relatórios de liquidação.
Ao integrar-se diretamente no nível da API, as empresas podem manter o controlo total sobre a experiência de checkout, enquanto delegam o tratamento de dados sensíveis para um ambiente compatível com PCI-DSS.
Essa abordagem estrutural reduz a dívida técnica e garante que os sistemas de backend permaneçam sincronizados com o livro-razão do adquirente.
Como funciona
Autenticação e Segurança de Credenciais
A integração começa com a autenticação de pedidos usando chaves secretas ou tokens OAuth transmitidos via TLS. Os programadores configuram webhooks para receber notificações assíncronas para eventos como liquidações bem-sucedidas ou inícios de disputas.
Isso garante que a base de dados interna do comerciante permanece alinhada com o estado de cada transação sem sondagens constantes do servidor.
Construção e Validação de Pedidos
Os programadores constroem cargas JSON contendo valores de transação, códigos de moeda e detalhes do instrumento de pagamento. A API valida estas entradas em relação aos requisitos do esquema antes de tentar a autorização.
Erros de validação detalhados são retornados imediatamente se campos obrigatórios, como o CVV ou o nome do titular da conta, estiverem ausentes ou formatados incorretamente para o MCC específico.
Idempotência e Teste de Resiliência
Para lidar com a instabilidade da rede, a API emprega chaves de idempotência. Se um pedido for repetido devido a um tempo limite, o sistema reconhece a chave única e retorna a resposta original em vez de criar uma cobrança duplicada.
Esta lógica é tipicamente verificada num ambiente de sandbox usando códigos de resposta simulados para vários cenários.
Tratamento de Respostas e Mapeamento de Erros
Ao receber uma resposta do emissor, a API mapeia códigos de resposta bancários complexos em categorias padronizadas e acionáveis.
Os programadores usam esses códigos categorizados para acionar fluxos de trabalho específicos, como solicitar ao utilizador um método de pagamento diferente após uma recusa 'hard' ou iniciar um desafio 3DS para uma recusa 'soft'.
Por que importa
Latência de Integração Reduzida
APIs bem estruturadas com documentação abrangente e SDKs nativos permitem que as equipas de engenharia passem da configuração inicial para um ambiente de teste funcional num período de tempo mais curto.
Ao fornecer definições claras para cada endpoint e campo, a necessidade de perguntas e respostas de suporte é minimizada.
Essa eficiência garante que a lógica de pagamento possa ser implementada juntamente com os recursos principais do produto, sem se tornar um gargalo para o ciclo de desenvolvimento mais amplo.
Estabilidade Operacional e Depuração
Registos detalhados e mensagens de erro transparentes são críticos para manter alta disponibilidade em ambientes de produção.
Quando uma API fornece feedback granular sobre o motivo de uma transação ter falhado, como restrições específicas relacionadas com o BIN ou requisitos SCA, os programadores podem automatizar a resposta apropriada.
Isso reduz a sobrecarga manual para as equipas financeiras e de suporte que, de outra forma, precisariam de investigar motivos de recusa vagos através de um portal adquirente.
Arquitetura de Pagamento Escalável
À medida que uma empresa se expande para novos mercados ou adota novos modelos de negócio, uma API flexível permite a adição de métodos de pagamento alternativos e suporte multi-moeda sem reescrever toda a integração.
Objetos padronizados para clientes, subscrições e métodos de pagamento permitem que os programadores construam sistemas modulares que podem adaptar-se a requisitos regulamentares em evolução, como a PSD3, ou a regras de esquema em mudança da Visa e Mastercard.
Casos de uso
Escalabilidade de Assinaturas SaaS
As equipas técnicas de empresas SaaS usam a API para automatizar ciclos de cobrança complexos e atualizações de assinatura. O acesso programático ao vault permite mudanças de faturação contínuas à medida que os clientes mudam de níveis.
Automação de Pagamentos em Marketplaces
As plataformas de marketplace integram APIs para dividir pagamentos entre vendedores e calcular comissões em tempo real. Isso garante que os subcomerciantes verificados por KYB recebam os pagamentos de acordo com os seus termos contratuais específicos.
Checkout Móvel Personalizado
Os programadores móveis usam SDKs específicos para construir fluxos de checkout personalizados que acionam a autenticação 3DS nativamente. Isso mantém a consistência da marca, garantindo que os dados sensíveis do cartão nunca toquem nos próprios servidores do comerciante.
Sincronização do Sistema ERP
Grandes empresas conectam os seus sistemas ERP diretamente à API de pagamentos para automatizar a reconciliação bancária. Os metadados das transações são usados para fechar faturas em aberto automaticamente após receber uma notificação de liquidação.
Em números
Ganhos de eficiência típicos relatados por equipas de engenharia ao mudar de interfaces SOAP legadas para APIs RESTful modernas com SDKs abrangentes.
O benchmark padrão da indústria para a sobrecarga da gateway por pedido, excluindo atrasos na rede a jusante introduzidos pelas redes de cartão e bancos emissores.
A taxa de fiabilidade observada para evitar transações duplicadas em ambientes de alto volume onde novas tentativas de rede são comuns.
Termos relacionados
Talk to our team about a live rollout on your acquiring stack.
O que obtém com API amigável para programadores
- Arquitetura RESTful abrangente para URLs orientados a recursos previsíveis e uso de métodos HTTP padrão.
- SDKs nativos para Python, Node.js e Java para acelerar a integração e manutenção do lado do servidor.
- Ambientes de sandbox isolados para testes rigorosos de casos extremos sem afetar dados financeiros em tempo real.
- Notificações granulares de webhook para atualizações em tempo real sobre estornos, reembolsos e eventos de liquidação bem-sucedidos.
- Suporte ao cabeçalho de idempotência para evitar transações duplicadas durante falhas intermitentes de conexão de rede.
- Documentação abrangente com exemplos de código, descrições de campo e ferramentas interativas de explorador de API.
- Objetos de erro padronizados com códigos específicos e mensagens legíveis para uma resolução rápida de problemas.
- Versões da API para garantir a compatibilidade retroativa e a migração controlada para novas funcionalidades.
- Endpoints de tokenização compatíveis com PCI para minimizar o âmbito de auditorias e avaliações de segurança anuais.
- Suporte para campos de metadados personalizados para facilitar a reconciliação com ferramentas internas de business intelligence.
A short scoping call, then a written plan for your MIDs.
Perguntas sobre API amigável para programadores
Como a API lida com os requisitos de Autenticação Forte do Cliente (SCA) sob a PSD2?
A API foi projetada para suportar os protocolos 3-D Secure, incluindo sinalizadores específicos no pedido de autorização. Quando uma transação requer autenticação, a API retorna uma resposta indicando que um desafio é necessário.
O programador então redireciona o utilizador para a página de autenticação do emissor ou usa um SDK para lidar com o desafio dentro da aplicação. Uma vez autenticada, o processo de transação continua.
Esta lógica garante a conformidade com os regulamentos regionais, minimizando o atrito para o utilizador final, acionando a SCA apenas quando exigido pelas regras do emissor ou do esquema.
Qual é o papel das chaves de idempotência nas integrações de pagamento B2B?
As chaves de idempotência são identificadores únicos enviados no cabeçalho de um pedido POST. O seu propósito principal é garantir que uma operação seja realizada apenas uma vez, mesmo que o pedido seja reenviado várias vezes.
Em ambientes B2B onde os valores das transações são altos, isso evita a dupla cobrança acidental devido a tempos limite de rede ou atualizações do navegador.
Se a API receber um segundo pedido com a mesma chave de idempotência, ela retornará o resultado armazenado do primeiro pedido bem-sucedido, em vez de tentar autorizar o pagamento novamente.
Podemos gerir diferentes liquidações de moeda através de uma única ligação API?
Sim. A API suporta o processamento multi-moeda, permitindo que os programadores especifiquem o código da moeda na carga da transação.
Dependendo da sua configuração de adquirente e MID, o sistema pode processar transações numa moeda e liquidar noutra, ou fornecer liquidação idêntica.
A resposta da API incluirá tipicamente o valor da transação na moeda original e o valor convertido, se for necessária liquidação doméstica, permitindo que o seu software de contabilidade rastreie os impactos cambiais com precisão.
Como os códigos de erro são estruturados para fins de depuração?
Os erros são retornados usando códigos de status HTTP padrão combinados com um corpo JSON contendo um tipo e código de erro específico.
Por exemplo, um 400 Bad Request pode incluir um código para 'invalid_cvv', enquanto um 402 Payment Required pode indicar um evento 'card_declined' do emissor.
Esta hierarquia permite que os programadores distingam entre problemas de integração do lado do cliente, como parâmetros em falta, e problemas financeiros a jusante, como fundos insuficientes, permitindo o tratamento automático e específico de erros na interface do utilizador.
Que medidas de segurança protegem a API contra acessos não autorizados?
A segurança é mantida através de uma abordagem multi-camadas, começando com TLS 1. 2 obrigatório ou superior para toda a comunicação.
A autenticação é gerida através de chaves de API que devem ser restritas a chamadas do lado do servidor para evitar exposição no código do lado do cliente.
Adicionalmente, o whitelisting de IP pode ser configurado para endpoints sensíveis, e os webhooks são frequentemente assinados com uma assinatura criptográfica. Isto permite que o servidor do comerciante verifique se a notificação realmente se originou da gateway de pagamentos e não foi adulterada em trânsito.
A API suporta metadados personalizados para reconciliação?
A API permite a inclusão de objetos de metadados personalizados dentro de recursos de pagamento e cliente. Os programadores podem anexar identificadores internos, como números de fatura ou IDs de cliente de um CRM externo, ao registo da transação.
Estes metadados não são passados para os esquemas de cartão, mas permanecem associados à transação dentro da gateway e dos sistemas de relatórios. Isto facilita a reconciliação automatizada, pois estes identificadores podem ser recuperados via API ou incluídos em exportações CVS de liquidação programadas.
Funcionalidades relacionadas.
Pronto para a velocidade?
Fale-nos do seu negócio. Iremos apresentá-lo aos parceiros adquirentes e à rota certa, normalmente em menos de uma semana.