Demo ao vivo

API de pagamento para viagens

API de gateway de pagamento para reservas de viagem: do checkout ao estorno

Uma API de gateway de pagamento é o que permite ao seu site de reservas receber o dinheiro do viajante sem nunca tocar no cartão. Esta página mostra as chamadas de um pagamento com cartão, os status pelos quais ele passa, o que torna os pagamentos de viagem mais difíceis que os do varejo e como o PHPTRAVELS conecta o seu fluxo de reserva ao gateway que você escolher.

  • Sessão, 3-D Secure, captura
  • Todos os status de pagamento
  • Cartões, carteiras, banco, crédito
  • Nenhum dado de cartão no seu servidor

Como as chamadas funcionam

Um pagamento com cartão, chamada por chamada

Uma API de gateway de pagamento é um conjunto de serviços web que uma empresa de pagamentos abre aos lojistas. Seu servidor pede a criação de um pagamento com valor e moeda, o viajante digita o cartão no formulário do próprio gateway, e o gateway conversa com a bandeira e com o banco emissor. Seu servidor nunca vê o número do cartão; ele recebe de volta um ID de pagamento e um status.

Quatro partes participam. O diagrama mostra cada uma como uma coluna e cada mensagem como uma seta numerada. Os nomes mudam de um gateway para outro (payment intent, sessão, pedido, cobrança), mas a sequência é a mesma.

Um viajante pagando uma viagem online enquanto um site de reservas, um gateway de pagamento e um banco trocam mensagens de pagamento

A seta tracejada é um webhook: o gateway chama o seu servidor por conta própria, de modo que o pagamento ainda atualiza a reserva mesmo que o viajante feche o navegador. A página Integração de gateways de pagamento explica como cada etapa é vinculada a uma reserva no PHPTRAVELS.

  • Viajante
  • Seu site
  • Gateway
  • Bandeira / banco

  1. 01CheckoutViajante Seu site

    O viajante revisa a viagem e clica em Pagar. A reserva fica retida no fornecedor, ainda sem confirmação.

  2. 02Criar payment intent ou sessãoSeu site Gateway

    Seu servidor envia valor, moeda, referência da reserva e uma chave de idempotência com a chave secreta da API. O gateway devolve um ID de pagamento.

  3. 03Campos hospedados ou redirecionamentoGateway Viajante

    O formulário do cartão é servido pelo gateway, dentro da sua página ou em uma página própria, e os dados do cartão vão direto para ele.

  4. 043-D SecureBandeira / banco Viajante

    Se o banco emissor exigir, o viajante confirma o pagamento no app do banco ou com um código de uso único.

  5. 05AutorizarGateway Bandeira / banco

    O gateway pede ao emissor, pela bandeira do cartão, que aprove o valor.

  6. 06Aprovado, valor retidoBandeira / banco Gateway

    O emissor reserva o dinheiro no cartão. Nada foi movimentado ainda.

  7. 07Resultado para o seu siteGateway Seu site

    O viajante volta ao seu site com o ID do pagamento. Seu servidor lê o status na API e confirma a reserva com o fornecedor.

  8. 08CapturaSeu site Gateway

    Quando o fornecedor confirma, seu servidor captura o valor total ou um valor menor. Muitos gateways também podem capturar na hora.

  9. 09WebhookGateway Seu siteEnviado pelo gateway por conta própria

    O gateway envia um evento assinado (pagamento capturado, estornado, contestado) ao seu endpoint. Seu servidor confere a assinatura e atualiza a reserva.

Status do pagamento

A vida de um pagamento como máquina de estados

Toda API de gateway informa um status para cada pagamento. As palavras variam, mas correspondem aos mesmos poucos estados, e a lógica da sua reserva deve reagir a cada um deles.

  1. created

    Criado

    O pagamento existe com valor e moeda, aguardando o viajante.

    failedFinal

    Falhou

    Recusado, 3-D Secure não concluído ou abandonado. Nada é cobrado.

  2. authorized

    Autorizado

    O emissor aprovou o valor e o mantém retido no cartão.

    voidedFinal

    Cancelado

    A retenção é cancelada antes da captura, então o viajante nunca é cobrado.

  3. captured

    Capturado

    O dinheiro foi cobrado e será liquidado na sua conta de lojista.

    partially_refundedFinal

    Parcialmente estornado

    Parte do valor capturado é devolvida, por exemplo após uma taxa de cancelamento.

    refundedFinal

    Estornado

    Todo o valor capturado é devolvido ao cartão.

Uma autorização não dura para sempre: se não for capturada a tempo, a retenção expira e o banco libera o dinheiro. Um pagamento parcialmente estornado ainda pode ser estornado de novo, até o valor capturado.

Por que viagem é mais difícil

Por que os pagamentos de viagem são diferentes

Uma loja vende o que tem em estoque. Um vendedor de viagens recebe por uma reserva que o fornecedor ainda precisa confirmar, muitas vezes meses antes da viagem. A API de pagamento precisa se adaptar a isso.

  • 01

    Autorizar agora, capturar depois

    Hotéis sob consulta, tarifas de grupo e passeios são confirmados horas ou dias depois do pedido. Autorizar primeiro e capturar na confirmação evita cobrar por uma reserva que não acontece.

  • 02

    O fornecedor ainda pode recusar

    Uma tarifa pode esgotar entre o pagamento e a emissão. Com uma autorização, o dinheiro é liberado com um cancelamento; depois da captura, vira um estorno.

  • 03

    Estornos parciais após taxas de cancelamento

    Cancelar uma hospedagem ou uma passagem normalmente mantém uma taxa. A chamada de estorno envia um valor menor contra o pagamento original, quantas vezes as regras exigirem.

  • 04

    Multimoeda

    Os viajantes pagam na sua moeda, enquanto os fornecedores faturam na deles. O gateway precisa aceitar a moeda de apresentação, e seus registros devem guardar os dois valores.

  • 05

    Verificações antifraude para valores altos

    Passagens para amanhã, para outra pessoa, pagas com um cartão novo, são um padrão clássico de fraude. 3-D Secure, a pontuação de risco do gateway e uma fila de revisão manual protegem os pedidos de alto valor.

  • 06

    Chargebacks meses depois

    As contestações costumam chegar depois da viagem. Guarde juntos o resultado da autenticação, os documentos da reserva e os eventos do gateway, para responder a cada uma com provas.

Meios de pagamento

Quais formas de pagamento uma API de gateway de pagamento cobre

Cartões são apenas uma opção. Viajantes e agentes pagam de maneiras diferentes, e cada uma é estornada de um jeito.

MeioO que éQuando o dinheiro chegaEstornos
CartõesCartões de débito e crédito pelo gateway, com 3-D Secure quando o emissor exige.Autorizado no checkout; capturado na hora ou quando o fornecedor confirma.Estorno total ou parcial para o mesmo cartão pela API.
Carteiras digitaisContas de carteira aceitas pelo gateway, como PayPal ou uma carteira de celular com cartão tokenizado.No checkout, depois que o viajante aprova na carteira.De volta à carteira ou ao cartão vinculado, pelo gateway.
Transferência bancáriaO viajante ou o agente envia o dinheiro para a sua conta bancária e o pagamento é registrado na reserva.Dias depois; a reserva aguarda até sua equipe confirmar o recebimento.Devolvido por transferência, fora do gateway.
Pagar depoisA reserva é feita agora e paga depois; sua equipe registra o pagamento quando ele chega.Após a reserva, quando o viajante paga.Só é devolvido o que foi realmente pago.
Carteira ou crédito de agente B2BSubagentes pagam com um saldo que financiam antecipadamente ou com um limite de crédito concedido por você.Debitado na reserva; depósitos e crédito liquidados conforme os seus termos.Creditado de volta no saldo do agente.

Transferência bancária, pagar depois e saldo da carteira são formas de liquidação da própria plataforma, não gateways. Saldos e limites de crédito de agentes estão na página Carteira B2B para agentes; pagamentos bancários, na página Pagamentos por transferência.

Pronto no PHPTRAVELS

APIs de gateway de pagamento já conectadas

Esses gateways já estão conectados ao PHPTRAVELS. Você abre uma conta de lojista no provedor, informa as chaves de API no admin, testa no sandbox e entra em produção. A lista é a ativa do nosso diretório de integrações.

Taxas e aprovação do lojista são combinadas com a empresa de pagamentos, não com o PHPTRAVELS. Um gateway que não está aqui pode ser adicionado como Integração de API personalizada, e a página Integração de gateways de pagamento explica como cada um é configurado.

Segurança

Mantendo os dados do cartão fora do seu sistema

O número de cartão mais seguro é aquele que o seu servidor nunca recebe. Uma API de gateway de pagamento foi feita para que isso não seja necessário.

  • Nunca armazene números de cartão

    Os dados do cartão vão para o gateway, que devolve um token ou um ID de pagamento. Seu banco de dados guarda essa referência, nunca o número do cartão nem o código de segurança.

  • Campos hospedados e redirecionamentos reduzem o escopo PCI DSS

    O PCI DSS se aplica a quem manipula dados de cartão. Quando o formulário do cartão é a página do gateway ou campos incorporados, muito menos do seu sistema entra no escopo. Seu adquirente confirma qual autoavaliação se aplica a você.

  • Webhooks verificados por assinatura

    Cada webhook traz uma assinatura feita com um segredo compartilhado. Seu servidor a recalcula e rejeita qualquer evento que não corresponda, para que ninguém possa forjar uma reserva paga.

  • Chaves secretas ficam no servidor

    O navegador recebe apenas uma chave pública. A chave secreta que cria pagamentos e estornos fica na configuração do seu servidor, e cada requisição leva uma chave de idempotência para que uma nova tentativa nunca cobre duas vezes.

webhook.php
 1$payload   = file_get_contents("php://input"); 2$signature = $_SERVER["HTTP_X_SIGNATURE"] ?? ""; 3$expected  = hash_hmac("sha256", $payload, $webhookSecret); 4 5if (!hash_equals($expected, $signature)) { 6    http_response_code(400); exit;      // reject 7} 8$event = json_decode($payload, true); 9if (alreadyHandled($event["id"])) exit; // repeat delivery10updateBooking($event["data"]["metadata"]["booking_ref"], $event["type"]);

Exemplo genérico. Os nomes dos cabeçalhos e o método de assinatura seguem o gateway que você escolher.

O PHPTRAVELS é um software auto-hospedado, então a conformidade com o PCI DSS é avaliada para o seu negócio e o seu servidor, não apenas para o software.

Veja uma reserva paga, capturada e estornada

Faça uma reserva na demo ao vivo e acompanhe o pagamento no admin. No plano Enterprise, o PHPTRAVELS também oferece a sua própria REST API e webhooks para seus apps e parceiros.

Vai vender voos também? A página API de voos explica o lado do fornecedor, e APIs de viagens lista todas as APIs que o PHPTRAVELS conecta.

Testar a demo ao vivoComparar planosLer a documentação para desenvolvedores

FAQ

API de gateway de pagamento: dúvidas de quem vende viagens

Fale com vendas

É um conjunto de serviços web que uma empresa de pagamentos oferece para que um site crie pagamentos, envie o cartão ao banco para aprovação, capture o dinheiro, faça estornos e receba atualizações de status por webhook, sem armazenar dados de cartão.

O gateway é a parte com a qual o seu site conversa: ele coleta o cartão com segurança e repassa o pedido. A processadora leva a transação pelas bandeiras até o banco emissor. Muitos provedores oferecem os dois como um único serviço.

A que aprova o seu negócio, atende os países, moedas e meios de pagamento dos seus clientes e oferece autorização e captura separadas, além de estornos parciais. Muitas agências combinam um gateway global de cartões com um regional.

Autorizar reserva o valor no cartão do viajante; capturar efetivamente o cobra. Separar os dois permite cobrar só quando o fornecedor confirma a reserva e cancelar a retenção se ele não confirmar.

Em muitas regiões, incluindo o Espaço Econômico Europeu e o Reino Unido, a autenticação forte do cliente é exigida na maioria dos pagamentos online com cartão, e o 3-D Secure é como os cartões a cumprem. A API do gateway trata o desafio; seu fluxo de reserva aguarda o resultado.

Não por si só. Usar os campos hospedados ou a página de pagamento do gateway mantém os dados do cartão fora do seu servidor e reduz o escopo do PCI DSS, mas você ainda precisa concluir a avaliação que o seu adquirente solicitar.

Sim, se o gateway aceitar estornos parciais, o que a maioria dos gateways de cartão faz. Você envia um estorno de valor menor contra o pagamento original, por exemplo o preço menos uma taxa de cancelamento.

Não. Você abre uma conta de lojista no gateway que escolher e combina as taxas com ele. O PHPTRAVELS conecta a sua plataforma de reservas a essa conta com as chaves de API que você informa no admin.

Sim. Qualquer gateway com API documentada pode ser adicionado como integração personalizada e, como o código-fonte está incluído, seus desenvolvedores também podem estender o fluxo de pagamento.

Continue a explorar

Mais sobre a plataforma