Create subscription

Create subscription

For this service, the following endpoint must be consumed: 

  1. https://sandbox-merchant.greenpay.me/subscriptions

Step by step to successfully create a subscription in our API :


1. Create the JSON object to be sent

It must contain the following structure: 

JSON subscription structure example

  1. {
  2.     "secret": "provided_by_GreenPay",
  3.     "merchantId": "provided_by_GreenPay",
  4.     "terminal": "provided_by_GreenPay",
  5.     "userId": "user_unique_id",
  6.     "description": "subscrption description", *
  7.     "currency": "USD",
  8.     "tokens": [
  9.         "card_token"
  10.     ],
  11.     "initialPayment": {
  12.         "amount": 100,
  13.         "description": "down payment descriptionl"
  14.     },
  15.     "subscription": [
  16.         {
  17.             "startDate": 1536991200000,
  18.             "endDate": 1544853600000,
  19.             "amount": 10, *
  20.             "cadence": {
  21.                 "mode": "EVERY", *
  22.                 "unit": "MONTH", *
  23.                 "every": 1
  24.             }
  25.         }
  26.     ],
  27.     "optional":{
  28.         "key":"value",
  29.         "key1":"value1"
  30.     }
  31. }
Required parameters.
  1. secret: secret provided by Greenpay.
  2. merchant: merchantId provided by Greenpay.
  3. terminal: terminalId provided by Greenpay.
  4. userId: user to subscribe unique identifier, this identifier is managed by the merchant and not by Greenpay.
  5. description: subscription service description.
  6. currency: currency type in ISO 4217 format.
  7. tokens: Card token in which subscription deductions will be applied.
  8. amount: subcription amount.
  9. mode: how the subscription will be charged.
  10. unit: 
  11. every: Indicates how often the recurrence is executed, for example if the value “1” is sent, the recurrence would be executed once every month.

Optional parameters.
  1. initialPayment: Indicates if the subscription has a down payment.
    1. amount: initial payment amount.
    2. description: initial payment description.
  2. optional: These are additional key-value fields, in which the merchant can send relevant information to the subscription.
  3. startDate: Subscription start date, this field is a timestamp type
  4. endDate: Subscription end date, this field is a timestamp type
Recommendations

1.  The API only receives the value ‘EVERY’ in the mode field.

2. The API only receives the value ‘MONTH’ int the unit field.
3. The currencies supported by Greenpay are USD (US Dollar), CRC (Costa Rican Colon), GTQ (Guatemalan Quetzal).
4. If the EndDate field is not sent, the subscription will not expire.
5. If the StartDate field is not sent, the subscription starts on the day it was registered. 
6. The EndDate and StartDate fields are of type timestamp.
7. Charges are made at midnight.
  1. If the subscription was created with startDate, it will be charged that same day. Otherwise the payment will be executed on the registration day.

2. Send subscription request

An HTTP POST request must be sent to the subscriptions endpoint with the JSON that contains the subscription data.

Once the subscription request has been sent and has been successfully completed, a JSON object is obtained in response.

Upon receiving this response, the parameter that must be obtained from the JSON object is the “body”, since it contains the subscription result.

​
The following code shows an example of the subscription request response:

Down payment subscription response example

 
  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": "711b346c8dac7bdcb121c1ba4a919131b879e889f979b2e239cb70ea45f2eee2812031cbcafe3de77d7841179b2d02337219f24829bcf55d8f8d5c557ed422af1b094bb82ec6baa7dd6164e0c3dc5958f6731abb951a83dfe56133640cde3b24e695630ae27d0d2b8a9cbed9e974d8607d8d974a7e3553f5d7a62b2ded78e513",
  14.     "nextPaymentDate": "2018-10-12"
  15. }

Subscription response without down payment example

  1. {
  2.     "status": 200,
  3.     "subscriptionId": "f82d93dc794470f7deef4ed3ed4afe1c",
  4.     "result": {},
  5.     "errors": [],
  6.     "_signature": "6a7d2f00600598d3a19ef84e08b2b160c594aef4728b10b8525228bc9de3258ac73de40ff94d0238881ce73567b53b900d8b63689a77ffbf4de92ff9f9b9ac7f67fcc29fbf9400c2b5fb953d1abb350a5d986eee2bbc60267614bd8ef415cee78453f84f27797d3671a5f6f6845d46ce5f0c454577b5ec4400a52c9a3897a31b",
  7.     "nextPaymentDate": "2018-10-12"
  8. }
Below is an javascript example of the subscription request endpoint . This function also obtains the JSON object “body” that’s received in response.

Subscription service POST request example

  1. var req = unirest("POST", "https://sandbox-merchant.greenpay.me/subscriptions");
  2.  
  3. var data = {
  4.   "secret": "ZjAzZWZhOGU2NmFkOTQ1NTdjYjA0ODI5NTY1MTc1YWQyNTM0YzdkM2ZmYmYxNWZjNTE4ZDNkMDIxZGQ4NTc4OTZhNjRjMGI1NjZmMDQwNjI4ZDg5ZDE4NmQ1MjEyZTQ2YzM3ZTg2ZjAxYTk1NGQ4MzE0NTE4ZTU0NjcyNTQ2OTA=",
  5.   "merchantId": "d4975982-3c5d-4abe-bde5-b1414a6c890d",
  6.   "terminal": "Magento-BNCR-Colones",
  7.   "userId": "Guide example",
  8.   "description": "subscription guide example",
  9.   "currency": "USD",
  10.   "tokens": [
  11.     "968212cb-7481-414c-a504-ccaf76696d08"
  12.   ],
  13.   "initialPayment": {
  14.     "amount": 100,
  15.     "description": "Guide initial payment"
  16.   },
  17.   "subscription": [
  18.     {
  19.       "startDate": 1536991200000,
  20.       "endDate": 1544853600000,
  21.       "amount": 10,
  22.       "cadence": {
  23.         "mode": "EVERY",
  24.         "unit": "MONTH",
  25.         "every": 1
  26.       }
  27.     }
  28.   ]
  29. }
  30.  
  31. req.headers({
  32.   "cache-control": "no-cache",
  33.   "Content-Type": "application/json"
  34. });
  35.  
  36. req.type("json");
  37. req.send(data);
  38.  
  39. req.end(function (res) {
  40.   if (res.error) throw new Error(res.error);
  41.  
  42.   console.log(res.body);
  43. });

    • Related Articles

    • Cancel subscription

      For this service the following endpoint must be consumed:  https://sandbox-merchant.greenpay.me/subscriptions/cancel Below is the step by step to successfully unsubscribe in our API: 1. Create JSON object to be sent  The JSON must be structured as ...

    • Subscription service - General information

      This service allow merchants to subscribe their customers to automatic collections in a set time window. This functionality only allows subscription monthly payments. It will be deducted from the customer’s card every month, while the subscription is ...

    • Create tokenization order

      To consider A tokenization order is created to prepare the Greenpay API for create a token from credit or debit card data. The following aspects have to be consider for it: Use these endpoints: Sandbox: https://sandbox-merchant.greenpay.me/tokenize ...

    • Create payment order

      To consider A payment order is created to prepare the Greenpay API for a make a payment process. The following aspects have to be consider: Use these endpoints: Sandbox: https://sandbox-merchant.greenpay.me/ Production: https://merchant.greenpay.me/ ...

    • Update amount

      For this service, the following endpoint must be consumed:  https://sandbox-merchant.greenpay.me/subscriptions/update Step by step to update a subscritpion amount in our API 1. Create a JSON object  JSON structure example {   "subscriptionId": "id ...