Transactions are a way to manage balance changes on accounts in the Rehive platform. Every transaction can be either a debit or a credit. In simple terms debit transactions reduce an account’s balance and credit transactions increases an account’s balance. A transfer can be thought of as a 2-step transaction where one user is debited and another is credited the same amount simultaneously.
Every transaction has a status that can be used to gauge the state of the transaction. The statuses are:
| status | description |
|---|---|
| Initiating | the transaction is processing immediately after insert. |
| Pending | the transaction has passed all validation amd applied to the account’s available balance if a debit transaction. |
| Complete | the transaction has been executed applied to the account’s balance. |
| Failed | the transaction has been executed but did not succeed and had no impact on the account’s balance. |
Transactions are immutable once executed in Rehive. This means that once a transaction has reached an executed status of Complete or Failed they cannot be further modified in the system. To reverse a transaction’s balance changes once it has executed you should create another transaction instead.
Transactions can be made by both admin users and end-users. However, end-users are not permitted to alter the status of a transaction. Only admins have permission to make changes to transactions.
Object
Transactions are basically a series of logs recording actions on an account balance. With this in mind, transactions contain information that can be used to identify who made the transaction, what account and user the transaction was made on, and how the transaction impacted the balance of an account.
A full transaction object looks like:
{
"id": "00000000-0000-0000-0000-000000000000",
"collection": "00000000-0000-0000-0000-000000000000",
"parent": null,
"partner": null,
"inferred": false,
"tx_type": "credit",
"subtype": null,
"note": "",
"metadata": {},
"status": "Complete",
"reference": "",
"amount": 500,
"total_amount": 500,
"balance": 0,
"account": "0000000000",
"label": "Credit",
"currency": {
"code": "USD",
"description": "United States dollar",
"symbol": "$",
"unit": "dollar",
"divisibility": 2,
},
"user": {
"id": "00000000-0000-0000-0000-000000000000",
"first_name": "Joe",
"last_name": "Soap",
"email": "[email protected]",
"username": null,
"mobile": "+27840000000",
"profile": null
},
"messages": [],
"archived": false,
"created": 1476691969394,
"updated": 1496135465287
}
A debit transaction will look much the same as the above, except the amount will be a negative value and the tx_type will be debit.
On the other hand, a transfer will have some additional information in the partner attribute. As stated previously, transfers are simply debits/credits themselves. So, if a transfer is made between two accounts then two transactions will be created:
- A debit transaction reducing the balance of the sender. In addition the
partnerattribute will be populated with a pointer to the receiver transaction. - A credit transaction increasing the balance of the receiver. In addition the
partnerattribute will be populated with a pointer to the sender transaction.
Endpoints
Take a look at the Platform API Reference for the list of transaction endpoints.
Take a look at the Platform Admin API Reference for the list of transaction management endpoints.
Usage
Usage remains the same for all endpoints in Rehive. Simply invoke one of the allowed HTTP methods with the correct Content-Type and an Authorization header.
When creating transactions and supplying a custom id, that id must be a version 4 UUID and there must be no other transactions in the system with the same id.