---
updatedAt: 2026-04-08T12:47:12.000Z
agentTools:
  projectIndex: https://docs.shophumm.com.au/llms.txt
---

# Process Authorisation

This endpoint processes an authorisation to initiate and finalise the transaction.

<br />

## humm Endpoints

**Method**: ProcessAuthorisation

| humm Environment | URL                                                          |
| :--------------- | :----------------------------------------------------------- |
| Production       | <https://pos.shophumm.com.au/webapi/v1/processauthorisation> |
| Sandbox          |                                                              |

> 📘 Info
>
> All Humm API requests are required to be secured using TLS 1.2 or greater

## Request POST

POST to humm in the format `application/x-www-form-urlencoded` and prefix all key names with `x_`

Below is an overview of the various key-value pairs that can be passed.

<br />

<Table align={["left","left","left","left"]}>
  <thead>
    <tr>
      <th>
        Parameter
      </th>

      <th>
        Type
      </th>

      <th>
        Length
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        x_pos_transaction_ref
      </td>

      <td>
        Unicode string
      </td>

      <td>
        64
      </td>

      <td>
        This must be the same reference that would get passed through on future **ProcessSalesAdjustment** requests. This field is mandatory - if the POS system does not have this information at the time of the request, it should pass through a temporary unique value (e.g. a GUID) so that humm has the information it needs to process retry attempts. If a temporary value is used; a subsequent request to SendReceipt must be made when the actual transaction reference is known by the POS system, so that humm can successfully reconcile future **ProcessSalesAdjustment** requests.
      </td>
    </tr>

    <tr>
      <td>
        x_merchant_id
      </td>

      <td>
        Unicode string
      </td>

      <td>
        10
      </td>

      <td>
        Merchant identifier as defined by humm
      </td>
    </tr>

    <tr>
      <td>
        x_purchase_amount
      </td>

      <td>
        int
      </td>

      <td>
        12
      </td>

      <td>
        Total purchase amount (in cents)
      </td>
    </tr>

    <tr>
      <td>
        x_finance_amount
      </td>

      <td>
        int
      </td>

      <td>
        12
      </td>

      <td>
        Amount that the customer wants the finance for from humm (in cents)
      </td>
    </tr>

    <tr>
      <td>
        x_pre_approval_code
      </td>

      <td>
        Unicode string
      </td>

      <td>
        6, optionally 10 digits when including 6199 prefix
      </td>

      <td>
        The pre-approval code obtained from barcode that the customer is presented
      </td>
    </tr>

    <tr>
      <td>
        purchase_items `optional`
      </td>

      <td>
        String
      </td>

      <td>
        200
      </td>

      <td>
        A JSON formatted string containing information about the purchase items e.g. `{ "PurchaseItems": [ "Item1", "Item2" ] }`

        * _Note_*: the purchase item array is assigned to a field named "PurchaseItems".
      </td>
    </tr>

    <tr>
      <td>
        x_device_id
      </td>

      <td>
        Unicode string
      </td>

      <td>
        64
      </td>

      <td>
        Unique device identifier for the POS terminal
      </td>
    </tr>

    <tr>
      <td>
        x_operator_id
      </td>

      <td>
        Unicode string
      </td>

      <td>
        64
      </td>

      <td>
        ID of POS/terminal operator
      </td>
    </tr>

    <tr>
      <td>
        x_firmware_version
      </td>

      <td>
        Unicode string
      </td>

      <td>
        64
      </td>

      <td>
        Current firmware version of POS device
      </td>
    </tr>

    <tr>
      <td>
        tracking_data `optional`
      </td>

      <td>
        Associative array
      </td>

      <td>
        Max 1000000
      </td>

      <td>
        A map that can be populated with additional tracking/state information that will get passed back in the response
      </td>
    </tr>

    <tr>
      <td>
        buyer_confirms `optional`
      </td>

      <td>
        Boolean (true/false)
      </td>

      <td>
        5
      </td>

      <td>
        New field to indicate that the POS Vendor supports the Buyer Confirms flow. If not specified, it is assumed to be ‘false’
      </td>
    </tr>

    <tr>
      <td>
        signature
      </td>

      <td>
        Hex string case-insensitive
      </td>

      <td>
        200
      </td>

      <td>
        Payload that is signed using HMAC-SHA256 using a device specific key
      </td>
    </tr>
  </tbody>
</Table>

## Response

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th>
        Parameter
      </th>

      <th>
        Type
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        x_status
      </td>

      <td>
        Unicode string
      </td>

      <td>
        Success/Failure/Error
      </td>
    </tr>

    <tr>
      <td>
        x_code
      </td>

      <td>
        Unicode string
      </td>

      <td>
        A code that maps to a specific reason
      </td>
    </tr>

    <tr>
      <td>
        x_message
      </td>

      <td>
        Unicode string
      </td>

      <td>
        A string explaining the status/code above. Example: For an Approval, what will be customer’s first direct debit date. For an Error: Bank declined – Insufficient Funds
      </td>
    </tr>

    <tr>
      <td>
        x_purchase_number
      </td>

      <td>
        Unicode string
      </td>

      <td>
        Unique transaction identifier generated by humm
      </td>
    </tr>

    <tr>
      <td>
        tracking_data
      </td>

      <td>
        Associative array
      </td>

      <td>
        Echoes tracking_data sent on the request
      </td>
    </tr>

    <tr>
      <td>
        retry_duration
      </td>

      <td>
        int
      </td>

      <td>
        Set to 5 seconds by default. When the status returned is ‘Pending’ the POS Response will include a new ‘retry_duration’. The intent is for the calling POS Vendor to wait the specified retry duration in seconds

        (Only if `buyer_confirms` passed in initial request)
      </td>
    </tr>

    <tr>
      <td>
        signature
      </td>

      <td>
        Hex string case-insensitive
      </td>

      <td>
        Payload that is signed using HMAC-SHA256 using a device specific key
      </td>
    </tr>
  </tbody>
</Table>

## Testing

The following describes dummy API requests that return a predictable response. Please contact <pit@shophumm.com.au> to get access to the test/dummy APIs.

| Request -> x\_pre\_approval\_code | Response -> x\_status | Response -> x\_code  |
| :-------------------------------- | :-------------------- | :------------------- |
| 01######                          | Success               | SPRA01               |
| Pending                           | SPND01                | ProcessAuthorisation |
| Cancelled                         | FCNL01                | ProcessAuthorisation |
| 10######                          | Failed                | FPRA01               |
| 11######                          | Failed                | FPRA02               |
| 12######                          | Failed                | FPRA03               |
| 13######                          | Failed                | FPRA04               |
| 14######                          | Failed                | FPRA05               |
| 15######                          | Failed                | FPRA06               |
| 16######                          | Failed                | FPRA07               |
| 17######                          | Failed                | FPRA08               |
| 18######                          | Failed                | FPRA21               |
| 19######                          | Failed                | FPRA22               |
| 20######                          | Failed                | FPRA23               |
| 21######                          | Failed                | FPRA24               |
| 22######                          | Failed                | FPRA99               |
| 23######                          | Failed                | FPRA09               |
| 30######                          | Error                 | EVAL01               |
| 31######                          | Error                 | EAUT01               |
| 32######                          | Error                 | EVAL02               |
| any other value                   | Error                 | EISE01               |

> 📘 Info
>
> "#" signifies an alphanumeric digit
>
> Testing Assumptions To generate the signature, use a device-signing-key of "1234567890". A invalid signature will cause an ESIG01 Error.