Captura manual

Por padrão, os pagamentos no ponto de venda são capturados automaticamente. Dependendo do seu modelo de negócios, você pode preferir capturar manualmente seus pagamentos no terminal. Isso permite que você estabeleça fundos, por exemplo:

• Em fulfillment: Você captura o pagamento quando um pedido é enviado.
• Em return: Quando o comprador devolve itens indesejados de um pedido, você captura o pagamento pelos itens que eles mantêm.

Com a captura manual, você também pode cancelar a autorização. Isso libera os fundos de volta para um cliente e pode ser usado em caso de problemas no envio de um pedido ou quando um comprador retorna todo o pedido.

Para usar a captura manual:

• Você precisa habilitar a captura manual.
• Seu sistema de gerenciamento de pedidos precisa ser capaz de gerar uma solicitação de captura quando um pedido for atendido ou devolvido.

Antes de começar

Antes de usar capturas manuais:

1. Configure as notificações de webhook. O resultado de uma solicitação de captura ou cancelamento é fornecido de forma assíncrona. Informamos se isso é bem-sucedido com uma notificação de webhook.
2. Gere uma chave de API. É necessário fazer solicitações de captura manual e cancelar autorizações de uma caixa registradora.

   Se você estiver usando comunicações baseadas na nuvem, poderá usar a Chave da API existente usada para chamadas da API do Terminal.

Ativar captura manual

Ao ativar a captura manual, as solicitações de pagamento feitas com sua conta merchant account resultam apenas em uma autorização. Para liquidar um pagamento, você precisa fazer uma solicitação de captura explícita.

Para habilitar a captura manual:

1. Faça login na sua Customer Area.
2. Mude para a sua merchant account.
3. Vá para Account > Account settings.
4. Para o campo POS Capture Delay, selecione manual.
5. Selecione Submit.

Faça uma solicitação de captura

Se você ativou a captura manual, poderá capturar um pagamento usando o pspReferenceretornado em sua resposta de pagamento.

Você pode solicitar uma captura total ou parcial, mas várias capturas parciais não são suportadas.

Para capturar um pagamento:

• Faça uma /payments/{paymentPspReference}/captures chamda para API, specificando:

  • content-type: application/json.
  • x-api-key: Sua chave de API.
  • merchantAccount: O nome da sua merchant account.
  • amount: A currency e o value sendo capturados.

    Para chamadas para o /payments/{paymentPspReference}/captures endpoint, especifique o value unidades secundárias (sem um ponto decimal)

    Para capturar o valor total, especifique um value igual ao requestedAmount que você autorizou na solicitação de pagamento.
    Para fazer uma captura parcial, especifique um valor value igual ao requestedAmount que você autorizou na solicitação de pagamento. O restante é devolvido ao cartão do cliente.

  • paymentPspReference: O pspReference da autorização que está sendo capturada..

    Você recebeu isso como parte do transactionID campo na resposta à sua solicitação de pagamento. Consulte Identificador de transação.

  O exemplo abaixo mostra como você capturaria uma autorização de pagamento de 10,99 EUR com pspReference 981517998282382C.

  curl https://checkout-test.adyen.com/v68/payments/981517998282382C/captures \
  -H "content-type:application/json" \
  -H "x-api-key:YOUR_API_KEY" -X POST --data-binary \
  '{
     "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
     "modificationAmount": {
        "currency": "EUR",
      "value": 1099
     }
  }'

• Se a solicitação de captura for recebida com êxito, a resposta conterá:

  • status: received

  • pspReference: Nosso identificador exclusivo para esta solicitação de captura.

    Isso é diferente do pspReference da autorização.

As capturas de pagamento são processadas de forma assíncrona e enviaremos uma notificação de webhook para que você saiba o resultado. Se a captura for enviada com êxito para processamento, esta notificação conterá:

• eventCode: CAPTURE
• originalReference: O pspReference da autorização.
• pspReference: Nosso identificador exclusivo para esta solicitação de captura.

• success: true

  Se success for false, sua solicitação de captura falhou. Revise o reason que você recebeu na notificação, corrija o problema e envie a solicitação de captura novamente.

Cancelar uma autorização

Ao usar a captura manual, você pode cancelar uma autorização com uma chamada de API da sua caixa registradora, especificando a pspReference da autorização que deseja cancelar:

• Faça uma solicitação POST para o /cancel endpoint, especificando:

  • content-type: application/json.
  • x-api-key: Sua chave API.
  • merchantAccount: O nome de sua merchant account.

  • originalReference: O pspReference da autorização sendo cancelada.

    Você recebeu isso como parte do campo transactionID na resposta à sua solicitação de pagamento. Consulte Identificador de transação.

  O exemplo abaixo mostra como você cancelaria uma autorização com pspReference 981517998282382C.

  curl -H "content-type:application/json" -H "x-api-key:YOUR_API_KEY" -X POST --data-binary '{
    "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
    "originalReference": "981517998282382C",
  }' --url https://pal-test.adyen.com/pal/servlet/Payment/v46/cancel

• Se a solicitação de cancelamento for recebida com êxito, a resposta conterá:

  • response: [cancel-received]

  • pspReference: Nosso identificador exclusivo para esta solicitação de cancelamento.

    Isso é diferente do pspReference da autorização.

As solicitações de cancelamento são processadas de forma assíncrona e enviaremos uma notificação de webhook para que você saiba o resultado. Se a autorização for cancelada com sucesso, a notificação conterá:

• eventCode: CANCELLATION
• originalReference: O pspReference da autorização cancelada.
• pspReference: Corresponde ao pspReference na /cancel resposta da API.

• success: true

  Se success for false sua solicitação de cancelamento falhou. Revise o reason que você recebeu na notificação, corrija o problema e reenvie a solicitação de cancelamento novamente.

Capturar notificações com falha

Embora rara, uma captura pode falhar após ser enviada para processamento. Quando isso acontece, você recebe uma notificação contendo:

• eventCode: CAPTURE_FAILED
• originalReference: O pspReference da autorização.
• pspReference: Nosso identificador exclusivo para esta solicitação de captura com falha.

O exemplo abaixo é de uma autorização com o pspReference 981517998282382C, que falhou ao capturar.

{
  "live":"false",
  "notificationItems":[
    {
      "NotificationRequestItem":{
        "amount":{
          "currency":"EUR",
          "value":1099
        },
        "eventCode":"CAPTURE_FAILED",
        "eventDate":"2019-05-20T15:30:00+02:00",
        "merchantAccountCode":"YOUR_MERCHANT_ACCOUNT",
        "originalReference":"981517998282382C",
        "paymentMethod":"mc",
        "pspReference":"991540215241817C",
        "reason":"Capture Failed",
        "success":"true"
      }
    }
  ]
}

Isso pode ocorrer alguns dias após uma solicitação de captura e geralmente ocorre devido a um problema técnico. Tentaremos resolver o problema e reenviar automaticamente a solicitação de captura.

Na maioria dos casos, podemos resolver o problema e liquidar os fundos na sua conta logo depois. Quando isso acontece, você recebe uma notificação contendo:

• eventCode: CAPTURE
• originalReference: O pspReference da autorização.
• pspReference: Nosso identificador exclusivo para esta solicitação de captura bem-sucedida.
• success: true
• reason: Transaction Recaptured

Não conseguiremos capturar um pagamento se o cliente:

• Solicitar ao banco que revogasse a autorização.
• Estiver com a conta fechada.

Veja também