--- updatedAt: 2026-04-22T22:43:18.000Z agentTools: projectIndex: https://developers.akahu.nz/llms.txt --- # Make a payment Initiate a payment from the user's connected bank account to another New Zealand bank account. The payee bank account is not required to be connected to Akahu. 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}}" }, "ContentType": { "name": "Content-Type", "in": "header", "schema": { "type": "string" }, "example": "application/json" } }, "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": { "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": { "post": { "tags": [ "Payments" ], "summary": "Make a payment", "security": [ { "user_token": [] } ], "description": "Initiate a payment from the user's connected bank account to another New Zealand bank account.\n\nThe payee bank account is not required to be connected to Akahu.\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)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "from", "to", "amount" ], "properties": { "from": { "type": "string", "description": "The Akahu Account ID you want to pay from", "example": "acc_1111111111111111111111111" }, "to": { "type": "object", "description": "Account details specifying who you'd like to pay to", "properties": { "name": { "type": "string", "description": "The name of the person or company you want to pay", "example": "Sammy Sample" }, "account_number": { "type": "string", "description": "The NZ bank account number you want to pay", "example": "01-2345-6789012-00" } } }, "amount": { "type": "number", "description": "The payment amount", "example": 9.5 }, "meta": { "type": "object", "description": "Metadata relating to the payment including references for both `source` (from) and `destination` (to).\n\nFor more details check out the [📚 Payment PCR Fields guide](/docs/making-a-payment#payment-pcr-fields).", "properties": { "source": { "type": "object", "properties": { "code": { "type": "string", "description": "The `Code` field on the source statement", "example": "code" }, "reference": { "type": "string", "description": "The `Reference` field on the source statement", "example": "reference" } } }, "destination": { "type": "object", "properties": { "particulars": { "type": "string", "description": "The `Particulars` field on the destination statement. Including this field will disable [📖 arrival tracking](/docs/making-a-payment#payment-arrival-tracking) on this payment." }, "code": { "type": "string", "description": "The `Code` field on the destination statement", "example": "code" }, "reference": { "type": "string", "example": "reference", "description": "The `Reference` field on the destination statement" } } } } } } } } } }, "parameters": [ { "$ref": "#/components/parameters/xAkahuId" }, { "$ref": "#/components/parameters/ContentType" } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "item": { "$ref": "#/components/schemas/Payment" }, "item_id": { "type": "string", "example": "payment_1111111111111111111111111", "deprecated": true, "description": "⚠️ **Deprecated**\nThe Akahu Payment ID replaced via `item._id`" }, "status": { "type": "string", "example": "READY", "deprecated": true, "description": "⚠️ **Deprecated**\nThe Akahu Payment status replaced via `item.status`" } } } } } }, "400": { "description": "Your request was malformed or otherwise unacceptable. The `message` key in the response will give more details.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "message": { "type": "string" } } }, "examples": { "invalid_pcr": { "summary": "Invalid PCR Characters", "description": "Unsupported characters were supplied for the particulars, code or reference. These fields only support [A-Z][a-z][0-9]-_ and spaces.", "value": { "success": false, "message": "Invalid characters in `meta.source.code`" } }, "hit_app_limit": { "summary": "Payment Above App Limit", "description": "This payment is higher than your app's payment limit.", "value": { "success": false, "message": "Payment above app limit" } }, "hit_daily_limit": { "summary": "Payment Above Daily Limit", "description": "Payment above app daily limit.", "value": { "success": false, "message": "Payment above app daily limit" } }, "unable_to_pay": { "summary": "Source Unable To Pay", "description": "The source account is unable to make payments (eg. some savings accounts, kiwisavers, etc.).", "value": { "success": false, "message": "from account is unable to make payments" } } } } } }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "500": { "$ref": "#/components/responses/500" } } } } } } ```