Gerenciar saldos pré-pagos da conta

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

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

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

  Também é possível gerenciar a recarga rastreando pagamentos manualmente ou por 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 de uma conta pré-paga cair abaixo de um determinado limite usando a API Monetização e um provedor de pagamento de terceiros, como a Worldpay. Essa opção é útil para gerenciar pagamentos recorrentes para planos de tarifas. Para mais informações, consulte Configurar recarga automática de saldos de contas pré-pagas usando a API.

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

Ao acessar o saldo da conta pré-paga de um desenvolvedor ou de uma empresa, conforme descrito nas seções a seguir, é necessário 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 do dinheiro usado durante o período de faturamento atual. Esse valor é atualizado com cada transação qualificada monetizada ou emitindo um crédito (positivo ou negativo).

É possível calcular o saldo restante da conta pré-paga para o período de faturamento atual subtraindo o valor de usage do 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 maneira:

amount(335.50) - usage(34) = 229.50

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

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

Como conferir os saldos pré-pagos da conta de um desenvolvedor

Para conferir os saldos de 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 as 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 imposto de 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 conferir os saldos pré-pagos da conta de uma empresa

Para visualizar os saldos de 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 conferir o saldo de uma conta pré-paga de um desenvolvedor.

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

Gerenciar saldos pré-pagos da conta configurando uma conta de comerciante com um provedor de pagamento de terceiros, 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 de contas pré-pagas 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 de terceiros:

• Configurar uma conta de comerciante com o provedor de pagamento 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
• Como iniciar o pagamento de uma conta pré-paga usando um provedor de pagamentos
• Como recarregar o saldo de uma conta pré-paga usando a API
• Como excluir um provedor de pagamentos de terceiros

Como configurar uma conta de comerciante com o provedor de pagamentos Worldpay

Antes de começar, entre em contato com um provedor de pagamento de terceiros (Worldpay) para configurar suas contas de comerciante. É recomendável configurar duas contas, uma para testes e outra para produção. Para mais informações sobre as contas de comerciante da Worldpay, acesse www.worldpay.com e wp-support.crm.worldpay.com (central de suporte da Worldpay).

Depois de configurar sua conta do comerciante e receber as credenciais, siga estas etapas para configurar a conta com a Worldpay:

1. Acesse https://secure.worldpay.com/sso/public/auth/login.html.
2. Faça login na sua conta da Worldpay usando as credenciais fornecidas pela empresa.
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 pagamento da Worldpay no Edge no campo Senha XML.
   3. Insira uma chave secreta MAC de 20 a 30 caracteres no campo Redirect MAC secret.
   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. Informe o IP do servidor de gerenciamento do Apigee Edge.
   4. Clique em Salvar.
5. Configure o URL do comerciante para anexar os parâmetros da Worldpay, incluindo o código de autenticação do método (MAC):
   1. Clique em Instalações > Páginas de pagamento hospedadas > Designer da página 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 de parâmetros de URL de envio como True.
   5. Clique na guia Publish.
   6. Promova 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 Promote 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 pagamento para uma organização específica usando a seguinte API:

/organizations/{org-name}/providers

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

/config/providers

Ao chamar cada API, é necessário especificar as seguintes informações no corpo da solicitação:

Por exemplo, o comando a seguir configura uma conta de comerciante com a 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 

Como acessar provedores de pagamentos terceirizados

Para conferir e confirmar os provedores de pagamento de terceiros configurados para sua organização do Edge, emita uma solicitação GET para o seguinte recurso:

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

Por exemplo, o exemplo a seguir mostra os provedores de pagamento de terceiros atualmente configurados para myorg:

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

Confira a seguir um exemplo de resposta que mostra duas contas de comerciante, uma para testes 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 de monetização e Worldpay necessários no portal do desenvolvedor. Para mais detalhes, consulte Configurar a monetização no Portal do desenvolvedor.

Como iniciar um pagamento em uma conta pré-paga usando o provedor de pagamentos

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

• Aceitar um plano de tarifa, mas não tiver saldo suficiente na conta pré-paga
• Pedir 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 recurso a seguir, 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, você precisa especificar 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, é necessário transmitir detalhes básicos da conta, como o endereço de faturamento da empresa.

Por exemplo, o sistema a seguir recarrega um saldo de conta pré-paga usando o provedor de pagamento Worldpay. A transferência inicial para sua conta pré-paga será de 10 dólares americanos (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 da Worldpay é retornado em referenceUrl com sua chave de pedido exclusiva anexada como um parâmetro de consulta.

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

Conforme mostrado na etapa 15 do fluxo de gerenciamento de contas pré-pagas, depois de verificar o processamento pelo provedor de pagamento, 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 pré-pago de um desenvolvedor

Para recarregar o saldo de uma conta pré-paga de um desenvolvedor usando a API, envie 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 emitir a solicitação, é necessário especificar no corpo da solicitação 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 da solicitação para recarregar uma conta pré-paga.

Como recarregar o saldo pré-pago de uma conta de empresa

Para recarregar o saldo de uma 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 emitir a solicitação, é necessário especificar no corpo da solicitação 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 o Resumo das propriedades da solicitação para recarregar uma conta pré-paga.

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

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

Como excluir provedores de pagamento terceirizados

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

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

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

Somente clientes do Apigee Edge para nuvem privada 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 atualmente 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

Como alternativa, é possível gerenciar a recarga de saldos pré-pagos rastreando pagamentos manualmente ou usando um sistema de faturamento integrado e, em seguida, chamando a API Monetização para recarregar a conta, conforme descrito em Como recarregar o saldo de uma conta pré-paga usando a API.

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

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

Configurar a atualização automática de saldos de contas pré-pagas de um desenvolvedor

Para configurar o recarregamento automático do saldo de uma conta pré-paga de um desenvolvedor quando o saldo cair 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, você precisa especificar o seguinte:

• ID do provedor de pagamento a ser usado para recarregar a conta (providerID)
• Flag que ativa a recarga automática (isRecurring)
• Limite mínimo que o saldo da conta pré-paga precisa atingir 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 abaixo, quando o saldo da conta pré-paga do desenvolvedor cai abaixo de US$ 5, US$ 10 adicionais 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 de solicitação, consulte Resumo das propriedades de solicitação para configurar a recarga automática de contas pré-pagas.

Configurar a recarga automática de saldos de contas pré-pagas para uma empresa

Para configurar a atualização automática do saldo de conta pré-paga de uma empresa quando o saldo 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, você precisa especificar o seguinte:

• ID do provedor de pagamentos a ser usado para recarregar a conta (providerID)
• Flag que ativa a recarga automática (isRecurring)
• Limite mínimo que o saldo da conta pré-paga precisa atingir 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 abaixo, quando o saldo da conta pré-paga da empresa cai abaixo de US$ 5, US$ 10 adicionais 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 de 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 abaixo podem ser especificados ao recarregar saldos de contas pré-pagas automaticamente usando a API.

Como migrar para as páginas de pagamento hospedadas da WorldPay

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

Se você configurou os provedores de pagamento da WorldPay usando o fluxo de processamento de pagamento seguro descontinuado (antes de agosto de 2017), será necessário migrar para as novas páginas de pagamento hospedado da 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.
2. Configure novos provedores de pagamento da WorldPay, conforme descrito em Como 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 o recarregamento automático de uma conta pré-paga usando o provedor de pagamento, será necessário reconfigurar o recarregamento automático para usar o novo ID do provedor, conforme descrito em Como configurar o recarregamento automático 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 fazer isso em Gerenciar saldos pós-pagos.