Documentation

  2. Home
  4. Docs
  6. Documentation
  8. Cash APIs – V1
  10. API: Create Transaction

API: Create Transaction

The purpose of this API is to create new transaction.

Request

URL https://your_account.modulus.biz/api/csh/v1/Transaction?token=YOUR_TOKEN
API Name Transaction
Method POST
Source Third Party Server
Recipient modulus® Server
Content Type application/json

Query String Parameters

Parameter Required Type Description
token Yes Text Your authentication token.

Payload Parameters

Parameter Required Type Description
account_code Yes Text The code of the cash account used in the transaction.
date Yes Date Date format must be ISO 8601 (Example: “2020-01-10”) and can not be in the future.
amount Yes Decimal The amount of the the transaction in account currency.
cash_book_id Yes Number Refers to cash book used for the transaction.
transaction_nature
 Yes Text Refers to the transaction nature of the transaction, possible values ( LKP_ENUM_CASH_IN, LKP_ENUM_CASH_OUT)
counter_party Yes Text Refers to other party of the transaction.
related_party No Object Object with the info of counter party provided either customer or supplier. The structure explained here.
account_exchange_rate No Decimal Number The exchange rate of the account currency when the transaction is created. Mandatory if the account has foreign currency.
counter_party_exchange_rate
 No Decimal Number The exchange rate of the pay party currency when the transaction is created. Mandatory if the pay party has foreign currency differs the account currency.
reference No Text Transaction reference.
description No Text Transaction description.

 

Customer Parameter details

Parameter Required Type Description
code Yes Text The code of the related party used in the transaction.
name Yes Text The name of the related party used in the transaction.
type Yes Text The Type of the related party used in the transaction.
Possible values are: individual or organization.
tax_registration_number No Number Related party’s Tax Registration Number.
account_code No Text The code of the cash account of the related party.
price_list_code (for counter parties of type customer) No Number The code of the price list of the related party.
It must have the same currency as the customer and account.
address No Object The address of the related party. The structure is explained elsewhere.
contact No Object The contact of the related party. The structure is explained elsewhere.

 

Address Parameter details

Parameter Type Required Description
label Text Yes The label of the address.
country_code Text Yes The country code of the address (Example: “EG”).
city Text Yes The name of the city in the specified country.
address Text No Additional info of the address.

 

Contact Parameter details

Parameter Type Required Description
type Text Yes The type of the contact provided. Possible values are: mobile, phone, email, fax, website, or other.
label Text Yes The label of the contact.
value Text Yes The value of the contact.

 

Responses

HTTP Status result title message object
Success Responses
200 OK true Success Transaction added successfully. 
{
    "transaction_id": xxx,
    "transaction_serial": "YYY_ZZZZ",
    "creation_date_time": "yyy-mm-dd hh:MM:ss"
}
Failure Responses
400 Bad Request false Error Error message as elaborated here. 
{
    "error_code": xxx
}
500 Internal Server Error false Error Error message as elaborated here. 
{
    "error_code": xxx
}

Example 1

Request 
curl --request POST 'https://your_account.modulus.biz/api/csh/v1/Transaction=YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "account_code": "1.6.2.5",
    "account_exchange_rate": 50,
    "date": "2024-01-01",
    "cash_book_id": 4,
    "amount": 300,
    "transaction_type_code": "3",
    "counter_party": "Customer",
    "related_party": {
      "code": "1",
      "name": "Test name",
      "type": "individual",
      "account_code": "1.6.10.2",
      "price_list_code": "1",
      "tax_registration_number": "1",
      "contact": {
        "type": "mobile",
        "label": "القاهرة الجديدة",
        "value": "0102224791"
      },
      "address": {
        "label": "HEADOFFICE",
        "country_code": "EG",
        "city": "Alexandria",
        "address": "Test Address"
      }
    },
    "party_exchange_rate": 20,
    "reference": "Test Reference",
    "description": "Test Description"
  }'
200 OK 
{
    "result": true,
    "title": "Success",
    "message": "Transaction added successfully",
    "object": {
      "transaction_id": 631,
      "transaction_serial": "RCT-2024-0055",
      "creation_date_time": "2024-05-01 13:48:43"
    }
  }

Example 2

Request 
curl --request POST 'https://your_account.modulus.biz/api/csh/v1/Transaction=YOUR_TOKEN' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "account_code": "1.6.4.2",
    "date": "2024-9-26",
    "amount": 1000.00,
    "cash_book_id": 26,
    "counter_party": "Customer",
    "transaction_type_code": "1",
    "reference": "Test Reference",
    "description": "Test Description",
    "related_party":{
        "code":"20",
        "account_code":"1.6.10.2",
        "price_list_code":"1",
        "name":"Test Customer",
        "tax_registration_number":"",
        "type": "individual",
        "contact":{
            "type": "mobile",
            "label": "القاهرة الجديدة",
            "value": "1"
        },
        "address": {
            "label": "HEADOFFICE",
            "country_code": "EG", 
            "city": "Alexandria", 
            "address": "Test Address"
        }
    }
  }'
400 Bad Request 
{
    "result": false,
    "title": "Error",
    "message": "Invalid Currency",
    "object": {
      "error_code": "5609"
    }
  }