Administra los saldos de cuenta prepagas

Estás viendo la documentación de Apigee Edge.
Ir a la documentación de Apigee X. info

Para administrar el saldo de una cuenta prepaga, puedes hacer lo siguiente:

• Consulta el saldo actual de la cuenta prepaga. Consulta Cómo ver los saldos de las cuentas prepagadas con la API.
• Recargar (agregar dinero a) el saldo de la cuenta según sea necesario con un proveedor de pagos externo, como Worldpay Consulta Cómo administrar saldos prepagados con un proveedor de pagos externo.

  Como alternativa, puedes administrar la recarga haciendo un seguimiento de los pagos de forma manual o a través de un sistema de facturación integrado y, luego, llamar a la API de monetización para recargar la cuenta, como se describe en Cómo administrar los saldos prepagados de forma manual.

• Configura la recarga automática cuando el saldo de una cuenta prepagada cae por debajo de un umbral determinado con la API de Monetization y un proveedor de pagos externo, como Worldpay. Esta opción es útil para administrar los pagos recurrentes de los planes de tarifas. Para obtener más información, consulta Cómo configurar la recarga automática de saldos de cuentas prepagadas con la API.

¿Cómo calculo el saldo restante de la cuenta prepagada?

Cuando consultes el saldo de cuenta prepaga de un desarrollador o una empresa, como se describe en las siguientes secciones, deberás obtener los siguientes valores de la respuesta:

• amount: Es la cantidad total de dinero disponible para el período de facturación actual. Este valor se actualiza cuando recargas la cuenta prepagada con los métodos que se describen en esta sección.
• usage: Es la cantidad total de dinero que se usó durante el período de facturación actual. Este valor se actualiza con cada transacción monetizada apta o con la emisión de un crédito (positivo o negativo).

Puedes calcular el saldo restante de la cuenta prepagada para el período de facturación actual restando el valor de usage del valor de amount. Por ejemplo, si el valor de amount es 335.50 y el valor de usage es 34, el saldo restante se calcularía de la siguiente manera:

amount(335.50) - usage(34) = 229.50

Visualiza los saldos de cuentas prepagadas con la API

En las siguientes secciones, se describe cómo ver los saldos de las cuentas prepagas de un desarrollador o una empresa con la API.

Cómo ver los saldos de las cuentas prepagas de un desarrollador

Para ver los saldos de las cuentas prepagas de un desarrollador, envía una solicitud GET a una de las siguientes APIs, en la que {developer_id} es la dirección de correo electrónico del desarrollador:

• /mint/organizations/{org_name}/developers/{developer_id}/developer-balances: Muestra el saldo de la cuenta prepagada y la información de configuración recurrente para un desarrollador.
• /mint/organizations/{org_name}/developers/{developer_id}/prepaid-developer-balances: Muestra información sobre el saldo de la cuenta prepagada, incluido el saldo actual y total, el uso, las recargas y el impuesto sobre el uso.

Puedes pasar los siguientes parámetros de consulta para filtrar los resultados:

Por ejemplo:

$ 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

A continuación, se proporciona un ejemplo de la respuesta.

{
    "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
}

Cómo ver los saldos de las cuentas prepagas de una empresa

Para ver los saldos de las cuentas prepagadas de una empresa, envía una solicitud GET a /mint/organizations/{org_name}/companies/{company_id}/developer-balances, donde {company_id} es el ID de la empresa. Si la empresa es prepagada, la solicitud recupera el saldo actual de la cuenta prepagada. Si la empresa es pospago, la solicitud recupera el límite de crédito actual.

Puedes pasar los siguientes parámetros de consulta para filtrar los resultados:

Por ejemplo:

$ 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

La respuesta es similar a la que se muestra arriba, cuando se ven los saldos de las cuentas prepagas de un desarrollador.

Administra los saldos de cuenta prepaga con un proveedor de pagos

Administra los saldos de cuenta prepaga configurando una cuenta de comerciante con un proveedor de pagos externo, como Worldpay. En la siguiente figura, se muestra cómo se administra el saldo de las cuentas prepagas con el proveedor de pagos Worldpay.

En la siguiente tabla, se describe cada paso del flujo de administración del saldo de la cuenta prepagada que se muestra arriba.

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

En las siguientes secciones, se describen los pasos necesarios para administrar los saldos prepagados con un proveedor de pagos externo:

• Cómo configurar una cuenta de comerciante con el proveedor de pagos Worldpay
• Configura el proveedor de pagos en Edge
• Cómo ver los proveedores de pagos configurados para tu organización
• Cómo habilitar y configurar los módulos obligatorios en el portal para desarrolladores
• Cómo iniciar un pago a una cuenta prepaga con un proveedor de pagos
• Cómo recargar el saldo de una cuenta prepagada con la API
• Cómo borrar un proveedor de pagos externo

Cómo configurar una cuenta de comerciante con el proveedor de pagos Worldpay

Antes de comenzar, debes comunicarte con un proveedor de pagos externo (Worldpay) para configurar tus cuentas de comerciante. Te recomendamos que configures dos cuentas, una para las pruebas y otra para la producción. Para obtener más información sobre las cuentas de comercio de Worldpay, consulta www.worldpay.com y wp-support.crm.worldpay.com (Centro de ayuda de Worldpay).

Después de configurar tu cuenta de comerciante y recibir las credenciales de la cuenta, sigue estos pasos para configurarla con Worldpay:

1. Navega a https://secure.worldpay.com/sso/public/auth/login.html.
2. Accede a tu cuenta de Worldpay con las credenciales que te proporcionó Worldpay.
3. Establece la contraseña XML y la clave secreta del código de autenticación de mensajes (MAC):
   1. Haz clic en Perfil.
   2. Establece la contraseña que se usará cuando configures el proveedor de pagos de Worldpay en Edge en el campo Contraseña XML.
   3. Ingresa una clave secreta de MAC de entre 20 y 30 caracteres en el campo Secreto de redireccionamiento de MAC.
   4. Haz clic en Guardar perfil.
4. Agrega el servidor de administración de Apigee Edge a la lista de IPs de comercios (lista de entidades permitidas):
   1. Haz clic en Perfil > Entorno del comercio.
   2. Haz clic en New Test IP.
   3. Ingresa la IP del servidor de administración de Apigee Edge.
   4. Haz clic en Guardar.
5. Configura la URL del comercio para agregar los parámetros de Worldpay, incluido el código de autenticación del método (MAC):
   1. Haz clic en Instalaciones > Páginas de pago alojadas > Diseñador de páginas de pago.
   2. En Edit Payment Pages, selecciona tu ID de instalación en la lista desplegable Select channel.
   3. En la pestaña Propiedades, selecciona Editar la configuración del comercio.
   4. Establece el valor de Enviar parámetros de URL en Verdadero.
   5. Haz clic en la pestaña Publicar.
   6. Promueve los cambios de la siguiente manera:
      • En el caso de los entornos de prueba, haz clic en Promote en Design para promover el entorno de diseño al entorno de zona de pruebas.
      • En el caso de los entornos de producción, haz clic en Promote en Sandbox para promover la zona de pruebas a producción.

Configura el proveedor de pagos en Edge

El siguiente paso es configurar el proveedor de pagos en Edge.

Puedes configurar tu proveedor de pagos para una organización específica con la siguiente API:

/organizations/{org-name}/providers

Solo los clientes de Apigee Edge Private Cloud con privilegios de administrador del sistema pueden configurar de forma opcional un proveedor de pagos global con la siguiente API:

/config/providers

Cuando llames a cada API, debes especificar la siguiente información en el cuerpo de la solicitud:

Por ejemplo, el siguiente comando configura una cuenta del comerciante con Worldpay llamada 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 

Cómo ver los proveedores de pagos externos

Para ver y confirmar los proveedores de pagos externos configurados para tu organización de Edge, envía una solicitud GET al siguiente recurso:

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

Por ejemplo, el siguiente comando muestra los proveedores de pagos externos configurados actualmente para myorg:

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

A continuación, se proporciona un ejemplo de la respuesta que muestra dos cuentas de comerciante, una para pruebas y otra para producción.

{
  "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"
  } ]
}

Habilita y configura los módulos de Monetización y Worldpay en el portal para desarrolladores

Habilita los módulos necesarios de Monetización y Worldpay en el portal para desarrolladores. Para obtener más información, consulta Cómo configurar la monetización en el portal para desarrolladores.

Inicia el pago a una cuenta prepaga con el proveedor de pagos

Como se muestra en el paso 2 del flujo de administración de cuentas prepagadas, el portal para desarrolladores inicia el pago a una cuenta prepagada con un proveedor de pagos cuando los consumidores de la API realizan las siguientes acciones:

• Aceptan un plan de tarifas, pero no tienen fondos suficientes en su cuenta prepagada
• Solicitar agregar dinero a su cuenta prepagada

Para iniciar un pago desde un proveedor de pagos externo con la API, envía una solicitud POST al siguiente recurso, en el que {developer_id} es la dirección de correo electrónico del desarrollador.

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

Cuando envíes la solicitud, deberás especificar los siguientes valores como parámetros de consulta:

• Importe que se agregará al saldo de cuenta prepagada (amount={amount})
• ID del proveedor de pagos (provider={providerId})
• Moneda admitida (supportedCurrencyId={currency})

Además, debes pasar los detalles básicos de la cuenta, como la dirección de facturación de la empresa.

Por ejemplo, el siguiente código vuelve a cargar el saldo de una cuenta prepaga con el proveedor de pagos Worldpay. La transferencia inicial a tu cuenta prepagada será de 10 dólares estadounidenses (el parámetro de consulta amount se establece en 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

A continuación, se proporciona un ejemplo de la respuesta.

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

La URL de la página de pago seguro de Worldpay se devuelve en referenceUrl con tu clave de pedido única agregada como parámetro de consulta.

Cómo recargar el saldo de una cuenta prepagada con la API

Como se muestra en el paso 15 del flujo de administración de cuentas prepagas, después de verificar que el proveedor de pagos procesó correctamente la solicitud, el portal para desarrolladores envía una solicitud a Edge para volver a cargar la cuenta prepaga.

Puedes recargar el saldo de cuenta prepagada con la API para un desarrollador o una empresa, como se describe en las siguientes secciones.

Cómo recargar el saldo de una cuenta prepagada para un desarrollador

Para recargar el saldo de una cuenta prepaga de un desarrollador con la API, envía una solicitud POST a /mint/organizations/{org_name}/developers/{developer_id}/developer-balances, donde {developer_id} es la dirección de correo electrónico del desarrollador. Cuando envíes la solicitud, deberás especificar en el cuerpo de la solicitud el importe que se agregará al saldo y la moneda que se usará.

Por ejemplo, la siguiente solicitud agrega USD 1,000 al saldo de cuenta prepaga de un desarrollador:

$ 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 obtener una descripción de las propiedades de la solicitud, consulta Resumen de las propiedades de la solicitud para recargar una cuenta prepagada.

Cómo recargar el saldo de una cuenta prepagada para una empresa

Para recargar el saldo de una cuenta prepaga de una empresa con la API, envía una solicitud POST a /mint/organizations/{org_name}/companies/{company_id}/developer-balances, donde {company_id} es el ID de la empresa. Cuando envíes la solicitud, deberás especificar en el cuerpo de la solicitud el importe que se agregará al saldo y la moneda que se usará.

Por ejemplo, la siguiente solicitud agrega USD 1,000 al saldo de cuenta prepaga de una 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 obtener una descripción de las propiedades de la solicitud, consulta Resumen de las propiedades de la solicitud para recargar una cuenta prepagada.

Resumen de las propiedades de la solicitud para recargar una cuenta prepagada

Se deben especificar las siguientes propiedades cuando se recargan los saldos de las cuentas prepagas con la API:

Cómo borrar proveedores de pagos externos

Puedes borrar un proveedor de pagos externo configurado para tu organización de Edge enviando una solicitud DELETE al siguiente recurso:

Para borrar un proveedor de pagos de una organización específica, usa la siguiente API:

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

Solo los clientes de Apigee Edge Private Cloud con privilegios de administrador del sistema pueden borrar de forma opcional un proveedor de pagos global con la siguiente API:

/config/providers/id

Por ejemplo, el siguiente comando borra los proveedores de pagos externos configurados actualmente para myorg:

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

Cómo administrar los saldos de cuenta prepaga de forma manual

Como alternativa, puedes administrar la recarga de saldos prepagados haciendo un seguimiento de los pagos de forma manual o a través de un sistema de facturación integrado y, luego, llamar a la API de monetización para recargar la cuenta, como se describe en Cómo recargar el saldo de una cuenta prepagada con la API.

Cómo configurar la recarga automática de saldos de cuentas prepagadas con la API

En las siguientes secciones, se describe cómo configurar la recarga automática de los saldos de las cuentas prepagadas para un desarrollador o una empresa que utiliza un proveedor de pagos externo. Esta opción es útil para administrar los pagos recurrentes de los planes de tarifas.

Cómo configurar la recarga automática de saldos de cuentas prepagas para un desarrollador

Para configurar la recarga automática del saldo de una cuenta prepagada para un desarrollador cuando el saldo cae por debajo de un cierto límite, envía una solicitud POST a /mint/organizations/{org_name}/developers/{developer_id}/developer-balances/recurring-setup, donde {developer_id} es la dirección de correo electrónico del desarrollador.

Cuando envíes la solicitud, deberás especificar lo siguiente:

• ID del proveedor de pagos que se usará para recargar la cuenta (providerID)
• Marca que habilita la recarga automática (isRecurring)
• Límite por debajo del cual debe caer el saldo de la cuenta prepagada para activar la recarga automática (replenishAmount)
• Importe que se agregará automáticamente a la cuenta (recurringAmount)
• Parámetro de consulta supportedCurrencyID para especificar la moneda.

En el siguiente ejemplo, cuando el saldo de cuenta prepaga del desarrollador sea inferior a USD 5, se agregarán automáticamente USD 10 adicionales a la cuenta.

$ 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 obtener una descripción de las propiedades de la solicitud, consulta Resumen de las propiedades de la solicitud para configurar la recarga automática de cuentas prepagadas.

Cómo configurar la recarga automática de saldos de cuentas prepagas para una empresa

Para configurar la recarga automática del saldo de una cuenta prepagada para una empresa cuando el saldo cae por debajo de un importe determinado, envía una solicitud POST a /mint/organizations/{org_name}/companies/{company_id}/developer-balances/recurring-setup, donde {company_id} es el ID de la empresa.

Cuando envíes la solicitud, deberás especificar lo siguiente:

• ID del proveedor de pagos que se usará para recargar la cuenta (providerID)
• Marca que habilita la recarga automática (isRecurring)
• Límite por debajo del cual debe caer el saldo de la cuenta prepagada para activar la recarga automática (replenishAmount)
• Importe que se agregará automáticamente a la cuenta (recurringAmount)
• Parámetro de consulta supportedCurrencyID para especificar la moneda.

En el siguiente ejemplo, cuando el saldo de cuenta prepagada de la empresa sea inferior a USD 5, se agregarán automáticamente USD 10 adicionales a la cuenta.

$ 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 obtener una descripción de las propiedades de la solicitud, consulta Resumen de las propiedades de la solicitud para configurar la recarga automática de cuentas prepagadas.

Resumen de las propiedades de la solicitud para configurar la recarga automática de cuentas prepagadas

Se pueden especificar los siguientes atributos cuando se recargan automáticamente los saldos de las cuentas prepagadas con la API.

Migración a las páginas de pago alojadas de WorldPay

WorldPay actualizó su flujo de procesamiento de pagos seguro para usar un nuevo conjunto de páginas, conocidas como Hosted Payment Pages.

Si configuraste tus proveedores de pagos de WorldPay con el flujo de procesamiento de pagos seguros obsoleto (antes de agosto de 2017), deberás migrar a las nuevas páginas de pagos alojadas de WorldPay antes de enero de 2018.

Para migrar a las páginas de pago alojadas de WorldPay, sigue estos pasos:

1. Comunícate con WorldPay para migrar tu cuenta actual y usar las nuevas páginas de pago alojadas, y obtener un nuevo ID de instalación para tu cuenta.
2. Configura nuevos proveedores de pagos de WorldPay, como se describe en Configura el proveedor de pagos en Edge, y pasa el ID de instalación en el campo authType.
3. Configura los nuevos proveedores de pagos en tu portal para desarrolladores, como se describe en Configura la monetización en el portal para desarrolladores.
4. Si configuraste la recarga automática de una cuenta prepagada con el proveedor de pagos, debes volver a configurar la recarga automática para usar el nuevo ID del proveedor, como se describe en Cómo configurar la recarga automática de saldos de cuentas prepagadas con la API.

Próximos pasos

Puedes establecer límites de crédito para desarrolladores individuales de pospago. Obtén más información en Administra saldos pospagos.