Cobranças (Billing)

Dados da API

API Gateway
Esta API é utilizada para operações do gateway de pagamento:

• Produção: https://api.sopague.com.br/gateway
• Homologação: https://api-hmg.sopague.com.br/gateway
• Arquitetura: Representational State Transfer (REST)

Introdução

As operações de Billing (Cobranças) permitem gerenciar os pagamentos recorrentes gerados pelas assinaturas. Através dessas operações, você pode consultar, cancelar e acompanhar o status dos pagamentos automáticos.

---

Buscar Pagamentos

Para buscar pagamentos é necessário enviar uma requisição utilizando o método GET para o recurso conforme o exemplo:

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

Dicionário de dados - Query Parameters

PROPRIEDADE	DESCRIÇÃO	TIPO	LOCAL	OBRIGATÓRIO
Mid	Número do Estabelecimento	string	query params	não
Status	Status do pagamento (Opened, PaymentInvalid, Canceled, Denied, Paid)	string	query params	não
ExpirationDateRangeStartDate	Data de Expiração (Data Inicial ex.:2020-01-01)	string	query params	não
ExpirationDateRangeEndDate	Data de Expiração (Data Final ex.:2020-01-31)	string	query params	não
OrderBy	Ordenação do resultado	string	query params	não
Page	Número da página	integer	query params	não
Limit	Limite de itens por página	integer	query params	não

🟢 200

Pagamentos encontrados

{
  "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
}

Dicionário de dados - Retorno

PROPRIEDADE	DESCRIÇÃO	TIPO
Status	Status do pagamento	string
ExpireAt	Data de expiração do pagamento.	datetime
Amount	Valor do pagamento	decimal
Installment	Número da parcela	integer
Id	Identificador do pagamento	string
CreatedBy	Usuário responsável pela criação do pagamento	string
CreatedDate	Data e hora de criação do pagamento	datetime
ModifiedBy	Usuário responsável pela última modificação no pagamento	string
ModifiedDate	Data e hora da última modificação no pagamento	datetime
Subscription.VaultId	Identificador do cofre	string
Subscription.OrderNumber	Número da Ordem de Serviço ou Pedido	string
Subscription.Status	Status da assinatura	string
Subscription.Id	Identificador da assinatura	string
Subscription.CreatedBy	Usuário responsável pela criação da assinatura.	string
Subscription.CreatedDate	Data e hora da criação da assinatura	datetime
Subscription.Plan.MerchantId	Identificador do estabelecimento	string
Subscription.Plan.Name	Nome do Plano	string
Subscription.Plan.Description	Descrição do plano	string
Subscription.Plan.Amount	Valor parcelas do plano	decimal
Subscription.Plan.PlanType	Tipo do plano	string
Subscription.Plan.TrialDays	Número de dias em degustação	integer
Subscription.Plan.PaymentMethod	Método de pagamento	string
Subscription.Plan.Interval	Intervalo em dias entre as cobranças	integer
Subscription.Plan.Installments	Número de parcelas	integer
Subscription.Plan.Status	Status do plano	string
Subscription.Plan.Attempts	Número de tentativas da teimosinha	integer
Subscription.Plan.Id	Identificador do plano	string
Subscription.Plan.CreatedBy	Usuário responsável pela criação do plano.	string
Subscription.Plan.CreatedDate	Data e hora de criação do plano	datetime
Page	Número da página atual	integer
Limit	Limite de itens por página	integer
Total	Total de itens encontrados	integer

🔴 400

Erro na requisição

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

Filtros Disponíveis

Por Status

• Opened: Pagamentos em aberto
• PaymentInvalid: Pagamentos com erro
• Canceled: Pagamentos cancelados
• Denied: Pagamentos negados
• Paid: Pagamentos aprovados

Por Data de Expiração

• ExpirationDateRangeStartDate: Data inicial do período
• ExpirationDateRangeEndDate: Data final do período

Por Estabelecimento

• Mid: Número do estabelecimento

---

Cancelar Pagamento

Para cancelar um pagamento ainda não efetivado é necessário enviar uma requisição utilizando o método PUT para o recurso conforme o exemplo:

PUT /v1/recurrence/billing/{billingId}/cancel

Dicionário de dados - Parâmetros

PROPRIEDADE	DESCRIÇÃO	TIPO	LOCAL	OBRIGATÓRIO	TAMANHO MÁXIMO
BillingId	Identificador do pagamento a ser cancelado.	string	path	sim	36

🟢 200

Pagamento cancelado com sucesso

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

Dicionário de dados - Retorno

PROPRIEDADE	DESCRIÇÃO	TIPO
BillingId	Identificador do pagamento que foi cancelado.	string

🔴 400

Erro na requisição

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

🔴 404

Pagamento não encontrado

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

---

Status dos Pagamentos

Status	Descrição
Opened	Pagamento aberto, aguardando processamento
PaymentInvalid	Pagamento inválido ou com erro
Canceled	Pagamento cancelado
Denied	Pagamento negado pela operadora
Paid	Pagamento aprovado e processado

Para dúvidas ou problemas, acesse a seção de suporte no Cinq.