Administra los saldos de cuenta prepagas

Estás viendo la documentación de Apigee Edge.
Ve 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 prepagas con la API.
• Vuelve a cargar (agrega dinero al) saldo de la cuenta según sea necesario con un proveedor de pagos externo, como Worldpay. Consulta Administra saldos prepagados a través de un proveedor de pagos externo.

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

• Configura la recarga automática cuando el saldo prepagado de una cuenta caiga por debajo de un límite determinado mediante 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 Configura la recarga automática de saldos prepagados de cuentas mediante la API.

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

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

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

Para calcular el saldo restante de la cuenta prepaga del período de facturación actual, resta 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 las cuentas prepagas 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, donde {developer_id} es la dirección de correo electrónico del desarrollador:

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

Puedes pasar los siguientes parámetros de búsqueda 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 cuenta prepagados de una empresa, envía una solicitud GET a /mint/organizations/{org_name}/companies/{company_id}/developer-balances, en la que {company_id} es el ID de la empresa. Si la empresa es prepaga, la solicitud recupera el saldo actual de la cuenta prepaga. Si la empresa es de pospago, la solicitud recupera el límite de crédito actual.

Puedes pasar los siguientes parámetros de búsqueda 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 consultan los saldos de las cuentas prepagadas de un desarrollador.

Administra los saldos de cuenta prepaga con un proveedor de pagos

Para administrar los saldos de las cuentas prepagadas, configura una cuenta de comerciante con un proveedor de pagos externo, como Worldpay. En la siguiente imagen, se muestra cómo se administra el saldo prepagado de la cuenta mediante el proveedor de pagos Worldpay.

En la siguiente tabla, se describe cada paso del flujo de administración de saldos de cuentas prepagados 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
• Cómo configurar el proveedor de pagos en Edge
• Visualiza los proveedores de pagos configurados para tu organización
• Habilita y configura los módulos obligatorios en el portal para desarrolladores
• Cómo iniciar un pago a una cuenta prepagada con un proveedor de pagos
• Cómo volver a cargar 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 del comerciante. Se recomienda que configures dos cuentas, una para pruebas y otra para producción. Para obtener más información sobre las cuentas de comerciante 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 XML Password.
   3. Ingresa una clave secreta de MAC de 20 a 30 caracteres en el campo Secreto de MAC de redireccionamiento.
   4. Haz clic en Guardar perfil.
4. Agrega el servidor de administración de Apigee Edge a la lista de IPs del comercio (lista de entidades permitidas):
   1. Haz clic en Perfil > Entorno del comercio.
   2. Haz clic en Nueva IP de prueba.
   3. Ingresa la IP del servidor de administración de Apigee Edge.
   4. Haz clic en Guardar.
5. Configura la URL del comercio para que adjunte 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 Editar páginas de pago, selecciona tu ID de instalación en la lista desplegable Seleccionar canal.
   3. En la pestaña Propiedades, selecciona Editar configuración del comercio.
   4. Establece el valor del parámetro Send URL en True.
   5. Haz clic en la pestaña Publicar.
   6. Promociona los cambios de la siguiente manera:
      • En el caso de los entornos de prueba, haz clic en Promocionar en Diseño para ascender de Design a Sandbox.
      • En el caso de los entornos de producción, haz clic en Promover en Zona de pruebas para promover de la zona de pruebas a producción.

Cómo configurar 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 para la nube privada 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 de 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 

Consulta 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, a continuación, se muestran los proveedores de pagos de terceros 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"
  } ]
}

Habilitación y configuración de los módulos de Monetización y Worldpay en el portal para desarrolladores

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

Cómo iniciar un 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:

• Aceptar un plan de tarifas, pero no tiene fondos suficientes en su cuenta prepagada
• Solicitar que se agregue dinero a su cuenta prepagada

Para iniciar un pago de un proveedor de pagos externo con la API, envía una solicitud POST al siguiente recurso, en la 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, debes especificar los siguientes valores como parámetros de consulta:

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

Además, debe transmitir detalles básicos de la cuenta, como la dirección de facturación de la empresa.

Por ejemplo, el siguiente comando vuelve a cargar el saldo de una cuenta prepaga con el proveedor de pagos de Worldpay. La transferencia inicial a tu cuenta prepagada será de 10 dólares estadounidenses (el parámetro de consulta amount está configurado 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 a la página de pago seguro de Worldpay se muestra en referenceUrl con tu clave de pedido única adjunta como parámetro de consulta.

Cómo volver a cargar el saldo de una cuenta prepaga con la API

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

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

Cómo volver a cargar el saldo prepagado de una cuenta de desarrollador

Para volver a cargar 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, debes 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 la 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

Si deseas obtener una descripción de las propiedades de la solicitud, consulta el Resumen de propiedades de la solicitud para volver a cargar una cuenta prepagada.

Cómo volver a cargar el saldo de una cuenta prepaga de una empresa

Para volver a cargar 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, debes 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 la 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 volver a cargar una cuenta prepagada.

Resumen de las propiedades de la solicitud para volver a cargar una cuenta prepaga

Se deben especificar las siguientes propiedades cuando se vuelven a cargar los saldos de cuentas prepagados con la API:

Cómo borrar proveedores de pagos externos

Para borrar un proveedor de pagos de terceros configurado para tu organización de Edge, envía una solicitud DELETE al siguiente recurso:

Si quieres 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 de sistemas pueden borrar de manera opcional un proveedor de pagos global mediante 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 los saldos prepagos haciendo un seguimiento de los pagos de forma manual o a través de un sistema de facturación integrado y, luego, llamando 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 los saldos de las cuentas prepagas con la API

En las siguientes secciones, se describe cómo configurar la recarga automática de los saldos de las cuentas prepagas para un desarrollador o una empresa que usa 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 prepaga de un desarrollador cuando el saldo disminuya por debajo de un umbral determinado, 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, debes especificar lo siguiente:

• Es el ID del proveedor de pagos que se usará para volver a cargar la cuenta (providerID).
• Marca que habilita la recarga automática (isRecurring)
• Es el límite por debajo del cual debe caer el saldo de la cuenta prepaga para activar la recarga automática (replenishAmount).
• Es el 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 la cuenta prepaga del desarrollador disminuya a menos de 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

Si deseas obtener una descripción de las propiedades de la solicitud, consulta el Resumen de propiedades de la solicitud para configurar la recarga automática de una cuenta prepagada.

Configurar la recarga automática de los saldos de cuentas prepagados para una empresa

Para configurar la recarga automática del saldo de una cuenta prepagada de una empresa cuando el saldo disminuya 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, debes especificar lo siguiente:

• Es el ID del proveedor de pagos que se usará para volver a cargar la cuenta (providerID).
• Marca que habilita la recarga automática (isRecurring)
• Es el límite por debajo del cual debe caer el saldo de la cuenta prepaga para activar la recarga automática (replenishAmount).
• Es el importe que se agregará automáticamente a la cuenta (recurringAmount).
• Es el parámetro de consulta supportedCurrencyID para especificar la moneda.

En el siguiente ejemplo, cuando el saldo prepagado de la cuenta de la empresa sea inferior a 5 dólares, se agregarán automáticamente 10 dólares 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 una cuenta prepagada.

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

Los siguientes atributos se pueden especificar cuando se vuelven a cargar los saldos de las cuentas prepagas automáticamente con la API.

Cómo migrar a las páginas de pagos alojadas de WorldPay

WorldPay actualizó su flujo de procesamiento de pagos seguro para usar un nuevo conjunto de páginas, denominadas Páginas de pago alojadas.

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 pago 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 configuras 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 de 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 de pospago individuales. Obtén más información en Administra los saldos de pospago.