API Reference - Quidkey Docs

Base URLs

Quidkey provides separate environments for development and production:

Environment	Base URL	Purpose
Base URL	`https://core.quidkey.com`	All API requests

All endpoints are served under the /api/v1 prefix (for example https://core.quidkey.com/api/v1/oauth2/token).

Always use test_transaction: true in development to avoid processing real payments.

Authentication

All API endpoints require authentication using OAuth 2.0 Client Credentials flow.

Obtain credentials

Exchange for access token

Call POST /api/v1/oauth2/token with your credentials to receive an access_token

Use in requests

Include the token in all API requests: Authorization: Bearer <access_token>

Token Lifecycle:

Validity: 15 minutes (900 seconds)
Refresh: Use POST /api/v1/oauth2/refresh with your refresh_token
Best practice: Cache tokens and refresh before expiry

Try Authentication

Test the authentication flow in the interactive playground

API Endpoints

The Quidkey API is organized into logical groups:

Authentication

Obtain and refresh access tokens

Embedded Payment Flow

Create, update, and initiate payments

Payment Links

Create, list, and manage checkout links

Webhooks

Configure webhook endpoints and secrets

Common Response Format

All Quidkey API responses follow a consistent structure:

Success Response

{
  "success": true,
  "data": {
    // Response data here
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable error message",
    "metadata": {
      "errors": [
        {
          "field": "amount",
          "message": "Amount must be greater than 0"
        }
      ]
    }
  }
}

HTTP Status Codes

Status Code	Description	Common Scenarios
`200`	Success	Request processed successfully
`201`	Created	Resource created successfully
`400`	Bad Request	Validation error or malformed request
`401`	Unauthorized	Missing or invalid authentication
`403`	Forbidden	Valid auth but insufficient permissions
`404`	Not Found	Resource doesn’t exist
`500`	Internal Server Error	Server-side issue (rare)

Error Codes

Common error codes you may encounter:

Code	Description	Resolution
`VALIDATION_ERROR`	Request validation failed	Check `error.metadata.errors` for field-specific issues
`NO_TOKEN` / `INVALID_TOKEN`	Missing or expired token (HTTP `401`)	Refresh your access token; branch on the `401` status
`MERCHANT_NOT_FOUND`	Invalid merchant ID	Verify your credentials
`PAYMENT_REQUEST_NOT_FOUND`	Invalid payment token	Check token hasn’t expired (15 min TTL)
`PAYMENT_ALREADY_INITIATED`	Payment already in progress	Cannot update amount after customer selects bank
`PAYMENT_LINK_NOT_FOUND`	Invalid payment link token or ID	Verify the token or link ID
`PAYMENT_LINK_NOT_ACTIVE`	Link is used, expired, or cancelled	Check link status before attempting payment

All error responses include a human-readable message field. Use code for programmatic handling, message for logging/debugging.

Rate Limits

Quidkey currently does not enforce strict rate limits. However, we recommend implementing exponential backoff for retry logic and avoiding unnecessary API calls.

API Versioning

The current API version is v1, indicated in all endpoint paths: /api/v1/...

Breaking changes: Will be released as new versions (v2, v3, etc.)
Non-breaking changes: Added to existing version without path changes
Deprecation: Minimum 6 months notice before removing endpoints

Getting Started

Quickstart Guide

Get your first payment working in 10 minutes

Embedded Flow

Complete embedded payment integration guide

Need Help?

Contact Support

Email rabea@quidkey.com - we typically respond within one business day

​Base URLs

​Authentication

Try Authentication

​API Endpoints

Authentication

Embedded Payment Flow

Payment Links

Webhooks

​Common Response Format

​HTTP Status Codes

​Error Codes

​Rate Limits

​API Versioning

​Getting Started

Quickstart Guide

Embedded Flow

​Need Help?

Contact Support

Base URLs

Authentication

API Endpoints

Common Response Format

HTTP Status Codes

Error Codes

Rate Limits

API Versioning

Getting Started

Need Help?