Subscription

Introduction

This payment method offers an efficient solution for merchants who want to implement a recurring sales model. This modality allows automatic Credit Card charges to be made in monthly periods, ideal for businesses that operate in a subscription format.

Before starting to create subscriptions, it is essential to configure subscription plans. These plans function as "templates", providing the base structure upon which individual subscriptions are built. Each plan defines critical aspects such as billing frequency, amount, and other parameters necessary for processing recurring transactions. Consult your account manager to create subscription plans.

Getting Started

• Create Subscription
• Find Subscription
• Update Subscription
• Cancel Subscription

Create Subscription

Creating a credit card subscription REDIRECT order:

POST /api/v1/subscriptions/credit-card/form
Host: latamgateway.com
Content-Type: application/json
ACCOUNT_TOKEN: "<token>"

{
  "order":{
    "code":"123", # Order reference in your system (required)
    "notification_url":"https://yoursystem.com/postback/", # Where we'll notify when status changes (required)
    "redirect_url":"https://yoursystem.com/finish_checkout?auto_redirect=true", # If filled, at the end of checkout we'll automatic redirect to that page (optional)
    "additional_info":"A description of your order, as a string", # (required)
    "payment_method":"subscription" # (required)
  },
  "subscription":{ # Required
    "plan_id": "plan-01" # Plan id
  },
  "risk":{ # Optional
    "ip": "73.250.17.249", # Customer IP
    "fingerprint": "9d16d111d9e1a8fba7f87239f20feeef", # Fingerprint ID
    "browser": "Mozilla/5.0 (X11; Linux x86_64; rv:93.0) Gecko/20100101 Firefox/93.0" # User-Agent from headers
  },
  "customer": { # Optional
    "name":  "Customer’s full name",
    "document": "111.222.333-44",
    "email": "[email protected]",
    "phone": "11999999999",
    "birth": "1996-03-09"
  },
  "address": { # Optional
    "street": "Example Avenue",
    "number": "123",
    "neighborhood": "Downtown",
    "complement": "Apt 101",
    "zip": "12345-678",
    "city": "Sample City",
    "state": "PR"
  }
}

The response will be:

{
  "form_id": "dbcedec8-f587-4203-8aa4-a74da83fb32a", # Order reference in our system. You should save that.
  "url": "https://latamgateway.com/subscription/payment/dbcedec8-f587-4203-8aa4-a74da83fb32a" # Form URL, redirect your customer to here
}

Find Subscription

Finding a subscription by ID:

GET /api/v1/subscriptions/:subscription_id
Host: latamgateway.com
Content-Type: application/json
ACCOUNT_TOKEN: "<token>"

The response will be:

{
  "id": "bgwt7v", 
  "balance": 0.0, 
  "created_at": "2023-12-13", 
  "never_expires": true, 
  "plan_id": "bvt6", 
  "price": 10.0, 
  "status": "Active", 
  "billing_day_of_month": 13, 
  "billing_period_end_date": "2024-01-12", 
  "billing_period_start_date": "2023-12-13", 
  "current_billing_cycle": 1, 
  "days_past_due": null, 
  "description": null, 
  "failure_count": 0, 
  "first_billing_date": "2023-12-13", 
  "next_billing_date": "2024-01-13", 
  "number_of_billing_cycles": null, 
  "paid_through_date": "2024-01-12", 
  "updated_at": "2023-12-13", 
  "transactions": [
    {
      "id": "6hjfw847", 
      "status": "Paid", 
      "created_at": "2023-12-13", 
      "updated_at": "2023-12-13", 
      "amount": 10.0, 
      "order_id": null, 
      "card_holder": null,
      "card_last_digits": "7777", 
      "card_bin": null,
      "card_expiration": null,
      "card_brand": "Visa"
    }
  ]
}

Update Subscription

Changing the subscription payment method:

POST /api/v1/subscriptions/credit-card/update/:subscription_id
Host: latamgateway.com
Content-Type: application/json
ACCOUNT_TOKEN: "<token>"

{
  "address": { # Optional
    "street": "Example Avenue",
    "number": "123",
    "neighborhood": "Downtown",
    "complement": "Apt 101",
    "zip": "12345-678",
    "city": "Sample City",
    "state": "PR"
}

The response will be:

{
  "form_id": "dbcedec8-f587-4203-8aa4-a74da83fb32a", # Order reference in our system. You should save that.
  "url": "https://latamgateway.com/subscription/update/bbc79cca-c302-40f9-b4c5-0cf6b6e4f153" # Form URL, redirect your customer to here
}

Cancel Subscription

Canceling a subscription by ID:

POST /api/v1/subscriptions/cancel/:subscription_id
Host: latamgateway.com
Content-Type: application/json
ACCOUNT_TOKEN: "<token>"

The response will be:

{
  "message": "Successful cancellation."
}

Subscription params

Param	Description
event	Subscription event
id	Subscription ID
balance	Subscription balance due
created_at	Subscription created date
never_expires	Indicates whether the subscription will expire or not
plan_id	ID of the plan associated with the subscription
price	Subscription price
status	The current status of the subscription
billing_day_of_month	Day of the month that the subscription is charged
billing_period_end_date	End date of the current billing cycle
billing_period_start_date	Start date for the current billing period
days_past_due	Number of days that the subscription is overdue
description	Subscription description
failure_count	Count of failed charge attempts
first_billing_date	The day the subscription starts billing
next_billing_date	Day when the next billing cycle begins
number_of_billing_cycles	Number of billing cycles if not never expires
paid_through_date	Date until which the subscription is still considered paid
updated_at	Date of last subscription update
card_last_digits	Last digits of the credit card associated with the subscription
card_brand	Brand of the credit card associated with the subscription
transactions	Subscription transactions

Transactions Params

Param	Description
id	Transaction ID
status	The current status of the transaction
created_at	Transaction created date
updated_at	Date of last transaction update
amount	Transaction amount
order_id	the order ID associated with the transaction
card_last_digits	Last digits of the credit card associated with the transaction
card_brand	Brand of the credit card associated with the subscription
billing_cycle	Billing cycle number

Order Status meanings

Status	Meaning
paid	Order was paid with success
expired	Order was not paid at the available time
analysis	Order needs to be checked by our support team
reversed	Order value was paid back to customer
canceled	Order was canceled by reasons like: Manual analysis, fraud, etc

Subscription Status meanings

Status	Meaning
active	Subscription is active and all payments are up to date
overdue	Subscription payment is due. We will attempt to make charges for up to 1 week. After that, the subscription is cancelled
cancelled	Subscription is cancelled. When you make a request or when all billing attempts fail
expired	Subscription is expired. When the paid_through_date of the last billing cycle is exceeded

Transaction Status meanings

Status	Meaning
awaiting payment	Transaction still no payment attempt
paid	Transaction paid successfully
failed	Transaction failed payment attempt. When the last charge attempt made was unsuccessful
reversed	Transaction is reversed. Only when you request