Crear suscripción

Crear suscripción

Consideraciones

Para utilizar el servicio de suscripciones se deben tomar en cuenta las siguiente consideraciones:
  1. Utilizar el servicio en los endpoints:
    1. Sandbox: https://sandbox-merchant.greenpay.me/subscriptions
    2. Producción: https://merchant.greenpay.me/subscriptions
  2. Tener tarjetas registradas (tokenizadas en Greenpay), es decir, contar con tokens de tarjetas disponibles para utilizar. Para conocer cómo crear token de tarjeta visite la sección de artículos Registro de tarjetas.
  3. Tener una cuenta de sandbox o producción con Greenpay. Para crear una cuenta de sandbox puede registrarla en Crear cuenta sandbox y para la cuenta de producción debe haber finalizado el proceso con el equipo de afiliación de Greenpay (afiliacion@greenpay.me) y realizado una revisión técnica con el equipo de soporte de Greenpay (support@greenpay.me).

Pasos para uso del servicio

1. Estructura de los datos

Se debe crear un objeto JSON que tenga la siguiente estructura:


{
"secret": "secret_provisto_por_GreenPay",
"merchantId": "merchantId_provisto_por_GreenPay",
"terminal": "terminal_provisto_por_GreenPay",
"userId": "identificador_del_usuario",
"description": "descripción de la suscripción",
"currency": "USD",
"tokens": [
"token_de_la_tarjeta"
],
"initialPayment": {
"amount": 100,
"description": "descripción del pago inicial"
},
"subscription": [
{
"startDate": 1536991200000,
"endDate": 1544853600000,
"amount": 10,
"cadence": {
"mode": "EVERY",
"unit": "MONTH",
"every": 1
}
}
],
"optional": {
"key": "value",
"key1": "value1"
}
}


Los parámetros obligatorios para crea un pago recurrente o suscripción son:
  1. secret: String secret provisto por GreenPay.
  2. merchantId: String UUID provisto por GreenPay.
  3. terminal: String terminal provisto por GreenPay.
  4. userId: identificador único del usuario a suscribir, este identificador es gestionado por el comercio y no por GreenPay.
  5. description: descripción o  razón de la suscripción.
  6. currency : Tipo de moneda en formato ISO 4217, por ejemplo, CRC para colones, USD para dólares y GTQ  para el Quetzal guatemalteco.
  7. tokens: token de la tarjeta por la cual se aplicarán las rebajas de las suscripciones.
  8. amount: monto de la suscripción, lo que se cobrará en cada recurrencia.
  9. mode: Modo en que se cobrará la suscripción, actualmente solo soporta la opción EVERY
  10. unit: Unidad de tiempo en que se cobrar, actualmente solo soporta la opción MONTH.
  11. every: indica el tiempo establecido para la ejecución de la recurrencia, por ejemplo, si el valor es 1 entonces la recurrencia se ejecutará cada mes.
El valor mínimo del parámetro every es 1, es decir, cada mes. Si se establece un 3 entonces la recurrencia se ejecutará cada 3 meses. 
Además, los cobros de la recurrencia se efectuarán a la media noche.

Otros campos opcionales 
  1. initialPayment: Indica si la suscripción tiene un pago inicial.
    1. amount: monto del pago inicial
    2. description: descripción del pago inicial.
  2. optional: Son campos adicionales de tipo llave - valor, en la cual el comercio puede enviar información relevante a la suscripción.
  3. startDate : Fecha de inicio de la suscripción, este campo es de tipo timestamp
  4. endDate: Fecha en que finaliza la suscripción, este campo es de tipo timestamp.
Si la suscripción se crea sin el parámetro startDate entonces el primer cobró se realizará de una vez.  

2. Enviar la solicitud de suscripción

Se debe enviar una solicitud HTTP de tipo POST al endpoint de suscripciones con el objeto json que contiene los datos de la suscripción. Una vez se procesa la solicitud con éxito, se obtiene un objeto de tipo JSON como respuesta.

Si se envió la solicitud con un pago inicial entonces la respuesta obtenida será como la siguiente:

  1. {
  2.     "status": 200,
  3.     "subscriptionId": "c0e6009a015df5f9600c2062b41b0a81",
  4.     "result": {
  5.         "success": true,
  6.         "initialPayment": {
  7.             "orderId": "c0e6009a015df5f9600c2062b41b0a81_0",
  8.             "authorization": "533793",
  9.             "errors": []
  10.         }
  11.     },
  12.     "errors": [],
  13.     "_signature": "711b...6544fvy",
  14.     "nextPaymentDate": "2018-10-12"
  15. }
Si la solicitud se envió sin pago inicial la respuesta será como la siguiente:
  1. {
  2.     "status": 200,
  3.     "subscriptionId": "f82d93dc794470f7deef4ed3ed4afe1c",
  4.     "result": {},
  5.     "errors": [],
  6.     "_signature": "6a7d2f00600598.....4400a52c9a3897a31b",
  7.     "nextPaymentDate": "2018-10-12"
  8. }

A continuación, se muestra un ejemplo en javascript del envío de la solicitud al endpoint de suscripciones. 



var data = {
"secret": "ZjAzZWZhOGU2Nm.....2ZjAxYTk1NGQ4MzE0NTE4ZTU0NjcyNTQ2OTA=",
"merchantId": "d4967653-3c5d-4abe-bde5-b1414a6c890d",
"terminal": "Terminal-BNCR-Colones",
"userId": "Guide example",
"description": "subscription guide example",
"currency": "USD",
"tokens": [
"968212cb-7481-414c-a504-ccaf76696d08"
],
"initialPayment": {
"amount": 100,
"description": "Guide initial payment"
},
"subscription": [{
"startDate": 1536991200000,
"endDate": 1544853600000,
"amount": 10,
"cadence": {
"mode": "EVERY",
"unit": "MONTH",
"every": 1
}
}]
}

req.headers({
"cache-control": "no-cache",
"Content-Type": "application/json"
});

req.type("json");
req.send(data);

req.end(function(res) {
if (res.error) throw new Error(res.error);

console.log(res.body);
});





    • Related Articles

    • Cancelar suscripción

      Para este servicio se debe consumir el siguiente endpoint: https://sandbox-merchant.greenpay.me/subscriptions/cancel A continuación, se muestra el paso a paso para cancelar  una suscripción en nuestro API de forma exitosa: 1. Crear el objeto JSON a ...

    • Crear productos

      Consideraciones Para utilizar la funcionalidad de suscripciones debe considerar lo siguiente: El comercio debe estar habilitado, si esta deshabilitado no podrá ingresar y utilizar la funcionalidades del dashboard. Si desconoce el estado de su ...

    • Crear cliente

      Consideraciones Para utilizar la funcionalidad de link de pago debe considerar lo siguiente: El comercio debe estar habilitado, si esta deshabilitado no podrá ingresar y utilizar la funcionalidades del dashboard. Si desconoce el estado de su comercio ...

    • Crear link de cobro

      Consideraciones Para utilizar la funcionalidad de suscripciones debe considerar lo siguiente: El comercio debe estar habilitado, si esta deshabilitado no podrá ingresar y utilizar la funcionalidades del dashboard. Si desconoce el estado de su ...

    • Crear orden de pago

      Consideraciones Una orden de pago se crea para indicar al API de pago que se efectuará una transacción por el motivo de los datos indicados en la orden. Para esto se debe tener las siguientes consideraciones: Utilizar el servicio en los endpoints: En ...