Subscriptions
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
Subscribing to services and/or products is a common way for companies to retain customers. For example, a fashion or home decor magazine can offer monthly, quarterly, or annual subscriptions—so the customer receives the product (the magazine) every month or each edition. Every subscription is associated with a plan.
Create subscription
To create a subscription, send a POST request as shown below:
POST /v1/recurrences/subscriptions
Notes
- It’s possible to have different credentials for Gateway and Recurrence. Verify whether your credentials are distinct.
- To create a
vaultId, refer to the gateway Vault documentation: Card Vault.
Via REST request with the following body:
Request
{
"vaultId": "e7fa5a01-90a9-4abc-9bac-d9dbfa7db587",
"orderNumber": "1234567890",
"planId": "e776ab3b-4698-4afa-97d4-a621d70c4a11"
}
Data dictionary - Parameters
| PROPERTY | DESCRIPTION | TYPE | LOCATION | REQUIRED | MAX SIZE |
|---|---|---|---|---|---|
| VaultId | Vault identifier. | string | body | yes | 36 |
| OrderNumber | Service order / order number. | string | body | yes | 10 |
| PlanId | Plan identifier. | string | body | yes | 36 |
- 🟢 200
- 🔴 400
- 🔴 500
Subscription created successfully
"937d0108-c54c-44f5-9ddc-acdb3dd94cc6"
Data dictionary - Response
| PROPERTY | DESCRIPTION | TYPE |
|---|---|---|
| SubscriptionId | Identifier of the created subscription. | string |
Request error
[
{
"tag": "VaultId",
"description": "Cofre não encontrado"
}
]
Internal error
[
{
"tag": "",
"description": "Não foi possível executar comando. Erro desconhecido."
}
]
Search subscriptions
To search subscriptions, send a GET request as shown below:
GET /v1/recurrences/subscriptions?planName={planName}&status={status}&orderBy={orderBy}&page={page}&limit={limit}
Data dictionary - Query parameters
| PROPERTY | DESCRIPTION | TYPE | LOCATION | REQUIRED |
|---|---|---|---|---|
| PlanName | Plan name. | string | query params | no |
| Status | Subscription 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
- 🔴 400
Subscriptions found
{
"items": [
{
"vaultId": "fc3c5589-24b1-4bca-b8ab-e57b100c44cd",
"orderNumber": "1234567890",
"status": "Active",
"plan": {
"merchantId": "01700555550000",
"name": "PLANO CUSTOM DO SEU ZÉ",
"description": "PLANO DE RECORRÊNCIA EM 5X",
"amount": 31.000000,
"planType": "Custom",
"trialDays": 0,
"paymentMethod": "CreditCard",
"interval": 30,
"installments": 5,
"status": "Active",
"attempts": 0,
"id": "cef858c4-d0c6-4f27-b009-c303121f3b6e",
"createdDate": "2020-04-14T12:21:23.337"
},
"id": "013c7ec4-62c1-4d78-859d-e8d2a11f681d",
"createdDate": "2020-03-19T15:09:12.203"
},
{
"vaultId": "3a203c6b-553f-4a7c-9cc4-e30897966c2e",
"orderNumber": "1404202015",
"status": "Blocked",
"plan": {
"merchantId": "017005555500000",
"name": "plano - Mensal 1",
"description": "plano - Mensal 1",
"amount": 29.990000,
"planType": "Monthly",
"trialDays": 1,
"paymentMethod": "CreditCard",
"interval": 30,
"installments": 1,
"status": "Active",
"attempts": 0,
"id": "fc7f49da-0510-4884-9cad-ae3e0b2488d9",
"createdDate": "2020-04-14T12:21:23.337"
},
"id": "0405507a-c8d5-440d-bb83-80e45f24b35f",
"createdBy": "[email protected]",
"createdDate": "2020-04-14T15:45:04.73"
}
],
"page": 1,
"limit": 2,
"total": 41
}
Data dictionary - Response
| PROPERTY | DESCRIPTION | TYPE |
|---|---|---|
| VaultId | Vault identifier. | string |
| OrderNumber | Service order / order number. | string |
| Status | Subscription status. | string |
| Id | Subscription identifier. | string |
| CreatedBy | User responsible for creating the subscription. | string |
| CreatedDate | Subscription creation date/time. | datetime |
| Plan.MerchantId | Merchant identifier. | string |
| Plan.Name | Plan name. | string |
| Plan.Description | Plan description. | string |
| Plan.Amount | Plan installment amount. | decimal |
| Plan.PlanType | Plan type. | string |
| Plan.TrialDays | Trial days. | integer |
| Plan.PaymentMethod | Payment method. | string |
| Plan.Interval | Billing interval in days. | integer |
| Plan.Installments | Number of installments. | integer |
| Plan.Status | Plan status. | string |
| Plan.Attempts | Retry attempts count. | integer |
| Plan.Id | Plan identifier. | string |
| Plan.CreatedDate | Plan creation date/time. | datetime |
| Page | Current page number. | integer |
| Limit | Items per page. | integer |
| Total | Total items found. | integer |
Request error
[
{
"tag": "Query",
"description": "Parâmetros de consulta inválidos"
}
]
Get subscription by ID
To retrieve a subscription by ID, send a GET request as shown below:
GET /v1/recurrences/subscriptions/{subscriptionId}
Data dictionary - Parameters
| PROPERTY | DESCRIPTION | TYPE | LOCATION | REQUIRED | MAX SIZE |
|---|---|---|---|---|---|
| SubscriptionId | Subscription identifier. | string | path | yes | 36 |
- 🟢 200
- 🔴 404
Subscription found
{
"vaultId": "fc3c5589-24b1-4bca-b8ab-e57b100c44cd",
"orderNumber": "1234567890",
"status": "Blocked",
"plan": {
"merchantId": "01700555550000",
"name": "PLANO CUSTOM DO SEU ZÉ",
"description": "PLANO DE RECORRÊNCIA EM 5X",
"amount": 31.000000,
"planType": "Custom",
"trialDays": 0,
"paymentMethod": "CreditCard",
"interval": 30,
"installments": 5,
"status": "Active",
"attempts": 0,
"id": "cef858c4-d0c6-4f27-b009-c303121f3b6e",
"createdDate": "2020-04-14T12:21:23.337"
},
"id": "013c7ec4-62c1-4d78-859d-e8d2a11f681d",
"createdDate": "2020-03-19T15:09:12.203"
}
Data dictionary - Response
| PROPERTY | DESCRIPTION | TYPE |
|---|---|---|
| VaultId | Vault identifier. | string |
| OrderNumber | Service order / order number. | string |
| Status | Subscription status. | string |
| Id | Subscription identifier. | string |
| CreatedDate | Subscription creation date/time. | datetime |
| Plan.MerchantId | Merchant identifier. | string |
| Plan.Name | Plan name. | string |
| Plan.Description | Plan description. | string |
| Plan.Amount | Plan installment amount. | decimal |
| Plan.PlanType | Plan type. | string |
| Plan.TrialDays | Trial days. | integer |
| Plan.PaymentMethod | Payment method. | string |
| Plan.Interval | Billing interval in days. | integer |
| Plan.Installments | Number of installments. | integer |
| Plan.Status | Plan status. | string |
| Plan.Attempts | Retry attempts count. | integer |
| Plan.Id | Plan identifier. | string |
| Plan.CreatedDate | Plan creation date/time. | datetime |
Subscription not found
{
"error": "Assinatura não encontrada"
}
Update subscription status
To change the subscription status, send a request as shown below:
POST /v1/recurrences/subscriptions/{subscriptionId}/status
Via REST request with the following body:
Request
{
"status": "Actived"
}
Data dictionary - Parameters
| PROPERTY | DESCRIPTION | TYPE | LOCATION | REQUIRED | MAX SIZE |
|---|---|---|---|---|---|
| SubscriptionId | Identifier of the subscription to update. | string | path | yes | 36 |
| Status | Status value (Actived, Canceled). | string | body | yes | fixed |
- 🟢 200
- 🔴 400
Status updated successfully
{"id":"0dd23cbd-de75-45a5-b2d1-972191140593"}
Data dictionary - Response
| PROPERTY | DESCRIPTION | TYPE |
|---|---|---|
| id | Identifier of the updated subscription. | string |
Request error
[
{
"tag": "Status",
"description": "Status inválido"
}
]
Update vault on a subscription
To change the vault associated with a subscription, send a request as shown below:
POST /v1/recurrences/subscriptions/{subscriptionId}/vault
Via REST request with the following body:
Request
{
"vaultId": "e954a511-f081-42e1-8531-2c4dcdf9a2cf"
}
Data dictionary - Parameters
| PROPERTY | DESCRIPTION | TYPE | LOCATION | REQUIRED | MAX SIZE |
|---|---|---|---|---|---|
| SubscriptionId | Subscription identifier. | string | path | yes | 36 |
| VaultId | Vault identifier. | string | body | yes | 36 |
- 🟢 200
- 🔴 400
Vault updated successfully
{"id":"013c7ec4-62c1-4d78-859d-e8d2a11f681d"}
Data dictionary - Response
| PROPERTY | DESCRIPTION | TYPE |
|---|---|---|
| id | Identifier of the updated subscription. | string |
Request error
[
{
"tag": "VaultId",
"description": "Cofre não encontrado"
}
]
Subscription statuses
| Status | Description |
|---|---|
| Active | Subscription is active and running normally |
| Canceled | Subscription canceled by the user or the system |
For questions or issues, visit the support section in