# Payment

## Payment object

| Name                  | Type    | Description                                                                                            |
| --------------------- | ------- | ------------------------------------------------------------------------------------------------------ |
| object                | string  | The type of object, which is "payment" in this case.                                                   |
| id                    | string  | The unique identifier of the payment transaction.                                                      |
| livemode              | boolean | Indicates whether the transaction is in live mode (false) or test mode (true).                         |
| provider              | string  | The payment provider used for the transaction (e.g., "invoice").                                       |
| method                | string  | The payment method used for the transaction (e.g., "invoice").                                         |
| status                | string  | The status of the payment (e.g., "ok" for successful).                                                 |
| policy\_id            | string  | The ID of the policy associated with this payment.                                                     |
| charge\_id            | string  | The ID of the charge, if applicable.                                                                   |
| fee                   | number  | The fee amount for the transaction (usually 0 for no fee).                                             |
| reference             | string  | A reference ID for the payment, if applicable.                                                         |
| token                 | string  | A token representing the payment transaction.                                                          |
| reason                | string  | The reason for the payment, if applicable.                                                             |
| processed\_at         | string  | The timestamp when the payment was processed, if applicable.                                           |
| error\_code           | string  | The error code, if there was an error during the payment process.                                      |
| metadata              | string  | An array containing additional metadata about the payment.                                             |
| transaction\_metadata | string  | An array containing additional metadata related to the transaction.                                    |
| customer\_id          | string  | The ID of the customer associated with this payment.                                                   |
| refunds               | string  | An array of refund objects associated with the payment (empty in this case).                           |
| \_links               | string  | An object containing various links related to the payment (e.g., self-link for accessing the payment). |

{% hint style="info" %}
Depending on the requester permissions, some fields of payment object are restricted.
{% endhint %}

<details>

<summary>Payment object example</summary>

```json
{
    "object": "payment",
    "id": "t84223322f013e2287210b6295010fc6d",
    "livemode": false,
    "provider": "invoice",
    "method": "invoice",
    "status": "ok",
    "policy_id": "tpol_b1fc636ad446d6cb7144cfb31cae",
    "charge_id": null,
    "fee": 0,
    "reference": null,
    "token": "<PAYMENT-TOKEN>",
    "reason": null,
    "processed_at": null,
    "error_code": null,
    "metadata": [],
    "transaction_metadata": [],
    "customer_id": "eyJpZCI6ImRyMCIsIml2IjoiSmlsRXhkRllQUnljMjdQM0ZJSDk1QT09IiwibWFjIjoiNDM1N2VlNWQ1NzY5MGFhNWNkYTJlYzdlYjZiOTI2MmM2ZDZhZmY2NzdmZjU1NGRmMWM2MjcxZGE3NmQ0MGU4OSIsInZhbHVlIjoiU0ZKdHVXSzhqYURPR3ZkTDI5SlZ5V0d3QmQ1Z2RhemVqWVd1V1RBSGFCT3VSbTk5QlBMYVg0bDNTQmhPejlodnVBV1Jzc3BlcmNabzAzMW5yNEM2ZytxaTRxNytrRzZ6SmJSUkNPWDZrWURqaWF1Y2gxUzh0SlQzd0ZRNmpxeHNUKzh4TEJ1YWR4Z1FoOXM1cnIrNHZ3PT0ifQ__",
    "refunds": [],
    "_links": {
        "_self": {
            "href": "https://api.eu1.kaskocloud.com/payments/t84223322f013e2287210b6295010fc6d"
        }
    }
}
```

</details>

## Create a payment

## Convert an offer to paid policy.

<mark style="color:green;">`POST`</mark> `https://api.eu1.kaskocloud.com/payments`

#### Query Parameters

| Name | Type   | Description |
| ---- | ------ | ----------- |
| key  | String | Public key  |

#### Headers

| Name          | Type   | Description           |
| ------------- | ------ | --------------------- |
| Authorization | String | Bearer: \<Secret-key> |

#### Request Body

| Name       | Type   | Description      |
| ---------- | ------ | ---------------- |
| token      | String | Payment token    |
| provider   | String | Payment provider |
| method     | String | Payment method   |
| policy\_id | String | Policy ID        |

{% tabs %}
{% tab title="200: OK Payment successful" %}

```json
{
  "object": "payment",
  "id": "t7cc6b1ee53d57056256a991b48e61c67",
  "livemode": false,
  "provider": "payment_provider",
  "method": "payment_method",
  "status": "status",
  "transaction_metadata": [],
  "_links": {
    "_self": {
      "href": "https://api.eu1.kaskocloud.com/payments/t7cc6b1ee53d57056256a991b48e61c67"
    }
  }
}
```

{% endtab %}

{% tab title="400: Bad Request Bad Request" %}
Response indicates that one or more of the fields provided in payload are invalid or the associated entities and configuration do not meet the criteria to make a successful payment. All of the responses follow the same structure with a brief description in message property explaining the error.

```json
{
    "status": "Bad Request",
    "message": "Brief description"
}
```

{% endtab %}

{% tab title="404: Not Found Not Found" %}
Indicates that provided payment provider cannot be identified in platform.
{% endtab %}

{% tab title="422: Unprocessable Entity Pending payment already exists" %}
Response indicates that there is already a pending payment in progress.

```json
{
    "status": "Unprocessable Entity",
    "message": "Policy - tpol_bddc5c1ecc1668d49ba51a44945b already has pending payment - t9193b464fa449e0b6cbdc654189619a3."
}
```

{% endtab %}

{% tab title="401: Unauthorized Unauthorized" %}

```json
{
    "status": "Unauthorized",
    "message": "Not authorized for policy purchase."
}
```

{% endtab %}
{% endtabs %}

<details>

<summary>Payment creation request example</summary>

```
curl --location 'https://api.eu1.kaskocloud.com/payments?key=pk_test_2jngq6d7GRmxQ58w0yVKW3PBrJXbEvoM' \
--header 'Content-Type: application/json' \
--data '{
    "token": "<PAYMENT-TOKEN>",
    "method": "invoice",
    "provider": "invoice",
    "policy_id": "tpol_b1fc636ad446d6cb7144cfb31cae"
}'
```

</details>

## View payment

## View payment

<mark style="color:blue;">`GET`</mark> `https://api.eu1.kaskocloud.com/payments/{paymentId}`

#### Path Parameters

| Name                                        | Type   | Description |
| ------------------------------------------- | ------ | ----------- |
| paymentId<mark style="color:red;">\*</mark> | String | Payment ID  |

#### Headers

| Name          | Type   | Description           |
| ------------- | ------ | --------------------- |
| Authorization | String | Bearer: \<Secret-key> |

{% tabs %}
{% tab title="200: OK OK" %}

```json
{
    "object": "payment",
    "id": "t84223322f013e2287210b6295010fc6d",
    "livemode": false,
    "provider": "invoice",
    "method": "invoice",
    "status": "ok",
    "policy_id": "tpol_b1fc636ad446d6cb7144cfb31cae",
    "charge_id": null,
    "fee": 0,
    "reference": null,
    "token": "<PAYMENT-TOKEN>",
    "reason": null,
    "processed_at": null,
    "error_code": null,
    "metadata": [],
    "transaction_metadata": [],
    "customer_id": "eyJpZCI6ImRyMCIsIml2IjoiSmlsRXhkRllQUnljMjdQM0ZJSDk1QT09IiwibWFjIjoiNDM1N2VlNWQ1NzY5MGFhNWNkYTJlYzdlYjZiOTI2MmM2ZDZhZmY2NzdmZjU1NGRmMWM2MjcxZGE3NmQ0MGU4OSIsInZhbHVlIjoiU0ZKdHVXSzhqYURPR3ZkTDI5SlZ5V0d3QmQ1Z2RhemVqWVd1V1RBSGFCT3VSbTk5QlBMYVg0bDNTQmhPejlodnVBV1Jzc3BlcmNabzAzMW5yNEM2ZytxaTRxNytrRzZ6SmJSUkNPWDZrWURqaWF1Y2gxUzh0SlQzd0ZRNmpxeHNUKzh4TEJ1YWR4Z1FoOXM1cnIrNHZ3PT0ifQ__",
    "refunds": [],
    "_links": {
        "_self": {
            "href": "https://api.eu1.kaskocloud.com/payments/t84223322f013e2287210b6295010fc6d"
        }
    }
}
```

{% endtab %}

{% tab title="404: Not Found Payment not found" %}

```json
{
    "status": "Not Found"
}
```

{% endtab %}
{% endtabs %}

<details>

<summary>View payment request example</summary>

```
curl --location 'https://api.eu1.kaskocloud.com/payments/t84223322f013e2287210b6295010fc6a' \
--header 'Accept: application/vnd.kasko.v2+json' \
--header 'Authorization: Bearer <SECRET-KEY>'
```

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.kasko.io/kasko-api-documentation/rest-api/resources/payment.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.