Endpoint responsável por pagar uma cobrança já existente com cartão de crédito no momento da chamada.

Diferente da criação direta de cobrança com cartão, esse endpoint é utilizado quando a cobrança já existe e o pagamento será informado depois, com os dados do cartão ou com um token previamente gerado.

Quando utilizar

Utilize este endpoint quando sua integração já tiver uma cobrança criada no Asaas e precisar processar o pagamento por cartão de crédito posteriormente.

Alguns cenários comuns incluem:

• cobrança criada sem os dados do cartão no momento inicial;
• cobrança criada para pagamento posterior pelo cliente;
• tentativa de pagamento de uma cobrança já existente;
• uso de cartão tokenizado para pagar uma cobrança em aberto;
• reprocessamento manual ou operacional de uma cobrança ainda não paga;
• fluxo em que a aplicação coleta os dados do cartão depois da criação da cobrança;
• integração que separa a criação da cobrança da captura dos dados de pagamento.

Quando não utilizar

Não utilize este endpoint para:

• criar uma nova cobrança;
• criar uma cobrança já paga com cartão no mesmo momento;
• agendar pagamento futuro com cartão;
• pagar uma cobrança que já foi paga;
• pagar uma cobrança removida;
• estornar uma cobrança;
• atualizar dados cadastrais do cliente;
• criar ou atualizar um token de cartão sem pagar a cobrança;
• alterar a forma de pagamento de uma cobrança que não esteja apta para pagamento com cartão.

Caso a intenção seja criar uma cobrança e processar o cartão na mesma requisição, utilize o endpoint de criação de cobrança com cartão de crédito.

Caso a intenção seja apenas gerar um token para uso futuro, utilize o endpoint de tokenização de cartão de crédito.

Fluxo recomendado

Em uma integração típica, este endpoint faz parte do seguinte fluxo:

Criar ou localizar o cliente
↓
Criar uma cobrança no Asaas
↓
Armazenar o id da cobrança
↓
Coletar os dados do cartão ou recuperar um creditCardToken
↓
Enviar a requisição de pagamento da cobrança
↓
Receber o resultado do processamento
↓
Consultar a cobrança, se necessário
↓
Atualizar o status no sistema de origem

Pré-requisitos

Antes de utilizar este endpoint, valide se:

• a cobrança já existe no Asaas;
• o id da cobrança foi armazenado corretamente;
• a cobrança pertence à conta autenticada;
• a cobrança está em um estado que permite tentativa de pagamento;
• a cobrança ainda não foi paga;
• a cobrança não foi removida;
• a API Key pertence ao ambiente correto, Sandbox ou Produção;
• a aplicação possui autorização para processar pagamentos com cartão;
• os dados do cartão foram coletados de forma segura;
• o token de cartão, quando utilizado, pertence ao cliente correto.

Parâmetro da requisição

Este endpoint utiliza o identificador da cobrança no path da requisição.

Exemplo de identificador:

pay_123456789

O id deve corresponder a uma cobrança existente na conta Asaas autenticada.

Parâmetros principais do body

A requisição pode ser feita de duas formas:

• informando os dados completos do cartão e do titular;
• informando um creditCardToken previamente gerado.

Dados do cartão

Quando não utilizar token, envie o objeto creditCard com os dados do cartão.

Campos comuns do objeto:

Exemplo:

{
  "creditCard": {
    "holderName": "Marcelo H Almeida",
    "number": "5162306219378829",
    "expiryMonth": "05",
    "expiryYear": "2028",
    "ccv": "318"
  }
}

Dados do titular do cartão

Quando não utilizar token, envie também o objeto creditCardHolderInfo com os dados do titular.

Campos comuns do objeto:

Exemplo:

{
  "creditCardHolderInfo": {
    "name": "Marcelo Henrique Almeida",
    "email": "[email protected]",
    "cpfCnpj": "24971563792",
    "postalCode": "89223005",
    "addressNumber": "277",
    "addressComplement": null,
    "phone": "4738010919",
    "mobilePhone": "47998781877"
  }
}

Uso de cartão tokenizado

O creditCardToken permite pagar uma cobrança sem reenviar todos os dados do cartão e do titular.

Exemplo:

{
  "creditCardToken": "76496073-536f-4835-80db-c45d00f33695"
}

Ao utilizar token, considere que:

• o token deve ter sido gerado previamente;
• o token deve estar associado ao cliente correto;
• o token não deve ser usado para transações de outro cliente;
• o uso do token reduz a exposição de dados sensíveis;
• tokens inválidos, expirados ou incompatíveis podem gerar erro na tentativa de pagamento.

Exemplo de chamada com dados do cartão

curl --request POST \
  --url https://api-sandbox.asaas.com/v3/payments/pay_123456789/payWithCreditCard \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'access_token: $ASAAS_API_KEY' \
  --data '{
    "creditCard": {
      "holderName": "Marcelo H Almeida",
      "number": "5162306219378829",
      "expiryMonth": "05",
      "expiryYear": "2028",
      "ccv": "318"
    },
    "creditCardHolderInfo": {
      "name": "Marcelo Henrique Almeida",
      "email": "[email protected]",
      "cpfCnpj": "24971563792",
      "postalCode": "89223005",
      "addressNumber": "277",
      "addressComplement": null,
      "phone": "4738010919",
      "mobilePhone": "47998781877"
    }
  }'

Exemplo de chamada com token

curl --request POST \
  --url https://api-sandbox.asaas.com/v3/payments/pay_123456789/payWithCreditCard \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'access_token: $ASAAS_API_KEY' \
  --data '{
    "creditCardToken": "76496073-536f-4835-80db-c45d00f33695"
  }'

Retorno esperado

Em caso de sucesso, a API retorna 200 OK com os dados atualizados da cobrança.

Exemplo ilustrativo de retorno:

{
  "object": "payment",
  "id": "pay_123456789",
  "billingType": "CREDIT_CARD",
  "status": "CONFIRMED",
  "value": 100.00,
  "netValue": 97.00,
  "customer": "cus_000005219613",
  "creditCard": {
    "creditCardNumber": "8829",
    "creditCardBrand": "MASTERCARD",
    "creditCardToken": "76496073-536f-4835-80db-c45d00f33695"
  }
}

Processamento imediato

Esse endpoint tenta processar o pagamento no momento da chamada.

Isso significa que:

• a transação é enviada para validação no momento da requisição;
• o retorno da API indica o resultado conhecido naquele momento;
• o pagamento pode ser aprovado ou recusado;
• falhas de validação podem retornar erro;
• não há agendamento de pagamento futuro;
• a data de vencimento da cobrança não transforma essa chamada em pagamento agendado.

Comportamentos importantes

Ao utilizar este endpoint, considere que:

• a cobrança já deve existir antes da chamada;
• a operação tenta pagar a cobrança no momento da requisição;
• o endpoint não cria uma nova cobrança;
• o endpoint não agenda pagamento futuro;
• o endpoint não deve ser tratado como idempotente;
• o endpoint pode retornar erro se a cobrança estiver em estado incompatível;
• o endpoint pode retornar erro se o cartão for recusado;
• o endpoint pode retornar erro se o token não pertencer ao cliente correto;
• o pagamento aprovado altera o estado da cobrança;
• a integração deve consultar a cobrança antes de tentar novamente após timeout ou erro incerto.

Idempotência, timeout e retentativas

Não trate este endpoint como uma operação idempotente.

Como a chamada processa uma tentativa real de pagamento, uma retentativa automática sem validação pode gerar comportamento indesejado, principalmente em cenários de timeout ou perda de resposta.

Recomendações:

• configure timeout suficiente para aguardar o processamento;
• evite timeouts muito curtos;
• em caso de timeout, consulte a cobrança antes de tentar novamente;
• não repita automaticamente a chamada sem verificar o status atual;
• registre internamente a tentativa de pagamento;
• utilize identificadores internos para conciliar tentativas e retornos;
• trate erros de cartão recusado sem retentativa imediata indefinida.

Fluxo recomendado em caso de timeout:

Enviar tentativa de pagamento
↓
Timeout ou resposta inconclusiva
↓
Consultar a cobrança pelo id
↓
Verificar status atual
↓
Se ainda estiver em aberto, avaliar nova tentativa
↓
Se estiver paga ou confirmada, atualizar sistema de origem

Regras de negócio importantes

Antes de implementar este endpoint, considere as seguintes regras:

• a cobrança deve existir no Asaas;
• a cobrança deve pertencer à conta autenticada;
• a cobrança deve estar em estado compatível com pagamento;
• a cobrança não deve estar removida;
• a cobrança não deve estar paga;
• a requisição deve estar autenticada com uma API Key válida;
• informe creditCard e creditCardHolderInfo quando não utilizar token;
• informe creditCardToken quando optar por cartão tokenizado;
• não envie dados completos do cartão quando o token for suficiente;
• o token deve estar vinculado ao cliente correto;
• o pagamento é processado imediatamente;
• pagamentos recusados devem ser tratados conforme a resposta da API;
• estornos devem ser feitos por fluxo próprio, não por este endpoint.

Dependências com outros recursos

Este endpoint depende de recursos e estados anteriores do fluxo de cobrança.

Impactos operacionais

O uso deste endpoint pode impactar diretamente o fluxo financeiro e operacional da integração.

Alguns impactos importantes:

• o pagamento é tentado imediatamente;
• uma transação aprovada altera o status da cobrança;
• uma transação recusada pode exigir nova tentativa com outro cartão ou orientação ao cliente;
• retentativas sem consulta prévia podem causar duplicidade operacional ou inconsistência;
• timeouts podem deixar a aplicação sem saber o resultado real da tentativa;
• falhas de pagamento devem ser refletidas no sistema de origem;
• conciliação financeira deve considerar o status atualizado da cobrança;
• tokens devem ser tratados como dados sensíveis e usados apenas para o cliente correto;
• cobranças pagas por cartão podem estar sujeitas a estorno, contestação ou análise posterior, conforme o fluxo do cartão.

Tratamento de erros

Alguns erros comuns ao utilizar este endpoint incluem:

Segurança

Ao trabalhar com pagamentos por cartão, adote cuidados adicionais de segurança.

Recomendações:

• utilize HTTPS em todo o fluxo de captura de dados do cartão;
• não armazene número completo do cartão;
• não armazene código de segurança;
• não envie dados de cartão para logs, ferramentas de suporte ou sistemas de monitoramento;
• prefira tokenização quando houver pagamentos futuros para o mesmo cliente;
• restrinja o acesso interno a payloads de pagamento;
• mascare dados sensíveis em erros, logs e telas administrativas;
• valide se a aplicação está preparada para lidar com recusas e falhas de cartão.

Boas práticas

Para uma implementação mais segura, recomenda-se:

• criar a cobrança antes de chamar este endpoint;
• armazenar o id da cobrança no sistema de origem;
• consultar a cobrança antes de tentar o pagamento;
• utilizar creditCardToken sempre que possível;
• não enviar creditCard, creditCardHolderInfo e creditCardToken ao mesmo tempo sem necessidade;
• validar os dados do titular antes da chamada;
• configurar timeout mínimo adequado para o processamento;
• consultar a cobrança antes de realizar retentativas;
• registrar cada tentativa de pagamento no sistema de origem;
• refletir o resultado da tentativa no status interno;
• testar cenários de aprovação, recusa e timeout em Sandbox antes de operar em Produção.

Cuidados em Sandbox

Em Sandbox, utilize este endpoint para validar os principais cenários de pagamento com cartão.

Durante os testes, recomenda-se validar:

• pagamento com dados completos do cartão;
• pagamento com creditCardToken;
• tentativa com cobrança inexistente;
• tentativa com cobrança já paga;
• tentativa com cartão recusado;
• tentativa com token inválido;
• comportamento em caso de timeout;
• atualização do status no sistema de origem;
• consulta da cobrança após o retorno da API.

Conteúdos relacionados

Consulte também:

• Criar nova cobrança;
• Criar cobrança com cartão de crédito;
• Cobranças via cartão de crédito;
• Tokenização de cartão de crédito;
• Recuperar uma única cobrança;
• Recuperar status de uma cobrança;
• Estornar cobrança;
• Webhooks para cobranças;
• Testando pagamento com cartão de crédito.