Getting Started

Orkipay is a payment orchestration API that manages subscriptions, recurring billing, trials, upgrades, and multi-country pricing. It sits between your application and payment gateways, giving you a single API for everything billing-related.

Base URL

url
https://api.orkipay.com/api/v1

Authentication

All API requests require an API key sent in the X-API-Key header. You will receive your API key when your organization is set up.

javascript
fetch('https://api.orkipay.com/api/v1/customers', {
  headers: {
    'X-API-Key': 'sk_live_your_api_key_here',
    'Content-Type': 'application/json'
  }
})

Response Format

All responses follow a consistent JSON format:

Success

json
{
  "success": true,
  "result": { ... }
}

Error

json
{
  "success": false,
  "error": {
    "message": "Customer not found",
    "code": "NOT_FOUND",
    "statusCode": 404
  }
}

Quick Start

1

Configure your country and gateway

POST /organizations/me/country-configs — Set up payment processing for your region

2

Create plans and features

POST /plans — Define your products and pricing

3

Register customers and create subscriptions

Start billing your customers with recurring payments

Customers

Customers represent the end users of your application. Each customer belongs to an organization and can have one active subscription at a time. You can link customers to your own system using the externalId field.

Features

Features are reusable capabilities that you assign to plans. A feature can be free (included in the plan), quantifiable (billed per unit above the included usage), or a fixed add-on. Create features first, then attach them to plans.

Plans

Plans define your product offerings using a two-tier model: a Plan (product definition with features) and PlanPrices (pricing variants per country and billing interval). For example, a "Pro" plan can have prices for Colombia (monthly/yearly) and USA (monthly/yearly), each with different trial periods.

Subscriptions

Subscriptions are the core of Orkipay. They follow an 8-state deterministic lifecycle: provisioning → trialing → active → retrying → pending_cancellation → suspended / cancelled / expired. Each customer can have one active subscription at a time. The system handles billing, retries, upgrades, downgrades, and cancellations automatically.

Coupons

Coupons let you offer discounts to your customers. They support percentage or fixed-amount discounts, can be limited to specific plans or countries, and track redemptions automatically. Apply a coupon during subscription creation with the couponCode field.

Webhooks

Orkipay uses webhooks in two ways: inbound webhooks receive payment confirmations from gateways (Stripe, ePayco), and outbound webhooks notify your application about subscription and payment events. All outbound webhooks are signed with HMAC-SHA256 and follow an exponential backoff retry policy: 1min → 5min → 30min → 2h → 24h.