Esta página é uma tradução automática da página em inglês, que é a versão de referência. Ler a página em inglês
Pagamentos de apoiadores com PAY.JP
Com payments = payjp, os usuários locais assinam planos mensais ou anuais na página de pagamento deste servidor, e a função do plano é concedida e removida conforme muda o estado do pagamento. Quando as gorjetas estão ativadas, os usuários também pagam gorjetas únicas na página hospedada do PAY.JP (veja Gorjetas).
As chaves de implantação são descritas na referência de configuração. Para o programa como um todo (planos, funções, a lista de membros), veja supporters.md.
Um administrador ativa o programa e cria os planos na administração. Esta configuração apenas permite que o servidor se comunique com o PAY.JP.
Um servidor pode usar apenas um provedor. Para mudar do Stripe para o PAY.JP (ou o inverso), peça aos assinantes atuais que assinem de novo com o novo provedor.
O que o servidor faz no PAY.JP
Seção intitulada “O que o servidor faz no PAY.JP”O PAY.JP tem as APIs v1 e v2. A v2 ainda não tem API de cobrança recorrente, então o servidor usa a cobrança recorrente da API v1 (Plan e Subscription). A v1 não tem página de pagamento hospedada nem portal do cliente, então este servidor serve as páginas no lugar delas. As gorjetas são pagamentos únicos na API v2, que tem uma página de pagamento hospedada; veja Gorjetas. O PAY.JP permite as duas versões em uma conta com as mesmas chaves.
Como funciona uma assinatura mostra em um diagrama como se relacionam a página de pagamento, o webhook, a conciliação, a função do plano e a receita.
- Planos: Para cada preço, o servidor cria um Plan cujo ID é
my_<plan ID>_<month|year>_<amount>(metadata.my_plan_id). Um Plan do PAY.JP não pode mudar de valor, então mudar o valor cria um novo Plan, e o Plan antigo não é excluído, mas recebemetadata.my_archived=1. As assinaturas do Plan antigo são renovadas pelo valor dele. Não edite nem exclua esses Plans na administração do PAY.JP. A única moeda é o iene japonês, e os valores vão de 50 a 9.999.999 ienes. - Assinatura: O servidor envia o navegador do usuário para a sua própria página de pagamento (
/payments/pages/payjp/checkout). A página mostra os campos de cartão do payjp.js (o iframe do PAY.JP) e executa a autenticação 3-D Secure ao criar o token (o tipo iframe). O servidor aceita apenas um token cujo 3-D Secure foi concluído (three_d_secure_statuséverifiedouattempted), adiciona o cartão ao cliente como cartão padrão (na primeira vez, com o IDmy_<the server's subscription ID>) e cria uma assinatura com o ID de assinatura do servidor emmetadata.my_subscription_id. A primeira cobrança acontece na criação da assinatura. A URL da página tem curta duração e carrega um estado assinado pelo servidor (válido de 1 a 2 horas a partir da criação). Um usuário que sai da página e começa de novo, no mesmo plano ou em outro, recebe agora uma nova URL para o plano que pediu. Uma URL anterior continua funcionando até expirar, e a página que for paga primeiro gera a única assinatura: as outras passam a apontar para ela. Se uma página anterior já tiver sido paga, o usuário vai para a tela de retorno e não recebe uma nova URL. Uma URL assinada não pode ser retirada, então uma página continua pagável depois que a assinatura pendente dela é encerrada (o plano aposentado, a conta excluída). Um pagamento nela não compra nada: o servidor exclui a assinatura e reembolsa integralmente as suas cobranças (o PAY.JP aceita reembolso por 180 dias após a venda). A API v1 não aceita chave de idempotência, então, enquanto um envio da página cria a assinatura, o servidor marca o checkout como em andamento no banco de dados: um segundo envio (um clique duplo, outra aba ou outro processo do servidor atrás do mesmo load balancer) aguarda até 30 segundos e depois segue para a assinatura que o primeiro criou. A marca expira após 5 minutos se o processo que a detinha tiver parado. - Página do cartão e do histórico de pagamentos (no lugar do portal do cliente do Stripe): Na tela de assinatura, o assinante abre
/payments/pages/payjp/portalpara trocar o cartão e conferir os pagamentos recentes (a URL expira em uma hora). O formulário começa com o endereço de e-mail do cliente no PAY.JP, que é o endereço informado no primeiro pagamento, e não um endereço alterado depois na conta. Trocar o cartão retoma uma assinatura interrompida por um pagamento recusado e cobra na hora. Cancelar e trocar de plano são feitos na tela de assinatura deste servidor. - Falha de pagamento: O PAY.JP pausa (
paused) uma assinatura cuja cobrança de renovação falhou, e não tenta de novo. O servidor trata a pausa como um pagamento atrasado e mantém a função por um período de carência de 7 dias a partir do momento da pausa. Se o assinante trocar o cartão nesse período, a assinatura é retomada; se não, a função é removida após 7 dias (do lado do PAY.JP, a assinatura continua pausada e não é cobrada). - Mudanças de plano: Um upgrade cobra a diferença do restante do período atual, proporcional, como cobrança única (sem cobrança abaixo de 50 ienes), troca o plano e cobra o valor integral do novo plano no fim do período (o início do período não muda). Se a cobrança da diferença for recusada, o plano não muda.
Um downgrade, e a troca de anual para mensal, passam a valer no fim do período com
next_cycle_plan. - Ler o estado de volta: O servidor trata um webhook como um sinal e lê de volta a assinatura e as movimentações financeiras pela API do PAY.JP para decidir o estado.
Além disso, uma conciliação a cada
payments_reconcile_intervallê a lista de eventos, as movimentações financeiras e uma varredura de todas as assinaturas, e corrige qualquer webhook que o servidor tenha perdido. - Receita: Para cada pagamento, o servidor registra o valor bruto, a taxa (calculada a partir do
fee_rateda cobrança, arredondando para baixo abaixo de um iene) e o valor líquido. Um reembolso e um estorno registram a taxa devolvida como uma taxa negativa. Quando um período é encerrado e um extrato é emitido, a diferença entre a taxa do extrato e o cálculo do servidor (as taxas das cobranças das assinaturas e das gorjetas do período) é registrada como uma movimentação de taxa (o ID dela é o ID do extrato), de modo que o total de taxas do período bata com o extrato. Um extrato cobre as taxas de toda a conta, então use uma conta do PAY.JP dedicada a este servidor. - Datas: As datas de receita são contadas no horário do Japão.
O servidor envia no máximo 20 requisições por segundo (2 no modo de teste), somando as APIs v1 e v2. Isso fica dentro do limite de taxa do PAY.JP (para requisições com chave secreta, 30 por segundo no modo ao vivo e 2 no modo de teste). Diante de um 429, o servidor espera 1 segundo, dobrando a espera a cada tentativa, e tenta até 3 vezes.
No modo de teste, uma única conciliação é lenta (cerca de 8 minutos no limite de 1.000 requisições). Um job de continuação assume a tarefa, então nenhuma ação é necessária.
Gorjetas
Seção intitulada “Gorjetas”As gorjetas (veja supporters.md) usam a API v2 do PAY.JP com as mesmas chaves e o mesmo token de webhook das assinaturas. O PAY.JP lista as gorjetas entre os bens que considera difíceis de aprovar: se a sua conta pode receber gorjetas é algo que você deve resolver com o PAY.JP, de acordo com a análise e os termos dele.
- Pagamento: O servidor cria uma Checkout Session (
mode=payment) do valor único, apenas com cartão, que expira em uma hora, e envia o usuário à página dela no PAY.JP (uma páginahttpsempay.jp; o servidor recusa qualquer outro endereço). O ID da gorjeta no servidor está noclient_reference_idda sessão e emmetadata.my_tip_idda sessão e do seu PaymentFlow. A criação leva umaIdempotency-Key, então uma nova tentativa recebe a mesma sessão. O PAY.JP executa o 3-D Secure na página hospedada quando a empresa do cartão pede. Uma gorjeta está paga quando a sessão dela estácompletee o PaymentFlow dela foi bem-sucedido. Quando um usuário inicia outra gorjeta, o servidor primeiro expira a sessão aberta (POST /v2/checkout/sessions/{id}/expire); se o usuário a pagou nesse meio-tempo, esse pagamento é registrado no lugar. - Receita: O dinheiro das gorjetas vem das transações de pagamento da conta na API v2: um pagamento (o ID dele é o do PaymentFlow), um reembolso, um estorno e o cancelamento de um estorno, cada um com a taxa que o PAY.JP informa. Um reembolso e um estorno registram a taxa devolvida como uma taxa negativa, como nas assinaturas.
- Disputas: O PAY.JP envia um evento apenas quando uma disputa é aberta. Cada conciliação também lê as disputas encerradas a seu favor (status
cancel) e registra o cancelamento de um estorno que as transações de pagamento não informam por conta própria. Uma disputa encerrada sem estorno (uma consulta) não registra nada. - Reembolsos: Reembolse uma gorjeta no painel do PAY.JP. Um reembolso total e um estorno são registrados com a gorjeta; um reembolso parcial, apenas na receita.
Dados do cartão e PCI DSS
Seção intitulada “Dados do cartão e PCI DSS”Números de cartão, datas de validade e códigos de segurança são digitados apenas dentro do iframe do PAY.JP, que o payjp.js exibe. A página e o script deste servidor nunca os tocam. O servidor recebe apenas o ID do token que o payjp.js criou e o nome do titular e o endereço de e-mail de que o 3-D Secure precisa.
O servidor grava apenas IDs de objetos do PAY.JP (cus_, sub_, ch_, IDs de planos, IDs de eventos e as Checkout Sessions, PaymentFlows, reembolsos e disputas das gorjetas), valores, períodos e estados. O cartão de uma gorjeta é digitado na página própria do PAY.JP, que este servidor nunca serve. Ele não grava números de cartão, os quatro últimos dígitos nem datas de validade (a página do cartão apenas lê do PAY.JP os quatro últimos dígitos, a data de validade e o e-mail do cliente e os mostra). Os corpos dos webhooks e as respostas do PAY.JP não são mantidos nem nos logs nem no banco de dados.
A página de pagamento é servida a partir da origem deste servidor, então ela é construída com a gestão de scripts de páginas de pagamento do PCI DSS v4 (requisito 6.4.3) e a detecção de adulteração (requisito 11.6.1) em mente.
- A página é parte do cliente web, embutida no binário do servidor: ela carrega os scripts do próprio cliente web a partir deste servidor, cada um com seu Subresource Integrity, e
https://js.pay.jp/v2/pay.js, que o PAY.JP serve e atualiza. Ela não carrega nenhum script de análise ou de publicidade. - Cada versão traz
payment-scripts.json, a lista de todos os scripts que a página carrega: cada script do cliente web com seu hash, e o payjp.js. A página compartilha scripts com o restante do cliente web, então a lista muda de versão para versão; guarde a lista da versão que você executa. O servidor se recusa a iniciar com um build cuja lista não corresponde aos seus scripts. - A página sempre traz a sua própria Content-Security-Policy (
script-srcapenas este servidor ehttps://js.pay.jp,frame-srcapenashttps://js.pay.jpehttps://api.pay.jp,form-action 'self',frame-ancestors 'none'),Referrer-Policy: no-referrer,Cache-Control: no-storeeX-Content-Type-Options: nosniff. Nenhuma configuração altera a CSP. Envios de formulário só são aceitos da mesma origem.
Como resultado, espera-se que o escopo do operador seja o de um comerciante que deixa a entrada do pagamento ao iframe do PAY.JP (SAQ A). Confira o escopo que se aplica e o tipo de questionário de autoavaliação nas orientações do PAY.JP e nos requisitos das suas bandeiras de cartão.
Ao fazer isso, ajuda guardar um registro destes pontos: as URLs das páginas de pagamento (/payments/pages/payjp/checkout e /portal), a lista de scripts que a página carrega (payment-scripts.json da versão), a CSP da página e que o tráfego para o servidor usa TLS (a configuração do proxy reverso).
1. Preparar a conta do PAY.JP
Seção intitulada “1. Preparar a conta do PAY.JP”- Crie uma conta no PAY.JP e comece no modo de teste. Cobrar no modo ao vivo exige um aplicativo de produção e uma análise.
- Verifique “API settings > 3-D Secure” no painel do PAY.JP. O servidor pede o 3-D Secure a cada criação de token, então você também pode optar por exigir o 3-D Secure para toda criação de token.
- A página de divulgação comercial é definida na administração deste servidor (veja supporters.md).
2. Chaves e o token do webhook
Seção intitulada “2. Chaves e o token do webhook”Em “API” no painel do PAY.JP, confira estas duas chaves. O prefixo de uma chave define o modo, e as chaves de teste não cobram nada. As duas chaves precisam estar no mesmo modo.
| Chave | Exemplo | Uso |
|---|---|---|
| Chave secreta | sk_test_... / sk_live_... |
O servidor chama a API com ela. Ela também é a origem da chave que assina as URLs das páginas |
| Chave pública | pk_test_... / pk_live_... |
payjp.js nas páginas de pagamento e de cartão |
Passe a chave secreta na variável de ambiente MY_PAYMENTS_PAYJP_SECRET_KEY (ou o caminho de um arquivo em MY_PAYMENTS_PAYJP_SECRET_KEY_FILE). Ela não pode ser escrita no arquivo de configuração.
Se a chave secreta vazar, gere uma nova no painel e reimplante com a nova chave. As URLs das páginas de pagamento e de cartão que estavam abertas antes da reimplantação deixam de funcionar.
3. Registrar o webhook
Seção intitulada “3. Registrar o webhook”Em “Settings > Webhook” no painel do PAY.JP, adicione um destino. Registre o modo de teste e o modo ao vivo separadamente.
- URL:
https://<server domain>/payments/webhooks/payjp - Modo: o mesmo das chaves
Um webhook do PAY.JP identifica o remetente pelo token de origem da conta (whook_..., no cabeçalho X-Payjp-Webhook-Token). Passe o token mostrado no painel na variável de ambiente MY_PAYMENTS_PAYJP_WEBHOOK_TOKEN (ou _FILE).
O endpoint compara o token em tempo constante e rejeita com 400 um evento de teste recebido com uma chave ao vivo (e o inverso). Não há assinatura nem timestamp, então quem conhece o token pode enviar uma notificação, mas o servidor nunca grava estado a partir do conteúdo de uma notificação; ele apenas lê o estado de volta do PAY.JP.
O servidor usa estes eventos (outros tipos são aceitos, mas não são registrados).
subscription.created,subscription.updated,subscription.deleted,subscription.paused,subscription.resumed,subscription.canceled,subscription.renewedcharge.succeeded,charge.failed,charge.refundeddispute.createdstatement.created- Para as gorjetas (API v2):
checkout.session.completed,checkout.session.expired,payment_flow.succeeded,refund.created,refund.updated,refund.failededispute.created
O servidor distingue os eventos das APIs v1 e v2 pelo formato deles, então as duas versões vão para a mesma URL com o mesmo token.
O PAY.JP reenvia uma notificação apenas a cada 3 minutos, no máximo 3 vezes, e uma notificação além disso não chega até você reenviá-la pelo painel. A conciliação corrige o que foi perdido, então recomenda-se definir payments_reconcile_interval como 1 hora.
O estado do provedor (o modo, o momento em que chegou o último webhook e o resultado da última conciliação) aparece na seção “Provedor de pagamento” de /admin/supporters na administração.
4. Configurar o servidor
Seção intitulada “4. Configurar o servidor”MY_PAYMENTS=payjpMY_PAYMENTS_PAYJP_SECRET_KEY=sk_test_...MY_PAYMENTS_PAYJP_PUBLIC_KEY=pk_test_...MY_PAYMENTS_PAYJP_WEBHOOK_TOKEN=whook_...# The recommended reconciliation interval (15m to 168h, default 6h) and the most requests one reconciliation sends (default 1000)MY_PAYMENTS_RECONCILE_INTERVAL=1hMY_PAYMENTS_RECONCILE_MAX_REQUESTS=1000my config check verifica a configuração.
5. Experimentar no modo de teste
Seção intitulada “5. Experimentar no modo de teste”Comece com as chaves de teste. O modo de teste e o modo ao vivo têm Plans, clientes, assinaturas, webhooks e tokens separados. Para entrar no ar, registre o webhook no modo ao vivo, troque as chaves e o token pelos do modo ao vivo e reimplante. Os Plans são criados de novo na conta ao vivo.
Cartões de teste (documentação do PAY.JP):
| Número | Comportamento |
|---|---|
4242 4242 4242 4242 |
Tem sucesso |
4000 0000 0008 0319 |
O cartão pode ser cadastrado, mas a cobrança é recusada (uma assinatura que falha e uma retomada que falha após a troca de cartão) |
4000 0000 0000 4012 |
O cartão pode ser cadastrado, mas a cobrança falha por estar vencido |
4000 0000 0000 0002 |
O cadastro do cartão (a criação do token) é recusado |
Use uma data de validade futura; o código de segurança e o nome são arbitrários. No modo de teste, a tela de autenticação de teste do PAY.JP para o 3-D Secure permite escolher o resultado.
Para testar uma renovação rapidamente, defina o trial_end da assinatura alguns minutos à frente, pela API. A cobrança de renovação roda alguns minutos depois desse horário, não nele. Outra atualização de trial_end enquanto a primeira ainda está pendente reinicia a espera.
Para testar uma falha de pagamento e o período de carência, assine, troque o cartão na página do cartão pelo que é recusado (4000 0000 0008 0319) e deixe a assinatura renovar.
6. Experimentar localmente
Seção intitulada “6. Experimentar localmente”Os webhooks do PAY.JP vão para uma URL pública; então, para recebê-los em um servidor na sua máquina, exponha a porta por um túnel (cloudflared, ngrok e similares) e registre essa URL como um destino do modo de teste.
Espera-se que payjp listen --forward-to http://localhost:8080/payments/webhooks/payjp do payjp-cli também encaminhe os eventos, mas não se verificou se ele consegue encaminhar eventos da v1.
Abra as páginas de pagamento e de cartão na origem deste servidor (elas também funcionam em http://localhost:8080, mas o comportamento do payjp.js e do 3-D Secure varia conforme as configurações do navegador).
7. Operação
Seção intitulada “7. Operação”- Uma falha de conciliação do tipo
permissionindica uma chave secreta errada. duplicate_chargenos avisos da seção “Provedor de pagamento” significa que o servidor não conseguiu concluir o reembolso de um pagamento de uma assinatura encerrada. A linha de loga second subscription could not be canceled and refundedinforma a assinatura, e cada conciliação tenta de novo, inclusive depois que a assinatura é excluída. Reembolse a cobrança no painel se isso continuar: a próxima tentativa encontra o reembolso e limpa o aviso, desde que o PAY.JP ainda liste as cobranças da assinatura excluída (veja Itens a verificar). Uma cobrança com mais de 180 dias não pode ser reembolsada: o servidor registra isso e segue em frente.- Os outros reembolsos são tratados no painel do PAY.JP. Um reembolso total e um estorno removem a função e excluem a assinatura de imediato, e um reembolso parcial não remove a função.
- O cancelamento de um estorno de uma cobrança de assinatura não é registrado automaticamente, porque a API v1 não tem evento nem API para ele (o de uma gorjeta tem, veja Gorjetas). Quando isso acontecer, registre o valor cancelado na tela de receita da página de custos (
finance). A função não é restaurada automaticamente. - As taxas de plano pago e as taxas de transferência do PAY.JP não são subtraídas da receita. Registre-as como custos em
finance. - Quando as conciliações atingem o limite de requisições com frequência, aumente
payments_reconcile_max_requestsou alonguepayments_reconcile_interval.
Mudanças de plano
Seção intitulada “Mudanças de plano”Um upgrade cobra primeiro a diferença proporcional e só muda o plano depois que essa cobrança tem sucesso. Quando a cobrança é recusada, o plano permanece, e o usuário vê um erro com o caminho para atualizar o cartão, sem período de carência e sem notificação de pagamento falho; tentar de novo com um cartão válido cobra uma única vez. Se o plano não mudar depois da cobrança, tentar de novo não cobra outra vez. Uma diferença abaixo do mínimo de 50 ienes, e uma troca para o preço anual do mesmo plano, que não tem diferença positiva, não cobram nada agora e mudam de imediato; o novo valor é cobrado no fim do período, e uma falha nesse momento é uma renovação que falhou.
Itens a verificar
Seção intitulada “Itens a verificar”O comportamento a seguir não está definido pela documentação do PAY.JP nem pelo modo de teste.
- Como é calculada a taxa devolvida por um estorno, e se o extrato de um período bate com as taxas do servidor (o modo de teste mostrou uma taxa arredondada para baixo, e a taxa de um reembolso calculada a partir do seu valor).
- O que acontece num estorno real: o PAY.JP não documenta forma de provocar um estorno no modo de teste nem o corpo de
dispute.created. Um envio de teste do evento pelo painel recebe200e não altera nada. - Até onde a lista de eventos alcança no passado.
- Se excluir um Plan afeta as assinaturas existentes (o servidor nunca exclui um), e o tamanho máximo de um ID de Plan.
- Se o relatório de CSP ao carregar a página de pagamento importa: o
pay.jsaplica um estilo inline contrastyle-src 'self', enquanto os campos de cartão e o 3-D Secure funcionam no Chromium. Outros navegadores não foram verificados. - Se o payjp-cli consegue encaminhar eventos da v1.
- Que a cobrança de um cartão salvo do cliente não pede 3-D Secure, a menos que a requisição o peça. Uma cobrança recusada aparece em
GET /v1/chargescompaid: false, e o servidor ignora a que não foi paga. - Para as gorjetas na API v2, que foram construídas a partir dos guias e do SDK oficial do PAY.JP e ainda não foram testadas no modo de teste: que o PAY.JP envia os eventos da v2 para o mesmo destino e com o mesmo token dos da v1; que a página hospedada fica em
pay.jpou em um de seus subdomínios; que a criação de uma Checkout Session respeitaIdempotency-Key; que oresource_idde uma transação de pagamento é o PaymentFlow de um pagamento, o refund de um reembolso e o dispute de um estorno e do cancelamento dele; que as listas vêm da mais nova para a mais antiga, comstarting_aftereending_before; os sinais do valor e da taxa de uma transação; e que o extrato de um período da v1 inclui as taxas da v2. - Que
GET /v1/chargescomsubscriptionainda lista as cobranças de uma assinatura excluída. O servidor reembolsa antes de excluir, então só uma nova tentativa após um reembolso que falhou de vez depende disso. A referência da API documenta o filtro e não diz nada sobre assinaturas excluídas. Se a lista voltar vazia, o servidor registra uma falha em vez de um reembolso, eduplicate_chargepermanece mesmo depois que a cobrança é reembolsada manualmente.
Para LLMs e agentes de programação:llms.txt,llms-full.txt, llms-small.txt