Payments API

The Payments API drives the money-in side of servicing: a borrower repaying their facility, an early settlement, or a scheduled instalment plan that mirrors the loan's repayment terms. Money-out (disbursement of approved funds) is handled separately and is not exposed on the partner ring. Every resource lives under the partner/v1 base URL and is authenticated with a bearer token.

Base URL

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

Auth

OAuth 2.0 bearer token — scope payments:write for creation, payments:read for retrieval.

Rails

Open banking payment initiation (PISP) for collections; Faster Payments settlement.

Idempotency

Required on every write — send a unique Idempotency-Key header.

Endpoints

Create a payment link

A payment link returns a hosted pay.credicorp.co.uk URL you can email, SMS or embed. The borrower selects their bank, authenticates in their banking app, and the payment settles by Faster Payments. You receive a payment.paid webhook on settlement.

curl -s https://hub.credicorp.co.uk/partner/v1/payments/links \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: pl_3f9a1c" \
  -H "Content-Type: application/json" \
  -d '{
        "account_id": "acc_2WdR7yK",
        "amount_pence": 50000,
        "reference": "INV-2026-0481",
        "description": "June instalment",
        "redirect_url": "https://app.acme.co.uk/repay/done"
      }'

import Credicorp from '@credicorp/sdk';
const cc = new Credicorp({ token: process.env.CC_TOKEN });

const link = await cc.payments.links.create({
  account_id:   'acc_2WdR7yK',
  amount_pence: 50000,
  reference:    'INV-2026-0481',
  description:  'June instalment',
  redirect_url: 'https://app.acme.co.uk/repay/done'
}, { idempotencyKey: 'pl_3f9a1c' });

console.log(link.url); // → https://pay.credicorp.co.uk/l/9Lm…

use Credicorp\Client;

$cc = new Client(token: getenv('CC_TOKEN'));

$link = $cc->payments->links->create([
    'account_id'   => 'acc_2WdR7yK',
    'amount_pence' => 50000,
    'reference'    => 'INV-2026-0481',
    'description'  => 'June instalment',
], idempotencyKey: 'pl_3f9a1c');

echo $link->url;

Parameters

Response 201 Created

{
  "id": "pay_9Lm4Qx",
  "object": "payment",
  "account_id": "acc_2WdR7yK",
  "status": "pending",
  "amount_pence": 50000,
  "currency": "GBP",
  "reference": "INV-2026-0481",
  "url": "https://pay.credicorp.co.uk/l/9Lm4Qx",
  "expires_at": "2026-07-06T11:04:00Z",
  "created_at": "2026-06-29T11:04:00Z"
}

Create a collection schedule

A schedule sets up recurring collections — typically the repayment plan agreed at origination — against a payment mandate held on the account. Each due date generates a child payment which is initiated automatically; you are notified per instalment by payment.paid or payment.failed.

curl -s https://hub.credicorp.co.uk/partner/v1/payments/schedules \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: sch_88c0" \
  -d '{
        "account_id": "acc_2WdR7yK",
        "amount_pence": 41667,
        "cadence": "monthly",
        "start_date": "2026-07-15",
        "count": 12,
        "mandate_id": "mnd_7Hb2"
      }'

Parameters

Response 201 Created

{
  "id": "sch_5Tk9Pa",
  "object": "payment_schedule",
  "account_id": "acc_2WdR7yK",
  "status": "active",
  "cadence": "monthly",
  "amount_pence": 41667,
  "remaining": 12,
  "next_collection": {
    "payment_id": "pay_A1c…",
    "due_date": "2026-07-15"
  }
}

Payment statuses

A payment moves through a small, deterministic lifecycle. Drive your ledger from webhooks rather than polling — statuses are terminal once reached, except paid → refunded.

Failure reasons

Refund a payment

Reverses a settled payment over the same rails. Only full refunds are supported; the resulting credit is applied back to the account and a payment.refunded event is emitted.

curl -s -X POST https://hub.credicorp.co.uk/partner/v1/payments/pay_9Lm4Qx/refund \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: rf_001" \
  -d '{ "reason": "duplicate_collection" }'

Reconciliation

Every state change is delivered as a signed webhook, so your ledger never has to poll. Subscribe to the payment.* family and match each event to your records using the account_id plus your own reference. Events are HMAC-signed and retried with exponential back-off — verify the signature and de-duplicate on event.id.

{
  "id": "evt_Qm0v2",
  "type": "payment.paid",
  "created_at": "2026-06-29T11:09:42Z",
  "data": {
    "id": "pay_9Lm4Qx",
    "account_id": "acc_2WdR7yK",
    "reference": "INV-2026-0481",
    "amount_pence": 50000,
    "status": "paid",
    "settled_at": "2026-06-29T11:09:40Z"
  }
}

Errors

All errors from this endpoint use the standard hub error envelope. Branch on code for precise handling; quote correlation_id when contacting 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 error code list and all envelope fields are on the Errors page.

Related: Accounts roadmap for balances and repayment schedules, Webhooks roadmap for signed delivery, and Idempotency for safe retries.