Skip to main content

Getting Started

This guide walks you through your first signed request and your first sandbox order. It should take you from credentials to a delivered test gift card in a few minutes.

1. Get Your Credentials​

Your finperks contact sets up your account and your access to the finperks Control Center. In the Control Center you can create API keys yourself, separately for the sandbox and live environments. An API key consists of a key id and a key secret — the secret is only shown once at creation time, so store it securely.

Start with a sandbox API key. The sandbox behaves like the live API but never triggers monetary settlement, see Accessing the API.

2. Make Your First Request​

Every request must be signed. Implement the signature algorithm described under Authentication — it includes code examples in several languages, test vectors, and a signature generator to verify and debug your implementation.

Then call the GET /v1/ping endpoint, which exists exactly for this step: it lets you verify connectivity and your signature implementation without any side effects. A 200 response with an empty JSON object means authentication works. If you receive a 401, compare your implementation against the signature generator and the test vectors on the authentication page.

3. Set Your Sandbox Balance​

Orders are executed against your balance, and a fresh sandbox account may not have one yet. In the sandbox you can set it yourself:

PATCH /v1/balances/EUR

{
  "balance": "1000.00"
}

4. Find a Product​

List the products available to you and pick one to order:

GET /v1/products?country=DE

Note the product's code, its supported delivery_methods and processing_modes, and the allowed amounts in denominations.

5. Create Your First Order​

Create a synchronous order for the selected product. The Idempotency-Key header is required and is part of the request signature, see Idempotency:

POST /v1/orders
Idempotency-Key: 123e4567-e89b-12d3-a456-426614174000

{
  "product_code": "b713c564-9e18-4810-a9bb-7b2d86afc8cd",
  "customer": {
    "id": "test-customer-1"
  },
  "country": "DE",
  "face_value": {
    "currency": "EUR",
    "amount": "10.0"
  },
  "processing_mode": "sync",
  "delivery_method": {
    "type": "code"
  }
}

The response contains the completed order including the delivery data — your first gift card code. You can retrieve the order again at any time via GET /v1/orders/{id}.

Next Steps​