Skip to main content

​
Base URLs

Quidkey provides separate environments for development and production:
EnvironmentBase URLPurpose
Developmenthttps://core-dev.quidkey.comTesting and integration development
Productionhttps://core.quidkey.comLive payments
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.
1

Obtain credentials

Sign up at merchants.quidkey.com to get your client_id and client_secret
2

Exchange for access token

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

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

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": "INVALID_INPUT",
    "message": "Human-readable error message",
    "errors": [ // Optional - for validation errors
      {
        "field": "amount",
        "message": "Amount must be greater than 0"
      }
    ]
  }
}

​
HTTP Status Codes

Status CodeDescriptionCommon Scenarios
200SuccessRequest processed successfully
201CreatedResource created successfully
400Bad RequestValidation error or malformed request
401UnauthorizedMissing or invalid authentication
403ForbiddenValid auth but insufficient permissions
404Not FoundResource doesn’t exist
500Internal Server ErrorServer-side issue (rare)

​
Error Codes

Common error codes you may encounter:
CodeDescriptionResolution
INVALID_INPUTRequest validation failedCheck the errors array for field-specific issues
UNAUTHORIZEDInvalid or expired tokenRefresh your access token
MERCHANT_NOT_FOUNDInvalid merchant IDVerify your credentials
PAYMENT_REQUEST_NOT_FOUNDInvalid payment tokenCheck token hasn’t expired (15 min TTL)
PAYMENT_ALREADY_INITIATEDPayment already in progressCannot update amount after customer selects bank
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

Integration Guide

Complete production-ready integration

​
Need Help?

Contact Support

Email [email protected] - we typically respond within one business day