# Create payment

`POST` `/payments`

Creates a new payment for analysis

## Request body

- **payment** (`object`, required)
  - **id** (`string | null`) — Identify the payment with a unique code that does not repeat within the same account. If not provided, a random identifier will be generated. See the [documentation on the identifiers](https://docs.glassdata.io/en/transactional/payment_modeling/identifiers/).
  - **type** (`string enum`, required) — Payment type
    - Allowed: `purchase`, `verify`
  - **status** (`string enum`) — Payment status. See the [documentation for more details on possible statuses](https://docs.glassdata.io/en/transactional/payment_modeling/status/).
    - Allowed: `initiated`, `succeeded`, `declined`, `failed`, `blocked`
  - **currency** (`string`, required) — Payment currency according to the ISO 4217 standard.
  - **amount** (`float`) — Value with two decimal places. Use "." as the decimal separator.
  - **timestamp** (`date-time | null`) — Date and time when the payment was initiated in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. If not sent, the current time will be used. The maximum period for retroactive submission (backfill) is 24 hours. Future timestamps are not allowed.
  - **method** (`object`, required) — Payment method. Preferably, send all available information in this request. If some data is not available at this stage of your flow, it can be sent later through the same parameter in the update operation.
    - **type** (`string`, required) — Payment method type.
    - **card** (`object`)
      - **network** (`string enum`, required) — Card network
        - Allowed: `visa`, `mastercard`, `american_express`, `diners_club`, `elo`, `hipercard`, `jcb`, `discover`, `other`
      - **presence** (`string enum`, required) — Indicates whether the transaction was made with card present (CP) or card not present (CNP). See the [card presence documentation](https://docs.glassdata.io/en/api/methods/post_payments/) for more information.
        - Allowed: `card_present`, `card_not_present`
      - **bin** (`string | null`) — First 8 digits of the PAN that identify the card issuer (also known as IIN)
      - **last_four** (`string | null`) — Last 4 digits of the PAN
  - **backend** (`object`) — Information about the external server sending the request to your backend API. Make sure the data sent is from the remote server outside your security perimeter, not from intermediate servers within your infrastructure.
    - **ip_address** (`string | null`) — IPv4 or IPv6 address of the external server. If this data is not available, leave the field blank. [Private addresses](https://en.wikipedia.org/wiki/Private_network) will be ignored in the analysis.
    - **headers** (`object | null`) — HTTP headers sent by the external server. If possible, send all of them. Otherwise, send at least `User-Agent`, `Accept`, `Accept-Encoding`, `Accept-Language`, and `Host`. Confidential headers used for authentication and session will be automatically removed.
  - **device** (`object`) — Information about the user's device, if the payment was made in an online environment (web or app). Do not send this block for attempts initiated without direct user interaction (recurring renewal, for example).
    - **ip_address** (`string | null`) — IPv4 or IPv6 address of the user's device. If this data is not available, leave the field blank. [Private addresses](https://en.wikipedia.org/wiki/Private_network) will be rejected.
    - **headers** (`object | null`) — HTTP headers sent by the user's device in the request. If possible, send all of them. Otherwise, send at least `User-Agent`, `Accept`, `Accept-Encoding`, `Accept-Language`, and `Host`. Confidential headers used for authentication and session will be automatically removed.
    - **fingerprint** (`object`) — User's device fingerprint.
      - **id** (`string`, required) — Unique identifier code of the device fingerprint.
      - **provider** (`string enum`, required) — Fingerprint collection service provider.
        - Allowed: `fingerprintjs`, `basic`
  - **user** (`object`) — Information about the user making the payment.
    - **id** (`string | null`) — User identifier code.
    - **email** (`string | null`) — User email. If you want analysis without personal data, provide only the domain (e.g. `gmail.com`).
  - **order** (`object`) — Order information.
    - **id** (`string | null`) — Optional order identifier code (or purchase, subscription, cart, etc). Payment retries on the same order should use the same identifier to track the number of attempts. See the [documentation for more details on the order code](https://docs.glassdata.io/en/transactional/payment_modeling/identifiers/).
  - **merchant** (`object`, required) — Merchant information. Use this field to specify the business unit, franchise, or company performing the operation.
    - **id** (`string`, required) — Identifier code of the merchant performing the operation.
    - **country** (`string | null`) — Merchant country in [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#search/code/) format (2 characters).
    - **category_code** (`string | null`) — Merchant category code (MCC) according to the ISO 18245 standard.
  - **transactions** (`array`) — List of transaction attempts for this payment. Required if payment `status` is `succeeded` or `declined`. Recommended for `failed` and `blocked` if there are transaction attempts.
    - **id** (`string`) — Unique transaction identifier code. See the [documentation for more details on the transaction code](https://docs.glassdata.io/en/transactional/payment_modeling/identifiers/).
    - **status** (`string enum`, required) — Transaction attempt return status. See the [documentation for more details on possible statuses](https://docs.glassdata.io/en/transactional/payment_modeling/status/).
      - Allowed: `succeeded`, `declined`, `failed`, `canceled`
    - **duration** (`integer`) — Transaction execution time in milliseconds (1 second = 1000 milliseconds).
    - **timestamp** (`date-time | null`) — Date and time when the transaction was initiated in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. If not sent, the current time will be used. The maximum period for retroactive submission (backfill) is 24 hours. Future timestamps are not allowed.
    - **connector** (`object`, required) — Information about the payment connector used in the transaction. The connector can be an acquirer, a sub-acquirer, or a gateway.
      - **id** (`string`, required) — Integration code with the connector. Provide a code that represents an affiliation contract or a specific integration connection. We recommend prefixing the code with the connector type to facilitate report queries.
      - **type** (`string`) — Connector type (e.g., acquirer, sub-acquirer, or gateway). Optional free-text field; we recommend a standardized value to facilitate report queries.
      - **response_code** (`string | null`) — Alphanumeric response code of the attempt. For credit cards in Brazil, preferably use the standard determined by [ABECS normative 21](https://api.abecs.org.br/wp-content/uploads/2019/09/Normativo-021.pdf). Required if `transaction.status` is `succeeded` or `declined`. Recommended for `failed` and `canceled` when present.
  - **metadata** (`object | null`) — Additional metadata. For information about requirements and limits, see the [metadata documentation](https://docs.glassdata.io/en/api/metadata/).
  - **analyze** (`object`) — Enables payment analysis.
    - **rule** (`object | null`) — Optionally specify the rule to be applied in the risk recommendation.
      - **name** (`string | null`) — Rule name, as previously registered. If the specified rule does not exist or does not have an active published version, the request will not fail and the risk recommendation will be provided according to the account's default configuration.
    - **bot_behaviour** (`boolean`) — Detects automated behavior (bots, scripts, etc.). See the [documentation on the recommendation and the score](https://docs.glassdata.io/en/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
    }
  }
}
```

## Responses

### 201 — Payment created successfully

- **payment** (`object`)
  - **id** (`string`) — Identifier code of the created payment.
  - **status** (`string`) — Payment status.
  - **analyses** (`object`) — Results of the requested analyses.
    - **bot_behaviour** (`object`) — Result of the risk analysis. See the [documentation on the recommendation and the score](https://docs.glassdata.io/en/transactional/analysis/).
      - **action** (`string enum`) — Recommended action based on the risk score and the configuration in the admin panel.
        - Allowed: `allow`, `challenge`, `deny`
      - **score** (`float`) — Risk score in decimal format between `0.00` and `1.00` with two decimal places. The closer to 1, the higher the probability the payment was made by a bot. This is an informational field only. We recommend using the `action` field recommendation to implement decision-making. To simulate an arbitrary score in the test account, check the [documentation](https://docs.glassdata.io/en/transactional/analysis/test-environment/#simulating-a-score).
    - **rule** (`object | null`) — Rule applied to the payment, or `null` when no rule was applied.
      - **name** (`string`) — Name of the applied rule.
      - **version** (`integer`) — Version of the applied rule.
      - **condition** (`object | null`) — Condition met, or `null` if no condition was met.
        - **id** (`string`) — Identifier of the met condition.
        - **name** (`string | null`) — Name of the met condition, or `null` if the condition has no name.

```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 — Invalid access credentials

- **errors** (`array`)
  - **field** (`string`) — Request field where the error occurred
  - **type** (`string`) — Error type code
  - **message** (`string`) — Error message

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

### 422 — Invalid parameters

- **errors** (`array`)
  - **field** (`string`) — Request field where the error occurred
  - **type** (`string`) — Error type code
  - **message** (`string`) — Error message

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