Getting started

Sandbox & test data

The Credicorp partner sandbox is a live, isolated transactional surface for integration testing. It uses its own credentials, database and synthetic fixtures. It never reads or writes production customer, lending, payment, identity, Companies House or webhook data.

Use the contract, not assumptions. OpenAPI and GET /v1/fixtures are the authoritative interface and fixture catalogue. The service version is returned by GET /healthz.

Get a client and token

Request an isolated sandbox client from developers@credicorp.co.uk. Store its one-time secret outside source control. Exchange it for an opaque bearer token using client credentials; tokens default to a one-hour lifetime and contain only sandbox:read and sandbox:write scopes.

POST/oauth/token

bash

export CC_BASE="https://sandbox.credicorp.co.uk"
export CC_CLIENT_ID="your-sandbox-client-id"
export CC_CLIENT_SECRET="your-sandbox-client-secret"

curl -s --user "$CC_CLIENT_ID:$CC_CLIENT_SECRET" \
  --data "grant_type=client_credentials" \
  "$CC_BASE/oauth/token"

OAuth requests are limited to 20 requests per client per minute. Authenticated API requests are limited to 600 requests per client per minute. A 429 rate_limited response includes retry information; never retry it as a successful write.

Discover deterministic fixtures

Fixtures describe the current synthetic company numbers, supported amounts, test bank accounts and expected outcomes. Fetch them at test time rather than copying values into code. Inputs outside the fixture contract fail honestly; real company, banking, payment and identity data are rejected and are never queried.

GET/v1/fixtures

bash

curl -s "$CC_BASE/v1/fixtures" \
  -H "Authorization: Bearer $TOKEN"

Exercise the lifecycle

Create an application with a fixture company and amount. If the fixture result is approvable, accept it with the matching fixture bank_account; that moves state in the sandbox only. Read a returned object with GET /v1/applications/{id}.

POST/v1/applications

bash

curl -s "$CC_BASE/v1/applications" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: application-001" \
  -H "Content-Type: application/json" \
  -d '{"business":{"company_number":"00000401"},"amount_pence":5000}'

POST/v1/applications/{id}/accept

Use a new idempotency key for every logical write. Repeating the same request with the same key returns the original result; a changed payload with a reused key returns 409 idempotency_key_reused. This is intentional and should be covered by your integration tests.

Simulate a payment

POST /v1/payments accepts a sandbox application id, fixture bank account and amount in pence. The fixture contract identifies settlement and failure paths. The response and any emitted event are durable sandbox records, enabling real retry and reconciliation tests without a money movement rail.

Receive and replay webhooks

Register a public HTTPS endpoint with POST /v1/webhook-endpoints. Private, loopback, link-local and reserved addresses are rejected; redirects are not followed and delivery is pinned to the validated address. The whsec_ signing secret is returned once only, so store it in your own secret manager.

GET/v1/events

POST/v1/events/{id}/replay

Deliveries carry an HMAC-SHA-256 signature in t=…,v1=… format. Verify it against the unmodified raw body and deduplicate by event id. Replaying an event creates a new delivery attempt for the original event; it does not create a new event.

Integration checklist

Fetch and pin the current fixture version for the test run.
Test an application, acceptance and payment lifecycle using unique idempotency keys.
Handle 401, 403, 409, 422 and 429 as non-success states.
Verify webhook signatures against the raw body and accept a replayed event safely.
Export any test evidence you need promptly: sandbox application data is retained for 30 days.

For complete field-level schemas and error envelopes, use the OpenAPI contract. Include the response request id when reporting a sandbox fault to developers@credicorp.co.uk.