# Partner Integration

Partners may consume MobiCred APIs directly and display MobiCred credit or
wallet capabilities inside their own applications.

## Partner Boundaries

- A partner owns its channel, UI, and partner-local customer reference.
- MobiCred owns canonical identity, credit decisions, loan offers, loan
  disbursement, repayment state, and Fineract integration.
- The same real person can appear through many partners, but should resolve to
  one canonical MobiCred subject.
- Partner-created users need attribution, scope, audit, and consent records.

The important tenant rule is that partner databases are allowed to duplicate
the business relationship, while Core/Fineract must not duplicate the person.

| System | What it stores for the same real person |
| --- | --- |
| InTouch partner DB | `INTC-DEMO-001` |
| Orange partner DB | `ORG-DEMO-001` |
| MTN partner DB | `MTN-DEMO-001` |
| Moov partner DB | `MOOV-DEMO-001` |
| Seeded MobiCred system partner | `MOBICRED-DEMO-001` |
| MobiCred Core/Fineract | One canonical customer/person |

Credit Intelligence can score any of the partner-local references after a
verified subject link exists. Core is only used when the score becomes a real
MobiCred credit line, loan, or repayment workflow.

## Partner Setup

MobiCred operators create partner access in Core before a partner can call the
public partner API:

| Step | Staff call |
| --- | --- |
| Create partner | `POST /internal/staff/partners` |
| Create tenant | `POST /internal/staff/partners/{partnerCode}/tenants` |
| Issue API key | `POST /internal/staff/partners/{partnerCode}/credentials` |
| Set IP/scope policy | `PUT /internal/staff/partners/{partnerCode}/access-policies` |

The credential response returns `apiKey` once. Store it in Bruno or a secret
manager as `partner_api_key`; Core stores only the hash. Partners then send
`X-API-Key-Id`, `X-API-Key`, `X-Tenant-Id`, and `X-Partner-Code`.

## Demo Credit Flow

Use the [Core API reference](/api/core) for the live partner credit contract.
All partner calls send `X-API-Key-Id`, `X-API-Key`, `X-Tenant-Id`, and
`X-Partner-Code`; `X-Partner-Code` must match `{partnerCode}` in the URL.

| Step | Call | Required scope |
| --- | --- | --- |
| Create partner-local user | `POST /v1/partners/{partnerCode}/users` | `users:write` |
| Check partner-local user | `GET /v1/partners/{partnerCode}/users/{partnerUserRef}` | `users:read` |
| Link partner customer | `POST /v1/partners/{partnerCode}/customer-references` | `customers:write` |
| Check linked customer | `GET /v1/partners/{partnerCode}/customers/{partnerCustomerRef}` | `customers:read` |
| See active credit lines | `GET /v1/partners/{partnerCode}/customers/{partnerCustomerRef}/credit-lines` | `credit-lines:read` |
| Create a NoStress application | `POST /v1/partners/{partnerCode}/credit-applications` with `X-Idempotency-Key` | `credit-applications:write` |
| Poll application status | `GET /v1/partners/{partnerCode}/credit-applications/{applicationId}/status` | `credit-applications:read` |

Partner-local user creation accepts `partnerUserRef`, channel/source details,
country, optional phone and identity evidence, consent, and non-secret metadata.
It does not create a mobile account or a Fineract customer. The seeded system
partner can be tested with `partnerCode=mobicred`, `X-Tenant-Id=mobicred-core`,
and a local or staging key stored as `{{partner_api_key}}`.

Customer linking accepts `partnerCustomerRef` plus either an existing
`customerId` or `phoneE164`. Core rejects attempts to rebind the same partner
reference to another person.

Application creation accepts `partnerCustomerRef`, `principal`, `termDays`, and
optional `purpose`. Reuse the same idempotency key only when replaying the exact
same request payload.

For an end-to-end demo, import `bruno/mobicred-partner-credit-demo` in Bruno.
Run `01-partner-local-users` first when you only need to prove partner-local
user creation without mobile UI. The scoring branch demonstrates standalone
Credit Intelligence. The optional Core branch shows the Core/Fineract credit
execution path.

```text
POST {{core_base_url}}/v1/partners/{{partner_mobicred}}/users
X-API-Key-Id: {{partner_api_key_id}}
X-API-Key: {{partner_api_key}}
X-Tenant-Id: {{partner_tenant_id}}
X-Partner-Code: {{partner_mobicred}}
Content-Type: application/json

{
  "partnerUserRef": "{{mobicred_partner_user_ref}}",
  "sourceChannel": "bruno",
  "countryCode": "CI",
  "phoneE164": "{{phone_e164}}",
  "identityEvidence": {
    "fullName": "MobiCred Demo User",
    "documentType": "demo_id"
  },
  "consent": {
    "basis": "customer-consent-v1",
    "capturedAt": "2026-06-29T12:00:00.000Z",
    "categories": ["identity", "scoring"]
  },
  "metadata": {
    "demo": true
  }
}
```

## Expected Gateway Capabilities

- Tenant-aware API keys, OAuth clients, or signed requests.
- Partner customer reference mapping to MobiCred subject IDs.
- Idempotent create-or-link endpoints.
- Consent and data usage capture for scoring inputs.
- Rate limits, quotas, and partner-level risk controls.
- Webhook delivery for score updates, offer status, disbursement, repayment, and
  account events.

## Do Not Leak

Partner APIs should not expose internal Fineract identifiers, raw provider
payloads, scoring model internals, or another partner's customer relationship.
The partner sees the customer data and products it is authorized to see.