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.
Alipay e WeChat Pay não suportam capturas manuais, e os pagamentos são capturados imediatamente.
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:
- 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.
- 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.
Recomendamos capturar um pagamento dentro de sete dias após a sua autorização. Após esse período, uma autorização pode ser cancelada pelo emissor - liberando os fundos de volta ao comprador.
Para habilitar a captura manual:
- Faça login na sua Customer Area.
- Mude para a sua merchant account.
- Vá para Settings > Account settings.
- Para o campo POS Capture Delay, selecione manual.
- Selecione Submit.
Se você não quiser mais usar a captura manual, selecione immediate como o POS Capture Delay, ou selecione um atraso de captura.
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
: Acurrency
e ovalue
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 aorequestedAmount
que você autorizou na solicitação de pagamento.
Para fazer uma captura parcial, especifique um valorvalue
igual aorequestedAmount
que você autorizou na solicitação de pagamento. O restante é devolvido ao cartão do cliente.-
paymentPspReference
: OpspReference
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
: CAPTUREoriginalReference
: OpspReference
da autorização.pspReference
: Nosso identificador exclusivo para esta solicitação de captura.-
success
: trueSe
success
for false, sua solicitação de captura falhou. Revise oreason
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
: OpspReference
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
: CANCELLATIONoriginalReference
: OpspReference
da autorização cancelada.pspReference
: Corresponde aopspReference
na /cancel resposta da API.-
success
: trueSe
success
for false sua solicitação de cancelamento falhou. Revise oreason
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_FAILEDoriginalReference
: OpspReference
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
: CAPTUREoriginalReference
: OpspReference
da autorização.pspReference
: Nosso identificador exclusivo para esta solicitação de captura bem-sucedida.success
: truereason
: Transaction Recaptured
Não conseguiremos capturar um pagamento se o cliente:
- Solicitar ao banco que revogasse a autorização.
- Estiver com a conta fechada.
Você pode encontrar uma visão geral das capturas com falha no seu relatório de contabilidade de pagamentos.