IOUs
IOUs are promissory notes from one user (the borrower) to make a specified payment to another user (the lender).
There can be at most one IOU for a specific pair of users. If a new IOU is registered for an existing pair, it is used to adjust the balance on the existing IOU.
If an IOU is registered by a user who is not the lender, it must be approved by the lender before being accepted.
IOU Object
An IOU is represented as a JSON object. This table specifies the properties that may be included in this object:
Property | Type | Required? (default) | Description |
---|---|---|---|
borrowerAFiUserId | string | yes | AmpliFi Id of the borrower (debtor) |
lenderAFiUserId | string | yes | AmpliFi Id of the lender (creditor) |
amount | number | yes | amount owed |
currency | string | yes | 3-letter currency code for the amount |
narrativeDebit | string | no (none) | description of the debit (for the borrower) |
narrativeCredit | string | no (none) | description of the credit (for the lender) |
narrative | string | no (none) | optional alternative to separate narratives |
attachments | object | no (none) | object to contain any attachments |
images | array | no (none) | array of binary images, if any |
isPending | boolean | no (false) | true if IOU requires borrower's approval |
Register IOU
POST /iou
Create and register a new IOU and an IOU transaction representing an amount owed by one user (the borrower) to another (the lender). This may be a new IOU for this pair of users. Alternately, it may adjust the balance for an IOU that is already registered.
Request body:
Response body:
List IOUs for specified user
GET /ious/for/:AFiUserId
List all IOUs that the specified user is a party to. This includes both debits and credits.
Response body:
List IOUs for current user
GET /ious
List all IOUs that the current user is a party to. This includes both debits and credits.
Response body:
Get IOU for a Pair of Users
GET /ious/for/:AFiUserId
Get an IOU between the current user and a specified user, if one exists. The creditor id is given as a path parameter. The current user is the debtor.
Response body example:
{
"success": true,
"payload": { // partial IOU object
"debitAFiUserId": "abcde",
"creditAFiUserId": "vwxyz",
"amount": 100,
"currency": "USD",
"narrative": " ",
"transactions": [
]
}
}
Approve an IOU
POST /iou/:IOUTransactionId/approve
Approve a pending IOU transaction. Used by a lender to agree to lend the requested amount. The lender must be the current user. The amount is added to the borrower's balance.
Response body:
Decline an IOU
POST /iou/:IOUTransactionId/decline
Decline a pending IOU transaction. Used by a lender to decline to lend the requested amount. No balances are changed. The transaction becomes inactive.
Response body:
Pay an IOU
POST /iou/:IOUTransactionId/pay
Make a payment on an IOU transaction. Used by the borrower to pay back a specified amount. THe amount may be less than or equal to the amount of the IOU.
The payment is taken from the borrower's main account. If the avaiable funds are not sufficient a partial payment is made. If the IOU is paid in full, the transaction is deleted.