### Coinify Webhook Payload Example (JSON)

Source: https://coinify.readme.io/docs/webhook-structure

An example of a typical webhook payload sent by Coinify. It demonstrates the common 'id', 'time', 'event', and 'context' properties, illustrating the structure of event-specific data within the 'context' object.

```json
{
  "id": "aeb7475b-39c4-41ae-8237-d74a7379c355",
  "time": "2020-04-01T12:47:02.147Z",
  "event": "payment-intent.completed",
  "context": {
    "id": "3589cb4a-0830-497d-a92d-c5178eb2ab9f",
    "customerId": "42",
    "amount": "7145.02",
    "currency": "EUR",
    "creditAmount": "7145.02",
    "creditCurrency": "EUR"
  }
}
```

--------------------------------

### API Error Response Example (JSON)

Source: https://coinify.readme.io/reference/create-payment-intent

This snippet shows an example of an error response from the Coinify API. It includes fields for errorCode, errorMessage, and requestId, which are crucial for debugging and identifying the cause of an issue.

```json
{
  "errorCode": "unavailable_legal_reasons",
  "errorMessage": "Unavailable For Legal Reasons",
  "requestId": "{requestId}"
}
```

--------------------------------

### Get Currency Estimations (OpenAPI)

Source: https://coinify.readme.io/reference/payment-intent-estimates

Defines the GET endpoint for retrieving currency estimations. It requires 'amount' and 'currency' as query parameters and can optionally filter by 'state'. The response includes a list of cryptocurrencies with their approximate FIAT values.

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "payment-intent",
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://api.payment.sandbox.coinify.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "sec0": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-KEY",
        "x-default": ""
      }
    }
  },
  "security": [
    {
      "sec0": []
    }
  ],
  "paths": {
    "/v1/payment-intents/estimates": {
      "get": {
        "summary": "Get Currency Estimations",
        "description": "This endpoint will return an approximate value of each supported cryptocurrency based on the FIAT amount provided.",
        "operationId": "payment-intent-estimates",
        "parameters": [
          {
            "name": "amount",
            "in": "query",
            "description": "The amount intended to be collected",
            "required": true,
            "schema": {
              "type": "number",
              "format": "float",
              "default": 99.95
            }
          },
          {
            "name": "currency",
            "in": "query",
            "description": "Three-letter ISO currency code of the fiat amount",
            "required": true,
            "schema": {
              "type": "string",
              "default": "EUR"
            }
          },
          {
            "name": "state",
            "in": "query",
            "description": "Comma-separated list of states to filter by, e.g. `available` or `available,unavailable_by_provider`.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n  \"estimates\": [\n    {\n      \"symbol\": \"BTC\",\n      \"name\": \"Bitcoin\",\n      \"state\": \"available\",\n      \"approximateAmount\": \"0.00408765\"\n    },\n    {\n      \"symbol\": \"AAVE\",\n      \"name\": \"Aave\",\n      \"state\": \"available\",\n      \"approximateAmount\": \"1.7613863863978189544\"\n    },\n    {\n      \"symbol\": \"ADA\",\n      \"name\": \"Cardano\",\n      \"state\": \"available\",\n      \"approximateAmount\": \"306.40424953113038672764\"\n    },\n    {\n      \"symbol\": \"BCH\",\n      \"name\": \"Bitcoin Cash\",\n      \"state\": \"available\",\n      \"approximateAmount\": \"0.98720591852607776289\"\n    },\n    {\n      \"symbol\": \"BNB\",\n      \"name\": \"BNB Mainnet\",\n      \"tagName\": \"Memo\",\n      \"state\": \"available\",\n      \"approximateAmount\": \"0.36497298629359084258\"\n    },\n    {\n      \"symbol\": \"BNBBSC\",\n      \"name\": \"BNB on Binance Smart Chain\",\n      \"state\": \"available\",\n      \"approximateAmount\": \"0.36497298629359084258\"\n    },\n    {\n      \"symbol\": \"BSV\",\n      \"name\": \"Bitcoin SV\",\n      \"state\": \"available\",\n      \"approximateAmount\": \"3.49148559183159093263\"\n    },\n    {\n      \"symbol\": \"DOGE\",\n      \"name\": \"Dogecoin\",\n      \"state\": \"available\",\n      \"approximateAmount\": \"1552.23285486443970620815\"\n    },\n    {\n      \"symbol\": \"DOT\",\n      \"name\": \"Polkadot\",\n      \"state\": \"available\",\n      \"approximateAmount\": \"21.29669199431020634987\"\n    },\n    {\n      \"symbol\": \"ETH\",\n      \"name\": \"Ethereum\",\n      \"state\": \"available\",\n      \"approximateAmount\": \"0.05953818368313970107\"\n    },\n    {\n      \"symbol\": \"LINK\",\n      \"name\": \"Chainlink\",\n      \"state\": \"available\",\n      \"approximateAmount\": \"17.37695969841081874287\"\n    },\n    {\n      \"symbol\": \"LTC\",\n      \"name\": \"Litecoin\",\n      \"state\": \"available\",\n      \"approximateAmount\": \"1.20355854926525613103\"\n    },\n    {\n      \"symbol\": \"MATIC\",\n      \"name\": \"Polygon ERC-20\",\n      \"state\": \"available\",\n      \"approximateAmount\": \"124.44060861782384558077\"\n    },\n    {\n      \"symbol\": \"NANO\",\n      \"name\": \"Nano\",\n      \"state\": \"available\",\n      \"approximateAmount\": \"153.90267159091713208197\"\n    },\n    {\n      \"symbol\": \"OMG\",\n      \"name\": \"OmiseGo\",\n      \"state\": \"available\",\n      \"approximateAmount\": \"147.2108301835743730697\"\n    },\n    {\n      \"symbol\": \"PAX\",\n      \"name\": \"Paxos Standard Token\",\n      \"state\": \"unavailable_by_provider\",\n      \"approximateAmount\": null\n    },\n    {\n      \"symbol\": \"QTUM\",\n      \"name\": \"Qtum\",\n      \"state\": \"available\",\n      \"approximateAmount\": \"43.16032495749150550738\"\n    },\n    {\n      \"symbol\": \"SHIB\",\n      \"name\": \"SHIBA INU\",\n      \"state\": \"available\",\n      \"approximateAmount\": \"13129380.44089327328675280735\"\n    },\n    {\n      \"symbol\": \"SOL\",\n      \"name\": \"SOL\"\n    }\n  ]\n}"
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```

--------------------------------

### Coinify API Error Response Examples

Source: https://coinify.readme.io/reference/withdrawal-estimates

This snippet demonstrates the structure of error responses from the Coinify API for different HTTP status codes. It includes examples for invalid requests, authentication failures, forbidden access, and validation errors. These examples are crucial for implementing robust error handling in client applications.

```json
{
  "errorCode": "invalid_request",
  "errorMessage": "withdrawal_too_high",
  "requestId": "de65db89-e2cc-4f37-a42b-4ac11f54684f"
}
```

```json
{
  "errorCode": "invalid_authentication",
  "errorMessage": "Missing Authentication header",
  "requestId": "de65db89-e2cc-4f37-a42b-4ac11f54684f"
}
```

```json
{
  "errorCode": "forbidden",
  "errorMessage": "Forbidden method call for Merchant d560b17e-bae5-4fbf-8822-518273498c7ay",
  "requestId": "de65db89-e2cc-4f37-a42b-4ac11f54684f"
}
```

```json
{
  "errorCode": "requested_not_fiat",
  "errorMessage": "USDC is not a fiat currency",
  "requestId": "de65db89-e2cc-4f37-a42b-4ac11f54684f"
}
```

--------------------------------

### Merchant Object Example (JSON)

Source: https://coinify.readme.io/reference/payment-intent-resource

An example of the merchant object, which contains the ID and name of the merchant in Coinify's system. This data is captured within the merchant JSON object when a PaymentIntent is created.

```json
{
    "id": "de15d585-ed82-4627-953e-41f74353959d",
    "name": "Demo Merchant"
}
```

--------------------------------

### Coinify API Invalid Authentication Error Example

Source: https://coinify.readme.io/reference/get-all-settlements-list

This JSON example shows an error response from the Coinify API indicating an authentication failure, typically due to an invalid or missing API key. The response provides an error code, a message explaining the issue, and a request ID for troubleshooting.

```json
{
    "errorCode": "invalid_authentication",
    "errorMessage": "Unknown API key",
    "requestId": "31db6a2f-3c1d-46bb-8bd3-e087d3e36241"
}
```

--------------------------------

### Self-hosted Payment Window - Create Customer, Wallet, and Quote

Source: https://coinify.readme.io/docs/preselect-quote-currency-for-payment-intents

For self-hosted payment windows, you need to create a customer, a wallet for that customer, and then a quote for the Payment Intent. Always create a new quote for optimal UX.

```APIDOC
## POST /customers

### Description
Creates a new customer entry. This is a prerequisite for creating a wallet and a quote in a self-hosted payment window scenario.

### Method
POST

### Endpoint
/customers

### Parameters
#### Request Body
- **email** (string) - Required - The customer's email address.
- **firstName** (string) - Optional - The customer's first name.
- **lastName** (string) - Optional - The customer's last name.

### Request Example
```json
{
  "email": "customer@example.com",
  "firstName": "John",
  "lastName": "Doe"
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the customer.

#### Response Example
```json
{
  "id": "cust_xyz789"
}
```

---

## POST /customers/{customerId}/wallets

### Description
Creates a new wallet for an existing customer. This is required before creating a quote for a Payment Intent.

### Method
POST

### Endpoint
/customers/{customerId}/wallets

### Parameters
#### Path Parameters
- **customerId** (string) - Required - The ID of the customer for whom to create the wallet.

#### Request Body
- **currency** (string) - Required - The currency for the wallet (e.g., 'BTC', 'ETH').

### Request Example
```json
{
  "currency": "BTC"
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the wallet.
- **address** (string) - The wallet address.

#### Response Example
```json
{
  "id": "wallet_abc123",
  "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"
}
```

---

## POST /payment-intents/{paymentIntentId}/quotes

### Description
Creates a quote for a specific Payment Intent using the provided `walletId`. It is crucial to create a new quote for each transaction, even if an existing one is available, as Payment Intents expire when their latest quote expires.

### Method
POST

### Endpoint
/payment-intents/{paymentIntentId}/quotes

### Parameters
#### Path Parameters
- **paymentIntentId** (string) - Required - The ID of the Payment Intent for which to create a quote.

#### Request Body
- **walletId** (string) - Required - The ID of the customer's wallet.

### Request Example
```json
{
  "walletId": "wallet_abc123"
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the quote.
- **paymentIntentId** (string) - The ID of the associated Payment Intent.
- **walletId** (string) - The ID of the wallet used for the quote.
- **currency** (string) - The cryptocurrency currency for the quote.
- **amount** (number) - The amount in the cryptocurrency currency.
- **rate** (number) - The exchange rate at the time of quote creation.
- **expiresAt** (string) - The timestamp when the quote expires.

#### Response Example
```json
{
  "id": "q_fghij",
  "paymentIntentId": "pi_12345",
  "walletId": "wallet_abc123",
  "currency": "BTC",
  "amount": 0.0002,
  "rate": 500000,
  "expiresAt": "2023-10-27T11:00:00Z"
}
```
```

--------------------------------

### Coinify API Success Response Example

Source: https://coinify.readme.io/reference/get-all-settlement-transactions

This snippet demonstrates a typical successful response from the Coinify API, detailing transaction information. It includes fields such as subaccount name, reference ID, amount, currency, order ID, customer details, and transaction time. This structure is common for successful payment-related operations.

```json
{
  "subaccountName": {
    "type": "string",
    "example": "Demo subaccount"
  },
  "referenceId": {
    "type": "string",
    "example": "3de4fe93-5afd-4692-bead-2431416dd0bb"
  },
  "referenceType": {
    "type": "string",
    "example": "payment_intent"
  },
  "amount": {
    "type": "string",
    "example": "45.42"
  },
  "currency": {
    "type": "string",
    "example": "USD"
  },
  "orderId": {
    "type": "string",
    "example": "123456"
  },
  "customerId": {
    "type": "string",
    "example": "6af46318-9e60-4390-8bf0-e042d7b96b21"
  },
  "customerEmail": {
    "type": "string",
    "example": "customer@coinify.com"
  },
  "transactionTime": {
    "type": "string",
    "example": "2023-09-10T11:27:11.892Z"
  }
}
```

--------------------------------

### Withdrawal Context Object Example (JSON)

Source: https://coinify.readme.io/reference/withdrawals-resource

This JSON object demonstrates the 'context' field for a withdrawal request. It allows for arbitrary key-value pairs to associate additional data, such as shop IDs or timestamps, with the withdrawal. Personal data should not be included.

```json
{
  "shopId":"12345",
  "dateTime":"1678291098"
}
```

--------------------------------

### Coinify API Bad Request Error Example

Source: https://coinify.readme.io/reference/get-all-settlements-list

This JSON snippet illustrates a typical error response from the Coinify API when a request is malformed or contains invalid data, such as an incorrectly formatted date. It includes an error code, a descriptive error message, and a unique request ID for tracking purposes.

```json
{
    "errorCode": "bad_request",
    "errorMessage": "\"since\" must be a valid date",
    "requestId": "5254606d-43d7-4bda-9fde-ccbcb938bb13"
}
```

--------------------------------

### Create Refund

Source: https://coinify.readme.io/docs/refund-your-customers

Initiates a refund for a previously completed PaymentIntent. The merchant's account balance must be sufficient to cover the refund amount and network fees. A unique PaymentIntent ID is required.

```APIDOC
## POST /v1/refunds

### Description
Creates a refund for a previously completed PaymentIntent. The merchant account balance must be sufficient to cover the refund amount plus the network fee (5 EUR).

### Method
POST

### Endpoint
/v1/refunds

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **paymentIntentId** (string) - Required - The unique ID of the PaymentIntent to be refunded.
- **amount** (number) - Required - The amount to be refunded. Must be equal to the original PaymentIntent amount and greater than the minimum refund amount.

### Request Example
```json
{
  "paymentIntentId": "pi_123abc",
  "amount": 100.50
}
```

### Response
#### Success Response (201 Created)
- **refundId** (string) - The unique ID of the created refund.
- **status** (string) - The status of the refund (e.g., 'pending').

#### Response Example
```json
{
  "refundId": "ref_xyz789",
  "status": "pending"
}
```

#### Error Response (400 Bad Request)
- **error** (object) - Contains error details.
  - **code** (string) - Error code.
  - **message** (string) - Error message.

#### Error Response Example
```json
{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Merchant account balance is too low to cover the refund amount and network fee."
  }
}
```
```

--------------------------------

### Coinify API Settlement Request Example

Source: https://coinify.readme.io/reference/get-all-settlements-list

This snippet demonstrates the structure of a JSON request body for submitting settlement data to the Coinify API. It includes details for multiple settlements, such as ID, amount, currency, account label, and creation time. This format is crucial for correctly processing financial transactions.

```json
{
  "settlements": [
    {
      "id": "ba31954f-5591-4d93-9d25-f4f37fca5321",
      "amount": "999",
      "currency": "EUR",
      "account": {
        "label": "ING"
      },
      "createTime": "2023-06-21T10:04:36.286+02:00"
    },
    {
      "id": "375760cf-3cc9-4b1a-bac8-1ac3677fdb04",
      "amount": "1238",
      "currency": "EUR",
      "account": {
        "label": "ING"
      },
      "createTime": "2023-09-21T10:44:47.608+02:00"
    }
  ]
}
```

--------------------------------

### Create Customer

Source: https://coinify.readme.io/reference/create-customer-entry

This endpoint allows you to create a customer entry in the Coinify system. It is crucial for complying with Travel Rule regulatory requirements. Contact support@coinify.com to enable this endpoint.

```APIDOC
## POST /customers

### Description
This endpoint allows you to create a customer entry in Coinify system. Due to Travel Rule regulatory requirements, Coinify must collect this data for every customer. In case the customer does not give consent to share this data with Coinify and/or you do not provide it via this API endpoint, Coinify will collect this data directly from the customer as a part of the usual payment flow. See more info regarding Travel Rule and the data collection here: https://coinify.readme.io/update/docs/travel-rule-customer-data-collection#/

> ❗️ Make sure to get customer's consent to share the required data with Coinify before doing so.

<Callout icon="👍">
  In order to call this endpoint please contact `support@coinify.com` so that we can start the process of enabling this endpoint for you.
</Callout>

### Method
POST

### Endpoint
/customers

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
(Note: Specific request body fields are not detailed in the provided text, but would typically include customer identification and consent information.)

### Request Example
```json
{
  "example": "Request body structure will be provided upon endpoint enablement."
}
```

### Response
#### Success Response (200 or 201)
- **customerId** (string) - The unique identifier for the created customer.
- **status** (string) - The status of the customer creation.

#### Response Example
```json
{
  "customerId": "cus_123abc",
  "status": "created"
}
```
```

--------------------------------

### GET /v1/settlements/{id}/transactions

Source: https://coinify.readme.io/reference/get-all-settlement-transactions

Retrieves all transactions associated with a specific settlement. This includes payments, refunds, and fees.

```APIDOC
## GET /v1/settlements/{id}/transactions

### Description
This endpoint allows you to receive all the transaction that occurred within a single settlement.

### Method
GET

### Endpoint
https://api.payment.sandbox.coinify.com/v1/settlements/{id}/transactions

### Parameters
#### Path Parameters
- **id** (string) - Required - A unique identifier for the settlement

### Request Example
```json
{
  "example": "No request body needed for this GET request."
}
```

### Response
#### Success Response (200)
- **transactions** (array) - A list of transaction objects.
  - **merchantId** (string) - The ID of the merchant.
  - **merchantName** (string) - The name of the merchant.
  - **subaccountId** (string) - The ID of the subaccount, if applicable.
  - **subaccountName** (string) - The name of the subaccount, if applicable.
  - **referenceId** (string) - The ID of the reference transaction.
  - **referenceType** (string) - The type of the reference transaction (e.g., "payment_intent", "payment_intent_refund").
  - **amount** (string) - The transaction amount.
  - **currency** (string) - The currency of the transaction.
  - **orderId** (string) - The order ID associated with the transaction.
  - **customerId** (string) - The ID of the customer.
  - **customerEmail** (string) - The email of the customer.
  - **transactionTime** (string) - The timestamp of the transaction in ISO 8601 format.

#### Response Example
```json
{
  "transactions": [
    {
      "merchantId": "d560b17e-bae5-4fbf-8822-518273498c7a",
      "merchantName": "Demo payment merchant",
      "subaccountId": "9dfbb680-0662-47da-8d14-374c515c1c76",
      "subaccountName": "Demo subaccount",
      "referenceId": "3de4fe93-5afd-4692-bead-2431416dd0bb",
      "referenceType": "payment_intent",
      "amount": "45.42",
      "currency": "USD",
      "orderId": "123456",
      "customerId": "6af46318-9e60-4390-8bf0-e042d7b96b21",
      "customerEmail": "customer@coinify.com",
      "transactionTime": "2023-09-10T11:27:11.892Z"
    },
    {
      "merchantId": "d560b17e-bae5-4fbf-8822-518273498c7a",
      "merchantName": "Demo payment merchant",
      "subaccountId": null,
      "subaccountName": null,
      "referenceId": "cdd51ceb-5e21-4f76-ae93-44a83dc156d1",
      "referenceType": "payment_intent_refund",
      "amount": "-23.16",
      "currency": "USD",
      "orderId": "123456",
      "customerId": "2281",
      "customerEmail": "customer@coinify.com",
      "transactionTime": "2023-09-11T11:27:11.892Z"
    }
  ]
}
```
```

--------------------------------

### Render Coinify Payment Window (HTML/JavaScript)

Source: https://coinify.readme.io/page/payment-service-sdk

This snippet demonstrates how to load the Coinify SDK and render the payment window within an HTML page. It requires a `paymentIntentId` obtained from the server-side API and allows for theme customization. The SDK is loaded from a specified URL.

```html
<!DOCTYPE html>
<html lang="en">
<head>
  <title>Coinify SDK example</title>
  <script type="text/javascript" src="https://checkout.sandbox.coinify.com/sdk/v1/index.js"></script>
</head>
<body>
    <div id="container-id"></div>

	<script type="text/javascript">
    
      const payment = Coinify.Checkout({
        paymentIntentId: "{paymentIntentId}"
      });

      payment.render({
        containerId: "container-id",
        parameters: {
          themeMode: 'dark', // or light
          theme: {},
        },
      });

	</script>
</body>
</html>
```

--------------------------------

### Get All Settlement Transactions

Source: https://coinify.readme.io/reference/get-all-settlement-transactions

Retrieves all transactions that occurred within a single settlement. Note: A separate API key is required for Settlements API endpoints.

```APIDOC
## GET /settlements/transactions

### Description
Retrieves all transactions that occurred within a single settlement.

> ❕ You must request a separate API key to call Settlements API endpoints.
> Please contact [apisupport@coinify.com](mailto:apisupport@coinify.com) with a request to obtain one.

### Method
GET

### Endpoint
/settlements/transactions

### Parameters
#### Query Parameters
- **settlementId** (string) - Required - The ID of the settlement for which to retrieve transactions.

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200)
- **transactions** (array) - An array of Transaction objects.

#### Transaction Interface
- **merchantId** (string or NULL) - The ID of the merchant.
- **merchantName** (string or NULL) - The name of the merchant.
- **subaccountId** (string or NULL) - The ID of the subaccount.
- **subaccountName** (string or NULL) - The name of the subaccount.
- **referenceId** (string or NULL) - A unique identifier for the transaction reference type.
- **referenceType** (string (Enum)) - A curated list with all available reference types of the transactions. See below the Reference Type list for more details.
- **amount** (string) - The amount added or deducted from the balance for the specific transaction.
- **currency** (string) - The denomination currency of the amount.
- **orderId** (string or NULL) - The orderId of the entity.
- **customerId** (string or NULL) - The customer ID.
- **customerEmail** (string or NULL) - The customer email.
- **transactionTime** (string (DateTime)) - The UTC DateTime the transaction occurred.

#### Reference Type List
- **adjustment**: Manual positive or negative adjustment to the balance.
- **payment_intent**: Balance increase due to a completed Payment Intent.
- **payment_intent_refund**: Balance decrease due to a full or partial refund of a Payment Intent.
- **payment_intent_refund_fee**: Balance decrease due to a refund fee incurred for the created refund.
- **payment_intent_refund_reversal**: Balance increase due to a refund being cancelled by the merchant.
- **payment_intent_refund_fee_reversal**: Balance increase due to a refund fee being cancelled.
- **withdrawal**: Balance decrease due to a completed Withdrawal.
- **withdrawal_reversal**: Balance increase due to [cancellation of Withdrawal](https://coinify.readme.io/reference/withdrawals-webhooks#withdrawalcancelled).
- **payout_fee**: Balance decrease due to the payout.

#### Response Example
```json
{
  "transactions": [
    {
      "merchantId": "merchant_123",
      "merchantName": "Example Merchant",
      "subaccountId": "subaccount_456",
      "subaccountName": "Example Subaccount",
      "referenceId": "ref_789",
      "referenceType": "payment_intent",
      "amount": "100.50",
      "currency": "EUR",
      "orderId": "order_abc",
      "customerId": "cust_def",
      "customerEmail": "customer@example.com",
      "transactionTime": "2023-10-27T10:00:00Z"
    }
  ]
}
```
```

--------------------------------

### GET /v1/settlements

Source: https://coinify.readme.io/reference/get-all-settlements-list

Retrieves a list of settlements within a specified time period. You can define the period using the 'since' and 'until' query parameters.

```APIDOC
## GET /v1/settlements

### Description
This endpoint enables you to retrieve the list of settlements in a specified period. To receive the relevant settlement data, provide a starting and ending point for the period you want to fetch the settlement data from using the "since" and "until" query parameters.

### Method
GET

### Endpoint
https://api.payment.sandbox.coinify.com/v1/settlements

### Parameters
#### Query Parameters
- **since** (string) - Required - String (ISO DateTime). The beginning of the period to search in. Rightmost parts can be omitted, e.g. '2022-02' means beginning of the month (UTC timezone).
- **until** (string) - Required - String (ISO DateTime). The end of the period to search in. Rightmost parts can be omitted, e.g. '2022-02' means beginning of the month (UTC timezone).

### Request Example
```json
{
  "example": "No request body for GET requests"
}
```

### Response
#### Success Response (200)
- **settlements** (array) - An array of settlement objects.
  - **id** (string) - The unique identifier for the settlement.
  - **gross** (object) - The gross amount of the settlement.
    - **amount** (string) - The amount.
    - **currency** (string) - The currency of the amount.
  - **fee** (object) - The fee associated with the settlement.
    - **amount** (string) - The fee amount.
    - **currency** (string) - The currency of the fee amount.
  - **net** (object) - The net amount of the settlement.
    - **amount** (string) - The net amount.
    - **currency** (string) - The currency of the net amount.
  - **payout** (object) - The payout details.
    - **amount** (string) - The payout amount.
    - **currency** (string) - The currency of the payout amount.
  - **account** (object) - Details about the account.
    - **label** (string) - The label of the account.
  - **createTime** (string) - The ISO DateTime when the settlement was created.

#### Response Example
```json
{
    "settlements": [
        {
            "id": "1a0cf5d2-8f5d-4608-a7d5-f55d5a13fc24",
            "gross": { "amount": "999.99", "currency": "EUR" },
      			"fee": { "amount": "16.05", "currency": "EUR" },
      			"net": { "amount": "983.94", "currency": "EUR" },
     			  "payout": { "amount": "7342.81", "currency": "DKK" },
            "account": {
            "label": "International test"
            },
            "createTime": "2023-09-20T13:23:53.052Z"
        },
        {
            "id": "aaa9dd4a-7be8-4be4-8a14-212b329eb5a6",
            "gross": { "amount": "1238", "currency": "EUR" },
     				"fee": { "amount": "16.05", "currency": "EUR" },
     				"net": { "amount": "1221.95", "currency": "EUR" },
      			"payout": { "amount": "9119", "currency": "DKK" },
            "account": {
                "label": "Test EUR"
            },
            "createTime": "2023-09-19T13:46:00.468Z"
        }
    ]
}
```
```

--------------------------------

### POST /payment-intent

Source: https://coinify.readme.io/reference/create-payment-intent

Creates a payment intent for a transaction, returning a payment window URL for the user to complete the payment.

```APIDOC
## POST /payment-intent

### Description
Creates a payment intent for a transaction. Upon successful creation, it returns a URL that redirects the user to the Coinify payment window to complete the payment.

### Method
POST

### Endpoint
/payment-intent

### Parameters
#### Query Parameters
None

#### Request Body
- **amount** (number) - Required - The amount of the payment.
- **currency** (string) - Required - The currency of the payment (e.g., 'EUR', 'USD').
- **customer_email** (string) - Optional - The email address of the customer.
- **order_id** (string) - Optional - A unique identifier for the order.

### Request Example
```json
{
  "amount": 100.50,
  "currency": "EUR",
  "customer_email": "customer@example.com",
  "order_id": "order_12345"
}
```

### Response
#### Success Response (200 OK)
- **id** (string) - The unique identifier for the payment intent.
- **paymentWindowUrl** (string) - The URL to redirect the user to for payment completion.

#### Response Example
```json
{
  "id": "00dd6006-a76a-4e00-8085-cbd90d4a4272",
  "paymentWindowUrl": "https://checkout.sandbox.coinify.com/payment-intent/00dd6006-a76a-4e00-8085-cbd90d4a4272"
}
```

#### Error Responses
- **400 Bad Request**: Indicates an invalid request payload.
  - **errorCode** (string) - e.g., "invalid_request"
  - **errorMessage** (string) - A descriptive error message.
  - **requestId** (string) - Unique identifier for the request.
  ```json
  {
    "errorCode": "invalid_request",
    "errorMessage": "A descriptive error message",
    "requestId": "{requestId}"
  }
  ```
- **401 Unauthorized**: Indicates invalid authentication credentials.
  - **errorCode** (string) - e.g., "invalid_authentication"
  - **errorMessage** (string) - A descriptive error message.
  - **requestId** (string) - Unique identifier for the request.
  ```json
  {
    "errorCode": "invalid_authentication",
    "errorMessage": "A descriptive error message",
    "requestId": "{requestId}"
  }
  ```
- **404 Not Found**: Indicates that the requested resource was not found.
  - **errorCode** (string) - e.g., "not_found"
  - **errorMessage** (string) - e.g., "{resource} not found error"
  - **requestId** (string) - Unique identifier for the request.
  ```json
  {
    "errorCode": "not_found",
    "errorMessage": "{resource} not found error",
    "requestId": "{requestId}"
  }
  ```
- **422 Unprocessable Entity**: Indicates an invalid payload structure or missing required fields.
  - **errorCode** (string) - e.g., "invalid_payload"
  - **errorMessage** (string) - e.g., "\"{property}\" is required"
  - **requestId** (string) - Unique identifier for the request.
  ```json
  {
    "errorCode": "invalid_payload",
    "errorMessage": "\"{property}\" is required",
    "requestId": "{requestId}"
  }
  ```
```

--------------------------------

### Create Refund API (with Partial Refund capability)

Source: https://coinify.readme.io/changelog/partial-refunds-now-enabled

This endpoint allows merchants to create refunds for transactions. A new optional 'amount' parameter has been introduced to facilitate partial refunds.

```APIDOC
## POST /v1/refunds

### Description
Initiates a refund for a given transaction. This endpoint now supports partial refunds by specifying an optional 'amount' parameter.

### Method
POST

### Endpoint
/v1/refunds

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **transaction_id** (string) - Required - The ID of the transaction to refund.
- **amount** (number) - Optional - The amount to refund. If omitted, a full refund will be processed. If specified, only this amount will be refunded.
- **reason** (string) - Optional - The reason for the refund.

### Request Example
```json
{
  "transaction_id": "txn_12345abcde",
  "amount": 50.75,
  "reason": "Customer returned part of the order"
}
```

### Response
#### Success Response (200)
- **refund_id** (string) - The ID of the created refund.
- **transaction_id** (string) - The ID of the original transaction.
- **amount** (number) - The amount refunded.
- **currency** (string) - The currency of the refund.
- **status** (string) - The status of the refund (e.g., 'pending', 'completed', 'failed').

#### Response Example
```json
{
  "refund_id": "ref_67890fghij",
  "transaction_id": "txn_12345abcde",
  "amount": 50.75,
  "currency": "EUR",
  "status": "pending"
}
```
```

--------------------------------

### GET /websites/coinify_readme_io/settlements/{settlementId}

Source: https://coinify.readme.io/reference/get-all-settlement-transactions

Retrieves details for a specific settlement using its ID. This endpoint allows you to fetch comprehensive information about a settlement, including associated payment details.

```APIDOC
## GET /websites/coinify_readme_io/settlements/{settlementId}

### Description
Retrieves details for a specific settlement using its ID. This endpoint allows you to fetch comprehensive information about a settlement, including associated payment details.

### Method
GET

### Endpoint
/websites/coinify_readme_io/settlements/{settlementId}

### Parameters
#### Path Parameters
- **settlementId** (string) - Required - The unique identifier for the settlement.

### Response
#### Success Response (200)
- **subaccountName** (string) - The name of the subaccount associated with the settlement.
- **referenceId** (string) - The reference ID for the transaction.
- **referenceType** (string) - The type of reference (e.g., "payment_intent").
- **amount** (string) - The settlement amount.
- **currency** (string) - The currency of the settlement.
- **orderId** (string) - The order ID associated with the settlement.
- **customerId** (string) - The customer ID.
- **customerEmail** (string) - The customer's email address.
- **transactionTime** (string) - The timestamp of the transaction.

#### Response Example
```json
{
  "subaccountName": "Demo subaccount",
  "referenceId": "3de4fe93-5afd-4692-bead-2431416dd0bb",
  "referenceType": "payment_intent",
  "amount": "45.42",
  "currency": "USD",
  "orderId": "123456",
  "customerId": "6af46318-9e60-4390-8bf0-e042d7b96b21",
  "customerEmail": "customer@coinify.com",
  "transactionTime": "2023-09-10T11:27:11.892Z"
}
```

#### Error Response (401)
- **errorCode** (string) - An error code indicating the authentication issue.
- **errorMessage** (string) - A message describing the authentication error.
- **requestId** (string) - A unique identifier for the request.

#### Response Example
```json
{
    "errorCode": "invalid_authentication",
    "errorMessage": "Unknown API key",
    "requestId": "17e5c3e9-510d-48b7-a6d4-1734cc504f79"
}
```

#### Error Response (404)
- **errorCode** (string) - An error code indicating the resource was not found.
- **errorMessage** (string) - A message describing that the settlement was not found.
- **requestId** (string) - A unique identifier for the request.

#### Response Example
```json
{
    "errorCode": "not_found",
    "errorMessage": "Settlement \"1a0cf5d2-8f5d-4608-a7d5-f55d5a13fc25\" not found",
    "requestId": "763205e4-fcab-42b2-96d6-5ab73a14fc00"
}
```
```

--------------------------------

### POST /v1/payment-intents

Source: https://coinify.readme.io/reference/payment-intent-private-api

Creates a new payment intent with the specified details. This endpoint is used to initiate a payment process.

```APIDOC
## POST /v1/payment-intents

### Description
Creates a new payment intent with the specified details. This endpoint is used to initiate a payment process.

### Method
POST

### Endpoint
https://api.payment.sandbox.coinify.com/v1/payment-intents

### Parameters
#### Request Body
- **amount** (number) - Required - The amount to be paid.
- **currency** (string) - Required - The currency of the payment (e.g., EUR).
- **orderId** (string) - Required - A unique identifier for the order.
- **customerId** (string) - Required - The unique identifier for the customer.
- **customerEmail** (string) - Required - The email address of the customer.
- **pluginIdentifier** (string) - Optional - Identifier for the plugin or integration used.
- **successUrl** (string) - Required - The URL to redirect to upon successful payment.
- **failureUrl** (string) - Required - The URL to redirect to upon failed payment.

### Request Example
```json
{
  "amount": 99.99,
  "currency": "EUR",
  "orderId": "123456",
  "customerId": "6af46318-9e60-4390-8bf0-e042d7b96b21",
  "customerEmail": "customer@coinify.com",
  "pluginIdentifier": "DemoMerchant - Conify API Integration",
  "successUrl": "https://coinify.com",
  "failureUrl": "https://www.google.com"
}
```

### Response
#### Success Response (201)
- **success** (boolean) - Indicates if the operation was successful.

#### Response Example
```json
{
  "success": true
}
```
```

--------------------------------

### Get Settlements List

Source: https://coinify.readme.io/reference/get-all-settlements-list

Retrieves a list of settlements within a specified date range using 'since' and 'until' query parameters. An API key is required.

```APIDOC
## GET /v1/settlements

### Description
This endpoint enables you to retrieve the list of settlements in a specified period. To receive the relevant settlement data, provide a starting and ending point for the period you want to fetch the settlement data from using the "since" and "until" query parameters.

> ❕ You must request a separate API key to call Settlements API endpoints.
> 
> Please contact [apisupport@coinify.com](mailto:apisupport@coinify.com) with a request to obtain one.

### Method
GET

### Endpoint
/v1/settlements

### Parameters
#### Query Parameters
- **since** (string) - Required - The starting point for the period to fetch settlement data.
- **until** (string) - Required - The ending point for the period to fetch settlement data.

### Response
#### Success Response (200)
- **settlements** (array) - An array of Settlement objects.

```Text interface
{
	"settlements": [Settlement]
}
```

## Settlement Interface

| Property        | Type              | Description                                                       |
| :-------------- | :---------------- | :---------------------------------------------------------------- |
| id              | String (UUID)     | A unique identifier for the settlement report.                    |
| gross.amount    | String            | The total amount withdrawn from the merchant balance.             |
| gross.currency  | String            | The currency of the gross amount.                                 |
| fee.amount      | String            | The fee amount for the settlement.                                |
| fee.currency    | String            | The currency of the fee amount.                                   |
| net.amount      | String            | The net amount of the settlement which is gross minus fee.        |
| net.currency    | String            | The currency of the net amount.                                   |
| payout.amount   | String            | The amount expected to be received from the merchant.             |
| payout.currency | String            | The currency of the payout amount.                                |
| account.label   | String            | The label of the account to which the settlement was paid out.    |
| createTime      | String (DateTime) | The UTC date and time at which the settlement report was created. |
```