Post to Account

curl --request POST \
  --url https://{tenant}.fincode.software/api/v6/services/gateway/post-account \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: <x-auth-token>' \
  --header 'platform: <platform>' \
  --header 'uuid: <uuid>' \
  --data '
[
  {
    "primaryAccountNumber": "<string>",
    "currencyCode": "<string>",
    "creditDebitInstructionDirection": "<string>",
    "instructionIdempotencykey": "<string>"
  }
]
'

import requests

url = "https://{tenant}.fincode.software/api/v6/services/gateway/post-account"

payload = [
    {
        "primaryAccountNumber": "<string>",
        "currencyCode": "<string>",
        "creditDebitInstructionDirection": "<string>",
        "instructionIdempotencykey": "<string>"
    }
]
headers = {
    "platform": "<platform>",
    "uuid": "<uuid>",
    "X-Auth-Token": "<x-auth-token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    platform: '<platform>',
    uuid: '<uuid>',
    'X-Auth-Token': '<x-auth-token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify([
    {
      primaryAccountNumber: '<string>',
      currencyCode: '<string>',
      creditDebitInstructionDirection: '<string>',
      instructionIdempotencykey: '<string>'
    }
  ])
};

fetch('https://{tenant}.fincode.software/api/v6/services/gateway/post-account', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{tenant}.fincode.software/api/v6/services/gateway/post-account",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    [
        'primaryAccountNumber' => '<string>',
        'currencyCode' => '<string>',
        'creditDebitInstructionDirection' => '<string>',
        'instructionIdempotencykey' => '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Auth-Token: <x-auth-token>",
    "platform: <platform>",
    "uuid: <uuid>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{tenant}.fincode.software/api/v6/services/gateway/post-account"

	payload := strings.NewReader("[\n  {\n    \"primaryAccountNumber\": \"<string>\",\n    \"currencyCode\": \"<string>\",\n    \"creditDebitInstructionDirection\": \"<string>\",\n    \"instructionIdempotencykey\": \"<string>\"\n  }\n]")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("platform", "<platform>")
	req.Header.Add("uuid", "<uuid>")
	req.Header.Add("X-Auth-Token", "<x-auth-token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{tenant}.fincode.software/api/v6/services/gateway/post-account")
  .header("platform", "<platform>")
  .header("uuid", "<uuid>")
  .header("X-Auth-Token", "<x-auth-token>")
  .header("Content-Type", "application/json")
  .body("[\n  {\n    \"primaryAccountNumber\": \"<string>\",\n    \"currencyCode\": \"<string>\",\n    \"creditDebitInstructionDirection\": \"<string>\",\n    \"instructionIdempotencykey\": \"<string>\"\n  }\n]")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{tenant}.fincode.software/api/v6/services/gateway/post-account")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["platform"] = '<platform>'
request["uuid"] = '<uuid>'
request["X-Auth-Token"] = '<x-auth-token>'
request["Content-Type"] = 'application/json'
request.body = "[\n  {\n    \"primaryAccountNumber\": \"<string>\",\n    \"currencyCode\": \"<string>\",\n    \"creditDebitInstructionDirection\": \"<string>\",\n    \"instructionIdempotencykey\": \"<string>\"\n  }\n]"

response = http.request(request)
puts response.read_body

POST

gateway

post-account

Post to Account

curl --request POST \
  --url https://{tenant}.fincode.software/api/v6/services/gateway/post-account \
  --header 'Content-Type: application/json' \
  --header 'X-Auth-Token: <x-auth-token>' \
  --header 'platform: <platform>' \
  --header 'uuid: <uuid>' \
  --data '
[
  {
    "primaryAccountNumber": "<string>",
    "currencyCode": "<string>",
    "creditDebitInstructionDirection": "<string>",
    "instructionIdempotencykey": "<string>"
  }
]
'

import requests

url = "https://{tenant}.fincode.software/api/v6/services/gateway/post-account"

payload = [
    {
        "primaryAccountNumber": "<string>",
        "currencyCode": "<string>",
        "creditDebitInstructionDirection": "<string>",
        "instructionIdempotencykey": "<string>"
    }
]
headers = {
    "platform": "<platform>",
    "uuid": "<uuid>",
    "X-Auth-Token": "<x-auth-token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    platform: '<platform>',
    uuid: '<uuid>',
    'X-Auth-Token': '<x-auth-token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify([
    {
      primaryAccountNumber: '<string>',
      currencyCode: '<string>',
      creditDebitInstructionDirection: '<string>',
      instructionIdempotencykey: '<string>'
    }
  ])
};

fetch('https://{tenant}.fincode.software/api/v6/services/gateway/post-account', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://{tenant}.fincode.software/api/v6/services/gateway/post-account",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    [
        'primaryAccountNumber' => '<string>',
        'currencyCode' => '<string>',
        'creditDebitInstructionDirection' => '<string>',
        'instructionIdempotencykey' => '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Auth-Token: <x-auth-token>",
    "platform: <platform>",
    "uuid: <uuid>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://{tenant}.fincode.software/api/v6/services/gateway/post-account"

	payload := strings.NewReader("[\n  {\n    \"primaryAccountNumber\": \"<string>\",\n    \"currencyCode\": \"<string>\",\n    \"creditDebitInstructionDirection\": \"<string>\",\n    \"instructionIdempotencykey\": \"<string>\"\n  }\n]")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("platform", "<platform>")
	req.Header.Add("uuid", "<uuid>")
	req.Header.Add("X-Auth-Token", "<x-auth-token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://{tenant}.fincode.software/api/v6/services/gateway/post-account")
  .header("platform", "<platform>")
  .header("uuid", "<uuid>")
  .header("X-Auth-Token", "<x-auth-token>")
  .header("Content-Type", "application/json")
  .body("[\n  {\n    \"primaryAccountNumber\": \"<string>\",\n    \"currencyCode\": \"<string>\",\n    \"creditDebitInstructionDirection\": \"<string>\",\n    \"instructionIdempotencykey\": \"<string>\"\n  }\n]")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://{tenant}.fincode.software/api/v6/services/gateway/post-account")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["platform"] = '<platform>'
request["uuid"] = '<uuid>'
request["X-Auth-Token"] = '<x-auth-token>'
request["Content-Type"] = 'application/json'
request.body = "[\n  {\n    \"primaryAccountNumber\": \"<string>\",\n    \"currencyCode\": \"<string>\",\n    \"creditDebitInstructionDirection\": \"<string>\",\n    \"instructionIdempotencykey\": \"<string>\"\n  }\n]"

response = http.request(request)
puts response.read_body

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

X-Auth-Token

string

required

The JWT Access Token obtained from the /login or /refresh-token endpoint.

x-fapi-auth-date

string

required

The date and time at which the request was initiated (ISO 8601 format).

x-fapi-customer-ip-address

string

required

The IP address of the customer making the request.

x-fapi-interaction-id

string

required

Unique identifier for the interaction/session.

Content-Type

string

default:"application/json"

required

Must be application/json.

Request Body

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

accountPostings

array

required

Array of account posting instructions.

Show accountPostings array item

primaryAccountNumber

string

required

Account number of the primary account involved in the transaction.

currencyCode

string

required

Currency code for the transaction (e.g., NGN, USD, GBP).

creditDebitInstructionDirection

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

counterParties

array

required

Array of counterparty accounts to credit or debit.

Show counterParties array item

accountNumber

string

required

Account number of the counterparty account.

currencyCode

string

required

Currency code for the counterparty account.

amount

number

required

Amount to credit or debit from the counterparty account.

narration

string

Optional description or narration for the transaction.

instructionIdempotencykey

string

required

Unique idempotency key for this posting instruction to prevent duplicate processing.

insufficientFundHandler

object

Optional handler for insufficient fund scenarios.

Show insufficientFundHandler object

insufficientFundAuthorizationMode

string

How to handle insufficient funds:

ON_AVAILABLE_BALANCE: Only use available balance
FORCE_ON_UNARRANGED_OVERDRAFT: Allow unarranged overdraft (requires CASHIER authority)

overDraftFundOriginatingAccountNumberId

string

Account ID to source overdraft funds from (if applicable).

Code Examples

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"
    }
]'

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;
  }
}

Headers

platform

string

default:fincode

required

uuid

string

default:200

required

X-Auth-Token

string

required

Body

application/json

primaryAccountNumber

string

currencyCode

string

creditDebitInstructionDirection

string

instructionIdempotencykey

string

Response

200

Transaction result

Change Account Permission

Getting Started

Core Flows

API Endpoints

Post to Account

Request Headers

Request Body

Code Examples

Headers

Body

Response

​Request Headers

​Request Body

​Code Examples

Headers

Body

Response

Request Headers

Request Body

Code Examples