Demo ao vivo

Pagamentos para software de viagens

Integração com a API da Paddle: quando um merchant of record serve a um negócio de viagens

A Paddle vende software, SaaS e produtos digitais em seu nome, como merchant of record. Isso a torna ideal para uma empresa de tecnologia de viagens que cobra as próprias assinaturas e, em geral, a ferramenta errada para receber por voos, hotéis e passeios. Esta página explica a diferença, como funciona uma integração com a Paddle e como conectá-la ao PHPTRAVELS quando o seu caso se encaixa.

  • Merchant of record, não um gateway
  • Feita para software e assinaturas
  • Webhooks assinados
  • Conectada como integração personalizada

Dois modelos diferentes

Merchant of record x gateway de pagamento

Um gateway de pagamento movimenta o dinheiro por você: você é o vendedor, a empresa de pagamentos processa o cartão e impostos, notas fiscais, reembolsos e disputas continuam sendo sua responsabilidade. Um merchant of record vai um passo além e passa a ser o vendedor aos olhos do cliente e das autoridades fiscais. Quando alguém compra pela Paddle, é a Paddle que vende, cobra e repassa o imposto sobre vendas ou o IVA, emite a fatura, trata os estornos e depois paga a sua parte.

Esse modelo poupa muito trabalho fiscal e de conformidade a uma empresa de software, mas também significa que a Paddle decide o que aceita revender. A plataforma foi feita para software, SaaS e produtos digitais, não para serviços de viagem prestados por companhias aéreas, hotéis e operadoras de turismo. A mecânica geral dos pagamentos com cartão está na página API de gateway de pagamento.

Diagrama de um fluxo de pagamento em que um cliente paga online enquanto as responsabilidades de pagamento, imposto e repasse passam entre um vendedor e um provedor de pagamentos
PerguntaPaddle (merchant of record)Gateway de pagamento
Quem é o vendedor?A Paddle é o vendedor oficial. O recibo e a fatura do cartão do cliente vêm do lado da Paddle na venda.Você é o vendedor. O gateway apenas processa o pagamento na sua conta de lojista.
Quem cuida do imposto sobre vendas e do IVA?A Paddle calcula, cobra e repassa o imposto sobre vendas e o IVA nos locais onde vende.Você, com seus próprios registros fiscais, contador e emissão de faturas.
Quem emite a fatura?A Paddle emite a fatura ou o recibo para o comprador.O seu sistema emite, por exemplo a fatura da reserva no seu admin.
Quem trata os estornos?A Paddle lida com disputas e estornos como vendedora.Você responde às disputas com provas, pelo painel ou pela API do gateway.
O que você pode vender?Software, SaaS, assinaturas e produtos digitais, dentro das regras de uso aceitável da Paddle.Vendas de produtos físicos e serviços aprovadas pelo gateway, incluindo reservas de viagem para muitos lojistas do setor.
Como você recebe?A Paddle repassa seus ganhos após descontar as taxas, conforme o calendário de repasses dela.Os pagamentos capturados são liquidados na sua conta de lojista ou bancária, menos as taxas do gateway.

Taxas, países atendidos e a lista exata de produtos permitidos são definidos pela Paddle e mudam com o tempo. Consulte os termos da própria Paddle antes de contar com ela.

Guia de decisão

A Paddle serve para o que você vende?

Comece pelo que o cliente está pagando. Escolha o cenário mais próximo do seu negócio.

01

Viajantes pagam por voos, hotéis e passeios

O cliente está comprando uma viagem prestada por uma companhia aérea, um hotel ou uma operadora. Esses pagamentos costumam exigir autorizar agora e capturar depois, reembolsos parciais após taxas de cancelamento e checkout em várias moedas.

Nossa visão

Use um gateway de pagamento

Confira as regras de uso aceitável da Paddle antes de usá-la para reservas de viagem. A maioria dos negócios de viagem recebe as reservas por um gateway de pagamento como Stripe, PayPal, Adyen ou um gateway regional.

02

Você vende o seu próprio software de viagens ou SaaS

Você é um fornecedor de tecnologia de viagens e as agências pagam uma assinatura mensal ou anual pela sua ferramenta de reservas, acesso à API, um plugin ou um portal white label.

Nossa visão

A Paddle pode servir

É o tipo de venda para o qual um merchant of record foi criado: a Paddle cobra a assinatura, trata o imposto de cada país e repassa o valor a você, sem que precise se registrar para IVA em todo lugar onde estão seus clientes.

03

Você vende reservas e software

Sua agência mantém um site de reservas para viajantes e também licencia a plataforma ou as ferramentas para outras agências.

Nossa visão

Use os dois, separados

Receba as reservas por um gateway pronto no fluxo de reserva e cobre as assinaturas de software pela Paddle. Dois fluxos, dois conjuntos de registros, cada um com o tratamento fiscal correto.

Como funciona

Como funciona uma integração com a Paddle, de ponta a ponta

O Paddle Billing trabalha com produtos e preços criados na Paddle, um checkout aberto pelo Paddle.js e webhooks que avisam o seu servidor do que aconteceu.

  1. 01

    Produtos e preços

    Você cria cada plano uma vez na Paddle, por exemplo um preço mensal e um anual, e guarda os IDs de preço no seu sistema.

    pri_…

  2. 02

    Checkout do Paddle.js

    Sua página carrega o Paddle.js e abre o checkout como overlay ou frame embutido, com o ID do preço e a sua referência do cliente.

    Paddle.Checkout.open()

  3. 03

    Transação concluída

    O comprador paga, a Paddle cobra o cartão ou a carteira, aplica o imposto e cria uma transação, e uma assinatura quando o preço é recorrente.

    txn_…

  4. 04

    Webhook assinado

    A Paddle envia um evento como transaction.completed ao seu endpoint, assinado no cabeçalho Paddle-Signature.

    transaction.completed

  5. 05

    Seu sistema age

    Seu servidor verifica a assinatura e então ativa a conta, renova o plano ou registra o pagamento.

    200 OK

Mantenha a chave de API somente no servidor. O navegador usa um token de cliente separado, e os ambientes sandbox e produção têm cada um suas chaves, preços e segredos de webhook.

Segurança de webhooks

Verificando o cabeçalho Paddle-Signature

Qualquer pessoa que conheça a URL do seu endpoint pode forjar um webhook. Verificar a assinatura de cada evento é o que torna seguro ativar uma conta a partir de um webhook.

paddle-webhook.php
 1$raw    = file_get_contents("php://input"); 2$header = $_SERVER["HTTP_PADDLE_SIGNATURE"] ?? "";  // ts=…;h1=… 3parse_str(str_replace(";", "&", $header), $sig); 4 5$expected = hash_hmac("sha256", $sig["ts"] . ":" . $raw, $endpointSecret); 6if (!hash_equals($expected, $sig["h1"] ?? "")) { 7    http_response_code(400); exit;            // not from Paddle 8} 9if (time() - (int) $sig["ts"] > $tolerance) exit; // too old1011$event = json_decode($raw, true);12if (alreadyHandled($event["event_id"])) exit;      // repeat delivery13if ($event["event_type"] === "transaction.completed") {14    activatePlan($event["data"]["custom_data"]["account_id"]);15}16http_response_code(200);

Exemplo ilustrativo em PHP puro. Siga a documentação atual da Paddle, ou o SDK oficial, para o formato exato.

  1. 01

    Use o corpo bruto

    A assinatura é calculada sobre o corpo da requisição exatamente como recebido; leia-o antes que qualquer parse de JSON o altere.

  2. 02

    Timestamp mais hash

    O cabeçalho traz um timestamp e um hash HMAC-SHA256 feito com a chave secreta do endpoint. Refaça o cálculo e compare em tempo constante.

  3. 03

    Rejeite eventos antigos e repetidos

    Recuse eventos com timestamp muito antigo e guarde o ID de cada evento para que uma entrega repetida não seja processada duas vezes.

  4. 04

    Sandbox primeiro

    Desenvolva e teste no sandbox da Paddle com cartões de teste e depois troque as chaves, os preços e o segredo para produção.

PHPTRAVELS e Paddle

Conectando a Paddle ao PHPTRAVELS

Primeiro uma resposta honesta, depois as opções.

A Paddle não é um conector pronto

A Paddle não está na lista de gateways de pagamento do PHPTRAVELS e não tem guia de configuração publicado. Os gateways prontos, mostrados abaixo, são os feitos para receber pagamentos de reservas.

Pergunte sobre uma integração personalizadaExperimente a demo de reservas

  • Para pagamentos de reservas: um gateway pronto

    Ative um gateway pronto como Pagamentos com Stripe ou Pagamentos com PayPal no admin com a sua própria conta de lojista. Checkout, reembolsos e a referência da reserva já estão integrados ao fluxo de reserva, como explica a página Integração de gateways de pagamento.

  • Para vendas de software: a Paddle como integração personalizada

    Quando o seu caso se enquadra nas regras da Paddle, nossos desenvolvedores podem conectá-la como Integração de API personalizada: checkout do Paddle.js na sua página, um endpoint de webhook verificado e pagamentos registrados nos seus clientes. O trabalho é orçado antes de começar.

  • Ou construa você mesmo sobre o código-fonte

    O PHPTRAVELS é auto-hospedado e vem com o código-fonte completo, então seus próprios desenvolvedores podem adicionar a Paddle para assinaturas ao lado do motor de reservas. A página Preços lista o que cada licença inclui.

Prontos para pagamentos de reservas

Gateways de pagamento já conectados ao PHPTRAVELS

Para pagamentos de viajantes e agentes, estes gateways estão prontos: você abre uma conta no provedor, informa as chaves no admin, testa e entra em produção. A lista é a ativa do nosso diretório de integrações.

Subagentes também podem pagar com saldo pré-pago ou limite de crédito pela Carteira B2B para agentes, que dispensa qualquer gateway.

FAQ

Integração com a API da Paddle: perguntas frequentes

Fale com vendas

Não como conector pronto. A Paddle não está na lista de gateways de pagamento do PHPTRAVELS. Se o seu caso se enquadra nas regras da Paddle, por exemplo vender assinaturas do seu próprio software, ela pode ser adicionada como integração personalizada ou construída pelos seus desenvolvedores sobre o código-fonte incluído.

A Paddle é um merchant of record feito para software, SaaS e produtos digitais, então em geral não é a ferramenta para voos, hotéis ou passeios. Confira as regras de uso aceitável da Paddle antes de usá-la para reservas de viagem; a maioria dos negócios de viagem recebe as reservas por um gateway de pagamento como Stripe, PayPal, Adyen ou um gateway regional.

A empresa que vende legalmente ao cliente. Ela é responsável por cobrar e repassar o imposto sobre vendas ou o IVA, emitir faturas, tratar reembolsos e estornos, e aparece na fatura do cliente. Com a Paddle, é ela quem assume esse papel e depois paga você.

Um gateway processa pagamentos para você, que continua sendo o vendedor e fica com o trabalho de impostos e disputas. A Paddle se torna o próprio vendedor, o que elimina esse trabalho nas vendas de software, mas limita o que você pode vender por ela.

Quando você vende o seu próprio software em vez de viagens: uma ferramenta de reservas, uma API, um plugin ou um portal white label que as agências pagam por assinatura. A Paddle cobra e cuida do imposto em cada país.

A Paddle envia eventos, como uma transação concluída ou uma assinatura renovada, para uma URL que você registra. Cada requisição traz um cabeçalho Paddle-Signature com timestamp e hash, que o seu servidor confere com a chave secreta do endpoint antes de agir.

Sim. A Paddle tem um ambiente sandbox separado, com conta, chaves de API, preços e cartões de teste próprios. Desenvolva e teste nele e depois leve a configuração para o ambiente de produção.

Sim, como dois fluxos separados: o motor de reservas recebe os pagamentos dos viajantes por um gateway pronto, e a Paddle cobra as assinaturas do seu software. Mantenha os registros separados para que cada venda tenha o tratamento fiscal correto.

Continue a explorar

Mais sobre a plataforma