Documentação
Github

Criar ordem de pagamento

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

AtributoTipoDescriçãoObrigatórioTamanho
TerminalIdstringIdentificador da máquinaSim36
ApplicationstringNome da aplicação de automação comercialSimTamanho min: 03
Tamanho max: 100
ReferencestringCódigo de referência do sistema integradoSimTamanho min: 03
Tamanho max: 200
CallbackUrlstringURL para receber os eventos relacionados ao processamento da ordem de pagamentoNãoTamanho max: 400
PaymentMethodintCódigo para a forma de pagamento. Confira a tabela completaNãoCódigo 2 ou 4
AmountfloatValor de venda em R$NãoPara vendas parceladas feitas no crédito, o valor da parcela deve ser maior ou igual a R$ 5,00
InstallmentQuantityintNúmero de parcelas. Case seja informado 1 e o PaymentMethod for 2, será considerado crédito avista.NãoDeve 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ódigoDescrição
201 - CreatedA ordem de pagamento foi criada com sucesso e será enviada para máquina.
403 - ForbiddenO token enviado é inválido ou inexistente,
422 - Unprocessable EntityAs informações enviadas estão inválidas ou a máquina está inoperante.

Updated 11 months ago