API reference overview

Everything below applies to every resource — the same authentication, the same envelope for errors, the same cursor pagination and the same idempotency semantics. Read this page once and the individual resource pages become a quick lookup. If you are integrating for the first time, start with the Quickstart, then come back here for the catalogue.

Base URLs

The live environment is the regulated platform. All partner integrations use the partner/v1 ring on the hub origin.

Live base

https://hub.credicorp.co.uk/partner/v1

Token endpoint

https://hub.credicorp.co.uk/partner/v1/oauth/token

MCP endpoint

https://hub.credicorp.co.uk/partner/v1/mcp

Sandbox

roadmap — not yet available

Status

https://status.credicorp.co.uk

Authentication

Every request carries a bearer access token in the Authorization header. Tokens are short-lived (300 seconds — five minutes) and minted from your OAuth 2.0 client-credentials grant — re-request on expiry, no refresh token. Each token is bound to a set of scopes — you only get the resources you were granted at onboarding.

# 1. Mint a token (client_secret_basic; or use -d client_id/client_secret in the body)
curl -s https://hub.credicorp.co.uk/partner/v1/oauth/token \
  -u "$CC_CLIENT_ID:$CC_CLIENT_SECRET" \
  -d grant_type=client_credentials \
  -d scope=mcp.read

# 2. Call the live MCP endpoint (tools/list scoped to your token)
curl -s https://hub.credicorp.co.uk/partner/v1/mcp \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

// 1. Mint a token (Guzzle; any PSR-18 client works)
$http = new \GuzzleHttp\Client;
$tok  = json_decode($http->post(
    'https://hub.credicorp.co.uk/partner/v1/oauth/token',
    ['auth'        => [getenv('CC_CLIENT_ID'), getenv('CC_CLIENT_SECRET')],
     'form_params' => ['grant_type' => 'client_credentials', 'scope' => 'mcp.read']]
)->getBody(), true);

// 2. Call the live MCP endpoint
$res = json_decode($http->post(
    'https://hub.credicorp.co.uk/partner/v1/mcp',
    ['headers' => ['Authorization' => "Bearer {$tok['access_token']}",
                   'Content-Type'  => 'application/json'],
     'json'    => ['jsonrpc' => '2.0', 'id' => 1, 'method' => 'tools/list']]
)->getBody(), true);

// 1. Mint a token (Node fetch; works in browsers with btoa available)
const creds = btoa(`${process.env.CC_CLIENT_ID}:${process.env.CC_CLIENT_SECRET}`);
const tok = await fetch('https://hub.credicorp.co.uk/partner/v1/oauth/token', {
  method: 'POST',
  headers: { Authorization: `Basic ${creds}` },
  body: new URLSearchParams({ grant_type: 'client_credentials', scope: 'mcp.read' }),
}).then(r => r.json());

// 2. Call the live MCP endpoint
const list = await fetch('https://hub.credicorp.co.uk/partner/v1/mcp', {
  method: 'POST',
  headers: { Authorization: `Bearer ${tok.access_token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/list' }),
}).then(r => r.json());

The full token lifecycle, scope catalogue and key rotation are documented under OAuth 2.0. Server-to-server callers that disburse funds must additionally sign the request body — see Request signing roadmap.

Resources

The live surface today is the MCP tool tier at /partner/v1/mcp — a read-only, scope-filtered JSON-RPC 2.0 endpoint. The full REST write plane for lending applications, decisions, payments and webhooks is on the roadmap; those resources return 503 today and are documented below so you can design ahead.

Conventions

Requests & responses

Send and receive application/json; UTF-8 throughout. All monetary amounts are integer pence in GBP — 2500000 is £25,000.00. There are no floats anywhere in the API. Timestamps are RFC 3339 / ISO 8601 in UTC (2026-06-29T14:05:00Z). Every object carries a stable, prefixed id (app_, dec_, acc_, pay_) and a string object field so you can route polymorphically.

Errors

Conventional HTTP status codes signal the outcome. 2xx is success, 4xx is a problem with your request (a bad parameter, a failed validation, a missing scope) and 5xx is a problem on our side. Every error returns the same machine-readable envelope — switch on code for precise handling and quote correlation_id to support.

{
  "error": {
    "code": "validation_failed",
    "message": "The request failed validation.",
    "detail": [{ "field": "amount_pence", "reason": "min_value" }],
    "correlation_id": "cor_01J2K3M4N5P6Q7R8S9T0A1V2W3",
    "retryable": false
  }
}

The full code list lives on the Errors page.

Idempotency

Every POST accepts an Idempotency-Key header — any unique string (a UUID is ideal). We persist the first response against that key for 24 hours, so a retried request returns the original result instead of creating a duplicate application or taking a payment twice. Always set it on writes that move money or create records. Reusing a key with a different payload returns 409 conflict. See the idempotency guide.

Pagination

List endpoints are cursor-paginated. Pass limit (1–100, default 25) and walk forward with starting_after={id}. The envelope reports whether more pages exist; never infer the end from a short page.

{
  "object": "list",
  "data": [ { "id": "app_8Kd2c9Qm", …  } ],
  "has_more": true,
  "next_cursor": "app_8Kd2c9Qm"
}

Details and ordering guarantees are on the Pagination page.

Rate limits

Limits are applied per client, per environment, on a sliding window. Each response carries your budget so you can throttle pre-emptively rather than waiting for a 429.

Default ceilings and how to request an uplift are on the Rate limits page.

Where to go next

• Start here (live today). Follow the Quickstart — token → discover → MCP call. Three curl commands, five minutes.
• Understand the model. Core concepts covers rings, scopes and the MCP tool tiers.
• Designing ahead for lending? Read Apply roadmap → Decisioning roadmap → Payments roadmap for the planned shape — all return 503 today.
• Watch for availability. The write plane and its scopes will be announced on the changelog.