> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paypathiq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Credit-union integration walkthrough

> Map a member and loan, place arrears, record a payment and reconcile the balance.

This walkthrough explains the synthetic records in the [sandbox quickstart](/quickstart). Follow that page for runnable curl requests. Use an Integration granted the `credit_union.v1` profile, an approved Client and Portfolio, and the required [scopes](/authentication#scopes).

## Map the source records

Suppose Avery Example has a personal loan with EUR 4,000 outstanding, of which EUR 1,250 is authorized for collection.

| Source fact | API mapping | Example |
| - | - | - |
| Credit union whose debt is collected | Granted `clientCode` | Use the Client code issued with your key |
| Member | Customer with an opaque `externalCustomerId` | `CUS_<run suffix>` |
| Member's contact | Nested Contact with a stable `externalContactId` | `CON_<run suffix>` |
| Amount placed for collection | Receivable with its own opaque ID | `REC_<run suffix>` |
| Member liable for that placement | `responsibleCustomers` | Customer ID with role `primary` |
| Authorized collection amount | `recoverableAmount` | EUR 1,250.00 |
| Loan arrears | `creditUnion.arrearsAmount` | EUR 1,250.00 |
| Total loan outstanding, if supplied | `creditUnion.totalOutstandingAmount` | EUR 4,000.00; it does not increase collection authority |
| Payment received by the credit union | Payment observation with a stable event ID | `PAY_<run suffix>` |

Persist this mapping in your source integration. Do not use actual member or account numbers as URL IDs. The quickstart generates fresh IDs for each rehearsal; a real integration keeps each record's ID stable across updates and each payment event's ID stable across retries.

## Place the arrears

1. Create the Customer and Contacts. Always supply Contact IDs so you can update those Contacts later.
2. Create the Receivable with the Customer's ID, due date and required `creditUnion` loan details. Exactly one responsible Customer must be `primary`, and Customer IDs must be unique.
3. Read back the Receivable. Its `recoverableAmount` should be EUR 1,250.00. A supplied `balanceBreakdown` must sum to this amount, not to the total loan balance.

The quickstart omits the optional total loan balance. If you supply it, use the same Money shape as the other amounts: `{"amount":"4000.00","currency":"EUR"}`.

Accepting these records does not activate production recovery. Follow the separate [activation path](/environments#activation-path).

## Reconcile after a payment

The credit union receives EUR 250 by bank transfer. Submit a Payment observation for EUR 250.00 with `resultingRecoverableAmount` of EUR 1,000.00 and the Receivable's ID.

| Step | Expected recoverable amount | Check |
| - | - | - |
| Receivable accepted | EUR 1,250.00 | GET the Receivable |
| Payment accepted | EUR 1,000.00 | GET the Receivable; any old balance breakdown is removed |
| Same payment retried with the same ID and payload | EUR 1,000.00 | The payment must not be applied twice |
| Receivable paused on Client instruction | EUR 1,000.00 | GET shows `status: paused` |

If the Payment response is lost, repeat that observation with the same ID and payload. Do not replay the original EUR 1,250 Receivable PUT: it can restore that old amount. Serialize changes for each Receivable and reconcile before another balance write. See [Errors and retries](/errors-and-retries#retry-policy).

A mismatched resulting balance returns `409 balance_mismatch`. Read the current Receivable and reconcile the source events before correcting the request; do not invent a payment from a balance difference. Refunds and reversals must reference the original Payment observation and reverse it in full; partial adjustments are unsupported.

## Fit into a digital experience layer

Use this API to supply selected loan arrears, maintain your source facts, report external payments and issue the supported lifecycle instructions. Reads return the Integration's representation, not staff corrections or a feed of collection activity. Communications, payment initiation, Workflows and reporting are outside this API contract.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.