Skip to main content
Seus clientes já vêm pagando em algum lugar há um tempo. Conectar o gateway não traz ninguém para cá sozinho, e esta página explica por quê, e o que fazer a respeito.

​
Por que elas não chegam sozinhas

Toda assinatura que este sistema guarda é um espelho de uma do seu gateway, e o jeito comum de uma linha existir é um checkout iniciado aqui: a linha nasce primeiro, o id dela viaja até o gateway como referência do checkout, e é o checkout concluído que amarra os dois. Uma assinatura criada antes disso tudo — anos atrás, ou semana passada no painel da própria Stripe — nunca passou por essa porta. Os webhooks dela chegam, sim, e são guardados, e terminam com uma nota dizendo que nada aqui está ligado a sub_…. O que está certo: a resposta de um gateway nomeia um pagador que o gateway inventou, e qual dos seus times é esse não é algo que ele possa dizer. Essa é a única peça que falta, e é aqui que você a fornece.

​
Faça o catálogo primeiro

Uma assinatura adotada precisa de um plano, e o plano é resolvido a partir do preço em que ela é cobrada — então o preço do gateway precisa estar mapeado no seu catálogo antes que a assinatura possa ser adotada. Se você ainda não fez isso:
Isso lê os produtos e preços do seu gateway e escreve planos e preços aqui, com o mapeamento. Se você precificou seu produto aqui primeiro, publique seus preços no gateway — mesmo mapeamento, direção oposta. Garanta também que o health check da conexão já rodou pelo menos uma vez. Um mapeamento de preço é chaveado pela conta de comerciante, e a conta só é conhecida depois que alguém perguntou ao gateway a quem as chaves pertencem.

​
Depois dê os recursos a esses planos

É este o passo que fica de fora, e ele falha calado. A importação traz planos e preços, e mais nada — nenhum recurso, nenhuma matriz. Um gateway sabe o que ele cobra; ele não faz ideia do que o seu produto deixa alguém fazer. Então uma assinatura adotada num plano importado resolve para um plano sem recurso nenhum: o cliente está no Pro, paga o Pro, e não tem direito a nada. Nada dá erro, e o primeiro relato disso é um chamado no suporte. Configure os recursos de cada plano antes de adotar qualquer coisa — no painel, em Catálogo, ou pela API do catálogo. Se você já adotou, arrumar o plano arruma todas as assinaturas que apontam para ele: os entitlements resolvem pelo plano, não por uma cópia tirada na hora da adoção.

​
Adotando uma

201 quer dizer que agora existe uma linha que não existia. Nada nessa resposta veio do seu pedido além do cliente. O status, o período, o trial, um cancelamento agendado e a quantidade da linha são todos lidos do gateway; o plano vem do mapeamento de preço. Nada foi cobrado e nada mudou no gateway — o que mudou é que este sistema agora guarda a assinatura. Dali em diante ela se comporta como qualquer outra: os webhooks a encontram, a reconciliação noturna a relê, os entitlements resolvem pelo plano dela, e ela pode ser alterada ou cancelada por aqui.

​
Nomeando o cliente

Por customer_id, ou por customer_external_id — o seu id para o time, que é o que torna isso scriptável: seu backend já sabe qual conta corresponde a qual cus_, e não deveria ter que guardar um mapa dos nossos uuids também. Mande um ou outro; um pedido com os dois carrega duas convicções sobre quem está pagando. O cliente precisa existir. Este endpoint não cria um, porque um time conjurado para pendurar dinheiro seria um time sem membros — use POST /v1/customers na superfície de máquina, que é a chamada que sabe o nome do time.

​
Rodando sobre uma lista

Uma migração de qualquer tamanho é um script, então o mesmo ato está na superfície de máquina, sob uma chave uk_sk_ — onde o ambiente é o da chave e nenhum campo o move:
Duas camadas respondem a duas repetições diferentes, e vale saber qual é qual:
  • a Idempotency-Key repete a mesma resposta, bytes e status, para uma requisição repetida — é disso que o backoff de um cliente precisa, e é o que impede uma resposta perdida de virar uma segunda chamada;
  • adotar a mesma assinatura para o mesmo cliente de novo, sob uma chave nova, responde 200 com a linha e não escreve nada — é disso que uma re-execução do lote uma semana depois precisa.
A mesma assinatura para um cliente diferente é recusada dos dois jeitos: é a única repetição que significa que alguém errou. Ou seja: um script que morre no meio pode simplesmente ser rodado de novo. Leia o seu próprio mapa de conta para cus_, resolva as assinaturas de cada uma no gateway, e chame isto uma vez por linha — as recusas abaixo dizem quais linhas olhar, e o resto está feito.

​
O que ela se recusa a adivinhar

Não existe desadotar. Uma assinatura nunca é apagada aqui, e a referência do gateway só é escrita em uma coluna vazia — então um vínculo errado é permanente, e tudo que teria que ser presumido é recusado no lugar. customer_mismatch só dispara quando há com o que comparar. Não guardamos cus_ nenhum, então a referência de pagador de um cliente é descoberta lendo uma assinatura que ele já tem — e um cliente que você está prestes a migrar normalmente não tem nenhuma. Silêncio não é divergência, e recusar por causa dele recusaria a migração inteira.

​
O que ela não faz por você

Não encontra as assinaturas. Não existe um “importar tudo” aqui, e isso é deliberado: a qual time cada sub_ pertence é o único fato que este sistema não consegue derivar, e um endpoint em lote teria que adivinhá-lo para todas as linhas de uma vez. Seu backend tem o mapa; esta é a chamada que o registra. Não traz as faturas antigas. O que é adotado é a assinatura e o estado atual dela. Os pagamentos feitos antes de ela existir aqui ficaram no gateway, que continua sendo onde esse histórico vive; as faturas do próximo pagamento em diante chegam por webhook como sempre.

​
Por último: aponte o webhook do gateway para cá

A adoção registra a assinatura como ela está agora. Tudo o que vier depois — uma renovação, um pagamento que falha, um cancelamento, uma troca de plano feita no gateway — chega por webhook, e só se o gateway souber para onde mandar. O endereço está na tela do provedor de pagamento, no painel, em URL do webhook, assim que a conexão existe. Cole no painel do seu gateway e guarde o segredo de assinatura aqui. Pule este passo e tudo o que você acabou de migrar congela no estado em que chegou, sem nada indicando isso. Uma assinatura cancelada no mês passado continua lendo como ativa, e o cliente continua com o acesso.