Postar reembolsos

Você está vendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X.
informações

Introdução

A monetização permite que você publique reembolsos para "transações de compra". Suponha que você seja uma operadora de celular e ofereça aos desenvolvedores uma API de pagamento para cobrar assinantes de dispositivos móveis pela compra de um aplicativo ou conteúdo no aplicativo. Cada vez que um assinante usa a API para fazer uma compra, essa transação é considerada.

As transações de compra podem resultar em reembolsos. Por exemplo, o conteúdo pode não ser entregue ou o terceiro pode estar insatisfeito com a compra. Nesses casos, o desenvolvedor emite um reembolso para o terceiro. Com a monetização, você pode fazer um reembolso equivalente. Isso é especialmente pertinente para planos de participação na receita.

Imagine que o desenvolvedor que emitiu o reembolso para o assinante de dispositivo móvel comprou um plano de participação na receita do seu produto de API. Suponha que o plano peça para o desenvolvedor receber 70% do preço líquido/bruto da transação de compra. Ao postar um reembolso, você reverte a transação de compra, ou seja, deduz 70% do pagamento devido ao desenvolvedor no mês em que o reembolso foi aplicado. Esse mês pode ser diferente daquele em que ocorreu a transação de compra real.

Publicar um reembolso usando a interface clássica do Edge (somente no Edge para nuvem privada)

É possível publicar um reembolso para qualquer transação de compra bem-sucedida, ou seja, quando a API fez a cobrança do terceiro e você ainda não emitiu um reembolso total. Publicar um reembolso resulta na criação de uma transação de reembolso com um ID de transação principal, em que o ID é o ID da transação de compra.

Você pode postar um reembolso do valor total da transação de compra original ou de um valor parcial. Também é possível publicar vários reembolsos parciais, mas o valor total deles não pode ser maior do que o valor original da compra.

Para postar um reembolso:

  1. Na guia "Monetização", selecione "Reembolsos".

    A página "Reembolsos" será aberta.

  2. No menu suspenso "Mês do faturamento", selecione o mês em que a transação de compra ocorreu. Em seguida, clique em "+ Reembolsos".

    Uma lista de todas as transações de compra concluídas no mês selecionado será exibida.

    É possível filtrar a lista de reembolso por nome do desenvolvedor ou pesquisando a transação real.

    Para filtrar por desenvolvedor, selecione o desenvolvedor no menu suspenso "Desenvolvedor". Uma lista apenas das transações relacionadas ao desenvolvedor selecionado vai aparecer.

    Para filtrar por ID da transação, insira o ID da compra original que você quer reembolsar. Isso retorna a transação para esse ID.

  3. Marque a caixa de seleção nas linhas das transações que você quer reembolsar.
  4. Selecione Total ou Parcial no menu suspenso Tipo.

    Se você selecionar "Total", o valor total da compra será reembolsado. Se você selecionar Parcial, um valor parcial da compra será reembolsado.

    Se você selecionar Parcial, insira o valor do reembolso parcial no campo Valor. É possível reembolsar somente o valor total da compra. Se você já tiver publicado um reembolso parcial, só poderá inserir um valor até o valor restante da compra. Além disso, se a transação de compra original tiver preços brutos e líquidos, você também precisará indicar se o valor parcial que quer reembolsar é bruto ou líquido.

  5. Clique em Salvar para processar o reembolso (ou em Cancelar para cancelar).

    O reembolso será lançado no mês da compra original se o mês de faturamento ainda estiver aberto. Caso contrário, o reembolso será lançado para a data atual.

    Para um reembolso parcial, o valor parcial é processado, e qualquer participação na receita é deduzida com base na proporção desse valor sobre o valor total. No exemplo de reembolso parcial acima, o valor parcial é 0,50/1,12 = 45% do preço bruto, ou seja, 45% da participação na receita do desenvolvedor será deduzida.

Verificar na interface se um reembolso foi processado

Para determinar se um reembolso foi processado, selecione o mês de faturamento na parte de cima da página "Reembolsos". Esse será o mês da compra se o mês de faturamento ainda estiver aberto ou o mês atual se o mês de faturamento estiver fechado. Isso exibe uma lista de todos os reembolsos postados no mês.

Como publicar um reembolso usando a API

Para publicar um reembolso, emita uma solicitação POST para /organizations/{org_name}/monetization-packages/{package_id}/refund-transactions, em que {package_id} é a identificação do pacote de API a que o reembolso se aplica.

Ao emitir a solicitação, você precisa especificar como parâmetros de consulta:

  • A identificação da transação de compra que está sendo reembolsada.
  • O tipo de receita (GROSS ou NET) da transação de compra.
  • O valor do reembolso.
  • Uma observação descrevendo o motivo do reembolso.

Outra opção é identificar um pacote de API a que o reembolso se aplica como parâmetro de URL.

Consulte Configurações de reembolso para ver uma lista completa dos parâmetros de URL que podem ser especificados em uma solicitação de reembolso.

Por exemplo, a solicitação a seguir emite um reembolso para uma transação de compra. O valor do reembolso é 50% do valor bruto da transação de compra.

$ curl -H "Content-Type:application/json" -X POST \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/monetization-packages/payment/refund-transactions?revenueType=GROSS&refundAmount=0.5&parentTxId=abf50909-2492-4bf5-8704-ade05f4d43b3&transactionNote=Refund for purchase transaction" \
-u email:password

A resposta deve ser semelhante a esta (apenas parte da resposta é exibida):

{
  "application" : {
    ...
    },
    "product" : [ {
      ...
      
     {
      "customAtt1Name" : "user",
      "description" : "Payment",
      "displayName" : "Payment",
      "id" : "payment",
      "name" : "payment",
      "organization" : {
        ...
      },
      "status" : "CREATED",
      "transactionSuccessCriteria" : "Status=='200 OK'"
    } ],
    ...
  },
  "currency" : "USD",
  "developer" : {
    ...
    "legalName" : "DEV ONE",
    "name" : "Dev One",
    "organization" : {
      ...
    },
    ...
  },
  "endTime" : "2013-09-01 21:59:59",
  "environment" : "PROD",
  "euroExchangeRate" : 0.8123,
  "gbpExchangeRate" : 0.6910,
  "grossPrice" : 0.5,
  "id" : "61f7eb88-f8cc-4cda-afd8-4a61fba3dd33",
  "isRevOnGrossOrNet" : "NET",
  "isVirtualCurrency" : false,
  "notes" : "Refund for purchase transaction",
  "itemDesc" : "test application",
  "netPrice" : 0.4464,
  "orgRevenueShareAmount" : 0.1339,
  "parentId" : "abf50909-2492-4bf5-8704-ade05f4d43b3",
  "pkgId" : "myorg@@@payment",
  "pkgRatePlanProductName" : "Payment",
  ...
  },
  "ratePlanLevel" : "STANDARD",
  "revenueShareAmount" : 0.3125,
  "startTime" : "2013-09-01 21:59:59",
  "status" : "SUCCESS",
  "tax" : 0.0536,
  "taxModel" : "UNDISCLOSED",
  "txProviderStatus" : "SUCCESS",
  "type" : "REFUND",
  "usdExchangeRate" : 1.0724,
  "utcEndTime" : "2013-09-01 21:59:59",
  "utcStartTime" : "2013-09-01 21:59:59"
}

Configurações de reembolso para a API

Os seguintes parâmetros de consulta podem ser especificados em uma solicitação de reembolso:

Nome Descrição Padrão Obrigatório?
monetizationPackageId

O pacote de API a que o reembolso se aplica.

N/A Não
parentTxId

A transação de compra a ser reembolsada.

N/A Sim
revenueType

O tipo de receita (GROSS ou NET) da transação de compra.

N/A Sim
refundAmount

O valor do reembolso.

N/A Sim
transactionNote

Uma observação de texto que descreve o motivo do reembolso.

N/A Sim

Próximas etapas

Saiba como programar tarefas relacionadas a monetização e sobre aquelas que são programadas automaticamente em Programar jobs de monetização.