Administra los saldos de cuenta prepagas

Estás consultando la documentación de Apigee Edge.
Consulta la documentación de Apigee X. Información

Para administrar el saldo en una cuenta prepagada, puedes hacer lo siguiente:

• Consulta el saldo de cuenta prepagado actual. Consulta Cómo ver saldos de cuentas prepagados con la API.
• Vuelve a cargar (agrega dinero) al saldo de la cuenta según sea necesario mediante un proveedor de pagos externo, como Worldpay. Consulta Cómo administrar saldos prepagados con un proveedor de pagos de terceros.

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

• Configura la recarga automática cuando el saldo de una cuenta prepagada esté por debajo de cierto límite mediante la API de monetización y un proveedor de pagos externo, como Worldpay. Esta opción es útil para administrar los pagos recurrentes de los planes de tarifas. Si quieres obtener más información, consulta Configura la recarga automática de los saldos de cuentas prepagados con la API.

¿Cómo puedo calcular el saldo prepagado restante de una cuenta?

Cuando visualices el saldo de cuenta prepagado 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).

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

amount(335.50) - usage(34) = 229.50

Cómo ver los saldos de cuentas prepagadas con la API

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

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

Para ver los saldos de cuentas prepagadas de un desarrollador, emite 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 cuenta prepagado y la información de configuración recurrente de un desarrollador.
• /mint/organizations/{org_name}/developers/{developer_id}/prepaid-developer-balances: Muestra información del saldo de cuenta prepagado, incluidos 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 cuenta prepagados de una empresa

Para ver los saldos de cuentas 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 tiene un plan prepagado, la solicitud recupera el saldo prepagado actual de la cuenta. Si la empresa es de 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 visualizan los saldos de cuentas prepagadas de un desarrollador.

Cómo administrar saldos de cuentas prepagas a través de un proveedor de pagos

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

En la siguiente tabla, se describe cada paso del flujo prepagado de administración de saldo de la cuenta que se mostró anteriormente.

{
    "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 mediante un proveedor de pagos externo:

• Cómo configurar una cuenta del comerciante con el proveedor de pagos de Worldpay
• Configura 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
• Iniciar un pago a una cuenta prepagada a través de 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 del comerciante con el proveedor de pagos de Worldpay

Antes de comenzar, debes comunicarte con un proveedor de pagos externo (Worldpay) para configurar tus cuentas de comerciante. Se recomienda configurar dos cuentas, una para pruebas y otra para la producción. Para obtener más información sobre las cuentas de comerciante de Worldpay, consulte www.worldpay.com y wp-support.crm.worldpay.com (el Centro de asistencia de Worldpay).

Después de que configures tu cuenta de comerciante y recibas las credenciales de tu cuenta, sigue estos pasos para configurar tu cuenta de comerciante con Worldpay:

1. Ve 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. Configura la clave secreta del código de autenticación de mensajes (MAC) y la contraseña XML:
   1. Haz clic en Profile.
   2. En el campo Contraseña de XML, configura el proveedor de pagos de Worldpay en Edge para establecer la contraseña que se usará.
   3. Ingresa una clave secreta MAC de 20 a 30 caracteres en el campo Redireccionar secreto de MAC.
   4. Haz clic en Guardar perfil.
4. Agrega el servidor de administración de Apigee Edge a la lista de IP de comercios (lista de direcciones IP permitidas):
   1. Haz clic en Perfil > Entorno del comercio.
   2. Haz clic en IP de prueba nueva.
   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 pagos alojadas > Diseñador de páginas de pagos.
   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 configuración del comercio.
   4. Establece el valor de los parámetros de URL de envío en True.
   5. Haz clic en la pestaña Publicar.
   6. Promueve los cambios de la siguiente manera:
      • Para los entornos de pruebas, haz clic en Promover en Design para ascender de Design a Sandbox.
      • Para los entornos de producción, haz clic en Promover en Zona de pruebas para ascender de 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 Private Cloud con privilegios de administrador del sistema pueden configurar de manera opcional un proveedor de pagos global mediante la siguiente API:

/config/providers

Cuando llames a cada API, deberás 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 

Consulta los proveedores de pagos externos

A fin de ver y confirmar los proveedores de pagos externos configurados para la organización de Edge, emite una solicitud GET al siguiente recurso:

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

Por ejemplo, a continuación se muestran 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"
  } ]
}

Habilitar y configurar los módulos de Monetization y Worldpay en el portal para desarrolladores

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

Iniciar un pago a una cuenta prepagada a través del proveedor de pagos

Como se muestra en el paso 2 del flujo de administración prepagado de cuentas, el portal para desarrolladores inicia el pago a una cuenta prepagada mediante un proveedor de pagos cuando los consumidores de la API realizan lo siguiente:

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

Para iniciar un pago de un proveedor de pagos externo mediante la API, emite 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 emites la solicitud, debes especificar los siguientes valores como parámetros de consulta:

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

Además, debes proporcionar información básica de la cuenta, como la dirección de facturación de la empresa.

Por ejemplo, en el siguiente ejemplo, se vuelve a cargar el saldo de una cuenta prepagada con el proveedor de pagos Worldpay. La transferencia inicial a tu cuenta prepagada será de 10 dólares estadounidenses (amount el parámetro de consulta se estableció 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 Worldpay Secure Payment se muestra en referenceUrl con tu clave de pedido única anexada como parámetro de consulta.

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

Como se muestra en el paso 15 del flujo prepagado de administración de cuentas, después de verificar el procesamiento exitoso por parte del proveedor de pagos, el portal para desarrolladores envía una solicitud a Edge para volver a cargar la cuenta prepagada.

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

Cómo volver a cargar el saldo de una cuenta prepagada para un desarrollador

Para volver a cargar el saldo de una cuenta prepagada de un desarrollador que usa la API, envía una solicitud POST a /mint/organizations/{org_name}/developers/{developer_id}/developer-balances, en la que {developer_id} es la dirección de correo electrónico del desarrollador. Cuando emites 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, en la siguiente solicitud se agregan USD 1,000 al saldo de la cuenta prepagada 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 las propiedades de la solicitud para volver a cargar una cuenta prepagada.

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

Para volver a cargar un saldo de cuenta prepagado de una empresa que usa la API, emite una solicitud POST a /mint/organizations/{org_name}/companies/{company_id}/developer-balances, en la que {company_id} es el ID de la empresa. Cuando emites 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, en la siguiente solicitud se agregan USD 1000 al saldo de cuenta prepagado 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

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

Resumen de las propiedades de solicitud para volver a cargar una cuenta prepagada

Cuando se vuelven a cargar saldos de cuentas prepagados con la API, se deben especificar las siguientes propiedades:

Borra proveedores de pagos externos

Puedes borrar un proveedor de pagos externo configurado para tu organización de Edge mediante 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 manera opcional un proveedor de pagos global mediante la siguiente API:

/config/providers/id

Por ejemplo, lo siguiente 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 manualmente los saldos de cuentas prepagados

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, llamando a la API de monetización para volver a cargar la cuenta, como se describe en Vuelve a cargar un saldo de cuenta prepagado con la API.

Configurar la recarga automática de saldos de cuentas prepagados con la API

En las siguientes secciones, se describe cómo configurar la recarga automática de saldos de cuentas prepagados 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 los saldos de cuentas prepagados para un desarrollador

A fin de 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, en la que {developer_id} es la dirección de correo electrónico del desarrollador.

Cuando emitas la solicitud, debes especificar lo siguiente:

• ID del proveedor de pagos que se usará para volver a cargar la cuenta (providerID)
• Marca que habilita la recarga automática (isRecurring)
• Umbral de que el saldo prepagado de la cuenta debe ser inferior para activar la recarga automática (replenishAmount)
• Importe que se agregará automáticamente a la cuenta (recurringAmount)
• supportedCurrencyID para especificar la moneda.

En el siguiente ejemplo, cuando el saldo de la cuenta prepagada del desarrollador sea inferior a 5 dólares estadounidenses, se agregarán automáticamente 10 dólares estadounidenses 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 las propiedades de la solicitud para configurar la recarga automática de una cuenta prepagada.

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

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

Cuando emitas la solicitud, debes especificar lo siguiente:

• ID del proveedor de pagos que se usará para volver a cargar la cuenta (providerID)
• Marca que habilita la recarga automática (isRecurring)
• Umbral de que el saldo prepagado de la cuenta debe ser inferior para activar la recarga automática (replenishAmount)
• Importe que se agregará automáticamente a la cuenta (recurringAmount)
• supportedCurrencyID para especificar la moneda.

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

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

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

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

Migración a 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 pagos alojadas.

Si configuraste tus proveedores de pagos de WorldPay con el flujo de procesamiento de pagos seguro 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 pagos alojadas de WorldPay:

1. Comunícate con WorldPay para migrar tu cuenta actual, usar las nuevas Páginas de pagos alojadas y obtener un nuevo ID de instalación para tu cuenta.
2. Configura los nuevos proveedores de pagos de WorldPay como se describe en Cómo configurar 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 el portal para desarrolladores, como se describe en Cómo configurar la monetización en el Portal para desarrolladores.
4. Si configuras la recarga automática de una cuenta prepagada con el proveedor de pagos, deberás volver a configurarla para usar el ID de proveedor nuevo, como se describe en Cómo configurar la recarga automática de saldos de cuentas prepagados con la API.

Próximos pasos

Puedes establecer límites de crédito para desarrolladores de pospago individuales. Obtenga información sobre cómo hacerlo en Administrar saldos pospagos.