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

# Notify a payment

Call after the money has reached the account and validation returned `200`.

<RequestExample>
  ```bash Request theme={null}
  curl --request POST https://api.acealliance.capital/imbank/v1/payments \
    --header "Authorization: Bearer ACCESS_TOKEN" \
    --header "Content-Type: application/json" \
    --data '{
      "paymentType": "MPESA",
      "transactionReference": "FT260001",
      "transactionDate": "2026-06-19T10:30:00",
      "amount": 2500.25,
      "currency": "KES",
      "shortCode": "123456",
      "additions": {
        "customerRef": "1234567",
        "externalRefNumber": "QHM1X2Y3Z4",
        "payerName": "Daniel Kiptoo",
        "payerMobileNumber": "254700000000"
      }
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "resultCode": 0,
    "resultDesc": "Payment received",
    "erpRefId": "7Q3M9K2X"
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "resultCode": 1,
    "resultDesc": "Payment not recorded: customer not found",
    "erpRefId": ""
  }
  ```
</ResponseExample>

## Headers

<ParamField header="Authorization" type="string" required>
  `Bearer ACCESS_TOKEN`
</ParamField>

<ParamField header="Content-Type" type="string" required>
  `application/json`
</ParamField>

## Request body

<ParamField body="paymentType" type="string" required>
  `MPESA`, `RTGS`, `PESALINK`, `OTG`, `BRANCH`, or `CHEQUE`.
</ParamField>

<ParamField body="transactionReference" type="string" required>
  The Bank Reference. Unique for each payment.
</ParamField>

<ParamField body="transactionDate" type="string" required>
  Nairobi time as `YYYY-MM-DDTHH:mm:ss`. No `Z`, no offset.
</ParamField>

<ParamField body="amount" type="number" required>
  Greater than zero. At most two decimal places.
</ParamField>

<ParamField body="currency" type="string" required>
  `KES`
</ParamField>

<ParamField body="shortCode" type="string" required>
  The collection short code that received the payment.
</ParamField>

<ParamField body="additions" type="object" required>
  <Expandable title="properties" defaultOpen>
    <ParamField body="customerRef" type="string" required>
      The Member Number that validation confirmed.
    </ParamField>

    <ParamField body="externalRefNumber" type="string">
      The bank's external reference.
    </ParamField>

    <ParamField body="payerName" type="string" />

    <ParamField body="payerMobileNumber" type="string">
      For M-PESA.
    </ParamField>

    <ParamField body="senderBankCode" type="string">
      For a transfer.
    </ParamField>

    <ParamField body="senderAccountNumber" type="string">
      For a transfer.
    </ParamField>

    <ParamField body="senderAccountName" type="string">
      For a transfer.
    </ParamField>

    <ParamField body="senderAddress" type="string" />

    <ParamField body="chequeNumber" type="string">
      For a cheque.
    </ParamField>
  </Expandable>
</ParamField>

## Response

<ResponseField name="resultCode" type="integer" required>
  `0` recorded, `1` not recorded.
</ResponseField>

<ResponseField name="resultDesc" type="string" required>
  `Payment received`, or a text starting with `Payment not recorded`.
</ResponseField>

<ResponseField name="erpRefId" type="string" required>
  The Payment Receipt Number. Eight characters. Empty when not recorded.
</ResponseField>

## Errors

| Status | Meaning                                                                             | Action                        |
| ------ | ----------------------------------------------------------------------------------- | ----------------------------- |
| `400`  | A field is missing or invalid. `resultDesc` names the first failed rule.            | Correct and resend.           |
| `400`  | `Payment not recorded: customer not found`                                          | Hold the payment.             |
| `400`  | `Payment not recorded: a different payment already uses this transaction reference` | Use a unique Bank Reference.  |
| `401`  | Token missing, expired, or not valid. No body.                                      | Request a new token.          |
| `413`  | Body larger than 16384 bytes. No body.                                              | Correct and resend.           |
| `500`  | `Payment not recorded`. Nothing was recorded.                                       | Retry the same request later. |

All `resultDesc` texts: [Errors and messages](/bank-integration/errors).

## Retries

| Repeat                                      | Result                                             |
| ------------------------------------------- | -------------------------------------------------- |
| Same `transactionReference`, same body      | `200` with the same `erpRefId`. Recorded one time. |
| Same `transactionReference`, different body | `400`. The first payment stays recorded.           |

Retry with exactly the same body.