Billings (Recurring Charges)

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

Billing operations let you manage the recurring payments generated by subscriptions. With these operations, you can query, cancel, and track the status of automatic payments.

---

Search payments

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

GET /v1/recurrences/billing?mid={mid}&status={status}&expirationDateRangeStartDate={expirationDateRangeStartDate}&expirationDateRangeEndDate={expirationDateRangeEndDate}&orderBy={orderBy}&page={page}&limit={limit}

Data dictionary - Query parameters

PROPERTY	DESCRIPTION	TYPE	LOCATION	REQUIRED
Mid	Merchant number.	string	query params	no
Status	Payment status filter (Opened, PaymentInvalid, Canceled, Denied, Paid).	string	query params	no
ExpirationDateRangeStartDate	Expiration date range start (e.g., 2020-01-01).	string	query params	no
ExpirationDateRangeEndDate	Expiration date range end (e.g., 2020-01-31).	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

Payments found

{
  "items": [
    {
      "status": "Paid",
      "expireAt": "2020-06-05T00:00:00",
      "amount": 29.990000,
      "subscription": {
        "vaultId": "d2372c60-dc5f-465b-befc-2650976aaa55",
        "orderNumber": "123456789",
        "status": "Blocked",
        "plan": {
          "merchantId": "017005555500000",
          "name": "Plano custom 1",
          "description": "Plano customizado para você",
          "amount": 29.990000,
          "planType": "Monthly",
          "trialDays": 0,
          "paymentMethod": "CreditCard",
          "interval": 30,
          "installments": 1,
          "status": "Active",
          "attempts": 2,
          "id": "d9b8c7a2-e286-4dd0-aea7-d72fe8daafa9",
          "createdBy": "[email protected]",
          "createdDate": "2020-05-04T15:52:03.93"
        },
        "id": "145537c6-4ed6-4124-a5e1-be20735008a3",
        "createdBy": "[email protected]",
        "createdDate": "2020-05-04T15:53:36.13"
      },
      "installment": 2,
      "id": "4e389b08-7fae-4fe0-a6ba-1789373c8d05",
      "createdBy": "[email protected]",
      "createdDate": "2020-05-04T15:57:14.72",
      "modifiedBy": "[email protected]",
      "modifiedDate": "2020-05-04T15:57:26.41"
    },
    {
      "status": "PaymentInvalid",
      "expireAt": "2020-03-24T00:00:00",
      "amount": 41.000000,
      "subscription": {
        "vaultId": "ea7ff702-639d-4edc-ad36-8beca4c15e2c",
        "orderNumber": "1234567890",
        "status": "Blocked",
        "plan": {
          "merchantId": "017005555500000",
          "name": "PLANO MENSAL",
          "description": "PLANO DE RECORRÊNCIA QUADRIMESTRAL 2",
          "amount": 41.000000,
          "planType": "Quarterly",
          "trialDays": 0,
          "paymentMethod": "CreditCard",
          "interval": 30,
          "installments": 3,
          "status": "Active",
          "attempts": 3,
          "id": "fda81b20-8f85-418b-9eb7-cb61aee40fbc",
          "createdDate": "2020-04-14T12:21:23.337"
        },
        "id": "2211ca27-2c56-4528-ba48-bda4dcf17c22",
        "createdDate": "2020-02-23T00:00:00"
      },
      "installment": 2,
      "id": "5b04bece-7ede-4768-a079-8f42501c1adc",
      "createdDate": "2020-04-14T12:21:23.94"
    }
  ],
  "page": 1,
  "limit": 2,
  "total": 8
}

Data dictionary - Response

PROPERTY	DESCRIPTION	TYPE
Status	Payment status.	string
ExpireAt	Payment expiration date/time.	datetime
Amount	Payment amount.	decimal
Installment	Installment number.	integer
Id	Billing identifier.	string
CreatedBy	User responsible for creating the billing record.	string
CreatedDate	Billing creation date/time.	datetime
ModifiedBy	User responsible for the last billing update.	string
ModifiedDate	Last billing update date/time.	datetime
Subscription.VaultId	Vault identifier.	string
Subscription.OrderNumber	Service order / order number.	string
Subscription.Status	Subscription status.	string
Subscription.Id	Subscription identifier.	string
Subscription.CreatedBy	User responsible for creating the subscription.	string
Subscription.CreatedDate	Subscription creation date/time.	datetime
Subscription.Plan.MerchantId	Merchant identifier.	string
Subscription.Plan.Name	Plan name.	string
Subscription.Plan.Description	Plan description.	string
Subscription.Plan.Amount	Plan installment amount.	decimal
Subscription.Plan.PlanType	Plan type.	string
Subscription.Plan.TrialDays	Trial days.	integer
Subscription.Plan.PaymentMethod	Payment method.	string
Subscription.Plan.Interval	Billing interval in days.	integer
Subscription.Plan.Installments	Number of installments.	integer
Subscription.Plan.Status	Plan status.	string
Subscription.Plan.Attempts	Retry attempts count.	integer
Subscription.Plan.Id	Plan identifier.	string
Subscription.Plan.CreatedBy	User responsible for creating the plan.	string
Subscription.Plan.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"
  }
]

Available filters

By status

• Opened: Payments open
• PaymentInvalid: Payments with error
• Canceled: Canceled payments
• Denied: Denied payments
• Paid: Approved payments

By expiration date

• ExpirationDateRangeStartDate: Period start date
• ExpirationDateRangeEndDate: Period end date

By merchant

• Mid: Merchant number

---

Cancel payment

To cancel a payment that has not yet been finalized, call the endpoint below:

POST /v1/recurrences/billing/{billingId}/cancel

Data dictionary - Parameters

PROPERTY	DESCRIPTION	TYPE	LOCATION	REQUIRED	MAX SIZE
BillingId	Identifier of the billing to be canceled.	string	path	yes	36

🟢 200

Payment canceled successfully

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

Data dictionary - Response

PROPERTY	DESCRIPTION	TYPE
BillingId	Identifier of the canceled billing.	string

🔴 400

Request error

[
  {
    "tag": "Billing",
    "description": "Pagamento já foi processado, não é possível cancelar"
  }
]

🔴 404

Payment not found

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

---

Payment statuses

Status	Description
Opened	Payment is open and waiting to be processed
PaymentInvalid	Payment is invalid or has an error
Canceled	Payment has been canceled
Denied	Payment was denied by the network/operator
Paid	Payment approved and processed

---

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