All Collections
Payhawk for developers
Overview of the Payhawk Developer API
Overview of the Payhawk Developer API

Get an overview of how to use the Payhawk Developer API to create custom integrations as a partner or as a customer.

N
Written by Nikolay Babev
Updated over a week ago

Payhawk exposes its Developer API thus enabling users to further tailor their Payhawk experience to the specifics of their business.

Authenticating to the Payhawk Developer API

Authentication is achieved by attaching the API key to every request as a request header.

Store the API key securely.

To obtain the API key:

  1. Log in to the Payhawk web portal.

  2. Go to the Settings > Integrations > API Keys section.

Request throttling and limits

The Payhawk Developer API is limited to 15 requests per second which can be seen in the returned ratelimit headers of every API request.

Webhooks

Webhooks are a powerful tool that enables real-time integration. When an action happens in Payhawk, your system can be automatically notified of that action:

  1. Copy the Account ID of your Payhawk account. The key can be seen from the portal URL, for example, https://portal.payhawk.com/?account=payhawk_demo_6fc0db9a.

  2. Make sure you have the API key enabled. To obtain the key, go to Settings > Integrations > API Keys.

  3. Navigate to the Payhawk Developer Portal at https://developers.payhawk.io/#/Webhook%20Subscriptions.

  4. Navigate to Webhook Subscriptions.

  5. Create a webhook by using Create Webhook Subscription. Click on try it out to see the full request: https://api.payhawk.io/api/v3/accounts/payhawk_demo_6fc0db9a/webhooks:

    • EventType - The full list of events is under the NewWebhookSubscription > EventType. For example, if you want to receive notifications when new expenses are created, you can use the expense.created event.

    • Callback URL - This is the URL to which the webhook will be sent.

  6. Verify the webhook is created by using GET webhook subscriptions.

Querying expense records

To query expense records with the Payhawk Developer API:

  1. Copy the Account ID of your Payhawk account. The key can be seen from the portal URL, for example, https://portal.payhawk.com/?account=payhawk_demo_6fc0db9a.

  2. Make sure you have the API key enabled. To obtain the key, go to Settings > Integrations > API Keys.

  3. Navigate to the Expenses section at https://developers.payhawk.io/#/Expenses/get_api_v3_accounts__accountId__expenses.

  4. Use the GET request. Click on try it out to see the full request: https://api.payhawk.io/api/v3/accounts/payhawk_demo_6fc0db9a/expense.s.

Page size and request size

The page size is 1000 per request. However, the results support paging and Skip and Take parameters: https://api.payhawk.io/api/v3/accounts/payhawk_demo_6fc0db9a/expenses?%24skip=1000&%24take=1000%27.

Filters

Filters can be constructed by using the examples. To combine them, use the following approach: 

    {
      "status": {
        "$equal": "draft"
      }
    },
    {
      "supplier.name": {
        "$contains": "Payhawk"
      }
    },

The full list of filter properties is available in the IExpenseFilter type.

The filters are then attached as a Query Parameter encoded and attached to the URL, so the above filter translates to:

https://api.payhawk.io/api/v3/accounts/payhawk_demo_6fc0db9a/expenses?%24filter=%7B%0A%20%20%22%24and%22%3A%20%5B%0A%20%20%20%20%7B%0A%20%20%20%20%20%20%22status%22%3A%20%7B%0A%20%20%20%20%20%20%20%20%22%24equal%22%3A%20%22draft%22%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%2C%0A%20%20%20%20%7B%0A%20%20%20%20%20%20%22supplier.name%22%3A%20%7B%0A%20%20%20%20%20%20%20%20%22%24contains%22%3A%20%22Payhawk%22%0A%20%20%20%20%20%20%7D%0A%20%20%20%20%7D%0A%20%20%5D%0A%7D&%24

Sorting and ordering

OrderBy follows the same convention in the query string:

{
  "createdAt": "asc"
}

translates to orderBy=%5B%7B%22createdAt%22%3A%22asc%22%7D%5D&%24.

The full list of sortable options is available in the IExpenseOrderBy property.

Managing custom fields

The custom fields in Payhawk can be manipulated from the Payhawk web portal. However, there are use cases when an external system has to update or manage those fields. Examples of this are managing General Ledger codes or Project numbers from an external ERP or time-tracking software.

  1. Copy the Account ID of your Payhawk account. The key can be seen from the portal URL, for example, https://portal.payhawk.com/?account=payhawk_demo_6fc0db9a.

  2. Make sure you have the API key enabled. To obtain the key, go to Settings > Integrations > API Keys.

  3. Navigate to the custom fields section in the developer portal at https://developers.payhawk.io/#/Custom%20Fields/get_api_v3_accounts__accountId__custom_fields.

  4. You can perform the following actions with the custom fields:

    • Create, update, or delete a custom field.

    • Create, update, or delete a custom field value.

    • Create, update, or delete a custom field manager.

The ID of a custom field is auto-generated. To see it:

  1. Go to Settings > Expense fields.

  2. Scroll down to the desired custom field and click on a created custom field or from the GET custom field request.

If a custom field is deleted, the existing expenses that have that custom field attached are not updated.

Retrieving the invoice of an expense

The file can be found under Expense > Document and files array.

  1. Copy the Account ID of your Payhawk account. The key can be seen from the portal URL, for example, https://portal.payhawk.com/?account=payhawk_demo_6fc0db9a.

  2. Make sure you have the API key enabled. To obtain the key, go to Settings > Integrations > API Keys.

  3. Open the Developer Portal and check the Expenses section at https://developers.payhawk.io/#/Expenses.

  4. Use the GET Expenses (for many expenses) or GET Expense (for a single expense) endpoints and find the files array:

    "document": {
            "documentDate": "2024-02-15T12:53:50.809Z",
            "dueDate": "2024-02-15T12:53:50.809Z",
            "serviceDate": "2024-02-15T12:53:50.809Z",
            "documentNumber": "string",
            "documentType": "receipt",
            "files": [
              {
                "id": "string",
                "url": "string",
                "contentType": "string"
              }
            ]
          }

    The reason the returned value is an array is that Payhawk allows two or more documents to be attached to an expense.

Attaching properties or hidden references to expenses

Such a property is called externalLinks. The externalLinks can be used to keep a reference to a property that is stored in the external system.

  • The externalLinks property is not visible in the UI and contains two properties - title and url.

  • If you have an out-of-the-box integration, this property might not be empty.

To use the externalLinks property:

  1. Copy the Account ID of your Payhawk account. The key can be seen from the portal URL, for example, https://portal.payhawk.com/?account=payhawk_demo_6fc0db9a.

  2. Make sure you have the API key enabled. To obtain the key, go to Settings > Integrations > API Keys.

  3. To update the externalLinks property, use the Update request: https://developers.payhawk.io/#/Expenses/patch_api_v3_accounts__accountId__expenses__expenseId_.

Creating expenses

It is not possible to create an expense with the Payhawk Developer API.

  • For card transactions, expenses are created automatically when the card is used.

  • For bank transfers, you can use the Receipts Mailbox functionality to send invoices and create new bank transfer expenses. The creator of the expense will be the sender of the email.

Did this answer your question?