Transactions

Transactions involve shifting amounts from one account to another.

Attribute

Description

amount

The amount to transfer from the sender account.

reference

A reference for the transaction.

Relationship

Description

sender

The account to send this transaction from.

recipient

The account to send this transaction to.

List transactions

get

Authorizations

Query parameters

filter[account]stringOptional

Filter all transactions where either the sender or recipient is a specific account ID.

Example: a1b2c3d4e5

filter[sender]stringOptional

Filter all transactions where the sender is a specific account ID.

Example: a1b2c3d4e5

filter[recipient]stringOptional

Filter all transactions where the recipient is a specific account ID.

Example: a1b2c3d4e5

filter[reference]stringOptional

Filter all transactions where the reference contains a specific substring.

Example: hello-world

page[page]integerOptional

Set the page number of resources to return.

Default: 1

page[limit]integer · max: 100Optional

Set the maximum number of resources to return.

Default: 20

Responses

200

List of Transactions

application/json

401

The request is not authenticated

application/json

403

The request is authenticated but not authorised to perform this action.

application/json

500

An error occurred

application/json

get

GET /transactions HTTP/1.1
Host: api.testbank.dev
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": [
    {
      "type": "transactions",
      "id": "c3d4e5f6g7",
      "attributes": {
        "amount": "100.00",
        "reference": "text"
      },
      "relationships": {
        "sender": {
          "data": {
            "type": "accounts",
            "id": "a1b2c3d4e5"
          }
        },
        "recipient": {
          "data": {
            "type": "accounts",
            "id": "a1b2c3d4e5"
          }
        }
      },
      "meta": {
        "exchangeRate": 1,
        "createdAt": "2023-07-12T19:00:00.000Z"
      }
    }
  ],
  "meta": {
    "prev": "/resource?page[count]=2&page[limit]=100",
    "next": "/resource?page[count]=4&page[limit]=100",
    "first": "/resource?page[count]=1&page[limit]=100",
    "last": "/resource?page[count]=10&page[limit]=100"
  }
}

Create transaction

post

Authorizations

Body

Responses

200

Created transaction

application/json

401

The request is not authenticated

application/json

403

The request is authenticated but not authorised to perform this action.

application/json

404

Resource not found

application/json

500

An error occurred

application/json

post

POST /transactions HTTP/1.1
Host: api.testbank.dev
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 217

{
  "data": {
    "type": "transactions",
    "attributes": {
      "amount": "100.00",
      "reference": "text"
    },
    "relationships": {
      "sender": {
        "data": {
          "type": "accounts",
          "id": "a1b2c3d4e5"
        }
      },
      "recipient": {
        "data": {
          "type": "accounts",
          "id": "a1b2c3d4e5"
        }
      }
    }
  }
}

{
  "data": {
    "type": "transactions",
    "id": "c3d4e5f6g7",
    "attributes": {
      "amount": "100.00",
      "reference": "text"
    },
    "relationships": {
      "sender": {
        "data": {
          "type": "accounts",
          "id": "a1b2c3d4e5"
        }
      },
      "recipient": {
        "data": {
          "type": "accounts",
          "id": "a1b2c3d4e5"
        }
      }
    },
    "meta": {
      "exchangeRate": 1,
      "createdAt": "2023-07-12T19:00:00.000Z"
    }
  }
}

You cannot edit or delete a transaction after created.

Get transaction by ID

get

Authorizations

Path parameters

transactionIdstringRequired

Transaction ID

Example: c3d4e5f6h7

Responses

200

Found transaction

application/json

401

The request is not authenticated

application/json

403

The request is authenticated but not authorised to perform this action.

application/json

404

Resource not found

application/json

500

An error occurred

application/json

get

GET /transactions/{transactionId} HTTP/1.1
Host: api.testbank.dev
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": {
    "type": "transactions",
    "id": "c3d4e5f6g7",
    "attributes": {
      "amount": "100.00",
      "reference": "text"
    },
    "relationships": {
      "sender": {
        "data": {
          "type": "accounts",
          "id": "a1b2c3d4e5"
        }
      },
      "recipient": {
        "data": {
          "type": "accounts",
          "id": "a1b2c3d4e5"
        }
      }
    },
    "meta": {
      "exchangeRate": 1,
      "createdAt": "2023-07-12T19:00:00.000Z"
    }
  }
}

Examples

Crediting your account

You can credit your account by specifying "ROOT" as the sender account ID, and one of your accounts as the recipient.
This is a Create event, similar to minting new coin, where you receive "funds" from nothing.
Yes, you can credit your account insane amounts (but it's not real!).

POST /transactions HTTP/1.1
Content-Type: application/json
{
  "data": {
    "type": "transactions",
    "attributes": {
      "amount": "100.00",
      "reference": "Opening account"
    },
    "relationships": {
      // Specify ROOT as the sender
      "sender": { "data": { "type": "accounts", "id": "ROOT" } },
      // Specify one of your accounts as the recipient
      "recipient": { "data": { "type": "accounts", "id": "a1b2c3d4e5" } }
    },
    "meta": {
      "externalId": "b20e7841-39f4-4581-b858-c023c51ab463"
    }
  }
}

HTTP/1.1 201 Created
Content-Type: application/json
{
  "data": {
    "type": "transactions",
    "id": "01H5B3X62ENSWZBV0ZNXW7H9A4",
    "attributes": {
      "amount": "100.00",
      "reference": "Opening account"
    },
    "relationships": {
      "sender": { "data": { "type": "accounts", "id": "ROOT" } },
      "recipient": { "data": { "type": "accounts", "id": "a1b2c3d4e5" } }
    },
    "meta": {
      "externalId": "b20e7841-39f4-4581-b858-c023c51ab463"
    }
  }
}

Emptying your account

You can empty your account by specifying "ROOT" as the recipient account ID.
This is a Destroy event, where you send "funds" into nothing.

POST /transactions HTTP/1.1
Content-Type: application/json
{
  "data": {
    "type": "transactions",
    "attributes": {
      "amount": "100.00",
      "reference": "Closing account"
    },
    "relationships": {
      // Specify one of your accounts as the sender
      "sender": { "data": { "type": "accounts", "id": "a1b2c3d4e5" } },
      // Specify ROOT as the recipient
      "recipient": { "data": { "type": "accounts", "id": "ROOT" } }
    },
    "meta": {
      "externalId": "b20e7841-39f4-4581-b858-c023c51ab463"
    }
  }
}

HTTP/1.1 201 Created
Content-Type: application/json
{
  "data": {
    "type": "transactions",
    "id": "01H5B3X62ENSWZBV0ZNXW7H9A4",
    "attributes": {
      "amount": "100.00",
      "reference": "Closing account"
    },
    "relationships": {
      "sender": { "data": { "type": "accounts", "id": "ROOT" } },
      "recipient": { "data": { "type": "accounts", "id": "a1b2c3d4e5" } }
    },
    "meta": {
      "externalId": "b20e7841-39f4-4581-b858-c023c51ab463"
    }
  }
}

Transfer between 2 accounts

You can transfer funds between 2 accounts by specifying the relevant recipient account ID.

POST /transactions HTTP/1.1
Content-Type: application/json
{
  "data": {
    "type": "transactions",
    "attributes": {
      "amount": "100.00",
      "reference": "Lunch money"
    },
    "relationships": {
      // Specify one of your accounts as the sender
      "sender": { "data": { "type": "accounts", "id": "a1b2c3d4e5" } },
      // Specify another of your accounts as the sender
      "recipient": { "data": { "type": "accounts", "id": "f6g7h8i9j0" } }
    },
    "meta": {
      "externalId": "b20e7841-39f4-4581-b858-c023c51ab463"
    }
  }
}

HTTP/1.1 201 Created
Content-Type: application/json
{
  "data": {
    "type": "transactions",
    "id": "01H5B3X62ENSWZBV0ZNXW7H9A4",
    "attributes": {
      "amount": "100.00",
      "reference": "Lunch money"
    },
    "relationships": {
      "sender": { "data": { "type": "accounts", "id": "a1b2c3d4e5" } },
      "recipient": { "data": { "type": "accounts", "id": "a1b2c3d4e5" } }
    },
    "meta": {
      "externalId": "b20e7841-39f4-4581-b858-c023c51ab463"
    }
  }
}

You can transfer from any of your accounts.
You can transfer to any of your accounts, or any public/unlisted account.

As of now, you cannot transfer between accounts of different currencies.

Currency conversion will be addressed in a future version of this API.

PreviousAccounts NextStatic

Last updated 2 years ago