Prepare a sua primeira integração.

01 / Preparação

Defina o contexto da operação.

Configure a organização e a conta Stripe conectada, incluindo o onboarding e as capacidades necessárias aos meios de pagamento. Combine com a equipe a URL da API e o ambiente em que você vai testar.

As operações financeiras usam o prefixo /v2/organizations/{organizationId}/stripe. A conta conectada é selecionada pelo servidor; o cliente não precisa informar um cabeçalho Stripe-Account.

02 / Autenticação

Uma chave para os acessos necessários.

Um proprietário ou administrador pode criar uma chave para a organização. Armazene o valor completo no servidor no momento da criação; as consultas posteriores exibem somente o valor mascarado.

Envie a chave em x-api-key ou como Bearer no cabeçalho Authorization. Escolha uma forma por requisição. O acesso depende da organização, validade e permissões da chave.

curl --get \
  "$ADILA_PAY_BASE_URL/v2/organizations/$ORGANIZATION_ID/stripe/customers" \
  --data-urlencode "limit=10" \
  --header "x-api-key: $ADILA_PAY_API_KEY"

Antes de usar o exemplo, configure as três variáveis no seu servidor. Nunca exponha a chave no frontend ou nos logs.

03 / Checkout

Crie uma sessão para a venda.

Prepare produtos e preços na conta conectada. Crie a sessão em POST /v2/organizations/{organizationId}/stripe/checkout/sessions, com mode igual a payment ou subscription e os itens em line_items.

A criação exige payments:write; o modo de assinatura também exige subscriptions:write. Use os preços da organização e direcione o cliente à URL da sessão retornada.

Nas mutações, envie Idempotency-Key. Gere e persista uma chave por operação lógica e reutilize o mesmo valor nas tentativas dessa operação. Prepare o tratamento de erros e resultados pendentes.

04 / Confirmação

O retorno ao site é só uma etapa.

Consulte a sessão de checkout e o pagamento correspondente pela API antes de marcar o pedido como pago. Para assinaturas, considere também o estado da assinatura e das faturas ao decidir sobre o acesso.

O envio de webhooks para sistemas integradores ainda não está disponível. Combine uma estratégia de consulta e atualização com a equipe; os eventos recebidos internamente do provedor não são notificações para o seu backend.