{"info":{"title":"Akahu One-Off Payments API","version":"1.0.0"},"servers":[{"description":"Akahu One-off Payments API","url":"https://api.payments.akahu.io"}],"openapi":"3.1.0","components":{"schemas":{"OneOffPaymentId":{"type":"string","pattern":"^one_off_payment_[a-z0-9]{25,27}$","example":"one_off_payment_c01234567890123456789012345"},"OneOffPaymentRequestResponse":{"type":"object","properties":{"_id":{"$ref":"#/components/schemas/OneOffPaymentId"},"authorisation_url":{"type":"string","format":"uri","description":"The URL the user should be redirected to in order to approve the payment","example":"https://payments.akahu.nz/?payment=one_off_payment_c01234567890123456789012345"},"expires_at":{"type":"string","format":"date-time","description":"The payment will be cancelled at this time, unless it has been authorised"}},"required":["_id","authorisation_url"]},"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"]},"CreateOneOffPayment400ErrorResponseCode":{"type":"string","enum":["invalid_payee","invalid_payer","single_limit_exceeded","bank_limit_exceeded","invalid_bank"]},"IssuePath":{"type":"array","items":{"title":"IssuePathSegment","oneOf":[{"type":"string"},{"type":"number"}]}},"CreateOneOffPayment400ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"issues":{"type":"array","items":{"type":"object","properties":{"code":{"oneOf":[{"$ref":"#/components/schemas/Generic400ErrorResponseCode"},{"$ref":"#/components/schemas/CreateOneOffPayment400ErrorResponseCode"}]},"message":{"type":"string"},"path":{"$ref":"#/components/schemas/IssuePath"}},"required":["code","message","path"]}}},"required":["success","message","issues"]},"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."},"OneOffPaymentRequest":{"type":"object","properties":{"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"},"expires_at":{"type":"string","format":"date-time","description":"The payment will be cancelled at this time, unless it has been authorised. Defaults to 1 hour in the future."}},"required":["payee","amount","redirect_uri"],"description":"A request for payment from the user"},"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"]},"CancelOneOffPayment400ErrorResponseCode":{"type":"string","enum":["bad_payment_state"]},"CancelOneOffPayment400ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[false]},"message":{"type":"string"},"issues":{"type":"array","items":{"type":"object","properties":{"code":{"oneOf":[{"$ref":"#/components/schemas/Generic400ErrorResponseCode"},{"$ref":"#/components/schemas/CancelOneOffPayment400ErrorResponseCode"}]},"message":{"type":"string"},"path":{"$ref":"#/components/schemas/IssuePath"}},"required":["code","message","path"]}}},"required":["success","message","issues"]},"ConnectionId":{"type":"string","pattern":"^conn_[a-z0-9]{25,27}$","example":"conn_c01234567890123456789012345"},"OneOffPaymentLimitType":{"type":"string","enum":["single_payment","daily","weekly"],"description":"The payment or time period that the limit applies to."},"PaymentLimitClassification":{"type":"string","enum":["strict","informational"],"description":"How the published value should be interpreted. A `strict` value is a fixed upper bound. An `informational` value is a default or indicative amount and the customer's actual limit may differ."},"OneOffPaymentLimit":{"type":"object","properties":{"value":{"type":"number","exclusiveMinimum":0,"description":"The limit amount in dollars.","example":30000},"type":{"$ref":"#/components/schemas/OneOffPaymentLimitType"},"classification":{"$ref":"#/components/schemas/PaymentLimitClassification"},"description":{"type":"string","description":"Additional context about how the limit is applied."}},"required":["value","type","classification","description"]},"OneOffPaymentConnection":{"type":"object","properties":{"_id":{"$ref":"#/components/schemas/ConnectionId"},"bank":{"allOf":[{"$ref":"#/components/schemas/OneOffPaymentBank"},{"description":"The value to provide as payer.bank when creating a one-off payment.","example":"westpac"}]},"name":{"type":"string","description":"The name of the institution.","example":"Westpac"},"logo":{"type":"string","format":"uri","description":"A URL pointing to an image of the institution's logo."},"limits":{"type":"object","properties":{"oneoff":{"type":"array","items":{"$ref":"#/components/schemas/OneOffPaymentLimit"}}},"required":["oneoff"]}},"required":["_id","bank","name","logo","limits"]},"OneOffPaymentConnectionsResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true]},"items":{"type":"array","items":{"$ref":"#/components/schemas/OneOffPaymentConnection"}}},"required":["success","items"]}},"parameters":{}},"paths":{"/v1/one-off-payments":{"post":{"operationId":"CreateOneOffPayment","tags":["Payments"],"summary":"Create one-off payment","description":"Akahu's one-off payment service uses official open banking connections to initiate payments directly from your users' New Zealand bank accounts.\n\nCreate a payment by specifying the amount, payee account details, and optional statement reference fields.\nAll payments require a `redirect_uri`. This is where the user will be returned upon completing authorisation.\n\nOnce the payment is created, send your user to the `authorisation_url` to complete payment authorisation.","deprecated":false,"security":[{"AppSecret":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OneOffPaymentRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OneOffPaymentRequestResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateOneOffPayment400ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Generic401ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Generic403ErrorResponse"}}}}}}},"/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"}}}}}}},"/v1/one-off-payments/{paymentId}/cancel":{"put":{"operationId":"CancelOneOffPayment","tags":["Payments"],"summary":"Cancel pending one-off payment","description":"Note that cancellation is only possible before the payment is authorised (while it's status is `READY`).\n\nUpon cancellation payments will not be processed and the user will be \ndirected back to the 'redirect_uri'.","deprecated":false,"security":[{"AppSecret":[]}],"parameters":[{"schema":{"$ref":"#/components/schemas/OneOffPaymentId"},"required":true,"name":"paymentId","in":"path"}],"responses":{"204":{"description":"Accepted"},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelOneOffPayment400ErrorResponse"}}}},"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"}}}}}}},"/v1/webhooks/keys/{keyId}":{"get":{"operationId":"GetWebhookSigningKey","tags":["Webhooks"],"summary":"Get webhook signing key","description":"Retrieve a webhook public signing key by ID, in PEM format.\n\nThe IDs used for this endpoint are supplied in the `x-akahu-payments-signing-key` header on webhook requests.\n\nThis key can be used to verify a one-off payment webhook by:\n\n1. Taking the signature from the webhook request's `x-akahu-payments-signature` header.\n\n2. Taking the webhook signing key ID from the webhook request's `x-akahu-payments-signing-key` header.\n\n3. Fetching the webhook signing key from this endpoint, using the ID from step 2. This should be cached.\n\n4. Taking the raw body from the webhook request (before any parsing is applied)\n\n5. Use the public key to verify that the body was correctly signed (using RSA-SHA256). This varies by language, see our article on [enduring webhooks](https://developers.akahu.nz/docs/reference-webhooks#/verification) for some examples.","deprecated":false,"security":[{"AppSecret":[]}],"parameters":[{"schema":{"type":"string"},"required":true,"name":"keyId","in":"path"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"keyId":{"type":"string"},"publicKey":{"type":"string"}},"required":["keyId","publicKey"]}}}},"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"}}}}}}},"/v1/connections":{"get":{"operationId":"GetConnections","tags":["Connections"],"summary":"Get available connections","description":"Get the financial institution connections available to this application for one-off payments.","deprecated":false,"security":[{"AppSecret":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OneOffPaymentConnectionsResponse"}}}},"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"}}}}}}}},"webhooks":{}}