Caso de uso

"Preciso que meu cliente consiga realizar o envio de uma solicitação de ordem de pagamento via API para a máquina."

O que é uma ordem de pagamento?

Uma Ordem de pagamento é uma solicitação iniciada pelo Merchant usando a API Safe2Pay. O Merchant envia detalhes da transação, como identificador da máquina, referência, nome da aplicação, valor e método de pagamento, através da API. A API Safe2Pay valida e processa este pedido, comunica-se com o POS para a realização do pagamento pelo cliente, e, após o processamento da transação, envia um retorno (callback) sobre o sucesso ou falha do pagamento ao Merchant.

Diagrama de fluxo

Criação de uma ordem de pagamento

Para realizar a criação de uma Ordem, você pode utilizar a API Criar Ordem de Pagamento

🚧
Pré-requisitos para uso da Máquina
Antes de enviar uma solicitação de ordem de pagamento ou cancelamento para o POS, verifique se:

A máquina está ativa.

O aplicativo Safe2Pay está aberto.

O usuário está logado no aplicativo.

🚧
Nível mínimo de bateria
Assegure-se de que a máquina tenha pelo menos 6% de bateria para receber as ordens.

Informações sobre o payload de envio

Atributo	Tipo	Descrição	Obrigatório	Tamanho
TerminalId	string	Identificador da máquina	Sim	36
Application	string	Nome da aplicação de automação comercial	Sim	Tamanho min: 03 Tamanho max: 100
Reference	string	Código de referência do sistema integrado	Sim	Tamanho min: 03 Tamanho max: 200
CallbackUrl	string	URL para receber os eventos relacionados ao processamento da ordem de pagamento	Não	Tamanho max: 400
PaymentMethod	int	Código para a forma de pagamento. Confira a tabela completa	Não	Código 2 ou 4
Amount	float	Valor de venda em R$	Não	Para vendas parceladas feitas no crédito, o valor da parcela deve ser maior ou igual a R$ 5,00
InstallmentQuantity	int	Número de parcelas. Case seja informado 1 e o PaymentMethod for 2, será considerado crédito avista.	Não	Deve ser maior ou igual a 1 e menor ou igual a 12

📘
Método e valor de pagamento flexíveis
Com nossa API de criação de ordem de pagamento, oferecemos flexibilidade tanto na escolha do método quanto no valor do pagamento. Você pode definir previamente se a transação será por Crédito ou Débito ao enviar a ordem para a máquina. Além disso, tanto o método quanto o valor do pagamento podem ser ajustados diretamente na máquina no momento da transação.

Exemplos de payloads de envio

{
    "TerminalId": "adc9ab61-fda8-4b28-b1bc-695400af2d20",
    "Application": "API X",
    "Reference": "12345",
    "CallbackUrl": "https://webhook.site/8642673b-0ceb-4a57-86a5-2da3b13afaeb",
    "PaymentMethod": 2,
    "Amount": 5.00,
    "InstallmentQuantity": 1
}

{
    "TerminalId": "adc9ab61-fda8-4b28-b1bc-695400af2d20",
    "Application": "API X",
    "Reference": "12345",
    "CallbackUrl": "https://webhook.site/8642673b-0ceb-4a57-86a5-2da3b13afaeb",
    "PaymentMethod": 1,
    "Amount": 5.00,
    "InstallmentQuantity": 1
}

Exemplos de payloads de retorno

{
  "data": {
    "reference": "12345",
    "paymentOrderId": 176
  }
}

{
  "data": {
    "title": "Não foi possível concluir a operação. Um ou mais erros ocorreram.",
    "errors": [
      {
        "message": "O campo Application precisa ser fornecido."
      },
      {
        "message": "O campo Reference precisa ser fornecido."
      },
      {
        "message": "O campo TerminalId deve ser informado."
      }
    ]
  }
}

{
    "data": {
        "title": "Não foi possível concluir a operação. Um ou mais erros ocorreram.",
        "errors": [
            {
                "message": "A máquina está inoperante."
            }
        ],
        "traceId": 7403863412448116474
    }
}

{
    "data": {
        "title": "Não foi possível concluir a operação. Um ou mais erros ocorreram.",
        "errors": [
            {
                "message": "Não foi possível concluir a operação. A máquina vinculada ao merchant não foi encontrada."
            }
        ],
        "traceId": 2608947945305694113
    }
}

{
  "title": "Não foi possível concluir a operação. Um ou mais erros ocorreram.",
  "errors": [
    {
      "message": "Não foi possível realizar a autenticação com os parâmetros informados."
    }
  ]
}

Códigos de resposta

Código	Descrição
201 - Created	A ordem de pagamento foi criada com sucesso e será enviada para máquina.
403 - Forbidden	O token enviado é inválido ou inexistente,
422 - Unprocessable Entity	As informações enviadas estão inválidas ou a máquina está inoperante.