# Record money collected on an instalment

Books what actually landed on one instalment, with its split, and recomputes the schedule's totals — all in one transaction. Body: `actualAmountMinor` (MINOR UNITS) is the receipt, plus `penaltyAmountMinor`, `method` (ach, wire, check, card, revenue_split, manual, other), `externalTransactionId`, `achTraceNumber`, `batchId`, `notes`, and `allocations` as {allocationType, amountMinor, description} over principal, interest, fee, penalty, commission, buyout and other. An allocation list that does not sum to the receipt is refused rather than stored. The instalment lands on completed, or partial when the amount is short. Legal from the unsettled states only, in the WHERE, so two people recording the same receipt cannot both count it. This RECORDS money that already arrived; to actually debit the merchant's bank now, reach for `post_payments_id_collect`.

Access class: `workspace`.

## Endpoint

`POST /v1/payments/{id}/record`

## Parameters

| Name | In | Type | Required |
| --- | --- | --- | --- |
| id | path | string | Yes |

## Request body

Content type: `application/json`.

```json
{
  "body": {
    "achTraceNumber": "string",
    "actualAmountMinor": 1,
    "allocations": [
      {
        "allocationType": "string",
        "amountMinor": 1,
        "description": "string"
      }
    ],
    "batchId": "",
    "externalTransactionId": "",
    "method": "string",
    "notes": "string",
    "penaltyAmountMinor": 1
  },
  "params": {
    ":id": "string"
  },
  "query": {}
}
```

## Responses

### 201

the action's answer

Content type: `application/json`.

```json
{
  "data": {
    "achTraceNumber": "string",
    "actualAmountMinor": 1,
    "balanceAfterMinor": 1,
    "balanceBeforeMinor": 1,
    "batchId": "",
    "cashFlowId": 1,
    "counterpartyId": 1,
    "createdAt": "string",
    "currency": "string",
    "detail": {},
    "dueDate": "string",
    "expectedAmountMinor": 1,
    "externalTransactionId": "",
    "facilityId": 1,
    "failedAt": "string",
    "failureCode": "string",
    "failureReason": "string",
    "gracePeriodEnd": "string",
    "id": 1,
    "maxRetries": 1,
    "method": "string",
    "nextRetryDate": "string",
    "notes": "string",
    "paymentNumber": 1,
    "penaltyAmountMinor": 1,
    "processedAt": "string",
    "reconciled": true,
    "reconciledAt": "string",
    "reconciledByUserId": 1,
    "reconciliationNotes": "string",
    "referenceNumber": "string",
    "retryCount": 1,
    "reversedAt": "string",
    "scheduleId": 1,
    "settledAt": "string",
    "status": "string",
    "updatedAt": "string",
    "varianceMinor": 1,
    "waivedAt": "string"
  }
}
```

### default

a refusal: `{"error": "<what a person needs to read>"}`. 401 no credential, 402 the plan does not include this, 403 the seat does not, 404 the thing does not exist or is not yours to see.

Content type: `application/json`.

```json
{
  "error": "string"
}
```