# 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>