Create Recurring Payments (Subscriptions Engine)

This guide walks you through setting up recurring payments using the Getnet Subscriptions Engine. The engine automatically processes recurring charges according to subscription schedules without requiring any action from the merchant or cardholder for each transaction.

Prerequisites

Before following the steps, you need to:

  • Create your account by contacting the Integration Support team to get your API credentials client_id and client_secret.
  • Generate your token with your credentials using the Access Token endpoint.
information icon

Getnet provides a Postman Collection to help you replicate these use cases locally. You can also test the API in sandbox using the API Reference available in the documentation.

information icon
Important: The Subscriptions Engine is different from Cardholder-Initiated (One Click) and Merchant-Initiated recurring payments. With the Subscriptions Engine, Getnet automatically processes all recurring charges based on the plan schedule. You don't need to trigger each payment manually.

Process overview

The Subscriptions Engine uses three main components that work together:

  • Customer: The consumer of the product or service offered in the subscription.
  • Plan: Defines how recurring payments will be applied, including the installment value, periodicity, and number of installments.
  • Subscription: Links the customer to the plan with payment method details.

Once you create a subscription, the Getnet Subscriptions Engine automatically processes all subsequent recurring charges according to the plan schedule. The engine handles charge processing, retries, and lifecycle management automatically.

The process works as follows:

  1. Register a customer profile.
  2. Create a plan that defines the recurring payment schedule.
  3. Tokenize the card data to replace the raw card number with a secure token.
  4. Create a subscription that links the customer to the plan with payment method details.
  5. The engine automatically processes recurring charges according to the plan schedule.

The diagram below gives an overview of the process:

Steps

Follow these steps to set up a recurring payment subscription using the Subscriptions Engine.

Step 1: Register a customer

The Create Customer endpoint registers a customer profile in the Getnet platform. The customer represents the consumer of the product or service offered in the subscription. You need this customer ID to link them to a subscription later.

The following table describes the required fields for creating a customer:

FieldTypeRequiredDescription
seller_idstring (UUID)YesYour merchant identifier.
customer_idstringNoYour custom identifier for the customer. If not provided, Getnet generates one.
first_namestringYesCustomer's first name (max 40 characters).
last_namestringYesCustomer's last name (max 80 characters).
document_typestringYesCustomer's document type. See Document types for available values.
document_numberstringYesCustomer's document number without mask (11-15 characters).
emailstringNoCustomer's email address.
phone_numberstringNoCustomer's phone number without mask (max 15 characters).

Use the Create Customer endpoint to register customer details:

bash
curl --request POST \ --url https://api-sbx.globalgetnet.com/dpm/customers-gwproxy/v1/customers \ --header 'authorization: Bearer <your-token>' \ --header 'content-type: application/json' \ --header 'x-seller-id: 54f88e68-7764-4e87-8830-756b1e2c02f8' \ --data '{ "seller_id": "54f88e68-7764-4e87-8830-756b1e2c02f8", "customer_id": "customer-123", "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "document_type": "CPF", "document_number": "12345678900", "phone_number": "+5511999999999" }'

Example of response:

json
{ "seller_id": "54f88e68-7764-4e87-8830-756b1e2c02f8", "customer_id": "customer-123", "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "document_type": "CPF", "document_number": "12345678900", "phone_number": "+5511999999999", "created_at": "2025-11-06T10:30:00.000Z" }

Step 2: Create a plan

The Create Plan endpoint registers a recurrence plan that defines how recurring payments will be applied. The plan specifies the amount to charge, the billing frequency, and the number of billing cycles.

The following table describes the required fields for creating a plan:

FieldTypeRequiredDescription
seller_idstring (UUID)YesYour merchant identifier.
namestringYesPlan name (min 3 characters).
descriptionstringNoPlan description.
amountintegerYesAmount to charge in the smallest currency unit (e.g., cents).
currencystringYesCurrency code (e.g., BRL, ARS, CLP, MXN).
payment_typesarrayYesPayment methods accepted. Values: credit_card, debit_card.
periodobjectYesBilling period configuration. See table below.
product_typestringNoProduct type. Values: cash_carry, digital_content, digital_goods, gift_card, physical_goods, renew_subs, shareware, service.
The period object defines the billing frequency:
FieldTypeRequiredDescription
period.typestringYesBilling periodicity. See values below.
period.billing_cycleintegerYesNumber of billing cycles (installments).
The periodicity is defined in the period.type field:
PeriodicityField: period.typeDescription
AnnualyearlyCharges once a year
MonthlymonthlyCharges once a month
BimonthlybimonthlyCharges once every 2 months
QuarterlyquarterlyCharges once every 3 months
Half-yearlysemesterlyCharges once every 6 months
SpecificspecificSpecific billing cycle in days

Use the Create Plan endpoint:

bash
curl --request POST \ --url https://api-sbx.globalgetnet.com/rpy/be-plan/v1/plans \ --header 'authorization: Bearer <your-token>' \ --header 'content-type: application/json' \ --header 'x-seller-id: 54f88e68-7764-4e87-8830-756b1e2c02f8' \ --data '{ "seller_id": "54f88e68-7764-4e87-8830-756b1e2c02f8", "name": "Premium Monthly Plan", "description": "Monthly subscription for premium features", "amount": 9900, "currency": "BRL", "payment_types": ["credit_card"], "period": { "type": "monthly", "billing_cycle": 12 }, "product_type": "service" }'

Example of response:

json
{ "plan_id": "51995e24-b1ae-4826-8e15-2a568a87abdd", "seller_id": "54f88e68-7764-4e87-8830-756b1e2c02f8", "name": "Premium Monthly Plan", "description": "Monthly subscription for premium features", "amount": 9900, "currency": "BRL", "payment_types": "credit_card", "period": { "type": "monthly", "billing_cycle": 12 }, "product_type": "service", "status": "active", "create_date": "2025-11-06T10:35:00.000Z" }
information icon
Save the plan_id from the response. You will need this ID when creating the subscription in Step 4.

Step 3: Tokenize card data

The Generate Token endpoint converts a raw card number into a secure token. Tokenization replaces the actual card number with a token, ensuring PCI compliance and transaction security. The CVV is not required for token generation.

The following table describes the required fields for tokenizing a card:

FieldTypeRequiredDescription
card_numberstringYesCard number (13-19 digits).
customer_idstringNoCustomer identifier from Step 1.

Use the Card Tokenization endpoint to tokenize the card:

bash
curl --request POST \ --url https://api-sbx.globalgetnet.com/dpm/cofre-gw-proxy/v1/tokens/card \ --header 'authorization: Bearer <your-token>' \ --header 'content-type: application/json' \ --header 'x-seller-id: 54f88e68-7764-4e87-8830-756b1e2c02f8' \ --data '{ "card_number": "5155901222280001", "customer_id": "customer-123" }'

Example of response:

json
{ "number_token": "dfe05208b105578c070f806c80abd3af09e246827d29b866cf4ce16c205849977c9496cbf0d0234f42339937f327747075f68763537b90b31389e01231d4d13c" }
information icon
Save the number_token from the response. You will need this token when creating the subscription in Step 4.

Step 4: Create a subscription

The Create Subscription endpoint links a customer to a plan with payment method details. Once created, the Subscriptions Engine automatically processes recurring charges according to the plan schedule. The subscription remains in a scheduled status until the installment_start_date, when billing begins.

The following table describes the required fields for creating a subscription:

FieldTypeRequiredDescription
seller_idstring (UUID)YesYour merchant identifier.
customer_idstringYesCustomer identifier from Step 1.
plan_idstring (UUID)YesPlan identifier from Step 2.
installment_start_datestringNoSubscription billing start date (format: YYYY-MM-DD). Until this date, the subscription remains in scheduled status.
subscriptionobjectYesPayment method configuration. See table below.
The subscription.payment_type.credit object contains the card details:
FieldTypeRequiredDescription
transaction_typestringYesTransaction type. Use FULL for full payment.
number_installmentsintegerYesNumber of installments per charge.
card.number_tokenstringYesTokenized card number from Step 3.
card.brandstringYesCard brand. Values: VISA, MASTERCARD, AMEX, ELO, HIPERCARD.
card.cardholder_namestringYesCardholder name as printed on the card (max 26 characters).
card.expiration_monthstringYesTwo-digit expiration month (e.g., 12).
card.expiration_yearstringYesTwo-digit expiration year (e.g., 30).
card.security_codestringYesCard security code (CVV).

Use the Create Subscription endpoint:

bash
curl --request POST \ --url https://api-sbx.globalgetnet.com/rpy/be-subscription/v1/subscriptions \ --header 'authorization: Bearer <your-token>' \ --header 'content-type: application/json' \ --header 'x-seller-id: 54f88e68-7764-4e87-8830-756b1e2c02f8' \ --data '{ "seller_id": "54f88e68-7764-4e87-8830-756b1e2c02f8", "customer_id": "customer-123", "plan_id": "51995e24-b1ae-4826-8e15-2a568a87abdd", "installment_start_date": "2025-11-15", "subscription": { "payment_type": { "credit": { "transaction_type": "FULL", "card": { "number_token": "dfe05208b105578c070f806c80abd3af09e246827d29b866cf4ce16c205849977c9496cbf0d0234f42339937f327747075f68763537b90b31389e01231d4d13c", "cardholder_name": "John Doe", "security_code": "123", "brand": "MASTERCARD", "expiration_month": "12", "expiration_year": "30" }, "number_installments": 1 } } } }'

Example of response:

json
{ "seller_id": "54f88e68-7764-4e87-8830-756b1e2c02f8", "order_id": "ORDER-10187383", "installment_start_date": "2025-11-15", "create_date": "2025-11-06T10:40:00.000Z", "payment_date": 15, "next_scheduled_date": "2025-11-15T00:00:00.000Z", "status": "created", "status_details": "Subscription Plan flex successfully created", "subscription": { "subscription_id": "5d740ea0-b7d1-42f5-ad64-5a5521e12345" }, "customer": { "customer_id": "customer-123", "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com" }, "plan": { "plan_id": "51995e24-b1ae-4826-8e15-2a568a87abdd", "name": "Premium Monthly Plan", "amount": 9900, "currency": "BRL" } }

Step 5: Monitor charges (optional)

The Get Charges endpoint retrieves a list of charges processed for a subscription. After creating the subscription, the engine automatically processes all recurring charges according to the plan schedule. Use this endpoint to monitor charge status and payment history.

Use the Get Charges endpoint:

bash
curl --request GET \ --url 'https://api-sbx.globalgetnet.com/rpy/be-subscription/v1/charges?subscription_id=5d740ea0-b7d1-42f5-ad64-5a5521e12345' \ --header 'authorization: Bearer <your-token>' \ --header 'x-seller-id: 54f88e68-7764-4e87-8830-756b1e2c02f8'

Important considerations

  • If the change request date is within the period, it will be counted from the request date + 1 day.
  • Charges with scheduling that are in the retry process and had the payment denied will be disregarded in the validation of the period.
  • The engine only processes charges for active subscriptions.
  • The engine uses the payment method specified when creating the subscription. Ensure the card remains valid and active.

See also

On this page

Create Recurring Payments (Subscriptions Engine)