# Cria pagamento

`POST` `/payments`

Cadastra um novo pagamento para análise

## Corpo da requisição

- **payment** (`object`, obrigatório)
  - **id** (`string | null`) — Identifique o pagamento através de um código único que não se repete na mesma conta. Se não fornecido, um identificador aleatório será gerado. Consulte a [documentação sobre os identificadores](https://docs.glassdata.io/pt/transactional/payment_modeling/identifiers/).
  - **type** (`string enum`, obrigatório) — Tipo do pagamento
    - Allowed: `purchase`, `verify`
  - **status** (`string enum`) — Status do pagamento. Consulte a [documentação para mais detalhes sobre os status possíveis](https://docs.glassdata.io/pt/transactional/payment_modeling/status/).
    - Allowed: `initiated`, `succeeded`, `declined`, `failed`, `blocked`
  - **currency** (`string`, obrigatório) — Moeda do pagamento de acordo com o padrão ISO 4217.
  - **amount** (`float`) — Valor com duas casas decimais. Utilize "." como separador decimal.
  - **timestamp** (`date-time | null`) — Data e hora em que o pagamento foi iniciado no formato [ISO 8601](https://pt.wikipedia.org/wiki/ISO_8601). Se não for enviado, o horário atual será usado. O prazo máximo para envio retroativo (backfill) é 24 horas. Horários no futuro não são permitidos.
  - **method** (`object`, obrigatório) — Método de pagamento. Preferencialmente, envie todas as informações disponíveis nesta requisição. Caso algum dado não esteja disponível nesta etapa do seu fluxo, é possível enviá-lo posteriormente através do mesmo parâmetro na operação de atualização.
    - **type** (`string`, obrigatório) — Tipo do método de pagamento.
    - **card** (`object`)
      - **network** (`string enum`, obrigatório) — Bandeira
        - Allowed: `visa`, `mastercard`, `american_express`, `diners_club`, `elo`, `hipercard`, `jcb`, `discover`, `other`
      - **presence** (`string enum`, obrigatório) — Indica se a transação foi realizada com cartão presente (CP) ou cartão não presente (CNP). Consulte a [documentação sobre presença de cartões](https://docs.glassdata.io/pt/api/methods/post_payments/) para mais informações.
        - Allowed: `card_present`, `card_not_present`
      - **bin** (`string | null`) — Primeiros 8 números do PAN que identificam o emissor do cartão (conhecido também como IIN)
      - **last_four** (`string | null`) — Últimos 4 números do PAN
  - **backend** (`object`) — Informações sobre o servidor externo que está enviando a requisição para sua API backend. Certifique-se que os dados enviados são do servidor remoto fora do seu perímetro de segurança, e não de servidores intermediários dentro da sua infraestrutura.
    - **ip_address** (`string | null`) — Endereço IPv4 ou IPv6 do servidor externo. Se este dado não estiver disponível, deixe o campo em branco. [Endereços privados](https://pt.wikipedia.org/wiki/Rede_privada) serão ignorados na análise.
    - **headers** (`object | null`) — Cabeçalhos HTTP enviados pelo servidor externo. Se possível, envie todos. Caso contrário, envie no mínimo `User-Agent`, `Accept`, `Accept-Encoding`, `Accept-Language` e `Host`. Cabeçalhos confidenciais usados para autenticação e sessão serão removidos automaticamente.
  - **device** (`object`) — Informações sobre o dispositivo do usuário, caso o pagamento tenha sido realizado em ambiente online (web ou aplicativo). Não envie este bloco para tentativas iniciadas sem a interação direta do usuário (renovação da recorrência, por exemplo).
    - **ip_address** (`string | null`) — Endereço IPv4 ou IPv6 do dispositivo do usuário. Se este dado não estiver disponível, deixe o campo em branco. [Endereços privados](https://pt.wikipedia.org/wiki/Rede_privada) serão recusados.
    - **headers** (`object | null`) — Cabeçalhos HTTP enviados pelo dispositivo do usuário na requisição. Se possível, envie todos. Caso contrário, envie no mínimo `User-Agent`, `Accept`, `Accept-Encoding`, `Accept-Language` e `Host`. Cabeçalhos confidenciais usados para autenticação e sessão serão removidos automaticamente.
    - **fingerprint** (`object`) — Impressão digital do dispositivo do usuário.
      - **id** (`string`, obrigatório) — Código identificador único da impressão digital do dispositivo.
      - **provider** (`string enum`, obrigatório) — Fornecedor do serviço de coleta da impressão digital.
        - Allowed: `fingerprintjs`, `basic`
  - **user** (`object`) — Informações sobre o usuário que está efetuando o pagamento.
    - **id** (`string | null`) — Código identificador do usuário.
    - **email** (`string | null`) — Email do usuário. Se desejar a análise sem dados pessoais, informe apenas o domínio (ex. `gmail.com`).
  - **order** (`object`) — Informações sobre a compra.
    - **id** (`string | null`) — Código identificador opcional do pedido (ou compra, mensalidade, carrinho, etc). Retentativas de pagamento na mesma compra devem usar a mesma identificação para rastrear a quantidade de tentativas. Consulte a [documentação para mais detalhes sobre o código do pedido](https://docs.glassdata.io/pt/transactional/payment_modeling/identifiers/).
  - **merchant** (`object`, obrigatório) — Informações sobre o estabelecimento. Utilize este campo para informar a unidade de negócio, franquia ou empresa que está realizando a operação.
    - **id** (`string`, obrigatório) — Código identificador do estabelecimento que está realizando a operação.
    - **country** (`string | null`) — País do estabelecimento de acordo com o formato [ISO 3166-1 alfa-2](https://www.iso.org/obp/ui/#search/code/) (2 caracteres).
    - **category_code** (`string | null`) — Código de categoria da empresa (MCC) de acordo com o padrão ISO 18245.
  - **transactions** (`array`) — Lista com as tentativas de transação para este pagamento. Obrigatório se o `status` do pagamento for `succeeded` ou `declined`. Recomendável para `failed` e `blocked` se houverem tentativas de transação.
    - **id** (`string`) — Código identificador único da transação. Consulte a [documentação para mais detalhes sobre o código da transação](https://docs.glassdata.io/pt/transactional/payment_modeling/identifiers/).
    - **status** (`string enum`, obrigatório) — Status de retorno da tentativa de transação. Consulte a [documentação para mais detalhes sobre os status possíveis](https://docs.glassdata.io/pt/transactional/payment_modeling/status/).
      - Allowed: `succeeded`, `declined`, `failed`, `canceled`
    - **duration** (`integer`) — Tempo de execução da transação em milissegundos (1 segundo = 1000 milissegundos).
    - **timestamp** (`date-time | null`) — Data e hora em que a transação foi iniciada no formato [ISO 8601](https://pt.wikipedia.org/wiki/ISO_8601). Se não for enviado, o horário atual será usado. O prazo máximo para envio retroativo (backfill) é 24 horas. Horários no futuro não são permitidos.
    - **connector** (`object`, obrigatório) — Informações sobre o conector de pagamento utilizado na transação. O conector pode ser uma adquirente, um subadquirente ou um gateway.
      - **id** (`string`, obrigatório) — Código da integração com o conector. Informe um código que represente um contrato de filiação ou uma conexão de integração específica. Recomendamos prefixar o código com o tipo do conector para facilitar consultas em relatórios.
      - **type** (`string`) — Tipo do conector (ex.: adquirente, subadquirente ou gateway). Campo opcional e de texto livre; recomendamos um valor padronizado para facilitar consultas em relatórios.
      - **response_code** (`string | null`) — Código de resposta alfanumérico da tentativa. Para cartão de crédito no Brasil, utilizar preferencialmente o padrão determinado pela [normativa 21 da ABECS](https://api.abecs.org.br/wp-content/uploads/2019/09/Normativo-021.pdf). Obrigatório se `transaction.status` for `succeeded` ou `declined`. Recomendável para `failed` e `canceled` quando presente.
  - **metadata** (`object | null`) — Metadados adicionais. Para informações sobre requisitos e limites, consulte a [documentação sobre metadados](https://docs.glassdata.io/pt/api/metadata/).
  - **analyze** (`object`) — Habilita a análise do pagamento.
    - **rule** (`object | null`) — Informe, opcionalmente, a regra a ser aplicada na recomendação de risco.
      - **name** (`string | null`) — Nome da regra, conforme cadastrado previamente. Se a regra informada não existir ou se não possuir versão ativa publicada, a requisição não irá falhar e a recomendação de risco será fornecida de acordo com a configuração padrão da conta.
    - **bot_behaviour** (`boolean`) — Detecta comportamento automatizado (robôs, scripts, etc). Consulte a [documentação sobre a recomendação e o score](https://docs.glassdata.io/pt/transactional/analysis/).

```json
{
  "payment": {
    "id": "string",
    "type": "purchase",
    "status": "initiated",
    "currency": "BRL",
    "amount": 10.23,
    "timestamp": "2024-01-01T00:00:00Z",
    "method": {
      "type": "string",
      "card": {
        "network": "visa",
        "presence": "card_present",
        "bin": "40000000",
        "last_four": "1234"
      }
    },
    "backend": {
      "ip_address": "200.200.200.200",
      "headers": {
        "User-Agent": "Java-Http-Client/11.0",
        "Accept": "application/json",
        "EveryOtherHeader": "value"
      }
    },
    "device": {
      "ip_address": "200.200.200.200",
      "headers": {
        "User-Agent": "Chrome",
        "Accept": "text/html,application/xhtml+xml",
        "EveryOtherHeader": "value"
      },
      "fingerprint": {
        "id": "string",
        "provider": "fingerprintjs"
      }
    },
    "user": {
      "id": "string",
      "email": "teste@gmail.com"
    },
    "order": {
      "id": "string"
    },
    "merchant": {
      "id": "string",
      "country": "BR",
      "category_code": "7997"
    },
    "transactions": [
      {
        "id": "string",
        "status": "succeeded",
        "duration": 0,
        "timestamp": "2024-01-01T00:00:00Z",
        "connector": {
          "id": "cielo-39123747819782",
          "type": "cielo",
          "response_code": "00"
        }
      }
    ],
    "metadata": {
      "plano": "premium_1",
      "categoria_do_cliente": "vip"
    },
    "analyze": {
      "rule": {
        "name": "minha_regra"
      },
      "bot_behaviour": false
    }
  }
}
```

## Respostas

### 201 — Pagamento criado com sucesso

- **payment** (`object`)
  - **id** (`string`) — Código identificador do pagamento criado.
  - **status** (`string`) — Status do pagamento.
  - **analyses** (`object`) — Resultado das análises solicitadas.
    - **bot_behaviour** (`object`) — Resultado da análise de risco. Consulte a [documentação sobre a recomendação e o score](https://docs.glassdata.io/pt/transactional/analysis/).
      - **action** (`string enum`) — Ação recomendada de acordo com o score de risco e a configuração no painel de adminstração.
        - Allowed: `allow`, `challenge`, `deny`
      - **score** (`float`) — Score (pontuação de risco) no formato decimal entre `0.00` e `1.00` com duas casas decimais. Quanto mais próximo de 1, maior a probabilidade do pagamento ter sido realizado por um bot. Este é apenas um campo informativo. Recomendamos utilizar a recomendação do campo `action` para implementar a tomada de decisão. Para simular um score arbitrário na conta de testes, verifique a [documentação](https://docs.glassdata.io/pt/transactional/analysis/test-environment/#simulando-um-score).
    - **rule** (`object | null`) — Regra aplicada ao pagamento, ou `null` quando nenhuma regra foi aplicada.
      - **name** (`string`) — Nome da regra aplicada.
      - **version** (`integer`) — Versão da regra aplicada.
      - **condition** (`object | null`) — Condição atendida, ou `null` se nenhuma condição foi atendida.
        - **id** (`string`) — Identificador da condição atendida.
        - **name** (`string | null`) — Nome da condição atendida, ou `null` se a condição não possui nome.

```json
{
  "payment": {
    "id": "string",
    "status": "string",
    "analyses": {
      "bot_behaviour": {
        "action": "allow",
        "score": 0.25
      },
      "rule": {
        "name": "minha_regra",
        "version": 3,
        "condition": {
          "id": "string",
          "name": "string"
        }
      }
    }
  }
}
```

### 401 — Credenciais de acesso inválidas

- **errors** (`array`)
  - **field** (`string`) — Campo da requisição onde ocorreu o erro
  - **type** (`string`) — Código do tipo do erro
  - **message** (`string`) — Mensagem do erro

```json
{
  "errors": [
    {
      "field": "string",
      "type": "string",
      "message": "string"
    }
  ]
}
```

### 422 — Parâmetros inválidos

- **errors** (`array`)
  - **field** (`string`) — Campo da requisição onde ocorreu o erro
  - **type** (`string`) — Código do tipo do erro
  - **message** (`string`) — Mensagem do erro

```json
{
  "errors": [
    {
      "field": "string",
      "type": "string",
      "message": "string"
    }
  ]
}
```