Plans

API data

API Gateway
This API is used for payment gateway operations:

• Production: https://api.sopague.com.br/gateway
• Sandbox: https://api-hmg.sopague.com.br/gateway
• Architecture: Representational State Transfer (REST)

Introduction

Plans are offers presented by businesses to potential customers. For example, a gym can offer monthly, quarterly, or annual plans, allowing the customer to choose the plan that best fits their needs.

---

Create plan

To create a plan, send a POST request as shown below:

POST /v1/recurrences/plans

Via REST request with the following body:

Request

{
  "merchantId": "01700555550000",
  "name": "Jornal do Bairro - assinatura mensal",
  "description": "Jornal com notícias locais do bairro.",
  "amount": 5.99,
  "planType": "Monthly",
  "trialDays": 7,
  "paymentMethod": "CreditCard",
  "interval": 30,
  "installments": 12,
  "attempts": 3
}

Data dictionary - Parameters

PROPERTY	DESCRIPTION	TYPE	LOCATION	REQUIRED	MAX SIZE
MerchantId	Merchant identifier.	string	body	No (captured from authentication)	20
Name	Plan name.	string	body	yes	255
Description	Plan description.	string	body	yes	255
Amount	Plan installment amount.	decimal	body	yes	12 integers and 6 decimals
PlanType	Plan type (Monthly, Bimonthly, Quarterly, Semesterly, Yearly, Custom).	string	body	yes	fixed
TrialDays	Trial days.	integer	body	no	N/A
PaymentMethod	Payment method (CreditCard).	string	body	yes	fixed
Interval	Billing interval in days.	integer	body	conditional	Greater than 20
Installments	Number of installments.	integer	body	conditional	N/A
Attempts	Retry attempts ("Teimosinha") count (up to 4).	integer	body	conditional	4

Plan types

Monthly = Monthly
For the "Monthly" plan, billings happen every 30 days. There is no end date until the subscription is canceled, or the transaction is declined by the issuer/brand.

Bimonthly = Every two months
Quarterly = Quarterly
Semesterly = Semiannual
Yearly = Yearly

For any of the plan types above, you don’t need to send interval and installments, because the system will automatically set the interval and the number of installments according to the selected plan type.

A Custom planType must have interval of at least 20 and installments greater than zero.

Retry policy ("Teimosinha")

The attempts field indicates the number of retry attempts. Retries happen when the payment attempt fails due to insufficient funds. If the card is canceled, retries won’t happen and the system will block the subscription account.

Retry rules:

• If attempts is 1 and the first payment attempt fails, the system retries 2 days after the last failure.
• If attempts is 4 and 3 attempts have already failed, the system retries 4 days after the last failure.
• If attempts is 4 and 4 attempts have already failed, the system retries 8 days after the last failure and won’t try again.
• If a payment due date is 01/01, retries will happen on 03/01, 05/01, 09/01, and the 4th and last retry on 17/01.

🟢 200

Plan created successfully

"59ff5efc-33e0-4c5c-b45f-e342057c4775"

Data dictionary - Response

PROPERTY	DESCRIPTION	TYPE
PlanId	Identifier of the created plan.	string

🔴 400

Request error

[
  {
    "tag": "Amount",
    "description": "O valor deve ser maior que zero"
  }
]

🔴 500

Internal error

[
  {
    "tag": "",
    "description": "Não foi possível executar comando. Erro desconhecido."
  }
]

---

Search plans

To search plans, send a GET request as shown below:

GET /v1/recurrences/plans?name={name}&status={status}&orderBy={orderBy}&page={page}&limit={limit}

Data dictionary - Query parameters

PROPERTY	DESCRIPTION	TYPE	LOCATION	REQUIRED
Name	Plan name.	string	query params	no
Status	Plan status filter.	string	query params	no
OrderBy	Result ordering.	string	query params	no
Page	Page number.	integer	query params	no
Limit	Items per page.	integer	query params	no

🟢 200

Plans found

{
  "items": [
    {
      "merchantId": "017005555500000",
      "name": "plano - Mensal 1 9999",
      "description": "plano - Mensal 1 9999",
      "amount": 29.990000,
      "planType": "Monthly",
      "trialDays": 0,
      "paymentMethod": "CreditCard",
      "interval": 30,
      "installments": 1,
      "status": "Active",
      "attempts": 0,
      "id": "07d3e68a-1e61-4010-9dee-3f6db3c52dec",
      "createdDate": "2020-04-14T12:21:23.337"
    },
    {
      "merchantId": "017005555500000",
      "name": "PLANO CUSTOM 3",
      "description": "PLANO DE RECORRÊNCIA EM 5X",
      "amount": 27.000000,
      "planType": "Custom",
      "trialDays": 0,
      "paymentMethod": "CreditCard",
      "interval": 30,
      "installments": 5,
      "status": "Active",
      "attempts": 4,
      "id": "0dd23cbd-de75-45a5-b2d1-972191140593",
      "createdDate": "2020-04-14T12:21:23.337"
    }
  ],
  "page": 1,
  "limit": 2,
  "total": 47
}

Data dictionary - Response

PROPERTY	DESCRIPTION	TYPE
MerchantId	Merchant identifier.	string
Name	Plan name.	string
Description	Plan description.	string
Amount	Plan installment amount.	decimal
PlanType	Plan type.	string
TrialDays	Trial days.	integer
PaymentMethod	Payment method.	string
Interval	Billing interval in days.	integer
Installments	Number of installments.	integer
Status	Plan status.	string
Attempts	Retry attempts count.	integer
Id	Plan identifier.	string
CreatedDate	Plan creation date/time.	datetime
Page	Current page number.	integer
Limit	Items per page.	integer
Total	Total items found.	integer

🔴 400

Request error

[
  {
    "tag": "Query",
    "description": "Parâmetros de consulta inválidos"
  }
]

---

Get plan by ID

To retrieve a specific plan by ID:

GET /v1/recurrences/plans/{planId}

Data dictionary - Parameters

PROPERTY	DESCRIPTION	TYPE	LOCATION	REQUIRED	MAX SIZE
PlanId	Plan identifier.	string	path	yes	36

🟢 200

Plan found

{
  "merchantId": "017005555500000",
  "name": "PLANO CUSTOM 3",
  "description": "PLANO DE RECORRÊNCIA EM 5X",
  "amount": 27.000000,
  "planType": "Custom",
  "trialDays": 0,
  "paymentMethod": "CreditCard",
  "interval": 30,
  "installments": 5,
  "status": "Active",
  "attempts": 4,
  "id": "0dd23cbd-de75-45a5-b2d1-972191140593",
  "createdDate": "2020-04-14T12:21:23.337"
}

Data dictionary - Response

PROPERTY	DESCRIPTION	TYPE
MerchantId	Merchant identifier.	string
Name	Plan name.	string
Description	Plan description.	string
Amount	Plan installment amount.	decimal
PlanType	Plan type.	string
TrialDays	Trial days.	integer
PaymentMethod	Payment method.	string
Interval	Billing interval in days.	integer
Installments	Number of installments.	integer
Status	Plan status.	string
Attempts	Retry attempts count.	integer
Id	Plan identifier.	string
CreatedDate	Plan creation date/time.	datetime

🔴 404

Plan not found

{
  "error": "Plano não encontrado"
}

---

Update plan

To update a plan, send a request as shown below:

POST /v1/recurrences/plans/{planId}

Notes

• You cannot change plan amounts if the plan is active.
• Other plan fields can only be changed if the plan is not in use; otherwise only name and description can be changed.

Via REST request with the following body:

Request

{
  "merchantId": "017005555500000",
  "name": "plano - Mensal 1 9999",
  "description": "plano - Mensal 1 9999",
  "amount": 29.990000,
  "planType": "Monthly",
  "trialDays": 0,
  "paymentMethod": "CreditCard",
  "interval": 30,
  "installments": 1,
  "attempts": 0
}

Data dictionary - Parameters

PROPERTY	DESCRIPTION	TYPE	LOCATION	REQUIRED	MAX SIZE
PlanId	Identifier of the plan to update.	string	path	yes	36
MerchantId	Merchant identifier.	string	body	yes	20
Name	Plan name.	string	body	yes	255
Description	Plan description.	string	body	yes	255
Amount	Amount.	decimal	body	yes	12
PlanType	Plan type.	string	body	yes	fixed
TrialDays	Trial days.	integer	body	no	N/A
PaymentMethod	Payment method.	string	body	yes	fixed
Interval	Billing interval in days.	integer	body	conditional	Greater than 20
Installments	Number of installments.	integer	body	conditional	N/A
Attempts	Retry attempts count (up to 4).	integer	body	conditional	4

🟢 200

Plan updated successfully

"0dd23cbd-de75-45a5-b2d1-972191140593"

Data dictionary - Response

PROPERTY	DESCRIPTION	TYPE
PlanId	Identifier of the updated plan.	string

🔴 400

Request error

[
  {
    "tag": "Plan",
    "description": "Plano em uso, não é possível alterar valores"
  }
]

---

Update plan status

To update a plan status:

POST /v1/recurrences/plans/{planId}/status

Via REST request with the following body:

Request

{
  "status": "Active"
}

Data dictionary - Parameters

PROPERTY	DESCRIPTION	TYPE	LOCATION	REQUIRED	MAX SIZE
PlanId	Identifier of the plan to update.	string	path	yes	36
Status	Status (Active, Inactive, Canceled).	string	body	yes	fixed

🟢 200

Status updated successfully

"0dd23cbd-de75-45a5-b2d1-972191140593"

Data dictionary - Response

PROPERTY	DESCRIPTION	TYPE
PlanId	Identifier of the updated plan.	string

🔴 400

Request error

[
  {
    "tag": "Status",
    "description": "Status inválido"
  }
]

---

For questions or issues, visit the support section in Sopague.