Planos

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

Planos são as propostas apresentadas pelas empresas aos possíveis clientes. Por exemplo, uma academia pode disponibilizar planos mensais, trimestrais ou anuais, fazendo com que o cliente opte por um plano mais adequado para as suas necessidades.

---

Criar Plano

Para criar um plano é necessário enviar uma requisição utilizando o método POST para o recurso conforme o exemplo:

POST /v1/recurrence/plans

Via request Representational State Transfer (REST) com o body:

Requisição

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

Dicionário de dados - Parâmetros

PROPRIEDADE	DESCRIÇÃO	TIPO	LOCAL	OBRIGATÓRIO	TAMANHO MÁXIMO
MerchantId	Identificador do estabelecimento.	string	body	Não (capturado via autenticação)	20
Name	Nome do Plano	string	body	sim	255
Description	Descrição do plano	string	body	sim	255
Amount	Valor parcelas do plano	decimal	body	sim	12 inteiros e 6 decimais
PlanType	Tipo do plano (Monthly, Bimonthly, Quarterly, Semesterly, Yearly, Custom)	string	body	sim	Fixo
TrialDays	Número de dias em degustação	integer	body	não	Não aplicável
PaymentMethod	Método de pagamento (CreditCard)	string	body	sim	Fixo
Interval	Intervalo em dias entre as cobranças	integer	body	condicional	Maior que 20
Installments	Número de parcelas	integer	body	condicional	Não aplicável
Attempts	Número de tentativas da teimosinha (limitado até 4 tentativas)	integer	body	condicional	4

Tipos de Plano

Monthly = Mensal
Para plano "Monthly" as cobranças irão acontecer a cada 30 dias. Não há data de término até que a assinatura seja cancelada, ou que a transação seja negada pelo emissor/bandeira.

Bimonthly = Bimestral
Quarterly = Trimestral
Semesterly = Semestral
Yearly = Anual

Para qualquer plano citado acima, não é necessário o envio das tags interval e installments, pois o sistema irá automaticamente atribuir o intervalo de 30 dias corridos e o número de parcelas de acordo com o tipo de plano escolhido.

Um planType do tipo Custom deve apresentar interval de no mínimo 20 e installments maior que zero.

Teimosinha

O campo attempts indica o número de tentativas da teimosinha. A teimosinha ocorrerá quando a tentativa de pagamento não é concluída por falta de saldo. Se o cartão estiver cancelado, a teimosinha não ocorrerá e o sistema deixará a conta de assinatura bloqueada.

Regras da Teimosinha:

• Caso o valor apresentado no campo attempts seja 1 e a primeira tentativa de pagamento não obteve sucesso, o sistema irá realizar uma nova tentativa 2 dias após a última falha de pagamento.
• Caso o valor apresentado no campo attempts seja 4 e já foram feitas 3 tentativas de pagamento sem sucesso, o sistema irá realizar uma nova tentativa 4 dias após a última falha de pagamento.
• Caso o valor apresentado no campo attempts seja 4 e já foram feitas 4 tentativas de pagamento sem sucesso, o sistema irá realizar uma nova tentativa 8 dias após a última falha de pagamento e não tentará novamente.
• Caso um pagamento tenha data de pagamento em 01/01, a primeira tentativa de teimosinha será feita dia 03/01, a segunda no dia 05/01, a terceira no dia 09/01, e a quarta e última tentativa será no dia 17/01.

🟢 200

Plano criado com sucesso

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

Dicionário de dados - Retorno

PROPRIEDADE	DESCRIÇÃO	TIPO
PlanId	Identificador do plano criado.	string

🔴 400

Erro na requisição

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

🔴 500

Erro interno

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

---

Buscar Planos

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

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

Dicionário de dados - Query Parameters

PROPRIEDADE	DESCRIÇÃO	TIPO	LOCAL	OBRIGATÓRIO
Name	Nome do Plano	string	query params	não
Status	Status do plano	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

Planos encontrados

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

Dicionário de dados - Retorno

PROPRIEDADE	DESCRIÇÃO	TIPO
MerchantId	Identificador do estabelecimento.	string
Name	Nome do Plano	string
Description	Descrição do plano	string
Amount	Valor parcelas do plano	decimal
PlanType	Tipo do plano	string
TrialDays	Número de dias em degustação	integer
PaymentMethod	Método de pagamento	string
Interval	Intervalo em dias entre as cobranças	integer
Installments	Número de parcelas	integer
Status	Status do plano	string
Attempts	Número de tentativas da teimosinha	integer
Id	Identificador do plano	string
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"
  }
]

---

Buscar Plano por ID

Para buscar um plano específico por ID:

GET /v1/recurrence/plans/{planId}

Dicionário de dados - Parâmetros

PROPRIEDADE	DESCRIÇÃO	TIPO	LOCAL	OBRIGATÓRIO	TAMANHO MÁXIMO
PlanId	ID do plano	string	path	sim	36

🟢 200

Plano encontrado

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

Dicionário de dados - Retorno

PROPRIEDADE	DESCRIÇÃO	TIPO
MerchantId	Identificador do estabelecimento.	string
Name	Nome do Plano	string
Description	Descrição do plano	string
Amount	Valor parcelas do plano	decimal
PlanType	Tipo do plano	string
TrialDays	Número de dias em degustação	integer
PaymentMethod	Método de pagamento	string
Interval	Intervalo em dias entre as cobranças	integer
Installments	Número de parcelas	integer
Status	Status do plano	string
Attempts	Número de tentativas da teimosinha	integer
Id	Identificador do plano	string
CreatedDate	Data e hora de criação do plano	datetime

🔴 404

Plano não encontrado

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

---

Atualizar Plano

Para atualizar um plano é necessário enviar uma requisição utilizando o método PUT:

PUT /v1/recurrence/plans/{planId}

Observações

• Não é possível alteração de valores do plano caso estejam ativos.
• Demais campos do plano só podem ser alterados se o mesmo não estiver em utilização, caso contrário somente as tags name e description podem ser alteradas.

Via request Representational State Transfer (REST) com o body:

Requisição

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

Dicionário de dados - Parâmetros

PROPRIEDADE	DESCRIÇÃO	TIPO	LOCAL	OBRIGATÓRIO	TAMANHO MÁXIMO
PlanId	Identificador do plano a ser alterado.	string	path	sim	36
MerchantId	Identificador do estabelecimento.	string	body	sim	20
Name	Nome do Plano	string	body	sim	255
Description	Descrição do plano	string	body	sim	255
Amount	Valor	decimal	body	sim	12
PlanType	Tipo do plano	string	body	sim	Fixo
TrialDays	Número de dias em degustação	integer	body	não	Não aplicável
PaymentMethod	Método de pagamento	string	body	sim	Fixo
Interval	Intervalo em dias entre as cobranças	integer	body	condicional	Maior que 20
Installments	Número de parcelas	integer	body	condicional	Não aplicável
Attempts	Número de tentativas da teimosinha (limitado até 4 tentativas)	integer	body	condicional	4

🟢 200

Plano atualizado com sucesso

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

Dicionário de dados - Retorno

PROPRIEDADE	DESCRIÇÃO	TIPO
PlanId	Identificador do plano que foi atualizado.	string

🔴 400

Erro na requisição

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

---

Atualizar Status do Plano

Para atualizar o status de um plano:

PUT /v1/recurrence/plans/{planId}/status

Via request Representational State Transfer (REST) com o body:

Requisição

{
  "status": "Active"
}

Dicionário de dados - Parâmetros

PROPRIEDADE	DESCRIÇÃO	TIPO	LOCAL	OBRIGATÓRIO	TAMANHO MÁXIMO
PlanId	Identificador do plano a ser alterado.	string	path	sim	36
Status	Status (Active, Inactive, Canceled)	string	body	sim	Fixo

🟢 200

Status atualizado com sucesso

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

Dicionário de dados - Retorno

PROPRIEDADE	DESCRIÇÃO	TIPO
PlanId	Identificador do plano que foi atualizado.	string

🔴 400

Erro na requisição

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

---

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