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

# Charge Repayment

> Initiate a repayment charge against an active loan.

## Overview

Initiates a repayment charge for an active loan. All amounts are in **kobo**.

> **Note:** The `:loanId` path parameter is the **loan ID** (field `loan_id` on the application record, populated after disbursement) — not the `application_id`.

### Request

**Method:** `POST`\
**URL:** `/v1/loans/:loanId/repayments`

#### Parameters

| Name           | In     | Type     | Required | Description                                            |
| -------------- | ------ | -------- | -------- | ------------------------------------------------------ |
| `x-carbon-key` | Header | `string` | Yes      | API key for authentication.                            |
| `loanId`       | Path   | `string` | Yes      | Loan ID from the application record (`loan_id` field). |

#### Request Body

```json theme={null}
{
  "amount": 7199999,
  "reference": "REPAY_REF_20250215_001"
}
```

| Field       | Type   | Required | Description                                     |
| ----------- | ------ | -------- | ----------------------------------------------- |
| `amount`    | number | Yes      | Repayment amount in kobo. Must be positive.     |
| `reference` | string | Yes      | Merchant-supplied reference for this repayment. |

### Response

#### 200 OK

```json theme={null}
{
  "status": "success",
  "message": "Repayment initiated",
  "data": {}
}
```

#### Error Responses

| Status | Message                                      | Cause                                                |
| ------ | -------------------------------------------- | ---------------------------------------------------- |
| 400    | `Loan not found`                             | `loanId` does not match any loan under this merchant |
| 400    | `amount must be a positive number (in kobo)` | `amount` is zero, negative, or not a number          |
| 400    | `reference is required`                      | Missing repayment reference                          |
| 422    | `No SME loan ID on record`                   | Loan not yet registered in lending engine            |


## OpenAPI

````yaml POST /v1/loans/{loanId}/repayments
openapi: 3.0.0
info:
  title: Carbon Business API
  description: >-
    ## Welcome to our API Developer Documentation


    Carbon aims to unlock the full potential of your business with a
    feature-rich account designed for growth.


    ## Integrations


    We aim to provide our APIs for developers and businesses to offer financial
    services to their existing customer base through REST APIs without doing the
    heavy lifting. Our API has predictable resource-oriented URLs, accepts
    form-encoded request bodies, returns JSON-encoded responses, and uses
    standard HTTP response codes, authentication, and verbs.


    ### Authentication


    `Authorization : API Key`


    Header  

    `x-carbon-key : value`


    `x-carbon-key` can be generated via developer page on Carbon Business


    | Environment | URL |

    | --- | --- |

    | Live |  |

    | Sandbox |
    [https://carbonapistagingsecure.getcarbon.co/baas/api](https://carbonapistagingsecure.getcarbon.co/baas/api)
    |


    ### **Handling Errors**


    We use the conventional HTTP response codes to indicate the success or
    failure of an API request.  

    Codes in the 2xx range indicate success. Codes in the 4xx range indicate an
    error that failed given the information provided (e.g., a required parameter
    was omitted, etc.). Codes in the 5xx range indicate an error with our
    servers.


    | Error | Description |

    | --- | --- |

    | 400 - Bad Request | The request was unacceptable, often due to missing a
    required parameter. |

    | 401 - Unauthorized | Not a valid API key was provided. |

    | 402 - Request Failed | The parameters were valid but the request failed. |

    | 403 - Forbidden | The API key doesn't have permission to perform the
    request. |

    | 404 - Not Found | The requested resource doesn't exist. |

    | 429 - Too Many Requests | Too many requests hit the API |

    | 500, 502, 503, 504 - Server Errors | System Error |
  version: 1.0.0
servers:
  - url: https://carbonapistagingsecure.getcarbon.co/baas/api
    description: >-
      Replace {{base_url}} with your API base URL (e.g.,
      https://api.example.com)
security:
  - apikeyAuth: []
tags:
  - name: Accounts
    description: >-
      Virtual accounts are generated account details (account number and bank)
      that allow Carbon Business merchants to receive payments from customers
      via NGN bank transfer. This is currently only available in naira (NGN).


      Virtual accounts are either dynamic (temporary) or static (permanent). A
      dynamic account number expires after handling a transaction, while a
      static account number doesn't expire.


      **Static Account**


      Creating static accounts can be useful when receiving recurring payments
      through bank transfers. The process involves generating a static virtual
      account with customer information. Once payment is made, we will send you
      a webhook notification, which you can then manage.


      **Dynamic Account**


      Creating dynamic accounts can be useful when receiving one-time payments
      through bank transfers. The process involves generating a dynamic virtual
      account with a set amount for the customer during checkout. Once payment
      is made, we will send you a webhook notification, which you can then
      manage.


      Key things you can do with these endpoints:


      - Create an account

      - Retreive an account

      - Verify Transaction

      - Retreive a list of transactions
  - name: Accounts > Transactions
  - name: Banks
    description: |-
      - Get a list of banks and financial institutions
      - Verify/resolve account details
  - name: Customers
    description: >-
      This collection contains a set of API endpoints to manage customer-related
      operations for an application. The endpoints allow for creating a new
      customer, retrieving a list of all customers, and fetching details of a
      single customer.


      - Create Customer
          
      - Fetch Customer/Customers
  - name: Payout
    description: |-
      - Make Transfer
      - Verify Transfer
  - name: Status
    description: '- Service Health check'
  - name: Verification
  - name: Webhook
    description: |-
      ## EVENTS

      `account.incoming-transaction`

      ``` json
      {
          "event": "account.incoming-transaction",
          "data": {
              "id": "string",
              "amount": "float",
              "currency": "string",
              "transactionType": "string",
              "entryDate": "datetime",
              "uniqueRef": "string",
              "account": {
                  "id": "string",
                  "bankAccount": {
                      "accountName": "string",
                      "accountNumber": "string",
                      "bank": {
                          "code": "string",
                          "name": "string"
                      }
                  },
                  "static": boolean,
                  "currency": "string",
                  "clientId": "string"
              }
            }
      }

       ```

      `account.outgoing-transaction`

      ``` json
      {
          "event": "account.outgoing-transaction",
          "data": {
              "id": "string",
              "amount": "float",
              "currency": "string",
              "transactionType": "string",
              "entryDate": "datetime",
              "uniqueRef": "string",
              "account": {
                  "id": "string",
                  "bankAccount": {
                      "accountName": "string",
                      "accountNumber": "string",
                      "bank": {
                          "code": "string",
                          "name": "string"
                      }
                  },
                  "static": boolean,
                  "currency": "string",
                  "clientId": "string"
              }
          }
      }

       ```
  - name: Loans
    description: >-
      Partner lending API. Enables fintech partners to originate business loans
      for their end-customers.


      - Enroll customers for lending and trigger KYC

      - Submit loan applications and supporting documents

      - Manage offer acceptance, disbursement account, and post-offer steps

      - Charge repayments and retrieve repayment schedules
paths:
  /v1/loans/{loanId}/repayments:
    post:
      tags:
        - Loans
      summary: Charge Repayment
      description: >-
        Initiates a repayment charge against an active loan. All amounts are in
        kobo. Note — `loanId` is the `loan_id` field on the application record
        (populated after disbursement), not the `application_id`.

        ### Request Body

        - `amount` (number, required): Repayment amount in kobo (must be
        positive). - `reference` (string, required): Merchant-supplied reference
        for this repayment.

        ### Response

        - `status` (string): success - `message` (string): Repayment initiated
      parameters:
        - name: x-carbon-key
          in: header
          schema:
            type: string
          required: true
          example: '{{access_token}}'
        - name: loanId
          in: path
          schema:
            type: string
          required: true
          description: >-
            Loan ID from the application record (loan_id field, not
            application_id)
          example: LOAN_ABC123
      requestBody:
        description: Provide the required values for the request body.
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - amount
                - reference
              properties:
                amount:
                  type: number
                  description: Repayment amount in kobo
                  example: 7199999
                reference:
                  type: string
                  description: Merchant-supplied repayment reference
                  example: REPAY_REF_20250215_001
            example:
              amount: 7199999
              reference: REPAY_REF_20250215_001
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
              example:
                status: success
                message: Repayment initiated
                data: {}
components:
  securitySchemes:
    apikeyAuth:
      type: apiKey
      in: header
      name: apikey
      description: Provide your API key in the 'apikey' header.

````