--- updatedAt: 2026-04-30T03:13:44.000Z agentTools: projectIndex: https://developers.akahu.nz/llms.txt --- # Get one-off payment # OpenAPI definition ```json { "info": { "title": "Akahu One-Off Payments API", "version": "1.0.0" }, "servers": [ { "description": "Akahu One-off Payments API", "url": "https://api.payments.akahu.io" } ], "x-readme": { "apply-endpoint-order": true }, "openapi": "3.1.0", "components": { "schemas": { "OneOffPaymentId": { "type": "string", "pattern": "^one_off_payment_[a-z0-9]{25,27}$", "example": "one_off_payment_c01234567890123456789012345" }, "Generic400ErrorResponseCode": { "type": "string", "enum": [ "invalid", "invalid_id", "not_found", "bad_request", "invalid_type", "invalid_literal", "invalid_union", "invalid_union_discriminator", "invalid_enum_value", "unrecognized_keys", "invalid_arguments", "invalid_return_type", "invalid_date", "invalid_string", "too_small", "too_big", "invalid_intersection_types", "not_multiple_of", "not_finite" ] }, "IssuePath": { "type": "array", "items": { "title": "IssuePathSegment", "oneOf": [ { "type": "string" }, { "type": "number" } ] } }, "Generic401ErrorResponseCode": { "type": "string", "enum": [ "unauthorized" ] }, "Generic401ErrorResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/Generic401ErrorResponseCode" }, "message": { "type": "string" }, "path": { "$ref": "#/components/schemas/IssuePath" } }, "required": [ "code", "message", "path" ] } } }, "required": [ "success", "message", "issues" ] }, "Generic403ErrorResponseCode": { "type": "string", "enum": [ "forbidden" ] }, "Generic403ErrorResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/Generic403ErrorResponseCode" }, "message": { "type": "string" }, "path": { "$ref": "#/components/schemas/IssuePath" } }, "required": [ "code", "message", "path" ] } } }, "required": [ "success", "message", "issues" ] }, "BankAccountNumber": { "type": "string", "pattern": "^\\d{2}-\\d{4}-\\d{7}-\\d{2,3}$", "description": "The bank account number of the payee", "example": "12-3456-7890123-00" }, "OneOffPaymentBank": { "type": "string", "enum": [ "anz", "asb", "bnz", "kiwibank", "nzhl", "westpac", "demo_bank" ], "description": "The bank the customer must use to make this payment" }, "OneOffPaymentRedirectMode": { "type": "string", "enum": [ "deep_link" ], "description": "The mode used by Akahu when redirecting the user to your provided `redirect_uri`.\nThis option is important for native mobile app developers.\n - `deep_link` → Specify this value if your provided `redirect_uri` intends to activate your native mobile application via iOS [universal link](https://developer.apple.com/documentation/xcode/allowing-apps-and-websites-to-link-to-your-content/) or Android [app link](https://developer.android.com/training/app-links/about). When you supply this value, the user will be required to tap to confirm before returning to your application. This interaction is important to ensure successful native app activation." }, "OneOffPaymentStatus": { "type": "string", "enum": [ "READY", "AUTHORISED", "SUBMITTED", "SENT", "CANCELLED", "FAILED" ], "description": "The status of the payment", "example": "SUBMITTED" }, "OneOffPaymentStatusCode": { "type": "string", "enum": [ "PENDING", "SETTLEMENT_IN_PROGRESS", "INTERNAL_ERROR", "BANK_ERROR", "BANK_ERROR_INDETERMINATE", "REJECTED", "TIMED_OUT", "USER_CANCELLED", "APP_CANCELLED" ], "description": "A more specific code for the payment status", "example": "PENDING" }, "OneOffPayment": { "type": "object", "properties": { "_id": { "$ref": "#/components/schemas/OneOffPaymentId" }, "status": { "$ref": "#/components/schemas/OneOffPaymentStatus" }, "status_reason": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/OneOffPaymentStatusCode" }, "message": { "type": "string", "description": "A human readable message about the status", "example": "The payment was submitted to the bank" } }, "required": [ "code", "message" ], "description": "If applicable, more details about the payment status" }, "created_at": { "type": "string", "format": "date-time", "description": "When the payment was created" }, "updated_at": { "type": "string", "format": "date-time", "description": "When the payment was last updated" }, "expires_at": { "type": "string", "format": "date-time", "description": "The payment will be cancelled at this time, unless it has been authorised" }, "submitted_at": { "type": "string", "format": "date-time", "description": "When the payment was submitted" }, "terminal_at": { "type": "string", "format": "date-time", "description": "When the payment reached a terminal status" }, "payee": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 70, "pattern": "^[A-Za-z0-9 '\\.,\\-_]*$", "description": "The name of the payee", "example": "John Smith" }, "account_number": { "$ref": "#/components/schemas/BankAccountNumber" }, "particulars": { "type": "string", "maxLength": 12, "pattern": "^[A-Za-z0-9 \\-_]*$", "description": "The Particulars field that will go on the payee's bank statement" }, "code": { "type": "string", "maxLength": 12, "pattern": "^[A-Za-z0-9 \\-_]*$", "description": "The Code field that will go on the payee's bank statement" }, "reference": { "type": "string", "maxLength": 12, "pattern": "^[A-Za-z0-9 \\-_]*$", "description": "The Reference field that will go on the payee's bank statement" } }, "required": [ "name", "account_number" ], "description": "The payee's details" }, "payer": { "type": "object", "properties": { "bank": { "$ref": "#/components/schemas/OneOffPaymentBank" }, "name": { "type": "string", "minLength": 2, "maxLength": 70, "pattern": "^[A-Za-z0-9 '\\.,\\-_]*$", "description": "The name of the payer", "example": "Jane Smith" }, "account_number": { "allOf": [ { "$ref": "#/components/schemas/BankAccountNumber" }, { "description": "The bank account number of the payer", "example": "12-3456-7890123-10" } ] }, "release_account_details": { "type": "boolean", "default": false, "description": "Request that the bank releases the payer's account details. These details will be populated in the `payer.name` and `payer.account_number` fields of the payment once available. Payer account release cannot be requested when the payer account number is specified as part of the initial payment request." }, "particulars": { "type": "string", "maxLength": 12, "pattern": "^[A-Za-z0-9 \\-_]*$", "description": "The Particulars field that will go on the payer's bank statement" }, "code": { "type": "string", "maxLength": 12, "pattern": "^[A-Za-z0-9 \\-_]*$", "description": "The Code field that will go on the payer's bank statement" }, "reference": { "type": "string", "maxLength": 12, "pattern": "^[A-Za-z0-9 \\-_]*$", "description": "The Reference field that will go on the payer's bank statement" } }, "description": "The payer's details" }, "amount": { "type": "number", "minimum": 0.01, "maximum": 1000000, "description": "The amount to be paid in dollars, e.g. 12.34. (Rounded to 2 decimal places).", "example": 12.34 }, "redirect_uri": { "type": "string", "format": "uri", "description": "The URI to redirect the user to after payment approval", "example": "https://myapp.com/payments/complete" }, "redirect_mode": { "$ref": "#/components/schemas/OneOffPaymentRedirectMode" }, "webhook_uri": { "type": "string", "format": "uri", "description": "The URI to send webhooks regarding updates to this payment", "example": "https://myapp.com/payments/webhooks" } }, "required": [ "_id", "status", "created_at", "updated_at", "payee", "amount", "redirect_uri" ], "description": "The current state of a payment" }, "Generic400ErrorResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/Generic400ErrorResponseCode" }, "message": { "type": "string" }, "path": { "$ref": "#/components/schemas/IssuePath" } }, "required": [ "code", "message", "path" ] } } }, "required": [ "success", "message", "issues" ] }, "Generic404ErrorResponseCode": { "type": "string", "enum": [ "not_found" ] }, "Generic404ErrorResponse": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ] }, "message": { "type": "string" }, "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/Generic404ErrorResponseCode" }, "message": { "type": "string" }, "path": { "$ref": "#/components/schemas/IssuePath" } }, "required": [ "code", "message", "path" ] } } }, "required": [ "success", "message", "issues" ] } } }, "paths": { "/v1/one-off-payments/{paymentId}": { "get": { "operationId": "GetOneOffPayment", "tags": [ "Payments" ], "summary": "Get one-off payment", "deprecated": false, "security": [ { "AppSecret": [] } ], "parameters": [ { "schema": { "$ref": "#/components/schemas/OneOffPaymentId" }, "required": true, "name": "paymentId", "in": "path" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OneOffPayment" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Generic400ErrorResponse" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Generic401ErrorResponse" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Generic403ErrorResponse" } } } }, "404": { "description": "Payment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Generic404ErrorResponse" } } } } } } } } } ```