---
title: "Make a payment to IRD"
method: POST
path: "/payments/ird"
tags: ["Payments"]
---

# Make a payment to IRD

`POST /payments/ird`

Initiate a tax payment from user's connected bank account to [🔗 Inland Revenue Department](https://www.ird.govt.nz/).

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)

## Headers

- `X-Akahu-Id` string, required
- `Content-Type` string

## Request body

- object
  - `from` string, required — The Akahu Account ID you want to pay from
  - `amount` number, required — The payment amount
  - `meta` object, required — Metadata relating to the tax payment.
    - `tax_number` string, required — The 9-digit IRD or GST number that the payment relates to
    - `tax_type` string, required — The 3 character IRD tax type code that tells IRD what tax account the payment is for. For a full list of tax types check out the [🔗 IRD's account type guide](https://www.ird.govt.nz/managing-my-tax/make-a-payment/choosing-the-right-account-type) for more details.
    - `tax_period` string — The end date of the tax period which this payment is for, formatted as an ISO 8601 date e.g. 1970-01-01. This is required by IRD for most tax payments, however there are certain payment types that do not require it (e.g. ARR, KSS, LGL). For the complete list of exclusions see the [IRD website](https://www.ird.govt.nz/managing-my-tax/make-a-payment/ways-of-paying/paying-electronically)

## Response `200`

Successful response.

- object
  - `success` boolean
  - `item` Payment
    - `_id` string — The Akahu Payment ID
    - `from` string — The Akahu Account ID of the source account
    - `to` object — Information about who this payment is to
      - `account_number` string — The NZ bank account number to whom this payment is made
      - `name` string — The name of the account holder of the destination account
    - `amount` number — How much money the payment is for
    - `meta` object — Payment metadata that you have specified
      - `destination` object — Metadata that will appear in the destination account
        - `particulars` string — The particulars you have specified for the destination account
        - `code` string — The code you have specified for the destination account
        - `reference` string — The reference you have specified for the destination account
      - `source` object — Metadata that will appear in the source account
        - `code` string — The code you have specified for the source account
        - `reference` string — The reference you have specified for the source account
    - `sid` string — Akahu's unique ID inserted into the particulars field
    - `status` 'READY' | 'PENDING_APPROVAL' | 'SENT' | 'PAUSED' | 'DECLINED' | 'CANCELLED' | 'ERROR' — Status of the payment: - `READY` → Initial state payment is ready to be processed. - `PENDING_APPROVAL` → Payment requires user approval before processing see the guide for more details. - `SENT` → Payment initiated with the user's bank and we've received confirmation that it has been accepted. - `PAUSED` → Payment is not yet ready to be processed. - `DECLINED` → Payment has been declined by the user's bank. - `CANCELLED` → Payment was cancelled. - `ERROR` → Internal Akahu error occurred. For more details see: - [📚 Payments guide](/docs/making-a-payment) - [📚 Payments lifecycle guide](/docs/making-a-payment#payment-lifecycle)
    - `status_text` string — If available, more information about the payment's staus
    - `final` boolean — If this payment has reached it's final state
    - `timeline` object[] — A timeline of events regarding this payment
      - `status` string — The payment's status at this time
      - `time` string, date-time — An ISO 8701 timestamp of when this event was created
      - `eta` string, date-time — An ISO 8701 timestamp of when Akahu expects the payment to arrive. Only present on events for `SENT` statuses.
    - `created_at` string, date-time — An ISO 8701 timestamp of when this payment was created
    - `updated_at` string, date-time — An ISO 8701 timestamp of when this payment was last updated by Akahu
    - `received_at` string, date-time — 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.
  - `item_id` string — ⚠️ **Deprecated** The Akahu Payment ID replaced via `item._id`
  - `status` string — ⚠️ **Deprecated** The Akahu Payment status replaced via `item.status`

## Other responses

- `400` — Your request was malformed or otherwise unacceptable. The `message` key in the response will give more details.
- `401` — You are not authorised to access this content.
- `403` — You are not allowed to access this content.
- `500` — An internal error has prevented us from processing the request. More detail may be supplied in the `message` key.

---

[API](https://skmtc.dev/akahu/apis/akahu-enduring-api.md) · [All operations](https://skmtc.dev/akahu/apis/akahu-enduring-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/akahu/akahu-enduring-api/revisions/b2de9915920d/schema)