Skip to content

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:

{ // IOU object
}

Response body:

{
    "success": true
}

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:

{
    "success": true,
    "payload": [ // array of IOU objects
     ],
 }

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:

{
    "success": true,
    "payload": [ // array of IOU objects
     ],
 }

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:

{
    "success": true 
}

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:

{
    "success": true 
}

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.