Links de pagamento

Um link de pagamento abre o checkout de uma cobrança específica. O cliente, o título, a descrição, o valor e o vencimento vêm dessa cobrança. O link permite configurar os destinos de retorno ao site e restringir os meios de pagamento oferecidos ao pagador.

As requisições da integração usam https://api.raims.com.

A gestão dos links tem estas cinco requisições:

Vínculo com a cobrança

Cadastre a cobrança antes de solicitar seu link e guarde o identificador retornado pela API. Em Criar um link de pagamento, envie esse identificador no campo charge_id. A cobrança precisa pertencer à empresa e ao ambiente da sua chave de API.

charge_id usa o identificador da cobrança, com prefixo ch_. O id do link usa pl_; ele identifica o link nas consultas, na edição e no envio.

O link não cria outro cliente nem outra cobrança. Ele também não define preço, prazo ou status financeiro próprios. Para consultar esses dados, use Recuperar uma única cobrança com o charge_id.

Criar ou recuperar o link

POST /v1/payment_links cria o link de uma cobrança existente ou reutiliza o link que ela já possui. A resposta informa o id do link, o charge_id e a url para abrir o checkout, além das configurações do link. Para criar ou configurar o link, a cobrança precisa estar aberta e dentro do vencimento.

Para receber o link junto da criação da cobrança, use create_checkout: true em Criar nova cobrança. Essa opção dispensa uma requisição separada para obter a URL, sem exigir envio de e-mail ou URL de retorno.

Criar ou recuperar o link não confirma pagamento nem solicita envio de e-mail. Enquanto a cobrança permitir essa ação, repetir a requisição não cria outro link. Um link novo começa ativo. Se o link existente estiver pausado, o POST preserva a pausa. Para reativá-lo, use o PATCH.

Configurar o link

Você pode enviar success_redirect_url, cancel_redirect_url e payment_method_types em POST /v1/payment_links ao criar o link ou usar PATCH /v1/payment_links/{id}, descrito em Atualizar um link de pagamento depois.

Depois de configurar o link, consulte GET /v1/payment_links/{id} e confira is_payable. O campo is_active e a lista effective_payment_method_types podem continuar preenchidos sem que o checkout aceite pagamento. A lista informa os meios definidos pelas configurações; is_payable informa se ainda é possível pagar naquele instante.

success_redirect_url configura o destino de retorno após a confirmação do pagamento, nas condições descritas em Orientar quem recebeu um link. cancel_redirect_url configura o endereço da opção de voltar ao site da empresa. Essa navegação não cancela a cobrança, o Pix ou o boleto.

Envie URLs HTTPS completas e válidas. Omitir uma URL, enviar null, texto vazio ou somente espaços preserva o endereço já cadastrado. Em um link novo sem endereço informado, a respectiva opção de retorno fica sem destino.

Para remover um destino cadastrado, use o PATCH com clear_success_redirect_url: true ou clear_cancel_redirect_url: true. Você pode enviar os dois comandos para remover ambos os destinos. Enviar false ou omitir o comando não solicita remoção. Esses comandos são exclusivos da atualização do link; não são enviados ao criar a cobrança ou o link e não aparecem na resposta.

Depois da remoção, a URL correspondente retorna null. Sem destino de sucesso, o checkout não faz o retorno automático; sem destino de cancelamento, a opção de voltar ao site fica sem endereço. Remover um destino não cancela a cobrança, o Pix ou o boleto. A atualização exige cobrança aberta e dentro do vencimento, inclusive quando apenas remove um destino.

Uma URL preenchida e seu comando de limpeza com true são incompatíveis na mesma requisição. A API retorna HTTP 400, com INVALID_FIELDS e detalhes MUTUALLY_EXCLUSIVE nos dois campos. Escolha entre cadastrar e remover aquele destino. É permitido remover um destino e alterar o outro.

payment_method_types permite restringir os meios aceitos pelo link. Omitir o campo preserva a configuração existente. Enviar null remove a configuração própria do link e retoma a resolução pelos meios da cobrança e pelo checkout da conta. Uma lista preenchida precisa respeitar os meios aceitos pela cobrança e disponíveis na plataforma. Consulte os códigos em Meios de pagamento.

Alterar a configuração do link não modifica o cliente, o título, o valor, o vencimento ou o status da cobrança. Use as requisições de Cobranças para consultar os dados e fazer as alterações permitidas nesse recurso.

Você também pode pausar o checkout com is_active: false e reativá-lo com is_active: true no PATCH. Para o pagador, um link pausado sem pagamento confirmado aparece como não encontrado ou indisponível, sem informar a pausa. Consulte Pausar e reativar para as condições e os efeitos dessa configuração.

Pausar e reativar

Use Atualizar um link de pagamento com PATCH /v1/payment_links/{id} e is_active: false para pausar o checkout. Para reativá-lo, envie is_active: true no mesmo endpoint. Omitir esse campo preserva o estado atual; null, números e texto são inválidos.

{
  "is_active": false
}

A pausa mantém o mesmo identificador e a mesma URL. O checkout bloqueia novas ações de pagamento e novos pedidos de envio ou reenvio por e-mail enquanto estiver pausado. Pedidos de e-mail e pagamentos aceitos antes da pausa podem continuar normalmente. Você pode alterar suas outras configurações sem reativá-lo. A cobrança precisa estar aberta e dentro do vencimento para pausar, reativar ou configurar o link.

Depois que a cobrança vence, o PATCH não permite reativar seu link. Pausar ou reativar conserva o mesmo id e a mesma url; nenhuma dessas ações acrescenta prazo à cobrança.

Ao abrir a URL de um link pausado sem pagamento confirmado, o pagador recebe o mesmo aviso de link não encontrado ou indisponível. A página não revela a pausa. Esse aviso sozinho não permite identificar o motivo; o pagador deve conferir o endereço recebido e procurar a empresa que emitiu a cobrança. A empresa pode consultar is_active pela API autenticada para verificar a configuração. Comprovantes de pagamentos confirmados continuam acessíveis.

O vencimento continua correndo durante a pausa. Pix e boleto já emitidos não são cancelados e podem continuar sendo pagos fora do checkout. Para cancelar a cobrança, use Revogar cobrança e acompanhe a confirmação. Pausar o link não substitui a revogação.

As respostas de criação, listagem, consulta e atualização informam is_active. Um valor true indica que o link não está pausado, mas não garante que a cobrança aceite pagamento. Confira is_payable no GET individual antes de oferecer o checkout. Repetir a configuração atual mantém o mesmo link.

Consultar e compartilhar

Use GET /v1/payment_links, descrito em Listar links de pagamento, para percorrer os links da conta. O filtro charge_id seleciona os links vinculados à cobrança informada. Mantenha esse filtro ao navegar pelas páginas.

Use GET /v1/payment_links/{id}, descrito em Recuperar um link de pagamento, com o id do link para consultar sua URL, configuração e disponibilidade atual. Os identificadores do link e da cobrança têm finalidades diferentes; use cada um no campo indicado.

No GET individual, is_payable indica se a cobrança ainda pode ser paga pelo link. Quando ela é paga, revogada ou vence, o link continua disponível para consulta, mas não permite um novo pagamento. Outras situações, como um boleto aguardando confirmação, também podem impedir um novo pagamento.

payment_method_types informa a configuração própria do link, ou null para usar a configuração da cobrança e da conta. Nessa consulta, a lista fica vazia se a configuração não contiver Pix nem boleto; isso não permite enviar uma lista vazia ao criar ou atualizar o link. effective_payment_method_types informa os meios definidos pelas configurações da cobrança, do link e da conta, entre os disponíveis na plataforma. Uma cobrança já paga ou um link pausado pode continuar mostrando Pix e boleto nessa lista. Use is_payable para saber se ainda é possível pagar pelo checkout.

Quando is_payable é false, unavailable_reason informa o impedimento. Use unavailable_reason.code na integração; message é uma explicação em inglês para diagnóstico e seu texto pode mudar. Quando a cobrança pode ser paga pelo link, unavailable_reason é null.

Quando o impedimento for o estado da cobrança, a mensagem informa o estado atual e os aceitos. Se uma cobrança aberta ultrapassou o vencimento, informa também due_date em segundos Unix UTC. A mesma explicação aparece quando essa condição impede configurar o link ou solicitar seu envio por e-mail.

A disponibilidade acompanha as regras do checkout da cobrança e pode mudar depois da consulta. Esses campos não confirmam pagamento nem reservam um meio. A consulta não emite Pix ou boleto e não renova o vencimento. Criação, listagem e atualização continuam retornando a configuração do link; use o GET individual para conferir a disponibilidade.

Compartilhe a url retornada pela API. Não monte o endereço a partir do id. As consultas usam o link existente e não geram outro checkout.

Enviar por e-mail

Para enviar ou reenviar um link de pagamento existente pela API, use POST /v1/payment_links/{id}/send_email, descrito em Enviar link por e-mail. Informe o id no caminho, sem corpo de requisição. O link precisa estar ativo e a cobrança, aberta e dentro do vencimento. Um link pausado retorna HTTP 409 com PAYMENT_LINK_PAUSED; reative-o antes de solicitar o envio. O pedido não cria outro link, não altera o checkout e não emite Pix ou boleto.

O destinatário é o e-mail do pagador registrado no boleto, quando houver. Sem esse endereço, usa o e-mail registrado na cobrança e, se também não houver, o e-mail do cadastro atual do cliente. Um endereço inválido impede o envio. Não é possível informar outro destinatário nessa requisição. Enquanto o cadastro da empresa estiver pendente, o envio fica restrito ao e-mail do titular.

Após uma solicitação aceita por esse endpoint, aguarde 60 segundos antes de pedir outro envio da mesma cobrança. Esse prazo é compartilhado com a ação de reenvio do Dashboard e com as demais chaves e servidores da mesma empresa. Se receber HTTP 429, aguarde o prazo de Retry-After antes de tentar novamente pela API ou pelo Dashboard. A resposta de sucesso informa o destinatário em recipient_email e o prazo de reenvio em retry_after_seconds e retry_after_until, este em segundos Unix UTC.

HTTP 202 confirma que o pedido de envio foi registrado. Não comprova a entrega na caixa de entrada nem a leitura pelo destinatário. Para acompanhar o pagamento, consulte a cobrança vinculada.

Sandbox também pode enviar e-mails reais. Ao testar esse endpoint, use um endereço de teste sob seu controle.

Acompanhar o pagamento

Consulte a cobrança indicada em charge_id para acompanhar seu status e obter os dados de Pix ou boleto disponíveis. Abrir o link, emitir um meio de pagamento ou voltar ao site não confirma que a cobrança foi paga.

O link acompanha as condições da cobrança vinculada. A expiração do checkout não comprova o cancelamento de um boleto já emitido. Para cancelar uma cobrança elegível, use Revogar cobrança e acompanhe a confirmação; editar o link não substitui essa ação.

Ambiente e acesso

A gestão dos links usa https://api.raims.com e exige uma chave de API. Empresa e ambiente vêm da chave. Links e cobranças de Sandbox ficam separados dos dados de Produção. Use Sandbox para testar sem movimentar valores reais.

Quem recebe a URL pode abrir o checkout. Não compartilhe sua chave de API com o pagador nem a inclua na URL. O endereço público não permite administrar a configuração do link ou da cobrança.