ORION API DOC v1.0

1. Autenticação

Descrição: Para todos os endpoints, a autenticação é feita através do envio dos seguintes tokens nos cabeçalhos das requisições.

Cabeçalhos de Autenticação:
- public_token: client_id
- secret_token: client_secret
- accept: application/json
- content-type: application/json

2. Endpoints

2.1. Solicitação de QR Code para Pagamento (Cash-In)

Endpoint: https://api.orionpayments.app/webhook/transactions.php

Método: POST

Descrição: Este endpoint gera um QR Code para um pagamento via Pix. Inclui dados do cliente, valor da transação e informações de split de pagamento.

Cabeçalhos:
- public_token: client_id
- secret_token: client_secret
- accept: application/json
- content-type: application/json

2.2. Parâmetros de Requisição

Parâmetro	Tipo	Obrigatório	Descrição
`customer`	objeto	Sim	Detalhes do cliente que fará o pagamento.
`document.type`	string	Sim	Tipo de documento do cliente (ex.: `"cpf"`).
`document.number`	string	Sim	Número do documento do cliente (ex.: `"91516432002"`).
`name`	string	Sim	Nome do cliente (ex.: `"User"`).
`email`	string	Sim	Email do cliente (ex.: `"johndoe@gmail.com"`).
`phone`	string	Sim	Telefone do cliente com código do país (ex.: `"+5582985113768"`).
`amount`	int	Sim	Valor da transação em centavos (ex.: `15000` para R$150,00).
`paymentMethod`	string	Sim	Método de pagamento (deve ser `"pix"`).
`items`	array	Sim	Lista de itens que compõem a transação.
`tangible`	bool	Sim	Define se o item é tangível (ex.: `true`).
`title`	string	Sim	Título do item (ex.: `"Saldo"`).
`unitPrice`	int	Sim	Preço unitário em centavos (ex.: `15000`).
`quantity`	int	Sim	Quantidade de itens (ex.: `1`).
`split_to`	string	Não	Email do destinatário da divisão de pagamento (ex.: `"marydoe@gmail.com"`).
`percent_split`	int	Não	Percentual da transação que será dividido com o destinatário (ex.: `10`).
`postback_url`	string	Sim	URL de callback para notificações da transação.

Exemplo de Requisição:

{
  "customer": {
    "document": {
      "type": "cpf",
      "number": "39374428040"
    },
    "name": "User",
    "email": "johndoe@gmail.com",
    "phone": "+553191516432002"
  },
  "amount": 15000,
  "paymentMethod": "pix",
  "items": [
    {
      "tangible": true,
      "title": "Saldo",
      "unitPrice": 15000,
      "quantity": 1
    }
  ],
  "split_to": "marydoe@gmail.com",
  "percent_split": 10,
  "postback_url": "https://seusite.com/orion-callback"
}

Exemplo de Resposta:

{
  "status": "success",
  "transaction": {
    "id": "34089",
    "user_id": "417",
    "amount": "1.00",
    "paymentMethod": "pix",
    "card_id": "1",
    "card_hash": "0",
    "card_number": "0",
    "card_holderName": "0",
    "card_expirationMonth": "0",
    "card_expirationYear": "0",
    "card_cvv": "0",
    "installments": "0",
    "customer_id": "j5fafc7c6a9874635e34e5d5ec3a53qe",
    "customer_name": "John Doe",
    "customer_email": "johndoe@gmail.com",
    "customer_document_number": "39374428040",
    "customer_document_type": "cpf",
    "customer_phone": "553191516432002",
    "customer_externalRef": "0",
    "shipping_fee": "0.00",
    "shipping_street": "",
    "shipping_streetNumber": "",
    "shipping_complement": "",
    "shipping_zipCode": "",
    "shipping_neighborhood": "",
    "shipping_city": "",
    "shipping_state": "",
    "shipping_country": "BR",
    "item_title": "Teste API",
    "item_unitPrice": "1.00",
    "item_quantity": "1",
    "item_tangible": "1",
    "item_externalRef": "0",
    "boleto_expiresInDays": "30",
    "pix_expiresInDays": "30",
    "postbackUrl": "https://url-callback/orion-callback",
    "metadata": "",
    "traceable": "1",
    "ip": "",
    "split_recipientId": "1",
    "split_amount": "1.00",
    "split_chargeProcessingFee": "1",
    "status": "0",
    "idqrcode": "j5fafc7c6a9874635e34e5d5ec3a53qe",
    "created_at": "2024-11-13 10:31:24",
    "updated_at": "2024-11-13 10:31:24",
    "split_to": "0",
    "split_value": "0.00",
    "percent_split": "0.00",
    "pix_payload": "00020126850014br.gov.bcb.pix2563pix.voluti.com.br/qr/v3/at/2c9628ca-8cc0-4f89-aacc-8692e6a200d75204000053039865802BR5909DET_PAY_62070503***630413B9",
    "pix_image_base64": "https://generator.qrcodefacil.com/qrcodes/static-872718accef18e337d7da93d80ea8bd1.svg"
  }
}

2.3. Códigos de Status

Código de Status	Descrição
`200 OK`	QR Code gerado com sucesso.
`400 Bad Request`	Dados inválidos (ex.: valor fora dos limites permitidos).
`500 Internal Server Error`	Falha na comunicação com o banco.

2.4. Saque via Pix (Cash-Out)

Endpoint: POST https://api.orionpayments.app/webhook/saque.php

Descrição: Realiza um saque via Pix para o usuário especificado, com base nos dados de identificação e valor.

Cabeçalhos:
- public_token: client_id
- secret_token: client_secret
- accept: application/json
- content-type: application/json

2.5. Parâmetros de Requisição

Parâmetro	Tipo	Obrigatório	Descrição
`value_cents`	integer	Sim	Valor do saque em centavos.
`receiver_name`	string	Sim	Nome do recebedor.
`receiver_document`	string	Sim	Tipo de documento do recebedor (ex.: `"CPF"`).
`pix_key`	string	Sim	Chave Pix do recebedor.

Exemplo de Requisição:

{
  "value_cents": 15000,
  "receiver_name": "Nome do Recebedor",
  "receiver_document": "CPF",
  "pix_key": "39374428040"
}

Exemplo de Resposta:

{
  "status": "success",
  "response": {
    "endToEndId": "E3038525920241113134319026621e7c",
    "eventDate": "2024-11-13T13:43:19.026+00:00",
    "status": "PENDING",
    "id": 83226980,
    "payment": {
      "currency": "BRL",
      "amount": 2
    },
    "type": "QUEUED"
  }
}

2.6. Códigos de Status

Código	Status	Descrição
`200`	OK	Saque realizado com sucesso.
`400`	Bad Request	Dados inválidos ou ausência de permissões para realizar o saque.
`500`	Internal Server Error	Falha na comunicação com o banco.

3. Callback

A resposta de callback enviada pelo gateway de pagamento fornece informações sobre o status da transação realizada. Este callback será enviado para o endpoint de URL definido no parâmetro postback_url durante a criação de uma transação.

3.1 Estrutura Básica de um Callback

O callback é uma requisição HTTP enviada pelo Havenpay para a URL definida no campo postback_url no formato JSON. A estrutura da resposta de callback contém informações detalhadas sobre a transação, como o status, identificador da transação e detalhes adicionais.

3.2 Exemplo de Callback para Transação de Pagamento (Cash-In)

URL do Callback (definida no postback_url): https://seusite.com.br/orion-callback

Método: POST

Exemplo de Corpo da Requisição:

3.3 Exemplo de Resposta

{
  "id": "78548",
  "status": 1,
  "payment_method": "pix",
  "amount": "2.00",
  "external_ref": ""
}

3.4 Parâmetros de Resposta

Parâmetro	Tipo	Descrição
`id`	string	ID único da transação gerado pelo gateway de pagamento.
`status`	integer	Status da transação, onde `1` indica sucesso. Outros valores podem indicar falhas ou pendências.
`payment_method`	string	Método de pagamento utilizado para a transação (neste caso, `pix`).
`amount`	string	Valor da transação em moeda local, apresentado no formato decimal.
`external_ref`	string	Campo para referência externa, se aplicável. Este campo pode estar vazio se não houver referência externa fornecida.

3.5 Exemplo de Uso

Após receber a resposta de callback, o sistema deve processar os dados conforme o status da transação, utilizando o campo id para identificar a transação e status para verificar o sucesso ou erro da operação.

Este retorno deve ser usado para atualizar o status da transação no banco de dados, enviar notificações ao usuário ou realizar ações adicionais necessárias para o fluxo da aplicação.