finperks Giftcard API

https://docs.finperks.com
Admin
finperks Giftcard API is a JSON-based REST API that enables partners to purchase and manage...
Tokens:80,771
Snippets:477
Trust Score:6.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### C# HttpClient Example

Source: https://docs.finperks.com/api/get-products

Demonstrates how to make a GET request to the products endpoint using HttpClient in C#. Ensure you replace `<Authorization>` with your actual authorization token.

```csharp
var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Get, "https://docs.finperks.com/products");
request.Headers.Add("Accept", "application/json");
request.Headers.Add("Authorization", "<Authorization>");
request.Headers.Add("Date", "<Date>");
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

```

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

### Get Product Code using HttpClient in C#

Source: https://docs.finperks.com/api/get-product-code

Example of how to make a GET request to retrieve product details using HttpClient in C#. Ensure you replace `<Authorization>` and `<Date>` with your actual credentials.

```csharp
var client = new HttpClient();  
var request = new HttpRequestMessage(HttpMethod.Get, "https://docs.finperks.com/products/:code");  
request.Headers.Add("Accept", "application/json");  
request.Headers.Add("Authorization", "<Authorization>");  
request.Headers.Add("Date", "<Date>");  
var response = await client.SendAsync(request);  
response.EnsureSuccessStatusCode();  
Console.WriteLine(await response.Content.ReadAsStringAsync());  

```

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

### Example Order Object

Source: https://docs.finperks.com/api/get-order-id

This is an example of a complete order object, including product details and an ID.

```json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "product": {
    "code": "b713c564-9e18-4810-a9bb-7b2d86afc8cd",
    "name": "Brand Gift Card",
    "description": "A gift card that can be used at Brand stores and online.",
    "seller": {

```

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

### Go Signature Generation Example

Source: https://docs.finperks.com/authentication

An example demonstrating how to use the `generateSignature` function with sample data. It includes a check against an expected signature.

```go
// Usage example with test data
func main() {
	signature := generateSignature(
		"30ce906050147eab919e8258871c45e7e3a3cb07",
		"api.finperks.com:443",
		"POST",
		"/v1/orders",
		"",
		"Sun, 06 Nov 2005 08:49:37 GMT",
		"123e4567-e89b-12d3-a456-426614174000",
		`{"amount":1000,"currency":"USD"}`,
	)

	expected := "786bd09c754ad301bb267a158c7b79a5a5a262dc50656c6d24c2c49bb49a5270"
	if signature != expected {
		panic(fmt.Sprintf("Signature mismatch: %s", signature))
	}
	fmt.Printf("Signature: %s\n", signature)

	// For live requests, use getHTTPDate() instead of a fixed date:
	// dateHeader := getHTTPDate()
}
```

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

### HTTP Request for Getting Order by ID

Source: https://docs.finperks.com/api/get-order-id

This C# example demonstrates how to make a GET request to retrieve order details. Ensure you replace `<Authorization>` and `<Date>` with your actual credentials. The `id` parameter in the URL should be the specific order ID you are querying.

```csharp
var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Get, "https://docs.finperks.com/orders/:id");
request.Headers.Add("Accept", "application/json");
request.Headers.Add("Authorization", "<Authorization>");
request.Headers.Add("Date", "<Date>");
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

```

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

### C# HttpClient Example

Source: https://docs.finperks.com/api/get-settlement-pdf-media

This C# code snippet demonstrates how to use HttpClient to make a GET request to retrieve the PDF media of a settlement. Remember to replace placeholders for Authorization and Date headers.

```csharp
var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Get, "https://api.finperks.com/v1/settlements/:id/media/pdf");
request.Headers.Add("Accept", "application/pdf");
request.Headers.Add("Authorization", "<Authorization>");
request.Headers.Add("Date", "<Date>");
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

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

### Signature Usage Example

Source: https://docs.finperks.com/authentication

Example demonstrating how to use the generate_signature method with test data and verifying the output.

```ruby
signature = generate_signature(
  key_secret: '30ce906050147eab919e8258871c45e7e3a3cb07',
  host_with_port: 'api.finperks.com:443',
  method: 'POST',
  path: '/v1/orders',
  query_string: '',
  date_header: 'Sun, 06 Nov 2005 08:49:37 GMT',
  idempotency_key: '123e4567-e89b-12d3-a456-426614174000',
  body: '{"amount":1000,"currency":"USD"}'
)
expected = '786bd09c754ad301bb267a158c7b79a5a5a262dc50656c6d24c2c49bb49a5270'
raise "Signature mismatch: #{signature}" unless signature == expected
puts "Signature: #{signature}"
```

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

### C# Example for Getting Settlement CSV Media

Source: https://docs.finperks.com/api/get-settlement-csv-media

This C# code uses HttpClient to fetch the CSV media of a settlement. Remember to replace '<Authorization>' and '<Date>' with your actual credentials and the current date.

```csharp
var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Get, "https://api.finperks.com/v1/settlements/:id/media/csv");
request.Headers.Add("Accept", "text/csv");
request.Headers.Add("Authorization", "<Authorization>");
request.Headers.Add("Date", "<Date>");
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

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

### Example Request Headers with Signature

Source: https://docs.finperks.com/authentication

This example shows the structure of request headers including the Authorization header with a signature. Ensure no extra whitespace is present in any fields.

```http
POST /v1/orders HTTP/1.1  





```

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

### Java Signature Generation Example

Source: https://docs.finperks.com/authentication

Provides a usage example for the `generateSignature` method in Java, including test data and an assertion to verify the generated signature against an expected value.

```java
// Usage example with test data
    public static void main(String[] args) throws Exception {
        String signature = generateSignature(
                "30ce906050147eab919e8258871c45e7e3a3cb07",
                "api.finperks.com:443",
                "POST",
                "/v1/orders",
                "",
                "Sun, 06 Nov 2005 08:49:37 GMT",
                "123e4567-e89b-12d3-a456-426614174000",
                "{\"amount\":1000,\"currency\":\"USD\"}"
        );

        String expected = "786bd09c754ad301bb267a158c7b79a5a5a262dc50656c6d24c2c49bb49a5270";
        if (!signature.equals(expected)) {
            throw new AssertionError("Signature mismatch: " + signature);
        }

```

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

### Example Order Response

Source: https://docs.finperks.com/api/post-order

This is an example of a completed order response, showing the structure of the 'data' object for a 'code' delivery method.

```json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "product": {
    "code": "b713c564-9e18-4810-a9bb-7b2d86afc8cd",
    "name": "Brand Gift Card",

```

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

### Example Order Refund Response

Source: https://docs.finperks.com/api/post-order-id-actions-refund

This is an example of a successful response when initiating a refund for an order. It includes the order ID, product details, and a unique identifier for the refund action.

```json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "product": {
    "code": "b713c564-9e18-4810-a9bb-7b2d86afc8cd",
    "name": "Brand Gift Card",
    "description": "A gift card that can be used at Brand stores and online."
  }
}
```

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

### Get Product by Code

Source: https://docs.finperks.com/api/get-product-code

Fetches product details using the product code.

```APIDOC
## GET /products/:code

### Description
Retrieves the details of a specific product using its unique code.

### Method
GET

### Endpoint
/products/:code

### Parameters
#### Path Parameters
- **code** (string) - Required - The unique identifier for the product.

### Request Example
```
GET /v1/products/your_product_code HTTP/1.1
Host: api.finperks.com
Authorization: FP1-HMAC-SHA256 KeyId=..., Signature=...
Date: Tue, 15 Nov 1994 08:12:31 GMT
Accept: application/json
```

### Response
#### Success Response (200)
- **field1** (string) - Description of the field

#### Response Example
```json
{
  "example": "response body"
}
```
```

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

### Get Products

Source: https://docs.finperks.com/api/get-products

Retrieves a list of available products. Supports pagination using cursors.

```APIDOC
## GET /products

### Description
Retrieves a list of available products. This endpoint supports pagination using `next` and `previous` cursors returned in the response.

### Method
GET

### Endpoint
/products

### Query Parameters
#### Cursors
- **next** (string) - Optional - A cursor to retrieve the next page of products.
- **previous** (string) - Optional - A cursor to retrieve the previous page of products.

### Response
#### Success Response (200)
- **products** (object[]) - An array of product objects.
  - **code** (string) - Unique identifier for the product.
  - **name** (string) - The name of the product.
  - **description** (string) - A brief description of the product.
  - **currency** (string) - The currency in which the product is priced (ISO 4217 alpha-3 code).
  - **denominations** (object) - Details about product denominations.
    - **type** (string) - Type of denomination (e.g., `fixed`, `variable`).
    - **amounts** (string[]) - List of fixed amounts available for the product.
    - **min_amount** (string) - Minimum amount for variable denominations.
    - **max_amount** (string) - Maximum amount for variable denominations.
    - **increment** (string) - The increment value for variable denominations.
  - **margin_percentage** (string) - The margin percentage for the product.
  - **state** (string) - The current state of the product (e.g., `available`, `unavailable`).
  - **assets** (object) - URLs for product assets.
    - **logo_url** (string) - URL for the product logo.
    - **giftcard_logo_url** (string) - URL for the gift card logo.
  - **contents** (object) - URLs for product content.
    - **markdown** (object)
      - **redemption_instructions_url** (string) - URL for redemption instructions.
      - **terms_and_conditions_url** (string) - URL for terms and conditions.
      - **redemption_notes_url** (string) - URL for redemption notes.
  - **delivery_methods** (string[]) - Supported delivery methods (e.g., `code`, `url`, `email`).
  - **available_countries** (string[]) - List of countries where the product is available (ISO 3166-1 alpha-2 codes).
  - **redemption_methods** (string[]) - Supported redemption methods (e.g., `online`, `in_store`).
  - **redemption_attributes** (object) - Specific attributes for redemption.
    - **activation_delay_hours** (number) - Delay in hours before the product can be activated.
  - **distribution_scheme** (string) - Distribution scheme (`resale` or `agency`).
  - **use_cases** (string[]) - Possible use cases for the product (e.g., `gifting`, `cashback`).
  - **processing_modes** (string[]) - Supported processing modes (`sync`, `async`).
  - **seller** (object) - Information about the seller (only for `agency` distribution scheme).
    - **name** (string) - Name of the seller.
    - **street_and_number** (string) - Street and number of the seller's address.
    - **zipcode** (string) - Zipcode of the seller's address.
    - **city** (string) - City of the seller's address.
    - **country** (string) - ISO 3166-1 alpha-2 country code of the seller's address.
- **cursors** (object) - Pagination cursors.
  - **next** (string | null) - Cursor for the next page.
  - **previous** (string | null) - Cursor for the previous page.

#### Response Example
```json
{
  "products": [
    {
      "code": "b713c564-9e18-4810-a9bb-7b2d86afc8cd",
      "name": "Brand Gift Card",
      "description": "A gift card that can be used at Brand stores and online.",
      "currency": "EUR",
      "denominations": {
        "type": "fixed",
        "amounts": [
          "50.00"
        ],
        "min_amount": "5.00",
        "max_amount": "50.00",
        "increment": "0.01"
      },
      "margin_percentage": "5.0",
      "state": "available",
      "assets": {
        "logo_url": "https://cdn.finperks.com/logos/brand.png",
        "giftcard_logo_url": "https://cdn.finperks.com/logos/giftcard.png"
      },
      "contents": {
        "markdown": {
          "redemption_instructions_url": "https://cdn.finperks.com/products/redemption_instructions.md",
          "terms_and_conditions_url": "https://cdn.finperks.com/products/terms_and_conditions.md",
          "redemption_notes_url": "https://cdn.finperks.com/products/redemption_notes.md"
        }
      },
      "delivery_methods": [
        "code",
        "url",
        "email"
      ],
      "available_countries": [
        "DE"
      ],
      "redemption_methods": [
        "online",
        "in_store"
      ],
      "redemption_attributes": {
        "activation_delay_hours": 24
      },
      "distribution_scheme": "resale",
      "use_cases": [
        "gifting",
        "employee_benefit",
        "cashback"
      ],
      "processing_modes": [
        "sync",
        "async"
      ],
      "seller": {
        "name": "Best Seller Inc.",
        "street_and_number": "Uhlandstr. 32",
        "zipcode": "10719",
        "city": "Berlin",
        "country": "DE"
      }
    }
  ],
  "cursors": {
    "next": "string",
    "previous": "string"
  }
}
```

### Error Handling
#### Bad Request (400)
- **application/json**
  - **Schema**
    - **class** (string) - Machine-readable error class.
    - **code** (string) - Machine-readable error code.
    - **message** (string) - Human-readable error message.
    - **fields** (object[]) - Array of specific field errors.
      - **name** (string) - Field name.
      - **code** (string) - Detailed error code for the field.
  - **Example**
    ```json
    {
      "class": "invalid_request",
      "code": "invalid_parameters",
      "message": "At least some of the parameters were invalid.",
      "fields": [
        {
          "name": "customer.id",
          "code": "missing"
        }
      ]
    }
    ```

#### Internal Server Error (500)
- **application/json**
  - **Schema**
    - **class** (string) - Machine-readable error class.
    - **code** (string) - Machine-readable error code.
    - **message** (string) - Human-readable error message.
```

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

### Example API Response Structure

Source: https://docs.finperks.com/api/get-product-code

Illustrates a typical JSON structure for an API response, showing key-value pairs.

```json
{
  "name": "customer.id",
  "code": "missing"
}
```

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

### Get Product by Code

Source: https://docs.finperks.com/api/get-product-code

Retrieve detailed information about a specific product using its unique code.

```APIDOC
## GET /v1/products/:code

### Description
Retrieve detailed information about a specific product using its unique code as provided in the product list.

### Method
GET

### Endpoint
https://api.finperks.com/v1/products/:code

### Parameters
#### Path Parameters
- **code** (string) - Required - Unique identifier of the product as provided in the product list.
```

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

### HTTP Request Example in C#

Source: https://docs.finperks.com/api/post-retail-order

Demonstrates how to construct and send a POST request to the retail orders endpoint using HttpClient in C#. Ensure to replace placeholders for Authorization and Date headers.

```csharp
var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://api.finperks.com/v1/retail_orders");
request.Headers.Add("Accept", "application/json");
request.Headers.Add("Authorization", "<Authorization>");
request.Headers.Add("Date", "<Date>");
var content = new StringContent("{
  \"product_code\": 4001232232332,
  \"serial\": 12312312,
  \"store_id\": \"A1234\",
  \"terminal_id\": \"T01\",
  \"receipt_id\": \"R1234567890\",
  \"cashier_id\": \"C001\",
  \"country\": \"DE\",
  \"face_value\": {
    \"currency\": \"EUR\",
    \"amount\": \"100.0\"
  },
  \"receipt_printing\": {
    \"characters_per_line\": 40,
    \"locale\": \"de-DE\"
  }
}", null, "application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

```

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

### HTTP Client POST Order Example (C#)

Source: https://docs.finperks.com/api/post-order

Demonstrates how to make a POST request to the orders endpoint using HttpClient in C#. Ensure you replace placeholders for Authorization and Date headers.

```csharp
var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://docs.finperks.com/orders");
request.Headers.Add("Accept", "application/json");
request.Headers.Add("Authorization", "<Authorization>");
request.Headers.Add("Date", "<Date>");
var content = new StringContent(string.Empty);
content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

```

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

### HTTP Request with C# HttpClient

Source: https://docs.finperks.com/api/get-store

Demonstrates how to make a GET request to retrieve store details using C# and HttpClient. Ensure you replace '<Authorization>' and '<Date>' with your actual credentials.

```csharp
var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Get, "https://api.finperks.com/v1/stores/:id");
request.Headers.Add("Accept", "application/json");
request.Headers.Add("Authorization", "<Authorization>");
request.Headers.Add("Date", "<Date>");
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

```

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

### C# HttpClient Example for Posting Store Data

Source: https://docs.finperks.com/api/post-store

Demonstrates how to send a POST request to the /v1/stores endpoint using HttpClient in C#. Ensure you replace '<Authorization>' and '<Date>' with your actual credentials.

```csharp
var client = new HttpClient();  
var request = new HttpRequestMessage(HttpMethod.Post, "https://api.finperks.com/v1/stores");  
request.Headers.Add("Accept", "application/json");  
request.Headers.Add("Authorization", "<Authorization>");  
request.Headers.Add("Date", "<Date>");  
var content = new StringContent("{\n  \"store_id\": \"A12345\",\n  \"name\": \"Location XY\",\n  \"street_and_number\": \"Uhlandstr. 32\",\n  \"zipcode\": \"10719\",\n  \"city\": \"Berlin\",\n  \"country\": \"DE\",\n  \"latitude\": \"52.5004185\",\n  \"longitude\": \"13.3222062\",\n  \"opening_hours\": {\n    \"day\": \"mon\",\n    \"open\": [\n      {\n        \"begin\": \"09:00\",\n        \"end\": \"18:00\"\n      }\n    ]\n  },\n  \"enabled\": true\n}", null, "application/json");  
request.Content = content;  
var response = await client.SendAsync(request);  
response.EnsureSuccessStatusCode();  
Console.WriteLine(await response.Content.ReadAsStringAsync());  

```

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

### Example JSON Error Response

Source: https://docs.finperks.com/api/get-settlement-pdf-media

This is an example of a JSON error response that may be returned if the request parameters are invalid or the entity is not found.

```json
{
  "class": "invalid_request",
  "code": "invalid_parameters",
  "message": "At least some of the parameters were invalid.",
  "fields": [
    {
      "name": "customer.id",
      "code": "missing"
    }
  ]
}
```

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

### Retrieve Store Details

Source: https://docs.finperks.com/api/get-store

Use this endpoint to get the details of a specific store by providing its ID in the URL path. This is a GET request.

```http
GET https://api.finperks.com/v1/stores/:id
```

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

### C# HttpClient Example for Product Update Webhook

Source: https://docs.finperks.com/api/post-product-update-webhook

Demonstrates how to send a product update event using HttpClient in C#. Ensure you replace placeholders like '<Authorization>' and '<Date>' with actual values.

```csharp
var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://your-server.com/path/at/partner/system/product/events");
request.Headers.Add("Authorization", "<Authorization>");
request.Headers.Add("Date", "<Date>");
var content = new StringContent("{
  \"id\": \"5e943c75-2065-46cb-a74b-69a13e034333\",
  \"event_scope\": \"products\",
  \"event\": \"updated\",
  \"event_at\": \"2025-07-16T18:16:12.000Z\",
  \"data\": {
    \"code\": \"b713c564-9e18-4810-a9bb-7b2d86afc8cd\",
    \"name\": \"Brand Gift Card\",
    \"description\": \"A gift card that can be used at Brand stores and online.\",
    \"currency\": \"EUR\",
    \"denominations\": {
      \"type\": \"fixed\",
      \"amounts\": [
        \"50.00\"
      ],
      \"min_amount\": \"5.00\",
      \"max_amount\": \"50.00\",
      \"increment\": \"0.01\"
    },
    \"margin_percentage\": \"5.0\",
    \"state\": \"available\",
    \"assets\": {
      \"logo_url\": \"https://cdn.finperks.com/logos/brand.png\",
      \"giftcard_logo_url\": \"https://cdn.finperks.com/logos/giftcard.png\"
    },
    \"contents\": {
      \"markdown\": {
        \"redemption_instructions_url\": \"https://cdn.finperks.com/products/redemption_instructions.md\",
        \"terms_and_conditions_url\": \"https://cdn.finperks.com/products/terms_and_conditions.md\",
        \"redemption_notes_url\": \"https://cdn.finperks.com/products/redemption_notes.md\"
      }
    },
    \"delivery_methods\": [
      \"code\",
      \"url\",
      \"email\"
    ],
    \"available_countries\": [
      \"DE\"
    ],
    \"redemption_methods\": [
      \"online\",
      \"in_store\"
    ],
    \"redemption_attributes\": {
      \"activation_delay_hours\": 24
    },
    \"distribution_scheme\": \"resale\",
    \"use_cases\": [
      \"gifting\",
      \"employee_benefit\",
      \"cashback\"
    ],
    \"processing_modes\": [
      \"sync\",
      \"async\"
    ],
    \"seller\": {
      \"name\": \"Best Seller Inc.\",
      \"street_and_number\": \"Uhlandstr. 32\",
      \"zipcode\": \"10719\",
      \"city\": \"Berlin\",
      \"country\": \"DE\"
    }
  }
}", null, "application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

```

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

### String to Sign Example

Source: https://docs.finperks.com/authentication

This is the string that needs to be signed. It includes host, port, HTTP method, path, query string, Date header, idempotency key, and the SHA-256 digest of the request body, separated by newline characters.

```text
api.finperks.com:443
POST
/v1/orders

Wed, 09 Jul 2025 16:17:31 GMT
5433c546-82d1-4105-baf7-7243a562273d
9123e49bd48ab640096f65ed7b21fc2a1006a799dad0553a20ec9aff745be887
```

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

### HTTP Client Request in C#

Source: https://docs.finperks.com/api/get-stores

Demonstrates how to make a GET request to the /v1/stores endpoint using HttpClient in C#. Ensure you replace placeholders for Authorization and Date headers.

```csharp
var client = new HttpClient();  
var request = new HttpRequestMessage(HttpMethod.Get, "https://api.finperks.com/v1/stores");  
request.Headers.Add("Accept", "application/json");  
request.Headers.Add("Authorization", "<Authorization>");  
request.Headers.Add("Date", "<Date>");  
var response = await client.SendAsync(request);  
response.EnsureSuccessStatusCode();  
Console.WriteLine(await response.Content.ReadAsStringAsync());  
```

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

### Trigger Event Request Body Example

Source: https://docs.finperks.com/api/post-client-partners-code-actions-trigger-event

This is an example of the JSON body required to trigger an event for a client partner. Ensure the 'event' field is one of the possible values.

```json
{
  "event": "created"
}
```

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

### GET Request Test Data

Source: https://docs.finperks.com/authentication

Test data for verifying GET request signature generation. Includes secret, host, method, path, query string, and date.

```text
Parameter| Value  
---|---  
Secret| `30ce906050147eab919e8258871c45e7e3a3cb07`  
Host| `api.finperks.com:443`  
Method| `GET`  
Path| `/v1/products`  
Query String| `?countrycode=DE`  
Date| `Sun, 06 Nov 2005 08:49:37 GMT`  
Idempotency Key|  _(empty)_  
Body|  _(empty)_  
**Expected Signature**| `3c8e65ab28539ace0817369d6943584d78be271dbe93bcb5408ee98a0141e30e`
```

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

### Get Retail Order by ID

Source: https://docs.finperks.com/api/get-retail-order-id

Fetches a retail order by its ID.

```APIDOC
## GET /v1/retail_orders/:id

### Description
Retrieves a specific retail order using its unique identifier.

### Method
GET

### Endpoint
/v1/retail_orders/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the retail order.

### Headers
- **Authorization** (apiKey) - Required - finperks Signature Version 1. Clients must sign the request and include: `FP1-HMAC-SHA256 KeyId=..., Signature=...`
- **Date** (apiKey) - Required - [RFC7231](http://tools.ietf.org/html/rfc7231#section-7.1.1.2) Date Header

### Request Example
```csharp
var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Get, "https://api.finperks.com/v1/retail_orders/:id");
request.Headers.Add("Accept", "application/json");
request.Headers.Add("Authorization", "<Authorization>");
request.Headers.Add("Date", "<Date>");
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

### Response
#### Success Response (200)
- **[Response fields not specified in source]**
```

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

### Product Response Example

Source: https://docs.finperks.com/api/get-products

This JSON object represents a successful response when retrieving product information. It includes details about the product, its denominations, seller information, and distribution schemes.

```json
{
  "products": [
    {
      "code": "b713c564-9e18-4810-a9bb-7b2d86afc8cd",
      "name": "Brand Gift Card",
      "description": "A gift card that can be used at Brand stores and online.",
      "currency": "EUR",
      "denominations": {
        "type": "fixed",
        "amounts": [
          "50.00"
        ],
        "min_amount": "5.00",
        "max_amount": "50.00",
        "increment": "0.01"
      },
      "margin_percentage": "5.0",
      "state": "available",
      "assets": {
        "logo_url": "https://cdn.finperks.com/logos/brand.png",
        "giftcard_logo_url": "https://cdn.finperks.com/logos/giftcard.png"
      },
      "contents": {
        "markdown": {
          "redemption_instructions_url": "https://cdn.finperks.com/products/redemption_instructions.md",
          "terms_and_conditions_url": "https://cdn.finperks.com/products/terms_and_conditions.md",
          "redemption_notes_url": "https://cdn.finperks.com/products/redemption_notes.md"
        }
      },
      "delivery_methods": [
        "code",
        "url",
        "email"
      ],
      "available_countries": [
        "DE"
      ],
      "redemption_methods": [
        "online",
        "in_store"
      ],
      "redemption_attributes": {
        "activation_delay_hours": 24
      },
      "distribution_scheme": "resale",
      "use_cases": [
        "gifting",
        "employee_benefit",
        "cashback"
      ],
      "processing_modes": [
        "sync",
        "async"
      ],
      "seller": {
        "name": "Best Seller Inc.",
        "street_and_number": "Uhlandstr. 32",
        "zipcode": "10719",
        "city": "Berlin",
        "country": "DE"
      }
    }
  ],
  "cursors": {
    "next": "string",
    "previous": "string"
  }
}
```

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

### Get Stores

Source: https://docs.finperks.com/api/get-stores

Retrieves a list of stores with optional pagination parameters.

```APIDOC
## GET /v1/stores

### Description
Retrieves a list of stores. Supports pagination using `next`, `previous`, and `size` query parameters.

### Method
GET

### Endpoint
/v1/stores

### Query Parameters
- **next** (string) - Optional - Token for the next page of results.
- **previous** (string) - Optional - Token for the previous page of results.
- **size** (integer) - Optional - The number of results to return per page.

### Request Example
```http
GET /v1/stores?size=10 HTTP/1.1
Host: api.finperks.com
Authorization: FP1-HMAC-SHA256 KeyId=<KeyId>, Signature=<Signature>
Date: <RFC7231 Date Header>
Accept: application/json
```

### Response
#### Success Response (200)
- **stores** (array) - A list of store objects.
- **next** (string) - Token for the next page of results.
- **previous** (string) - Token for the previous page of results.

#### Response Example
```json
{
  "stores": [
    {
      "id": "store_123",
      "name": "Example Store",
      "address": "123 Main St, Anytown, USA"
    }
  ],
  "next": "next_page_token",
  "previous": "previous_page_token"
}
```
```

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

### C# HttpClient Example for Settlement Update

Source: https://docs.finperks.com/api/post-settlement-update-webhook

Demonstrates how to send a POST request to the settlement events endpoint using HttpClient in C#. Ensure you replace placeholders like '<Authorization>' with your actual credentials.

```csharp
var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://your-server.com/path/at/partner/system/settlement/events");
request.Headers.Add("Authorization", "<Authorization>");
request.Headers.Add("Date", "<Date>");
var content = new StringContent("{
  \"id\": \"5e943c75-2065-46cb-a74b-69a13e034333\",
  \"event_scope\": \"settlements\",
  \"event\": \"paid\",
  \"event_at\": \"2025-07-16T18:16:12.000Z\",
  \"data\": {
    \"id\": \"e887aa12-9d6d-4ed9-adf1-d7aeb9a1c2af\",
    \"settlement_identifier\": \"CEX123-00001\",
    \"currency\": \"EUR\",
    \"total_amount\": \"-100.23\",
    \"period\": {
      \"from\": \"2026-01-01\",
      \"to\": \"2026-01-31\"
    },
    \"settlement_date\": \"2026-02-05\",
    \"payment_due_date\": \"2026-02-10\",
    \"state\": \"paid\",
    \"paid_at\": \"2026-02-08T15:30:00.000Z\"
  }
}", null, "application/json");
request.Content = content;
var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

```

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

### Invalidate Order

Source: https://docs.finperks.com/use_cases/indirect_sale

Invalidate an order if needed, for example, due to technical issues.

```APIDOC
## POST /orders/{id}/actions/invalidate

### Description
Invalidate an order if needed, e.g. due to technical issues.

### Method
POST

### Endpoint
/orders/{id}/actions/invalidate

### Path Parameters
- **id** (string) - Required - The unique identifier of the order to invalidate.

### Response
#### Success Response (200 OK)
- **message** (string) - Confirmation message indicating the order has been invalidated.
```

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

### Create Store

Source: https://docs.finperks.com/api/post-store

Creates a new store with the provided details. Returns the created store object upon success.

```APIDOC
## POST /stores

### Description
Creates a new store with the provided details.

### Method
POST

### Endpoint
/stores

### Request Body
- **id** (string) - Required - An identifier unique for the client as provided on creation
- **name** (string) - Required - The name of the store
- **street_and_number** (string) - Required - The street address and number
- **zipcode** (string) - Required - The postal code
- **city** (string) - Required - The city name
- **country** (string) - Required - The country code (e.g., DE)
- **latitude** (string) - Optional - The latitude coordinate. Must match regex `^-?[0-9]+\.[0-9]+$`.
- **longitude** (string) - Optional - The longitude coordinate. Must match regex `^-?[0-9]+\.[0-9]+$`.
- **opening_hours** (object) - Optional - Opening hours details.
  - **day** (string) - Required - The day of the week. Possible values: [`mon`, `tue`, `wed`, `thu`, `fri`, `sat`, `sun`].
  - **open** (object[]) - Required - An array of opening time slots.
    - **begin** (string) - Required - The start time of the opening slot. Must match regex `^([01]\d|2[0-3]):?([0-5]\d)$`.
    - **end** (string) - Required - The end time of the opening slot. Must match regex `^([01]\d|2[0-3]):?([0-5]\d)$`.

### Request Example
```json
{
  "id": "A12345",
  "name": "Location XY",
  "street_and_number": "Uhlandstr. 32",
  "zipcode": "10719",
  "city": "Berlin",
  "country": "DE",
  "latitude": "52.5004185",
  "longitude": "13.3222062",
  "opening_hours": {
    "day": "mon",
    "open": [
      {
        "begin": "09:00",
        "end": "18:00"
      }
    ]
  }
}
```

### Response
#### Success Response (201)
- **id** (string) - An identifier unique for the client as provided on creation
- **name** (string) - The name of the store
- **street_and_number** (string) - The street address and number
- **zipcode** (string) - The postal code
- **city** (string) - The city name
- **country** (string) - The country code
- **latitude** (string) - The latitude coordinate
- **longitude** (string) - The longitude coordinate
- **opening_hours** (object) - Opening hours details.
  - **day** (string) - The day of the week.
  - **open** (object[]) - An array of opening time slots.
    - **begin** (string) - The start time of the opening slot.
    - **end** (string) - The end time of the opening slot.

#### Response Example
```json
{
  "id": "A12345",
  "name": "Location XY",
  "street_and_number": "Uhlandstr. 32",
  "zipcode": "10719",
  "city": "Berlin",
  "country": "DE",
  "latitude": "52.5004185",
  "longitude": "13.3222062",
  "opening_hours": {
    "day": "mon",
    "open": [
      {
        "begin": "09:00",
        "end": "18:00"
      }
    ]
  }
}
```

### Error Codes
HTTP Status| Class| Code| Description  
---|---|---|---
400| `invalid_request`| `invalid_body_parameters`| Invalid body parameters with details in the fields attribute  
500| `internal_server_error`| `unknown`| An unexpected error occurred on the server.
```

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

### List Available Products

Source: https://docs.finperks.com/use_cases/direct_sale

List available products to display to your customers and import them into your system.

```APIDOC
## GET /products

### Description
List available products to display to your customers and import them into your system.

### Method
GET

### Endpoint
/products
```

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

### Get Settlement by ID

Source: https://docs.finperks.com/api/get-settlement-by-id

Fetches a settlement's details using its unique identifier.

```APIDOC
## GET /settlements/:id

### Description
Get a settlement by its unique identifier.
**Note:** In live API only, not available in sandbox API.

### Method
GET

### Endpoint
/settlements/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the settlement.

### Responses
#### Success Response (200)
- **Settlement details** (object) - Contains the details of the settlement.

#### Error Responses
- **404 Not Found** - Entity not found.
- **500 Internal Server Error** - An unexpected error occurred.
```
Tokens:
Raw