SDKs overview

Official libraries

Three first-party clients are published and supported by Credicorp. Each tracks the same API ring and exposes the same resources, so concepts and method names carry across languages.

What the SDKs handle for you

The clients are not thin HTTP wrappers. They implement the operational concerns that every robust integration needs, the same way across each language:

• Authentication & token caching. You provide one secret key; the client performs the OAuth 2.0 client-credentials exchange, caches the resulting access token in memory, and refreshes it a little before expiry. You never touch /oauth/token directly. See OAuth 2.0.
• Sandbox vs live routing. The environment is inferred from the key prefix — sk_test_… hits the sandbox, sk_live_… hits production — so you cannot accidentally point test code at live money.
• Idempotency. Every write call (create, capture, withdraw) is sent with an Idempotency-Key. One is generated for you if you do not supply your own, making retries safe by construction. See Idempotency.
• Retries with back-off. Transient 429 and 5xx responses are retried automatically with exponential back-off and full jitter, honouring Retry-After. See Rate limits.
• Pagination. List endpoints return lazy iterators that follow the cursor for you, so you can loop over every application or payment without managing has_more by hand. See Pagination.
• Webhook verification. A one-line helper validates the Credicorp-Signature header and parses the event into a typed object, rejecting forged or replayed deliveries. See Webhooks.
• Typed models & errors. Applications, decisions, payments and accounts are real types, and API errors are raised as typed exceptions you can catch by class.

The same call, three languages

Creating an application is identical in shape everywhere — build the body, call applications.create(), read back the handoff_url you redirect the applicant to.

use Credicorp\Credicorp;

$cc  = new Credicorp(getenv('CC_SECRET_KEY'));
$app = $cc->applications->create([
    'business'     => ['company_number' => '16093826'],
    'amount_pence' => 2500000,
    'term_months'  => 12,
]);

echo $app->handoff_url;

import { Credicorp } from '@credicorp/sdk';

const cc  = new Credicorp(process.env.CC_SECRET_KEY);
const app = await cc.applications.create({
  business: { company_number: '16093826' },
  amount_pence: 2500000,
  term_months: 12,
});

console.log(app.handoff_url);

import os
from credicorp import Credicorp

cc  = Credicorp(os.environ["CC_SECRET_KEY"])
app = cc.applications.create(
    business={"company_number": "16093826"},
    amount_pence=2500000,
    term_months=12,
)

print(app.handoff_url)

Configuration & environments

Configure every client the same way: provide a single secret key, ideally read from the environment, and let the library do the rest. Because the environment is inferred from the key prefix, the identical build artefact runs in test and in production with no code change — you only swap the key.

Beyond the key, each client accepts a small set of options — request timeout and a max_retries ceiling for the automatic back-off. Sensible defaults are baked in, so most integrations pass nothing but the key. Token acquisition is lazy: the OAuth client-credentials exchange happens on the first API call and the resulting access token is cached and refreshed transparently, so you never serialise a token or schedule a refresh job yourself.

Versioning & support policy

SDKs follow semantic versioning and track the partner/v1 ring. The rules are deliberately boring so upgrades are predictable:

• New API fields are additive and ship in minor releases — pin a version range and upgrade on your own schedule.
• Breaking changes land only on a new major version and are announced first in the changelog.
• The current major of each SDK receives security and compatibility fixes for at least 12 months after the next major ships.