Transactions

Introduction

The transactions API call is used to get all the transactions in a given time frame.

List Transactions

This API will retrieve a list of transactions.

Path
`GET` `/transactions`

Query Parameters:

Parameter	Example
start_date	yyyy-mm-dd
end_date	yyyy-mm-dd

Please note this API will only pull data through for a given agent set in the API Key settings

Response:

{
    "status": true,
    "total": 30862,
    "records": [
        {
            "transaction_number": "c2e8dfd5-5cb8-46f7-dede-8c96df15df1f",
            "amount": "150.00",
            "status": "Paid",
            "transaction_date": "2023-11-04T00:00:00.000Z",
            "id_number": "8812345678901",
            "company_name": "",
            "response_reason": "",
            "reference_number": "B457",
            "member_number": "MEM450045",
            "workflow_reference": "1234-1234"
        },
        ...
    ]
}

Fields:

Name	Example	Description
transaction_number	c2e8dfd5-5cb8-46f7-dede-8c96df15df1f	System generated transaction number
amount	150.00	Transaction Amount
status	Paid	Please see list below of statuses
transaction_date	2023-11-04T00:00:00.000Z	Date the transaction occurred
id_number	8812345678901	ID number of person associated to the transaction
company_name	Inc Corp	Company name associated to the transaction
response_reason	Transaction Disputed	Description of reason transaction was declined
reference_number	B457	Reference number of transaction assigned, can be statement reference too
member_number	MEM450045	Customer or member number assigned to person or company
workflow_reference	1234-1234	Referenced passed through from contact centre

Transactions Statuses:

Pending
Generated
Unpaid
Updated/Pending
Transmission Accepted
Transmission Rejected
Account Type Corrected
Redirected
Paid
Sent
Undelivered
Reversed
Transmission Accepted (with warnings)
Unpaid (Permanent Failure)

All lookup values can be found under: Lookups API

Error Response:

{
    "status": false,
    "error": "Not authorized to make this API call. Requesting Read on General."
}

When you get this API response ensure that under the API keys section your API Key has the correct permissions: API Keys

Get Transaction Details

View transactions by user id or public id. All lookup values can be found under: Lookups API

Path
`GET` `/transactions/{people record_id\|companies record_id\|people public_id\|companies public_id}`

Success Response:

{
    "status": true,
    "records": [{
        "id": "{unique record_id}",
        "people_id": "{people record_id}",
        "companies_id": "{companies record_id}",
        "transaction_id": "{custom transaction id}",
        "transaction_time": "YYYY-MM-DD HH:mm:ss",
        "transaction_reference": "{reference as seen on bank statements}","transaction_status_lookups_id": "5c4a9234-c5f4-4bab-9868-b1120df89d96",
        "amount": "100.25",
        "is_debit": true,
        "payment_methods_id": "{payment_methods record_id}",
        "subscriptions_id": "{subscriptions record_id}",
        "cards_id": "{cards record_id}",
        "bank_accounts_id": "{bank_accounts record_id}",
        "interval_lookups_id": "04f6c27d-1eba-4ef1-a023-3baa79cff571",
        "response_reason": "Auth Done",
        "response_code": "990017",
        "response_raw": "{json body of 3rd party payments}",
        "is_reversed": false,
        "is_dispute": false,
        "notes": "notes about this subscription",
        "batches_accounts_id": "{batches_accounts record_id}",
        "documents_id": "{documents id}",
        "fee": "{fee amounts applicable to 3rd party payments}","accounts_currencies_id": "{accounts_currencies record_id}",
        "date_status_updated": "{date payment status updated YYYY-MM-DD HH:mm:ss}"
    }, ...]
}

Field	Type	Description	Options	Example
status	boolean	true - API request was a success, false - API request failed
records	Array of Objects	Transaction records
records .id	string	Unique ID associated with the record	UUID	"{unique record_id}"
records .people_id	string	People ID associated with the transaction	UUID	"{people record_id}"
records .companies_id	string	Companies ID associated with the transaction	UUID	"{companies record_id}"
records .transaction_id	string	Custom ID provided to the transaction		ABC123
records .transaction_time	datetime	At what date and time this transaction took place	"YYYY-MM-DD HH:mm:ss"	2024-09-01 17:15:34
records .transaction_reference	string	Reference number as seen on bank statements		TST24090100001
transaction_status_lookups_id	string	Status lookups ID of the transaction	UUID	"5c4a9234-c5f4-4bab-9868-b1120df89d96"
records .amount	decimal	Amount that was paid during the transaction		100.25
records .is_debit	boolean	If this transaction was debited from the person/company's account	true, false	true
records .payment_methods_id	string	Payment Methods ID related to the transaction	UUID	"{payment_methods record_id}"
records .subscriptions_id	string	Subscription ID related to the transaction	UUID	"{subscriptions record_id}"
records .cards_id	string	Cards ID related to the transaction	UUID	"{cards record_id}"
records .bank_accounts_id	string	Bank accounts ID related to the transaction	UUID	"{bank_accounts record_id}"
records .interval_lookups_id	string	Interval lookups ID of the transaction	UUID	"04f6c27d-1eba-4ef1-a023-3baa79cff571"
records .response_reason	string	Reason for the payment status (if applicable)		"Auth Done"
records .response_code	string	Response code related to the response reason (if applicable)		"990017"
records .response_raw	String	Raw response received by the payment method (if applicalbe)	max 8192 characters	"{json body of 3rd party payments}"
records .is_reversed	boolean	true - if this transaction payment has been reversed	true, false	false
records .is_dispute	boolean	true - if this transaction has been disputed at the bank	true, false	false
records .notes	string	Notes associated with this transaction		"some notes about this subscription"
records .batches_accounts_id	string	Batch Account ID associated with this transaction	UUID	"{batches_accounts record_id}"
records .documents_id	string	Documents ID associated with this transaction, if a document was uploaded along with this transaction	UUID	"{documents id}"
records .fee	decimal	Fee paid to the payment method (if applicable)		3.24
records .accounts_currencies_id	string	Account currency associated with this transaction	UUID	"{accounts_currencies record_id}"
records .date_status_updated	date	When the payment status of this transaction changed	"YYYY-MM-DD HH:mm:ss"	"2024-09-01 14:34:23"

Get Transactions by ID

Retrieve one or more transactions by their transaction record IDs.

Path
`GET` `/transactions/get`

Query Parameters:

Parameter	Example	Note
transaction_ids	{transaction record_id},{transaction record_id}	Required. Comma separated list of transaction record IDs

Success Response:

The response is a JSON array of transactions (without a status wrapper).

[
    {
        "id": "{unique record_id}",
        "created_at": "2024-09-01T15:15:34.000Z",
        "updated_at": "2024-09-01T15:15:34.000Z",
        "deleted_at": null,
        "accounts_id": "{accounts record_id}",
        "transaction_id": "ABC123",
        "transaction_time": "2024-09-01T15:15:34.000Z",
        "transaction_reference": "TST24090100001",
        "status": "Paid",
        "currency": "ZAR",
        "amount": "100.25",
        "is_debit": true,
        "abbreviated_name": "SWITCH",
        "bank_reference": "SWITCH DEBIT",
        "batch_reference_code": "B457",
        "provider": "DebitSwitch",
        "subscriptions_id": "{subscriptions record_id}",
        "card_number_obfuscated": null,
        "branch_code": "632005",
        "account_name": "J Doe",
        "account_number": "xxxxxxxx11",
        "interval": "Monthly",
        "document_number": "INV0001",
        "response_reason": "Auth Done",
        "response_code": "990017",
        "is_reversed": false,
        "is_dispute": false,
        "notes": "notes about this transaction"
    },
    ...
]

Field	Type	Description	Example
id	string	Unique ID of the transaction	"{unique record_id}"
created_at	datetime	When the transaction record was created	"2024-09-01T15:15:34.000Z"
updated_at	datetime	When the transaction record was last updated	"2024-09-01T15:15:34.000Z"
deleted_at	datetime	When the transaction record was deleted, null if not deleted	null
accounts_id	string	Account ID the transaction belongs to	"{accounts record_id}"
transaction_id	string	Custom ID provided to the transaction	"ABC123"
transaction_time	datetime	At what date and time this transaction took place	"2024-09-01T15:15:34.000Z"
transaction_reference	string	Reference number as seen on bank statements	"TST24090100001"
status	string	Status title of the transaction	"Paid"
currency	string	Currency code of the transaction, defaults to ZAR	"ZAR"
amount	decimal	Amount of the transaction	"100.25"
is_debit	boolean	If this transaction was debited from the person/company's account	true
abbreviated_name	string	Abbreviated name of the payment method	"SWITCH"
bank_reference	string	Bank statement reference of the payment method	"SWITCH DEBIT"
batch_reference_code	string	Batch reference code of the payment method	"B457"
provider	string	Payment provider of the payment method	"DebitSwitch"
subscriptions_id	string	Subscription ID related to the transaction	"{subscriptions record_id}"
card_number_obfuscated	string	Obfuscated card number, if paid by card	"4111 xxxx xxxx 1111"
branch_code	string	Branch code of the bank account, if paid by debit order	"632005"
account_name	string	Name on the bank account	"J Doe"
account_number	string	Bank account number with all but the last 20% of the digits masked	"xxxxxxxx11"
interval	string	Interval title of the transaction	"Monthly"
document_number	string	Finance document number linked to the transaction	"INV0001"
response_reason	string	Reason for the payment status (if applicable)	"Auth Done"
response_code	string	Response code related to the response reason (if applicable)	"990017"
is_reversed	boolean	true - if this transaction payment has been reversed	false
is_dispute	boolean	true - if this transaction has been disputed at the bank	false
notes	string	Notes associated with this transaction	"notes about this transaction"

Validation Error Response:

{
    "status": false,
    "error": "input validation failed",
    "errors": {
        "transaction_ids": {
            "message": "The transaction ids field is mandatory.",
            "rule": "required"
        }
    }
}

Error Response:

{
    "status": false,
    "error": "Not authorized to make this API call. Requesting Read on General."
}

When you get this API response ensure that under the API keys section your API Key has the correct permissions: API Keys

Companies

General Companies API documentation

Forms

General Forms API documentation