--- updatedAt: 2026-04-22T22:43:18.000Z agentTools: projectIndex: https://developers.akahu.nz/llms.txt --- # List payments Get a list of the payments that your application has initiated on behalf of the user within the `start` and `end` time range. >ī¸ ℹī¸ Time range defaults to the last 30 days. For more details about payments see: - [📖 Making a payment guide](/docs/making-a-payment) - [📚 Payment lifecycle guide](/docs/making-a-payment#payment-lifecycle) - [📚 Payment webhooks](/docs/reference-webhooks#payment) # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "Akahu Enduring API", "description": "This API is the primary way for apps to interact with a user's data.", "version": "1.0.0" }, "servers": [ { "url": "https://api.akahu.io/v1" } ], "components": { "parameters": { "xAkahuId": { "name": "X-Akahu-Id", "in": "header", "required": true, "description": "Your **App ID Token**.", "schema": { "type": "string" }, "example": "{{app_token}}" } }, "securitySchemes": { "user_token": { "type": "http", "scheme": "bearer", "description": "User-level Authentication:\n\nHttp Bearer Auth with the token being a consented **User Access Token**.\n> `Bearer {user_token}`\n\nThis will allow you to act on a **user's** behalf when accessing the API." } }, "responses": { "400": { "description": "Your request was malformed or otherwise unacceptable. More details are provided under the `message` key in the response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Invalid Content-Type" } } } } } }, "401": { "description": "You are not authorised to access this content.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Permission Denied" } } } } } }, "403": { "description": "You are not allowed to access this content.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Forbidden" } } } } } }, "500": { "description": "An internal error has prevented us from processing the request. More detail may be supplied in the `message` key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Something went wrong" } } } } } } }, "schemas": { "Payment": { "type": "object", "properties": { "_id": { "type": "string", "description": "The Akahu Payment ID", "example": "payment_1111111111111111111111111" }, "from": { "type": "string", "description": "The Akahu Account ID of the source account", "example": "acc_1111111111111111111111111" }, "to": { "type": "object", "description": "Information about who this payment is to", "properties": { "account_number": { "type": "string", "description": "The NZ bank account number to whom this payment is made", "example": "12-1234-1234567-12" }, "name": { "type": "string", "description": "The name of the account holder of the destination account", "example": "John Smith", "pattern": "^[A-Za-z0-9 \\-_]*$" } } }, "amount": { "type": "number", "format": "decimal", "multipleOf": 0.01, "description": "How much money the payment is for", "example": 9.51 }, "meta": { "type": "object", "description": "Payment metadata that you have specified", "properties": { "destination": { "type": "object", "description": "Metadata that will appear in the destination account", "properties": { "particulars": { "type": "string", "description": "The particulars you have specified for the destination account", "example": "destPart", "pattern": "^[A-Za-z0-9 \\-_]*$" }, "code": { "type": "string", "description": "The code you have specified for the destination account", "example": "destCode", "pattern": "^[A-Za-z0-9 \\-_]*$" }, "reference": { "type": "string", "description": "The reference you have specified for the destination account", "example": "destRef", "pattern": "^[A-Za-z0-9 \\-_]*$" } } }, "source": { "type": "object", "description": "Metadata that will appear in the source account", "properties": { "code": { "type": "string", "description": "The code you have specified for the source account", "example": "sourceCode", "pattern": "^[A-Za-z0-9 \\-_]*$" }, "reference": { "type": "string", "description": "The reference you have specified for the source account", "example": "sourceRef", "pattern": "^[A-Za-z0-9 \\-_]*$" } } } } }, "sid": { "type": "string", "description": "Akahu's unique ID inserted into the particulars field", "example": "akp111111111" }, "status": { "type": "string", "example": "READY", "enum": [ "READY", "SENT", "PAUSED", "DECLINED", "CANCELLED", "ERROR" ], "description": "Status of the payment:\n- `READY` → Initial state payment is ready to be processed.\n\n- `SENT` → Payment initiated with the user's bank and we've received confirmation that it has been accepted.\n\n- `PAUSED` → Payment is not yet ready to be processed.\n\n- `DECLINED` → Payment has been declined by the user's bank.\n\n- `CANCELLED` → Payment was cancelled.\n\n- `ERROR` → Internal Akahu error occurred.\n\nFor more details see:\n - [📚 Payments guide](/docs/making-a-payment)\n - [📚 Payments lifecycle guide](/docs/making-a-payment#payment-lifecycle)" }, "status_text": { "type": "string", "description": "If available, more information about the payment's staus", "example": "This payment has just been created and is ready to be sent" }, "final": { "type": "boolean", "description": "If this payment has reached it's final state", "example": false }, "timeline": { "type": "array", "description": "A timeline of events regarding this payment", "items": { "type": "object", "description": "A timeline event", "properties": { "status": { "type": "string", "description": "The payment's status at this time", "example": "READY" }, "time": { "type": "string", "format": "date-time", "description": "An ISO 8701 timestamp of when this event was created", "example": "2020-01-01T01:00:00.000Z" }, "eta": { "type": "string", "format": "date-time", "description": "An ISO 8701 timestamp of when Akahu expects the payment to arrive. Only present on events for `SENT` statuses.", "example": "2020-01-01T01:00:00.000Z" } } } }, "created_at": { "type": "string", "format": "date-time", "description": "An ISO 8701 timestamp of when this payment was created", "example": "2020-01-01T01:00:00.000Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "An ISO 8701 timestamp of when this payment was last updated by Akahu", "example": "2020-01-01T01:00:00.000Z" }, "received_at": { "type": "string", "format": "date-time", "description": "An ISO 8701 timestamp of when this payment was received by the destination account. This field will only be populated if the destination account is connected to Akahu.", "example": "2020-01-01T01:00:00.000Z" } } } } }, "tags": [ { "name": "Payments" } ], "paths": { "/payments": { "get": { "tags": [ "Payments" ], "summary": "List payments", "security": [ { "user_token": [] } ], "description": "Get a list of the payments that your application has initiated on behalf of the user within the `start` and `end` time range.\n\n>ī¸ ℹī¸ Time range defaults to the last 30 days.\n\nFor more details about payments see:\n - [📖 Making a payment guide](/docs/making-a-payment)\n - [📚 Payment lifecycle guide](/docs/making-a-payment#payment-lifecycle)\n - [📚 Payment webhooks](/docs/reference-webhooks#payment)", "parameters": [ { "$ref": "#/components/parameters/xAkahuId" }, { "name": "start", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 Date", "example": "2020-01-01T01:00:00.000Z" }, { "name": "end", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 Date", "example": "2020-02-01T01:00:00.000Z" } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } } } } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "500": { "$ref": "#/components/responses/500" } } } } } } ```