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

# Post to Account

> Executes a double-entry transaction by debiting and crediting accounts.

Processes a double-entry accounting transaction by debiting one account and crediting one or more counterparty accounts. This is the core transaction posting mechanism for the ledger engine.

## Request Headers

<ParamField header="X-Auth-Token" type="string" required>
  The **JWT Access Token** obtained from the `/login` or `/refresh-token` endpoint.
</ParamField>

<ParamField header="x-fapi-auth-date" type="string" required>
  The date and time at which the request was initiated (ISO 8601 format).
</ParamField>

<ParamField header="x-fapi-customer-ip-address" type="string" required>
  The IP address of the customer making the request.
</ParamField>

<ParamField header="x-fapi-interaction-id" type="string" required>
  Unique identifier for the interaction/session.
</ParamField>

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

## Request Body

The request body is an array of account posting instructions. Each instruction represents a transaction.

<ParamField body="accountPostings" type="array" required>
  Array of account posting instructions.

  <Expandable title="accountPostings array item">
    <ParamField body="primaryAccountNumber" type="string" required>
      Account number of the primary account involved in the transaction.
    </ParamField>

    <ParamField body="currencyCode" type="string" required>
      Currency code for the transaction (e.g., `NGN`, `USD`, `GBP`).
    </ParamField>

    <ParamField body="creditDebitInstructionDirection" type="string" required>
      Direction of the transaction:

      * `DEBIT_PRIMARY_ACCOUNT_CREDIT_COUNTERPARTY_ACCOUNT`: Debit primary account, credit counterparty
      * `CREDIT_PRIMARY_ACCOUNT_DEBIT_COUNTERPARTY_ACCOUNT`: Credit primary account, debit counterparty
    </ParamField>

    <ParamField body="counterParties" type="array" required>
      Array of counterparty accounts to credit or debit.

      <Expandable title="counterParties array item">
        <ParamField body="accountNumber" type="string" required>
          Account number of the counterparty account.
        </ParamField>

        <ParamField body="currencyCode" type="string" required>
          Currency code for the counterparty account.
        </ParamField>

        <ParamField body="amount" type="number" required>
          Amount to credit or debit from the counterparty account.
        </ParamField>

        <ParamField body="narration" type="string">
          Optional description or narration for the transaction.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="instructionIdempotencykey" type="string" required>
      Unique idempotency key for this posting instruction to prevent duplicate processing.
    </ParamField>

    <ParamField body="insufficientFundHandler" type="object">
      Optional handler for insufficient fund scenarios.

      <Expandable title="insufficientFundHandler object">
        <ParamField body="insufficientFundAuthorizationMode" type="string">
          How to handle insufficient funds:

          * `ON_AVAILABLE_BALANCE`: Only use available balance
          * `FORCE_ON_UNARRANGED_OVERDRAFT`: Allow unarranged overdraft (requires CASHIER authority)
        </ParamField>

        <ParamField body="overDraftFundOriginatingAccountNumberId" type="string">
          Account ID to source overdraft funds from (if applicable).
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl --location --request POST 'https://{domain}.fincode.software/api/v6/services/gateway/post-account' \
  --header 'X-Auth-Token: YOUR_JWT_ACCESS_TOKEN' \
  --header 'x-fapi-auth-date: 2024-01-15T10:30:00Z' \
  --header 'x-fapi-customer-ip-address: 192.168.1.1' \
  --header 'x-fapi-interaction-id: interaction-12345' \
  --header 'Content-Type: application/json' \
  --data '[
      {
          "primaryAccountNumber": "1234567890",
          "currencyCode": "NGN",
          "creditDebitInstructionDirection": "DEBIT_PRIMARY_ACCOUNT_CREDIT_COUNTERPARTY_ACCOUNT",
          "counterParties": [
              {
                  "accountNumber": "0987654321",
                  "currencyCode": "NGN",
                  "amount": 5000.00,
                  "narration": "Payment for services"
              }
          ],
          "instructionIdempotencykey": "unique-key-12345"
      }
  ]'
  ```

  ```javascript Node.js theme={null}
  const axios = require('axios');

  const BASE_URL = 'https://{domain}.fincode.software/api/v6/services/gateway';

  async function postToAccount(accessToken, postingInstructions) {
    try {
      const response = await axios.post(
        `${BASE_URL}/post-account`,
        postingInstructions,
        {
          headers: {
            'X-Auth-Token': accessToken,
            'x-fapi-auth-date': new Date().toISOString(),
            'x-fapi-customer-ip-address': '192.168.1.1',
            'x-fapi-interaction-id': `interaction-${Date.now()}`,
            'Content-Type': 'application/json',
          },
        }
      );

      response.data.data.forEach((result, index) => {
        console.log(`Instruction ${index + 1}:`, result.responseCode);
        if (result.instructions) {
          result.instructions.forEach((instruction) => {
            console.log(
              `  Account ${instruction.accountNumber}: ` +
              `${instruction.amount} (New Balance: ${instruction.newBalance})`
            );
          });
        }
      });

      return response.data.data;
    } catch (error) {
      console.error(
        'Failed to post to account:',
        error.response?.data || error.message
      );
      throw error;
    }
  }

  ```
</CodeGroup>


## OpenAPI

````yaml POST /gateway/post-account
openapi: 3.0.0
info:
  title: FinCode API
  version: v6
servers:
  - url: https://{tenant}.fincode.software/api/v6/services
    description: API v6
    variables:
      tenant:
        default: remitjunction
        description: Enter your tenant subdomain
  - url: https://{tenant}.fincode.software/api/v1/services
    description: API v1
    variables:
      tenant:
        default: finlend
        description: Enter your tenant subdomain
  - url: https://api.stag.songhaiexchange.io
    description: Songhai Exchange API
security: []
paths:
  /gateway/post-account:
    post:
      summary: Post to Account
      description: Executes a double-entry transaction.
      operationId: postAccount
      parameters:
        - $ref: '#/components/parameters/platformHeader'
        - $ref: '#/components/parameters/uuidHeader'
        - in: header
          name: X-Auth-Token
          schema:
            type: string
          required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                properties:
                  primaryAccountNumber:
                    type: string
                  currencyCode:
                    type: string
                  creditDebitInstructionDirection:
                    type: string
                  instructionIdempotencykey:
                    type: string
      responses:
        '200':
          description: Transaction result
components:
  parameters:
    platformHeader:
      in: header
      name: platform
      schema:
        type: string
        default: fincode
      required: true
    uuidHeader:
      in: header
      name: uuid
      schema:
        type: string
        default: '200'
      required: true

````