Pular para o conteúdo principal

Notificações

Dados da API

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

Introdução​

Caso uma tentativa de pagamento não obtenha êxito, será enviada uma notificação para os estabelecimentos que possuam cadastro de notificações que estão com o status ativo. O envio ocorrerá após cada tentativa de cobrança, mesmo nos casos que possuam teimosinha.

Criar Notificação​

Para criar os parâmetros de notificação é necessário enviar uma requisição utilizando o método POST para o recurso conforme o exemplo:

POST /v1/recurrence/merchantnotifier

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

Requisição
{
  "merchantId": "017005555500000",
  "name": "New Merchant Notifier",
  "description": "Adding callback",
  "callbackUrl": "http://test.com/feeds/paymentsFail/"
}

Dicionário de dados - Parâmetros​

PROPRIEDADEDESCRIÇÃOTIPOLOCALOBRIGATÓRIOTAMANHO MÁXIMO
MerchantIdIdentificador do estabelecimento.stringbodysim20
NameNome da notificaçãostringbodysim50
DescriptionDescrição da notificaçãostringbodysim150
CallbackUrlURL do endpoint do lado do estabelecimentostringbodysim500
Erro interno
[
  {
    "tag": "",
    "description": "Não foi possível executar comando. Erro desconhecido."
  }
]

Buscar Notificações​

Busca de cadastros de notificações:

GET /v1/recurrence/merchantnotifier?merchantId={merchantId}&name={name}&status={status}

Dicionário de dados - Query Parameters​

PROPRIEDADEDESCRIÇÃOTIPOLOCALOBRIGATÓRIOTAMANHO MÁXIMO
MerchantIdID do Estabelecimentostringquery paramsnão20
NameNome da notificaçãostringquery paramsnão50
StatusStatus da notificação (Active, Canceled)stringquery paramsnãoFixo
Notificações encontradas
[
  {
    "status": "Active",
    "merchantId": "017005555500000",
    "name": "New Merchant Notifier",
    "description": "Adding callback",
    "callbackUrl": "http://test.com/feeds/paymentsFail/",
    "id": "57412511-2940-477d-8422-f5c17a3fe4f5",
    "createdBy": "sopague",
    "createdDate": "2021-08-25T16:27:40.97"
  }
]

Dicionário de dados - Retorno​

PROPRIEDADEDESCRIÇÃOTIPO
StatusStatus da notificaçãostring
MerchantIdIdentificador do estabelecimentostring
NameNome da notificaçãostring
DescriptionDescrição da notificaçãostring
CallbackUrlUrl de callback da notificaçãostring
IdIdentificador da notificaçãostring
CreatedByUsuário responsável pela criação da notificaçãostring
CreatedDateData e hora de criação da notificaçãodatetime

Atualizar Notificação​

Para atualizar os dados da Notificação é necessário enviar uma requisição utilizando o método PUT para o recurso conforme o exemplo:

PUT /v1/recurrence/merchantnotifier/{merchantNotifierId}

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

Requisição
{
  "merchantId": "017005555500000",
  "name": "Merchant Notifier",
  "description": "Updating callback",
  "callbackUrl": "http://test.com/feeds/paymentsFail/v2",
  "status": "Active"
}

Dicionário de dados - Parâmetros​

PROPRIEDADEDESCRIÇÃOTIPOLOCALOBRIGATÓRIOTAMANHO MÁXIMO
MerchantNotifierIdIdentificador da notificação a ser alterada.stringpathsim36
MerchantIdIdentificador do estabelecimento.stringbodysim20
NameNome da notificaçãostringbodysim50
DescriptionDescrição da notificaçãostringbodysim150
CallbackUrlURL do endpoint do lado do estabelecimentostringbodysim500
StatusStatus da notificação (Active, Canceled)stringbodysimFixo
Notificação atualizada com sucesso
{
  "status": "Active",
  "merchantId": "017005555500000",
  "name": "Update Merchant Notifier",
  "description": "Updating callback",
  "callbackUrl": "http://test.com/feeds/paymentsFail/v2/",
  "id": "57412511-2940-477d-8422-f5c17a3fe4f6",
  "createdBy": "Sopague",
  "createdDate": "2021-08-25T16:27:40.97",
  "modifiedBy": "Sopague",
  "modifiedDate": "2021-08-25T16:37:29.917"
}

Dicionário de dados - Retorno​

PROPRIEDADEDESCRIÇÃOTIPO
StatusStatus da notificaçãostring
MerchantIdIdentificador do estabelecimentostring
NameNome da notificaçãostring
DescriptionDescrição da notificaçãostring
CallbackUrlUrl de callback da notificaçãostring
IdIdentificador da notificaçãostring
CreatedByUsuário responsável pela criação da notificaçãostring
CreatedDateData e hora de criação da notificaçãodatetime
ModifiedByUsuário responsável pela última modificação da notificaçãostring
ModifiedDateData e hora da última modificação da notificaçãodatetime

Notificações de Pagamentos com Falha​

Para receber notificações de falhas, é necessário que o Estabelecimento implemente um endpoint em sua aplicação, que receba uma requisição utilizando o método POST conforme o exemplo:

Observação

O sistema só envia notificação de falhas no pagamento.

POST "endpoint do Estabelecimento"

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

Requisição
{
  "SubscriptionId": "ba2dad08-7047-467d-8555-a947621d6554",
  "PlanId": "72c6bfb2-4437-4a6d-9513-d9b4db520323",
  "OrderNumber": "1234567890",
  "BillingId": "33d49aaa-2aa7-402c-98d7-bc6d46af3aee",
  "ExpireAt": "2021-08-20T07:00:00-03:00",
  "ErrorCode": "Falha ao enviar notificação",
  "ErrorMessage": "Não foi possível se conectar."
}

Dicionário de dados - Parâmetros​

PROPRIEDADEDESCRIÇÃOTIPOLOCALOBRIGATÓRIO
SubscriptionIdIdentificador da assinaturastringbodysim
PlanIdIdentificador do planostringbodysim
OrderNumberDescrição da ordemstringbodysim
BillingIdIdentificador da cobrançadecimalbodysim
ExpireAtData vencimento cobrançadatetimebodysim
ErrorCodeCódigo de erro recebido do autorizador.stringbodysim
ErrorMessageMensagem de erro recebido do autorizador.stringbodysim
Notificação recebida com sucesso
{
  "status": "success",
  "message": "Notificação processada"
}

Notificações de Pagamento​

Sempre que houver uma cobrança ou atualização de status de pagamento de uma transação de recorrência, caso as notificações estejam habilitadas, será enviado um POST para a URL configurada, com os seguintes campos:

Estrutura da Notificação de Pagamento

Dicionário de dados - Parâmetros​

PROPRIEDADEDESCRIÇÃOTIPO
PaymentIdPaymentId da transação.String
OrderNumberNúmero de ordem de transação.String
SubscriptionIdId da assinatura.String
BillingIdId do plano.String
StatusDescriptionDescrição do status do pagamento.String
StatusCodeCódigo do status do pagamento.String
DateData do pagamento.DateTime
PaymentMethodMétodo de pagamento.String

Exemplo de Notificação​

Exemplo de Notificação
{
  "paymentId": "",
  "checkoutOrderNumber": "",
  "orderNumber": "",
  "subscriptionId": "",
  "billingId": "",
  "statusDescription": "",
  "statusCode": "",
  "date": "2024-10-08T21:00:00",
  "paymentMethod": null
}

Resposta​

Caso o pagamento seja efetuado com sucesso, o campo statusCode será preenchido com 200. Em caso de statusCode diferente de 200, a descrição do erro no pagamento estará no campo statusDescription.

Para configurar e começar a receber as notificações acesse as instruções em nossa documentação.

Status das Notificações​

StatusDescrição
ActiveNotificação ativa e funcionando
CanceledNotificação cancelada

Códigos de Erro​

HTTP Status Code​

HTTP Status CodeDescrição
200OK
400Bad Request
401Unauthorized
402Client Error
500Internal Server Error

Exemplo de Erro​

Campo obrigatório não informado, a resposta será:

Exemplo de Erro
[
  {
    "tag": "Campo",
    "description": "Não pode ser nulo ou vazio."
  }
]
PropriedadeDescrição
TagCódigo de Erro da API.
DescriptionDescrição do erro.

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