Gerenciar saldos pré-pagos da conta

Você está lendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X. info

Para gerenciar o saldo de uma conta pré-paga, você pode:

• Confira o saldo atual da conta pré-paga. Consulte Como ver saldos de contas pré-pagas usando a API.
• Recarregue (adicione dinheiro ao) saldo da conta conforme necessário usando um provedor de pagamentos terceirizado, como o Worldpay. Consulte Gerenciar saldos pré-pagos usando um provedor de pagamento terceirizado.

  Outra opção é gerenciar a recarga rastreando os pagamentos manualmente ou usando um sistema de faturamento integrado e chamando a API de monetização para recarregar a conta, conforme descrito em Gerenciar saldos pré-pagos manualmente.

• Configure a recarga automática quando o saldo da conta de uma conta pré-paga ficar abaixo de um determinado limite usando a API de monetização e um provedor de pagamentos terceirizado, como o Worldpay. Essa opção é útil para gerenciar pagamentos recorrentes de planos de tarifas. Para mais informações, consulte Configurar a recarga automática de saldos de contas pré-pagas usando a API.

Como faço para calcular o saldo restante da conta pré-paga?

Ao visualizar o saldo da conta pré-paga de um desenvolvedor ou empresa, conforme descrito nas seções a seguir, você precisa extrair os seguintes valores da resposta:

• amount: valor total disponível para o período de faturamento atual. Esse valor é atualizado quando você recarrega a conta pré-paga usando os métodos descritos nesta seção.
• usage: valor total usado durante o período de faturamento atual. Esse valor é atualizado com cada transação qualificada monetizada ou ao emitir um crédito (positivo ou negativo).

Para calcular o saldo restante da conta pré-paga no período de faturamento atual, subtraia o valor usage do valor amount. Por exemplo, se o valor de amount for 335,50 e o valor de usage for 34, o saldo restante será calculado da seguinte forma:

amount(335.50) - usage(34) = 229.50

Como consultar saldos de contas pré-pagas usando a API

As seções a seguir descrevem como visualizar saldos de contas pré-pagas de um desenvolvedor ou empresa usando a API.

Como visualizar saldos pré-pagos da conta de um desenvolvedor

Para conferir os saldos das contas pré-pagas de um desenvolvedor, emita uma solicitação GET para uma das seguintes APIs, em que {developer_id} é o endereço de e-mail do desenvolvedor:

• /mint/organizations/{org_name}/developers/{developer_id}/developer-balances: retorna o saldo da conta pré-paga e informações de configuração recorrente para um desenvolvedor.
• /mint/organizations/{org_name}/developers/{developer_id}/prepaid-developer-balances: retorna informações sobre o saldo da conta pré-paga, incluindo saldo atual e total, uso, recargas e tributos sobre o uso.

É possível transmitir os seguintes parâmetros de consulta para filtrar os resultados:

Exemplo:

$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/{developer_id}/developer-balances" \
-u email:password

Veja a seguir um exemplo de resposta:

{
    "developerBalance": [
        {
            "amount": 2005,
            "chargePerUsage": false,
            "id": "your-provider-id",
            "isRecurring": false,
            "supportedCurrency": {
                "description": "United States Dollars",
                "displayName": "United States Dollars",
                "id": "usd",
                "name": "USD",
                "organization": {
                    "address": [
                        {
                            "address1": "10 Almaden Blvd.",
                            "city": "San Jose",
                            "country": "US",
                            "id": "32e808d8-3a3c-4d76-a0ae-17d70a982c61",
                            "isPrimary": true,
                            "state": "CA",
                            "zip": "95113"
                        }
                    ],
                    "approveTrusted": false,
                    "approveUntrusted": false,
                    "billingCycle": "CALENDAR_MONTH",
                    "country": "US",
                    "currency": "USD",
                    "description": "my-org",
                    "groupOrganization": false,
                    "hasBillingAdjustment": false,
                    "hasBroker": false,
                    "hasSelfBilling": false,
                    "hasSeparateInvoiceForProduct": false,
                    "id": "my-org",
                    "issueNettingStmt": false,
                    "name": "my-org",
                    "nettingStmtPerCurrency": false,
                    "selfBillingAsExchOrg": false,
                    "selfBillingForAllDev": false,
                    "separateInvoiceForFees": false,
                    "status": "ACTIVE",
                    "supportedBillingType": "BOTH",
                    "taxModel": "HYBRID",
                    "timezone": "UTC"
                },
                "status": "ACTIVE",
                "virtualCurrency": false
            },
            "usage": 2.1572
        }
    ],
    "totalRecords": 1
}

Como ver saldos pré-pagos da conta de uma empresa

Para conferir os saldos das contas pré-pagas de uma empresa, emita uma solicitação GET para /mint/organizations/{org_name}/companies/{company_id}/developer-balances, em que {company_id} é o ID da empresa. Se a empresa for pré-paga, a solicitação vai recuperar o saldo atual da conta pré-paga. Se a empresa for pós-paga, a solicitação vai recuperar o limite de crédito atual.

É possível transmitir os seguintes parâmetros de consulta para filtrar os resultados:

Exemplo:

$ curl -H "Accept:application/json" -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/companies/{company_id}/developer-balances" \
-u email:password

A resposta é semelhante à mostrada acima, ao visualizar os saldos de contas pré-pagas de um desenvolvedor.

Como gerenciar saldos de conta pré-pagos usando um provedor de pagamento

Gerencie saldos pré-pagos da conta configurando uma conta de comerciante com um provedor de pagamentos terceirizado, como a Worldpay. A figura a seguir mostra como o saldo da conta pré-paga é gerenciado usando o provedor de pagamentos Worldpay.

A tabela a seguir descreve cada etapa do fluxo de gerenciamento de saldo da conta pré-paga, mostrado acima.

{
    "isRecurring": "false",
    "orderCode": "1234",
    "referenceId": "3042815493",
    "referenceUrl": "https://secure.worldpay.com/wcc/dispatcher?OrderKey=MERCH_CODE_FROM_PROVIDER%5E1234",
    "success": "true"
}

As seções a seguir descrevem as etapas necessárias para gerenciar saldos pré-pagos usando um provedor de pagamentos terceirizado:

• Como configurar uma conta de comerciante com o provedor de pagamentos Worldpay
• Como configurar o provedor de pagamento no Edge
• Como visualizar os provedores de pagamento configurados para sua organização
• Ativar e configurar os módulos necessários no portal do desenvolvedor
• Início de pagamento para uma conta pré-paga usando um provedor de pagamentos
• Recarregar o saldo de uma conta pré-paga usando a API
• Excluir um provedor de pagamentos terceirizado

Configurar uma conta do comerciante com o provedor de pagamentos Worldpay

Antes de começar, entre em contato com um provedor de pagamento terceirizado (Worldpay) para configurar suas contas do comerciante. Recomendamos que você configure duas contas, uma para testes e outra para produção. Para mais informações sobre contas de comerciante do Worldpay, acesse www.worldpay.com e wp-support.crm.worldpay.com (Central de suporte do Worldpay).

Depois de configurar sua conta do comerciante e receber as credenciais dela, faça o seguinte para configurar sua conta do comerciante com o Worldpay:

1. Acesse https://secure.worldpay.com/sso/public/auth/login.html.
2. Faça login na sua conta do Worldpay usando as credenciais fornecidas por eles.
3. Defina a senha XML e a chave secreta do código de autenticação de mensagem (MAC):
   1. Clique em Perfil.
   2. Defina a senha a ser usada ao configurar o provedor de pagamentos Worldpay no Edge no campo Senha XML.
   3. Insira uma chave secreta MAC de 20 a 30 caracteres no campo Segredo MAC de redirecionamento.
   4. Clique em Salvar perfil.
4. Adicione o servidor de gerenciamento do Apigee Edge à lista de IPs do comerciante (lista de permissões):
   1. Clique em Perfil > Ambiente do comerciante.
   2. Clique em Novo IP de teste.
   3. Insira o IP do servidor de gerenciamento da Apigee Edge.
   4. Clique em Salvar.
5. Configure o URL do comerciante para anexar os parâmetros do Worldpay, incluindo o código de autenticação do método (MAC):
   1. Clique em Instalações > Páginas de pagamento hospedadas > Designer de páginas de pagamento.
   2. Em Editar páginas de pagamento, selecione seu ID de instalação na lista suspensa Selecionar canal.
   3. Na guia "Propriedades", selecione Editar configuração do comerciante.
   4. Defina o valor "Enviar parâmetros de URL" como Verdadeiro.
   5. Clique na guia Publicar.
   6. Promova as mudanças da seguinte maneira:
      • Para ambientes de teste, clique em Promover em Design para promover do Design para o Sandbox.
      • Para ambientes de produção, clique em Promover em Sandbox para promover do sandbox para a produção.

Como configurar o provedor de pagamento no Edge

A próxima etapa é configurar o provedor de pagamento no Edge.

É possível configurar seu provedor de pagamentos para uma organização específica usando a seguinte API:

/organizations/{org-name}/providers

Somente clientes do Apigee Edge Private Cloud com privilégios de administrador do sistema podem configurar um provedor de pagamento global usando a seguinte API:

/config/providers

Ao chamar cada API, especifique as seguintes informações no corpo da solicitação:

Por exemplo, o comando a seguir configura uma conta de comerciante com o Worldpay chamada Worldpay-myorg:

$ curl  -H "Content-Type:application/json" -X POST -d \
'{
    "name": "Worldpay-myorg",
    "description": "Worldpay payment provider",
    "endpoint": "https://secure.worldpay.com/jsp/merchant/xml/paymentService.jsp",
    "authType": "123456",
    "credential": "dXNlcm5hbWU6cGFzc3dvcmQ=",
    "merchantCode": "myMerchantCode"
  }' \
"https://api.enterprise.apigee.com/v1/organizations/myOrg/providers" \
-u email:password 

Visualizar provedores de pagamento terceirizados

Confira e confirme os provedores de pagamento terceirizados configurados para sua organização do Edge emitindo uma solicitação GET para o seguinte recurso:

/mint/organizations/{org-name}/providers

Por exemplo, o seguinte mostra os provedores de pagamento terceirizados configurados para myorg:

$ curl  -X GET \
"https://api.enterprise.apigee.com/v1/mint/organizations/myorg/providers" \
-u email:password

Confira a seguir um exemplo da resposta mostrando duas contas de comerciante, uma para teste e outra para produção.

{
  "provider" : [ {
    "authType" : "123456",
    "credential" : "dXNlcm5hbWU6cGFzc3dvcmQ=",
    "description" : "Worldpay payment provider",
    "endpoint" : "https://secure.worldpay.com/jsp/merchant/xml/paymentService.jsp",
    "id" : "worldpay-myorg",
    "merchantCode" : "MERCH_CODE",
    "name" : "Worldpay-myorg"
  }, {
    "authType" : "123456",
    "credential" : "dXNlcm5hbWU6cGFzc3dvcmQ=",
    "description" : "Worldpay payment provider",
    "endpoint" : "https://secure-test.worldpay.com/jsp/merchant/xml/paymentService.jsp",
    "id" : "worldpay-test",
    "merchantCode" : "MERCH_CODE_FROM_PROVIDER",
    "name" : "Worldpay-test"
  } ]
}

Como ativar e configurar os módulos de monetização e Worldpay no portal do desenvolvedor

Ative os módulos necessários de monetização e Worldpay no portal do desenvolvedor. Para mais detalhes, consulte Configurar a monetização no portal do desenvolvedor.

Iniciar o pagamento para uma conta pré-paga usando o provedor de pagamentos

Conforme mostrado na etapa 2 do fluxo de gerenciamento de contas pré-pagas, o pagamento a uma conta pré-paga usando um provedor de pagamentos é iniciado pelo portal do desenvolvedor quando os consumidores de API:

• Aceitar um plano de tarifas, mas não ter fundos suficientes na conta pré-paga
• Peça para adicionar dinheiro à conta pré-paga.

Para iniciar um pagamento de um provedor de pagamento terceirizado usando a API, emita uma solicitação POST para o seguinte recurso, em que {developer_id} é o endereço de e-mail do desenvolvedor.

/mint/organizations/{org_name}/developers/{developer_id}/payment?amount={amount}&provider={providerId}&supportedCurrencyId={currency}

Ao emitir a solicitação, especifique os seguintes valores como parâmetros de consulta:

• Valor a ser adicionado ao saldo da conta pré-paga (amount={amount})
• ID do provedor de pagamentos (provider={providerId})
• Moeda aceita (supportedCurrencyId={currency})

Além disso, você precisa transmitir detalhes básicos da conta, como o endereço de faturamento da empresa.

Por exemplo, o comando a seguir recarrega o saldo da conta pré-paga usando o provedor de pagamentos Worldpay. A transferência inicial para sua conta pré-paga será de US$ 10 (o parâmetro de consulta amount está definido como 10).

$ curl  -H "Content-Type:application/xml" -X POST -d \
'{
    "address1": "5115 Hopyard Ave.",
    "city": "Pleasanton",
    "country": "US",
    "state": "CA",
    "zip": "58158"
}'
' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/{developer_id}/payment?amount=10&provider=worldpay-myorg&supportedCurrencyId=usd" \
-u email:password

Veja a seguir um exemplo de resposta:

{
    "isRecurring": "false",
    "orderCode": "1234",
    "referenceId": "3042815493",
    "referenceUrl": "https://secure.worldpay.com/wcc/dispatcher?OrderKey=MERCH_CODE_FROM_PROVIDER%5E1234",
    "success": "true"
}

O URL da página de pagamento seguro do Worldpay é retornado em referenceUrl com sua chave de pedido exclusiva anexada como um parâmetro de consulta.

Como recarregar o saldo da conta pré-paga usando a API

Conforme mostrado na etapa 15 do fluxo de gerenciamento de contas pré-pagas, depois de verificar o processamento bem-sucedido pelo provedor de pagamentos, o portal do desenvolvedor envia uma solicitação ao Edge para recarregar a conta pré-paga.

É possível recarregar o saldo da conta pré-paga usando a API para um desenvolvedor ou empresa, conforme descrito nas seções a seguir.

Recarregar o saldo da conta pré-paga para um desenvolvedor

Para recarregar o saldo da conta pré-paga de um desenvolvedor usando a API, emita uma solicitação POST para /mint/organizations/{org_name}/developers/{developer_id}/developer-balances, em que {developer_id} é o endereço de e-mail do desenvolvedor. Ao fazer a solicitação, especifique no corpo dela o valor a ser adicionado ao saldo e a moeda usada.

Por exemplo, a solicitação a seguir adiciona US $1.000 ao saldo da conta pré-paga de um desenvolvedor:

$ curl -H "Content-Type:application/json" -X POST -d \
'{
  "amount": 1000,
  "supportedCurrency": {
      "id": "usd" 
  } 
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/{developer_id}/developer-balances" \
-u email:password

Para uma descrição das propriedades da solicitação, consulte Resumo das propriedades de solicitação para recarregar uma conta pré-paga.

Recarregar o saldo da conta pré-paga para uma empresa

Para recarregar o saldo da conta pré-paga de uma empresa usando a API, emita uma solicitação POST para /mint/organizations/{org_name}/companies/{company_id}/developer-balances, em que {company_id} é o ID da empresa. Ao fazer a solicitação, especifique no corpo dela o valor a ser adicionado ao saldo e a moeda usada.

Por exemplo, a solicitação a seguir adiciona US $1.000 ao saldo da conta pré-paga de uma empresa:

$ curl -H "Content-Type:application/json" -X POST -d \
'{
  "amount": 1000,
  "supportedCurrency": {
      "id": "usd" 
  } 
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/companies/{company_id}/developer-balances" \
-u email:password

Para uma descrição das propriedades da solicitação, consulte Resumo das propriedades de solicitação para recarregar uma conta pré-paga.

Resumo das propriedades da solicitação para recarregar uma conta pré-paga

As propriedades a seguir precisam ser especificadas ao recarregar saldos de contas pré-pagas usando a API:

Excluir provedores de pagamento terceirizados

É possível excluir um provedor de pagamento terceirizado configurado para sua organização do Edge emitindo uma solicitação DELETE para o seguinte recurso:

Para excluir um provedor de pagamento de uma organização específica, use a seguinte API:

/mint/organizations/{org-name}/providers/id

Somente clientes da nuvem privada do Apigee Edge com privilégios de administrador do sistema podem excluir um provedor de pagamento global usando a seguinte API:

/config/providers/id

Por exemplo, o comando a seguir exclui os provedores de pagamento de terceiros configurados para myorg:

$ curl  -X DELETE \
"https://api.enterprise.apigee.com/v1/mint/organizations/myorg/providers/worldpay-myorg" \
-u email:password

Como gerenciar saldos pré-pagos da conta manualmente

Outra opção é gerenciar a recarga de saldos pré-pagos rastreando pagamentos manualmente ou usando um sistema de faturamento integrado e chamando a API de monetização para recarregar o saldo da conta, conforme descrito em Recarregar o saldo de uma conta pré-paga usando a API.

Configurar a recarga automática dos saldos de contas pré-pagas usando a API

As seções a seguir descrevem como configurar a recarga automática dos saldos de contas pré-pagas para um desenvolvedor ou empresa usando um provedor de pagamentos terceirizado. Essa opção é útil para gerenciar pagamentos recorrentes de planos de tarifas.

Configurar a recarga automática dos saldos pré-pagos da conta de um desenvolvedor

Para configurar a recarga automática do saldo de uma conta pré-paga de um desenvolvedor quando o saldo ficar abaixo de um determinado limite, emita uma solicitação POST para /mint/organizations/{org_name}/developers/{developer_id}/developer-balances/recurring-setup, em que {developer_id} é o endereço de e-mail do desenvolvedor.

Ao emitir a solicitação, especifique o seguinte:

• ID do provedor de pagamentos a ser usado para recarregar a conta (providerID)
• Flag que ativa a recarga automática (isRecurring)
• Limite abaixo do qual o saldo da conta pré-paga precisa ficar para acionar a recarga automática (replenishAmount)
• Valor a ser adicionado automaticamente à conta (recurringAmount)
• Parâmetro de consulta supportedCurrencyID para especificar a moeda.

No exemplo a seguir, quando o saldo da conta pré-paga do desenvolvedor cai abaixo de US$ 5, outros US$ 10 são adicionados automaticamente à conta.

$ curl -H "Content-Type:application/json" -X POST -d \
'{
    "providerId": "worldpay-myorg",
    "isRecurring" : true,
    "replenishAmount" : 5,
    "recurringAmount" : 10
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/developers/{developer_id}/developer-balances/recurring-setup?supportedCurrencyId=usd" \
-u email:password

Para uma descrição das propriedades da solicitação, consulte Resumo das propriedades de solicitação para configurar a recarga automática de contas pré-pagas.

Como configurar a recarga automática de saldos pré-pagos de uma empresa

Para configurar a recarga automática do saldo de uma conta pré-paga de uma empresa quando ele ficar abaixo de um determinado valor, emita uma solicitação POST para /mint/organizations/{org_name}/companies/{company_id}/developer-balances/recurring-setup, em que {company_id} é o ID da empresa.

Ao emitir a solicitação, especifique o seguinte:

• ID do provedor de pagamentos a ser usado para recarregar a conta (providerID)
• Flag que ativa a recarga automática (isRecurring)
• Limite abaixo do qual o saldo da conta pré-paga precisa ficar para acionar a recarga automática (replenishAmount)
• Valor a ser adicionado automaticamente à conta (recurringAmount)
• Parâmetro de consulta supportedCurrencyID para especificar a moeda.

No exemplo a seguir, quando o saldo da conta pré-paga da empresa cai abaixo de US$ 5, outros US$ 10 são adicionados automaticamente à conta.

$ curl -H "Content-Type:application/json" -X POST -d \
'{
    "providerId": "worldpay-myorg",
    "isRecurring" : true,
    "replenishAmount" : 5,
    "recurringAmount" : 10
}' \
"https://api.enterprise.apigee.com/v1/mint/organizations/{org_name}/companies/{company_id}/developer-balances/recurring-setup?supportedCurrencyId=usd" \
-u email:password

Para uma descrição das propriedades da solicitação, consulte Resumo das propriedades de solicitação para configurar a recarga automática de contas pré-pagas.

Resumo das propriedades de solicitação para configurar a recarga automática de contas pré-pagas

Os atributos a seguir podem ser especificados ao recarregar automaticamente os saldos de contas pré-pagas usando a API.

Migrar para as páginas de pagamento hospedadas do WorldPay

O WorldPay atualizou o fluxo seguro de processamento de pagamentos para usar um novo conjunto de páginas, chamadas de páginas de pagamento hospedadas.

Se você configurou seus provedores de pagamento do WorldPay usando o fluxo de processamento de pagamentos seguros descontinuado (antes de agosto de 2017), migre para as novas páginas de pagamento hospedadas do WorldPay antes de janeiro de 2018.

Para migrar para as páginas de pagamento hospedadas da WorldPay:

1. Entre em contato com a WorldPay para migrar sua conta atual e usar as novas páginas de pagamento hospedadas e receber um novo ID de instalação para sua conta.
2. Configure novos provedores de pagamento do WorldPay, conforme descrito em Configurar o provedor de pagamento no Edge, transmitindo o ID de instalação no campo authType.
3. Configure os novos provedores de pagamento no portal do desenvolvedor, conforme descrito em Configurar a monetização no portal do desenvolvedor.
4. Se você configurar a recarga automática de uma conta pré-paga usando o provedor de pagamentos, precisará reconfigurar a recarga automática para usar o novo ID do provedor, conforme descrito em Configurar a recarga automática de saldos de contas pré-pagas usando a API.

Próximas etapas

É possível definir limites de crédito para desenvolvedores pós-pagos individuais. Saiba como em Gerenciar saldos pós-pagos.