Boas práticas de integração

Transcrição

1

2 2 Criaça o de pedidos Os seguintes itens devem ser levados em consideração quando estivermos criando novos pedidos através do método CreateOrder: Pedidos 1 - OrderReference: O campo OrderReference serve para identificar o seu pedido na MundiPagg. Caso não seja especificado, a MundiPagg criará automaticamente um valor para este campo. Você pode, por exemplo, especificar a chave do pedido no seu sistema interno e utilizá-lo para localizar o pedido no portal da MundiPagg. Atenção: Evite preencher o campo OrderReference com valores duplicados. Isso fará com que ao buscar os pedidos por este campo, mais de um pedido seja retornado, podendo gerar confusão ou dúvida. 2 - Retries: Utilize o campo Retries apenas quando necessário. Por padrão as todos os pedidos das lojas que possuem retentativas habilitadas serão retentados até 3 vezes, caso a transação não seja autorizada. Quando definimos Retries como 0 (zero), estamos dizendo que não queremos utilizar o recursos de retentativa. Utilizar valores muito altos, poderá fazer com que a adquirente bloqueie a afiliação da loja, pois poderá interpretar como tentativa de fraude ou afiliação com problema, caso os dados da transação sejam inválidos. Recorrências 1 - Recurrency: Ao trabalhar com recorrências, caso o pedido possua um número limitado de cobranças, preencha os campos AmountInCents e AmountInCentsToConsiderPaid do pedido como a soma do valor de todas as recorrências. Por exemplo, se você estiver criando uma recorrência de 6 cobranças, onde cada parcela possua o valor de R$ 100,00, você pode definir o valor de AmountInCents e AmountInCentsToConsiderPaid como R$ 600,00. Com isso quando a última parcela for paga, você poderá identificar esse pedido como pago e concluído. Caso não sejam definidos esses valores, o pedido será criado como o valor da primeira cobrança. Isso marcará o pedido com o status Pago, assim que a primeira recorrência for paga. Quando a segunda recorrência for paga, o pedido terá o total de 200 reais pagos e será marcado com o status Pago a maior, o que pode causar confusão na hora de gerenciar as recorrências. 2 - Datas das cobranças: Na MundiPagg é possível agendar recorrências para os dias 29, 30 e 31 de cada mês. Entretanto é importante notar que quando uma recorrência é agendada para uma dessas datas e o mês seguinte não possuir este dia, ele a cobrança será feita no último dia do mês. Por exemplo, uma recorrência foi agendada para ser cobrada todo dia 31. No mês de Fevereiro, tendo apenas 28 dias, todas as recorrências que estão agendadas para os dias 29, 30 e 31, serão cobradas no dia 28. Transações 1 - TransactionReference: O campo TransactionReference permite que seja informado um valor que será utilizado para identificar a transação na MundiPagg. Caso não seja especificado, a MundiPagg criará automaticamente um valor para este campo. Você pode, por exemplo, especificar a chave da transação no seu sistema interno e utilizá-lo para localizar a transação no portal da MundiPagg.

3 3 2 - PaymentMethodCode: Utilize sempre o valor 1 (um) nesta propriedade quando estiver em fase de desenvolvimento e homologação da sua integração, pois isso fará com que as transações sejam enviadas para nosso sistema de simulação, evitando cobranças desnecessárias de taxas de adquirentes com transações de testes. Após a integração estar concluída, testada e homologada, recomendamos que este campo seja deixado em branco, a menos que você deseje forçar a utilização de uma adquirente específica. Na prática este recurso afeta diretamente o processamento de transações da seguinte maneira: Quando uma loja é cadastrada na MundiPagg, cada afiliação que a loja possui recebe um nível de prioridade. Quando o PaymentMethodCode é deixado em branco, as transações são processadas na adquirente que possui maior prioridade. Geralmente tem maior prioridade a adquirente que possui uma taxa mais barata, que é informada pela loja. Com isso, quando a loja utiliza a funcionalidade de retentativas Multi-Adquirente, caso a transação não seja autorizada, a MundiPagg irá tentar autorizar a transação na próxima afiliação na lista de prioridade. Mesmo que a taxa de adquirência seja um pouco mais alta, por exemplo, a transação pode ser autorizada e a venda não será perdida. Quando o PaymentMethodCode é especificado, mesmo que a loja possua mais de uma afiliação cadastrada, será utilizada apenas a afiliação para o código especificado. Isso significa que caso sua loja possua o recurso Multi- Adquirente habilitado, será utilizado apenas a adquirente relacionada ao PaymentMethodCode especificado. Quando deve-se utilizar o PaymentMethodCode: Quando estiver desenvolvendo/homologando a integração com a MundiPagg, passando o valor "1". Quando tiver problemas com uma adquirente e deseje que suas transações sejam processadas por outra adquirente. Quando possuir um acordo financeiro com a adquirente. Por exemplo, transações a vista são mais baratas na adquirente A. Transações parceladas são mais baratas na adquirente B. Para aproveitar o desconto, deve-se informar o código de meio de pagamento da adquirente B para todas as transações parceladas. Fora essas situações, recomenda-se deixar este campo sempre em branco, para que a plataforma da MundiPagg gerencie o processamento das suas transações de forma automática.

4 4 Retentativas O tratamento de retentativas deve ser realizado preferencialmente através da MundiPagg. Por padrão, caso sua loja possua a funcionalidade de retentativas habilitada, quando não for possível autorizar uma transação, a MundiPagg tenta autorizar esta transação mais 3 vezes, seja na mesma adquirente ou em outra. Recomendamos fortemente que as retentativas não sejam realizadas manualmente pela loja, pois isso pode derrubar drasticamente a taxa de conversão. Isso acontece pois geralmente a loja envia para a MundiPagg um novo pedido com as mesmas informações do pedido não autorizado. Muitas vezes esse pedido duplicado também não é autorizado. Conforme novos pedidos duplicados forem sendo recebidos pela MundiPagg e não forem autorizados, uma quantidade enorme de pedidos não autorizados se acumulam, afetando os relatórios de conversão, jogando a taxa de conversão para um nível muito baixo. A maneira recomendável de realizar retentativas é solicitando que esta funcionalidade seja habilitada, junto à área de atendimento ao cliente da MundiPagg. Mesmo assim, caso a loja sinta a necessidade de fazer retentativas manualmente, recomendamos utilizar nosso serviço RetryOrder. Este serviço tem a inteligência de aproveitar o pedido já existente e entrar em contato novamente com a adquirente para tentar fazer uma nova autorização da transação. Com isso não será criado um pedido duplicado e garantindo maior integridade nos cálculos dos relatórios de conversão. Post de notificaça o Encorajamos a todas as lojas que integram com a MundiPagg que possuam uma URL para que possamos enviar notificações sobre mudanças de status das transações. A MundiPagg possui uma funcionalidade que envia para as lojas as informações de suas transações, sempre que estas possuírem o status alterado. Isso é muito importante, pois muitas vezes o resultado do processamento de uma transação não é obtido em tempo real. Principalmente para transações que são submetidas para o sistema de antifraude, já que a transação pode entrar em processo de análise manual e levar algum tempo para ser processada. Ao possuir uma URL, a MundiPagg poderá enviar as informações do resultado do processamento para que a loja possa dar prosseguimento no processo de venda. Independente da loja utilizar o sistema de anti-fraude, muitas outras situações podem afetar o processamento das transações. Recomendamos fortemente que todas as lojas disponibilizem uma url para eliminar qualquer surpresa que possa aparecer e garantir que receberão sempre o status atualizado das suas transações quando elas foram modificadas na MundiPagg.

5 5 Tratamento do retorno Entender a mensagem de retorno da MundiPagg é de vital importância para que sua loja possua uma integração de boa qualidade. Tentamos facilitar a resposta para que você não tenha que se preocupar com detalhes e possa focar no seu negócio. Os seguintes campos precisam de atenção especial quando se está criando um novo pedido atraves do CreateOrder: Pedido 1 - Success Quando o resultado da criação de um pedido possua o resultado de Success = true, significa que seu pedido foi criado e processado com sucesso. Salve os dados relevantes da resposta do processamento em seu sistema interno e prossiga com o processo de venda. Entretanto, um cuidado maior deve ser tomado caso Success possua o valor false. Nesta situação a loja deve verificar o nó de informação chamado de ErrorReport que também está presente na resposta, antes de tomar qualquer decisão de negócio que possa afetar o usuário comprador do site. 2 - ErrorReport Sempre que o Success de um pedido for false E ErrorReport NÃO for nulo, significa que um erro ocorreu no processamento do seu pedido. Esses erros são descritos dentro do nó ErrorReport. Como mais de um erro pode ter ocorrido, o ErrorReport contém uma lista de itens que especificam cada um dos erros detalhadamente, chamados de ErrorItem. 3 - ErrorItem Cada ErrorItem descreve um erro específico que ocorreu no processamento do seu pedido. Os dados relevantes são: ErrorCode: Código do erro. A mundipagg utiliza dois códigos principais, baseados no protocolo http. São eles, o código 400 e o código 500. Sempre que a MundiPagg retornar ErrorCode 400, significa que algum dado que foi especificado não é válido. Por exemplo, se sua loja tentar criar um pedido com uma transação de cartão de crédito, sem especificar o número do cartão de crédito, será retornado o código 400, indicando que sua solicitação foi inválida. ErrorCode 500 significa que houve um erro de processamento interno da MundiPagg. Descrevemos mais abaixo como trabalhar com este caso. ErrorField: Indica o nome do campo que teve o erro. No exemplo acima, receberíamos o valor CreditCardNumber, indicando que houve um erro no número do cartão de crédito. Description: Breve descrição do erro e como corrigí-lo. No exemplo acima, receberíamos a mensagem informando que o número do cartão de crédito não pode ser nulo.

6 6 Tratando seu pedido baseando-se no ErrorCode ErrorCode 400: Verifique os campos ErrorField e Description para identificar quais parâmetros estão sendo enviados de forma incorreta e corrigí-los. ErrorCode 500: Este erro indica que seu pedido não pôde ser processado devido a uma falha interna. Você pode criar um novo pedido e enviar para ser processado novamente na MundiPagg. Caso o erro persista, entre em contato com o serviço de atendimento ao cliente da MundiPagg. Transações Cada transação do seu pedido também possui informações específicas para o seu tratamento. Estas devem ser tratadas com tanta atenção quando o pedido, pois algumas ações podem ser tomadas baseando-se no resultado do processamento de cada transação. 1 - Success Assim como no pedido, cada transação possui o campo Success que indica se esta foi processada corretamente. O Success da transação é muito importante para pedidos que contenham mais de uma transação. Pois como as transações são processadas de forma independente, uma pode ser autorizada e outra negada pela adquirente. Com isso, a transação autorizada terá Success = true enquanto a transação negada receberá Success = false. Neste caso, o pedido possuirá Success = false, pois uma das transações não pode ser autorizada. É necessário analisar sempre o resultado de cada transação para ter certeza do que ocorreu no processamento do seu pedido. No exemplo acima, a loja poderia chamar o serviço RetryOrder da MundiPagg para tentar autorizar novamente a transação que foi negada, solicitar um novo meio de pagamento ao cliente, para substituir o que foi negado, entregar o produto ou serviço apenas da transação aprovada ou simplesmente cancelar a transação que foi autorizada com sucesso e notificar ao cliente que sua transação não foi aprovada. 2 - Código de retorno da adquirente Embora seja possível obter o código de retorno originais das próprias adquirentes, não aconcelhamos que estas informações sejam utilizadas para definir regras de negócio da sua loja, pois periódicamente novos códigos podem ser criados por cada adquirente, o que pode afetar o fluxo já existente do seu negócio. Caso precise armazenar estas informações utilize os dados dos campos 'AcquirerReturnCode' e 'AcquirerMessage' de cada transação de cartão de crédito. Estes dados são de inteira responsabilidade de cada adquirente e armazena o código de retorno e a mensagem descritiva do processamento, respectivmente.

7 7 Status Diversos status caracterizam a situação atual de um pedido. O bom entendimento de cada um deles facilita a tomada de decisão que mais se adequa a sua regra de negócio. Existem duas categorias principais de status. Status de pedidos e status de transações. Segue abaixo uma breve descrição dos status mais relevantes. Consulte o manual de integração da MundiPagg para mais informações sobre os status disponíveis. Pedidos Opened: Indica que o pedido possui transações que ainda não foram processadas totalmente. Exemplo, transações autorizadas que ainda não foram capturadas ou recorrências. Paid: Todas as transações do pedido foram pagas, ou o valor pago das transações é igual ao valor especificado no campó AmountInCentsToConsiderPaid. OverPaid: As transações foram pagas/capturadas com um valor maior do que o que foi especificado no pedido ou no campo AmountInCentsToConsiderPaid. Canceled: Todas as transações do pedido foram canceladas. PartialPaid: Nem todas as transações do pedido foram pagas, ou o valor pago é menor do que o valor especificado em AmountInCentsToConsiderPaid. WithError: Ocorreu um erro no processamento do pedido. Verifique a sessão Timeouts para mais informações sobre como tratar este status. Transações de cartão de crédito NotAuthorized: Indica que a transação de cartão de crédito não foi autorizada pela adquirente. Você pode tentar autorizar novamente utilizando o serviço RetryOrder. Captured: Indica que a transação foi capturada com seu valor integral. PartialCapture: A transação foi capturada com um valor menor no que o valor autorizado. Refunded: A transação foi estornada. O estorno é o cancelamento de uma transação que não foi feita no mesmo dia da captura. Voided: A transação foi cancelada. O cancelamento é possível apenas no mesmo dia em que a transação é capturada. Caso deseje cancelar uma transação capturada em outro dia, será realizado um estorno. OpenedPendingAuth: Status definido para transações agendadas. Muito comum em recorrências. Transações que deverão ser cobradas no mês seguintes ficam agendadas com este status. PendingVoid: Algumas adquirentes não cancelam as transações em tempo real. Quando a solicitação de cancelamento é recebida pela MundiPagg. A transação é marcada com o status PendingVoid. Quando a adquirente retorna a confirmação do cancelamento, o status é atualizado para Voided. Invalid: Ocorre particularmente para transações de recorrências. Quando é criado um plano de 6 meses, por exemplo, porém o cartão do cliente vence em 2 meses. A transação não é liberada e fica com este status. PartialRefunded: Ocorre quando apenas parte do valor da transação é estornado. OverCapture: Ocorre quando o valor capturado é maior do que o valor autorizado. PartialVoid: Ocorre quando apenas parte do valor da transação é cancelado.

8 8 PendingRefund: Algumas adquirentes não estornam as transações em tempo real. Quando a solicitação de estorno é recebida pela MundiPagg. A transação é marcada com o status PendingRefund. Quando a adquirente retorna a confirmação do estorno, o status é atualizado para Refunded. WithError: Ocorreu um erro no processamento da transação. Verifique a sessão Timeouts para mais informações sobre como tratar este status. Timeouts Timeout é um problema comum em qualquer produto ou serviço que funcione na Internet. Um timeout ocorre quando a comunicação entre dois serviços leva mais tempo que o esperado. Consideraremos também, para fins de procedimento, também quando a conexão é cortada ou a Internet "cai". Atualmente os seguintes tipos de timeouts podem ocorrer na MundiPagg: Loja - MundiPagg: Ocorre quando a loja não consegue enviar a transação para a MundiPagg. Pode ocorrer caso o servidor da loja esteja sem Internet ou a configuração de comunicação com a MundiPagg não tenha sido de forma correta. MundiPagg - Adquirente: Ocorre quando a MundiPagg recebe o pedido da loja e ao tentar enviar para a adquirente, esta estiver fora do ar ou indisponível no momento. Adquirente - MundiPagg: Geralmente ocorre quando a adquirente não consegue processar a transação em tempo hábil. Caso uma resposta não seja recebida em um período de tempo determinado, é considerado um timeout. MundiPagg - Loja: Ocorre quando a loja não consegue receber o resultado do processamento da MundiPagg. Pode ocorrer o servidor da loja esteja sem Internet ou o tempo de timeout especificado pela loja não seja o suficiente para aguardar o término do processamento. Tratando Timeouts 1 - Timeout do tipo Loja - MundiPagg Quando a loja não consegue enviar um pedido para a MundiPagg, ela pode livremente criar um novo pedido e reenviá-lo. Ações sugeridas: Chame o serviço QueryOrder da MundiPagg para certificar-se de que realmente seu pedido não foi recebido pela MundiPagg. Caso ele tenha sido recebido, o QueryOrder retornará os dados e o resultado do processamento do seu pedido. Caso o QueryOrder não retorne informações do pedido, sinta-se livre para criar um novo pedido. 2 - Timeout do tipo MundiPagg - Adquirente

9 9 Ao receber o pedido da loja, a MundiPagg o prepara para ser enviado para a adquirente. Caso a adquirente esteja fora do ar neste momento, a MundiPagg não será capaz de enviar a transação para ser processada. Nesta situação tem vantagem a loja que possui o recurso de retentativa Multi-Adquirente habilitado na MundiPagg, pois ao detectar que uma adquirente está fora do ar, a MundiPagg é capaz de enviar a sua transação para ser processada em outra adquirente. Caso sua loja não possua o recurso Multi-Adquirente habilitado, o pedido será retornado com o Success = false e a transação possuirá o status 'WithError'. Ações sugeridas: Tenha afiliação em mais de uma adquirente e solicite o recurso de retentativa Multi-Adquirente ao serviço de atendimento ao cliente da MundiPagg. Evite criar um novo pedido para transações que estiverem com o status 'WithError', pois a transação pode já exister e estar autorizada/capturada na adquirente, fazendo com que o cliente seja cobrado multiplas vezes. Sempre que receber o status 'WithError', aguarde pelo menos 1 (uma) hora antes de criar um novo pedido. A MundiPagg possui uma inteligência de procurar essas transações com timeout a cada 10 minutos. Caso a transação seja encontrada na adquirente, um post de notificação será enviado informando o status do processamento. Caso não possua uma url de post de notificação, sugerimos fazer uma consulta ao serviço QueryOrder 1 (uma) hora após receber a transação com status 'WithError'. Com isso você poderá verificar se a MundiPagg conseguiu obter o resultado do processamento da adquirente e evitar criação de pedidos duplicados e cobranças múltiplas ao cliente. 3 - Timeout do tipo Adquirente - MundiPagg Caso a transação tenha sido enviada para a adquirente mas esta não tenha retornado um resultado para a MundiPagg, a loja receberá o campo Success = false e a transação possuirá o status 'WithError'. Ações sugeridas: Tenha uma url de post de notificação, como sugerido no tópico "Post de Notificação". Com isso, caso a MundiPagg consiga processar seu pedido, sua loja receberá uma notificação com o resultado do processamento. Evite criar um novo pedido para transações que estiverem com o status 'WithError', pois a transação pode já exister e estar autorizada/capturada na adquirente, fazendo com que o cliente seja cobrado multiplas vezes. Sempre que receber o status 'WithError', aguarde pelo menos 1 (uma) hora antes de criar um novo pedido. A MundiPagg possui uma inteligência de procurar essas transações com timeout a cada 10 minutos. Caso a transação seja encontrada na adquirente, um post de notificação será enviado informando o status do processamento. Caso não possua uma url de post de notificação, sugerimos fazer uma consulta ao serviço QueryOrder 1 (uma) hora após receber a transação com status 'WithError'. Com isso você poderá verificar se a MundiPagg

10 10 conseguiu obter o resultado do processamento da adquirente e evitar criação de pedidos duplicados e cobranças múltiplas ao cliente. 4 - Timeout do tipo MundiPagg - Loja Se sua loja não receber o resultado do processamento de um pedido, seja qual for o motivo, é necessário realizar uma consulta antes de criar um novo pedido e correr o risco de cobrar seu cliente mais de uma vez. Ações sugeridas: Faça uma chamada ao serviço QueryOrder, para tentar localizar seu pedido. Caso ele não tenha sido aprovado, sinta-se livre para tentar aprová-lo novamente atraves do serviço RetryOrder ou informe ao seu cliente que a transação não foi aprovada e continuar com o fluxo do seu negócio. Fluxo sugerido quando o sistema fica offline