Fluxo de integração
Como a sua plataforma, o comprador e o PrincipiaPay interagem do onboarding até a venda confirmada.
A integração tem 3 grandes passos:
Validar o token e configurar os webhooks. Chame GET /seller para confirmar o token e cadastre sua URL de eventos com POST /webhooks. Veja Autenticação e Webhooks.
Criar um checkout. Quando o comprador decide pagar com o PrincipiaPay, sua plataforma chama POST /sales e redireciona o comprador para a checkoutUrl devolvida (ou embute o checkout na sua página). Veja Checkout.
Receber os eventos. O PrincipiaPay envia um evento para a sua URL a cada mudança relevante da venda (pagamento gerado, compra confirmada, cancelamento etc.). Sua plataforma atualiza a venda a partir desses eventos.
Fluxo de onboarding
Em amarelo, o que o cliente (parceiro) faz; em azul, o PrincipiaPay; em verde, a plataforma que integra a API.
Fluxo da venda
- O comprador acessa o checkout da sua plataforma, preenche os dados e escolhe pagar com o PrincipiaPay.
- Sua plataforma cria a venda com
POST /sales. O PrincipiaPay confere se o produto e a variação existem pelos SKUs e cadastra o que faltar. - O PrincipiaPay devolve a
checkoutUrl. Sua plataforma guarda os dados da venda (saleId) e redireciona o comprador. - O comprador conclui o checkout e vê a tela final do PrincipiaPay. O comprador só volta automaticamente para o seu site quando o checkout está embutido em um iframe com
redirectUrl; o camporeturnUrldePOST /salesnão é usado hoje. - O PrincipiaPay envia os eventos de webhook, e sua plataforma atualiza a venda.
Não dependa só do redirecionamento
Nem todo pagamento é confirmado na hora (boleto, por exemplo). A fonte de verdade sobre o estado da venda são os eventos de webhook, não a volta do comprador para o seu site.