.png)
Payhawk Integration Guide
Connect Payhawk spend, expense, reimbursement, bill, supplier, employee, and card data with enterprise systems through REST APIs, selected webhook events, and Martini workflows.
Payhawk integration options at a glance
Payhawk’s primary integration mechanism is its REST API, which can be used to retrieve and synchronize expenses, cards, reimbursements, bills, suppliers, and employees. Payhawk also supports webhook-style notifications for selected objects or lifecycle events where enabled, although event coverage must be confirmed for each tenant and resource. Bills and expenses may include receipt or invoice attachments, subject to endpoint-specific support. Authentication may use API keys, bearer credentials, or OAuth 2.0 for selected partner or delegated scenarios. Martini can consume the Payhawk API, receive supported callbacks, schedule incremental retrieval, map financial data, manage checkpoints, and expose normalized APIs to downstream applications.
| Integration point | Supported by Payhawk? | Common use cases | How Martini supports it |
|---|---|---|---|
| REST APIs | Yes | Retrieve and synchronize Payhawk Expenses, Cards, Reimbursements, Bills, Suppliers, and Employees. Confirm the current API version, resources, filters, and tenant permissions. | Martini can consume documented Payhawk REST endpoints, paginate collections, transform responses, and orchestrate downstream API calls. |
| Webhooks / outbound callbacks | Limited | Receive webhook-style notifications for selected Payhawk objects or lifecycle events where enabled. Coverage and payload completeness must be confirmed per event. | Martini can expose or invoke webhook workflows, validate incoming notifications, retrieve the authoritative object, and apply idempotency. |
| File / attachment APIs | Limited | Bills and Expenses may include invoice or receipt documents. Attachment download or upload operations, content formats, and limits require endpoint-level verification. | Martini can orchestrate attachment retrieval or transfer, validate content type and size, and map document metadata to downstream systems. |
| Authentication | Yes | Payhawk server-to-server access may use API keys or bearer credentials; OAuth 2.0 may apply to selected partner or delegated scenarios. | Martini can store credentials in secrets or environment configuration and send authenticated HTTPS requests without embedding credentials in workflows. |
| Pagination and incremental retrieval | Yes | Collection synchronization should use Payhawk’s documented pagination and filtering mechanisms. Updated-at filters or event coverage may vary by object. | Martini can schedule paginated retrieval, maintain durable checkpoints, use overlap windows, and reconcile late-arriving changes. |
| Bulk / async / batch APIs | Not confirmed | Do not assume a Payhawk bulk or asynchronous API. Use documented collection endpoints and endpoint-specific limits unless Payhawk confirms batch support. | Martini can process pages and controlled batches within workflows, but the Payhawk API must define the underlying batch capability. |
| Database / analytics access | No | Direct customer database access is not a confirmed Payhawk integration mechanism. Use Payhawk APIs or supported exports instead. | Martini can write synchronized data to an approved database or analytics destination after retrieving it through Payhawk-supported interfaces. |
| SDKs | Not confirmed | No specific official SDK is confirmed as necessary for Payhawk integrations. | Martini can consume documented HTTPS APIs directly, avoiding a dependency on an unconfirmed SDK. |
How Payhawk exposes data and business events
Payhawk REST APIs
Payhawk REST APIs are the primary mechanism for retrieving and synchronizing business objects such as Expenses, Cards, Reimbursements, Bills, Suppliers, and Employees. Available resources, filters, permissions, and status values depend on the API version and tenant configuration.
Martini implementation pattern
Martini implementation pattern: a workflow authenticates to Payhawk, retrieves paginated collections or individual objects, applies checkpoint and overlap logic, maps the response into a canonical model, and writes to one or more downstream systems.
Implementation sequence
Payhawk Webhook Notifications
Payhawk supports webhook-style notifications for selected objects or lifecycle events where enabled. Notifications should be treated as selective rather than universal, and the payload may contain only an identifier rather than a complete object.
Martini implementation pattern
Martini implementation pattern: expose a controlled webhook endpoint, validate the notification and any available signature or authentication data, retrieve the authoritative Payhawk object, and process the event idempotently. Scheduled reconciliation provides coverage for delayed, duplicated, or unavailable events.
Implementation sequence
Payhawk Attachments
Payhawk Expenses and Bills may include receipts or invoice documents. Attachment operations, binary formats, signed URLs, metadata, and file-size limits must be verified for the selected API version and tenant.
Martini implementation pattern
Martini implementation pattern: retrieve the Payhawk object and supported attachment reference, download or forward the document when available, validate content and metadata, and associate the result with the downstream expense or payable transaction.
Implementation sequence
Payhawk Scheduled Synchronization
Scheduled retrieval is the fallback and reconciliation mechanism for objects without reliable webhook coverage. Payhawk collection endpoints should be consumed with documented pagination, filters, and endpoint-specific limits.
Martini implementation pattern
Martini implementation pattern: schedule a workflow, read the stored high-water mark, retrieve an overlap window of changed objects, process pages with bounded concurrency, and update the checkpoint only after successful downstream handling.
Implementation sequence
Common Payhawk integration patterns
Pattern 1: Sync approved expenses to an accounting platform
When to use this pattern
Use this pattern when approved Payhawk Expenses must be posted to an accounting or ERP platform with consistent tax, cost-center, project, employee, and currency treatment.
Integration direction
Example Mapping
| Payhawk Field | Canonical Field | Target Field |
|---|---|---|
| Expense.id | externalExpenseId | externalId |
| Expense.amount | grossAmount | transactionAmount |
| Expense.employee | employeeReference | employee |
| Expense.costCenter | costCenterCode | department |
Martini implementation pattern
A scheduled Martini workflow retrieves approved or recently changed Expenses with pagination and an overlap window, maps them to the target accounting model, validates required dimensions, and uses the Payhawk identifier for deterministic create-or-update behavior. Transient API failures are retried, while validation and permission errors are routed to an exception path and included in reconciliation.
Martini capabilities used
- workflows
- API consumption
- scheduling
- data mapping
- business rules
- error handling
- idempotency
Pattern 2: Post bills and invoice documents to accounts payable
When to use this pattern
Use this pattern when Payhawk Bills must be transferred to an ERP together with supplier, approval, tax, currency, and available invoice-document information.
Integration direction
Example Mapping
| Payhawk Field | Canonical Field | Target Field |
|---|---|---|
| Bill.id | externalBillId | supplierInvoiceReference |
| Bill.supplier | supplierReference | supplier |
| Bill.currency | currencyCode | documentCurrency |
| Bill.attachment | invoiceDocument | invoiceAttachment |
Martini implementation pattern
Martini retrieves eligible Bills, resolves Supplier references, applies legal-entity and approval-state rules, and retrieves an attachment only when the Payhawk endpoint supports the required operation. The workflow validates duplicate invoice conditions, posts the payable transaction, and stores downstream references for retry-safe reconciliation.
Martini capabilities used
- workflows
- API consumption
- file handling
- data mapping
- validation
- business rules
- error handling
Pattern 3: Synchronize reimbursement status
When to use this pattern
Use this pattern when HR, payroll, or an employee-facing application needs current Payhawk Reimbursement status and selected employee or organizational context.
Integration direction
Example Mapping
| Payhawk Field | Canonical Field | Target Field |
|---|---|---|
| Reimbursement.id | externalReimbursementId | reimbursementReference |
| Reimbursement.status | reimbursementStatus | paymentStatus |
| Reimbursement.employee | employeeReference | workerReference |
| Reimbursement.amount | reimbursementAmount | amount |
Martini implementation pattern
If the required Payhawk event is available, Martini receives the notification and retrieves the current Reimbursement before mapping it to Workday or another target. Otherwise, a scheduled workflow polls incrementally. Status transitions are validated, duplicate notifications are ignored, and rejected or amended reimbursements are propagated as updates rather than new records.
Martini capabilities used
- webhook workflows
- API consumption
- scheduled triggers
- data mapping
- state handling
- idempotency
- error handling
Pattern 4: Monitor card and spend activity
When to use this pattern
Use this pattern when finance, reporting, or risk processes need normalized Payhawk Cards and associated activity, including later changes to merchant, coding, approval, or enrichment data.
Integration direction
Example Mapping
| Payhawk Field | Canonical Field | Target Field |
|---|---|---|
| Card.id | externalCardId | cardReference |
| Card.employee | cardholderReference | owner |
| Card.status | cardStatus | status |
| Card.activity | spendActivity | spendDetails |
Martini implementation pattern
A scheduled Martini workflow retrieves Cards and available activity, applies thresholds and ownership rules, and routes normalized spend data to the target application or reporting service. The workflow uses source identifiers for deduplication, allows later enrichment updates, and isolates incomplete or unmapped records for review.
Martini capabilities used
- workflows
- scheduling
- API consumption
- data transformation
- business rules
- routing
- monitoring
Applications commonly integrated with Payhawk
Payhawk data can be orchestrated into accounting, ERP, HR, payroll, and business applications. The exact object and field coverage should be confirmed against the Payhawk API version, tenant configuration, and enabled modules.
| Application | Scenario | Direction | Martini Pattern |
|---|---|---|---|
| NetSuite | Post approved Payhawk expenses, bills, suppliers, and accounting dimensions into the ERP. | Payhawk → Martini → NetSuite | A scheduled or event-assisted workflow retrieves approved Payhawk objects, maps legal entities, suppliers, tax, currency, and accounting dimensions, then creates or updates NetSuite transactions with idempotency and reconciliation controls. |
| Xero | Synchronize bills, expenses, suppliers, tax information, and accounting classifications with the accounting ledger. | Payhawk → Martini → Xero | Martini retrieves eligible Payhawk financial objects, transforms them into Xero request models, routes failures for review, and records downstream references to prevent duplicate postings. |
| QuickBooks Online | Transfer approved spend and payable data into the accounting ledger. | Payhawk → Martini → QuickBooks Online | A Martini workflow retrieves Payhawk expenses or bills, validates required accounting fields, maps suppliers and tax data, and submits deterministic create-or-update requests to QuickBooks Online. |
| Sage Intacct | Post expenses, bills, dimensions, and supplier information to financial management processes. | Payhawk → Martini → Sage Intacct | Martini applies legal-entity, status, currency, and dimension rules before transforming Payhawk objects and sending them to Sage Intacct with bounded retries and error isolation. |
| Microsoft Dynamics 365 Business Central | Synchronize Payhawk spend and payable transactions with Microsoft finance operations. | Payhawk → Martini → Microsoft Dynamics 365 Business Central | Martini uses Payhawk REST retrieval and Business Central API calls, maintaining a checkpoint and external-key mapping while routing reference-data mismatches to an exception workflow. |
| SAP S/4HANA | Consolidate corporate-card expenses, reimbursements, suppliers, and bills into SAP finance processes. | Payhawk → Martini → SAP S/4HANA | A Martini orchestration workflow normalizes Payhawk financial data, enriches it with mapping rules, and submits the target SAP representation while preserving source identifiers and audit metadata. |
| Workday | Align employee or organizational reference data with Payhawk and return selected reimbursement or expense status to HR or payroll processes. | Workday → Martini → Payhawk | Martini can receive reference data from Workday, map employee and organizational identifiers to Payhawk-compatible values where supported, and synchronize selected reimbursement status in the reverse direction. |
| Salesforce | Surface customer-related expense or spend information for account, project, or field-service processes. | Payhawk → Martini → Salesforce | Martini filters and transforms Payhawk spend data into Salesforce objects or API payloads, applies business rules for account and project association, and isolates invalid references for reprocessing. |
How to build a Payhawk integration in Martini
Objective
Establish secure access to the Payhawk tenant and the target applications.
Instructions in Martini
- Confirm the Payhawk API version, enabled resources, organization, and permissions.
- Configure the API key, bearer credential, OAuth 2.0 flow, or partner-specific method confirmed for the tenant.
- Store credentials in Martini secrets or environment configuration.
- Configure authenticated connections for each downstream application.
Objective
Select an event-driven, scheduled, or API-led entry point based on Payhawk event coverage.
Instructions in Martini
- Use a Payhawk webhook notification when the required object and event are confirmed.
- Use a scheduler for incremental retrieval and reconciliation where webhook coverage is unavailable.
- Expose a controlled Martini API when another system must request synchronized Payhawk data.
Objective
Obtain authoritative Payhawk objects and associated documents through supported endpoints.
Instructions in Martini
- Retrieve the current Expense, Bill, Reimbursement, Card, Supplier, or Employee after a notification.
- Implement pagination and documented filtering for collection endpoints.
- Use checkpoints and overlap windows for incremental synchronization.
- Verify attachment operations before transferring receipts or invoice documents.
Objective
Coordinate retrieval, enrichment, routing, downstream writes, and durable integration state.
Instructions in Martini
- Build the flow as a Martini workflow with clear stages for validation, transformation, and delivery.
- Branch by approval state, legal entity, currency, supplier, cost center, or destination.
- Persist checkpoints, source identifiers, downstream references, and processing outcomes.
Objective
Transform Payhawk structures into canonical and target-specific models.
Instructions in Martini
- Map employee, supplier, tax, currency, accounting dimension, and document fields explicitly.
- Preserve Payhawk identifiers and relevant source metadata.
- Validate required fields and handle unknown or newly introduced status values conservatively.
Objective
Enforce financial controls and deterministic processing before downstream writes.
Instructions in Martini
- Process only the required approval and payment states.
- Detect duplicate invoices, expenses, events, and reimbursements using stable identifiers.
- Apply legal-entity, currency, tax, cost-center, and ownership rules.
- Route validation and permission failures to an exception path rather than retrying unchanged requests.
Common Payhawk data objects used in integrations
| Object | Typical Use | Common target systems | Martini handling |
|---|---|---|---|
| Expenses | Employee spending transactions and their approval or accounting state. | NetSuite, Xero, QuickBooks Online, Sage Intacct, SAP S/4HANA, Salesforce | Martini retrieves approved or changed Expenses, maps employee, tax, cost center, project, currency, and accounting fields, and uses the Payhawk identifier as an external key. |
| Cards | Physical or virtual corporate cards and related card activity. | SAP S/4HANA, NetSuite, reporting platforms, risk applications | Martini periodically retrieves Cards and available activity, applies spend and legal-entity rules, and accounts for delayed enrichment or later coding changes. |
| Reimbursements | Employee-submitted reimbursement requests and lifecycle status. | Workday, payroll applications, finance platforms, employee-facing applications | Martini processes webhook notifications where available or polls incrementally, retrieves current status, and synchronizes approved, rejected, paid, or amended states. |
| Bills | Supplier invoices and accounts-payable processing data. | NetSuite, Xero, QuickBooks Online, Sage Intacct, Microsoft Dynamics 365 Business Central, SAP S/4HANA | Martini validates approval and accounting attributes, retrieves supplier and document information where supported, and creates deterministic payable transactions. |
| Suppliers | Vendor master data associated with bills and payments. | NetSuite, Xero, QuickBooks Online, Sage Intacct, SAP S/4HANA | Martini synchronizes supplier identifiers and attributes, resolves matching rules, and prevents duplicate downstream supplier creation. |
| Employees | Payhawk users or employees associated with cards, expenses, and reimbursements. | Workday, payroll applications, ERP platforms | Martini maps employee and organizational identifiers, applies ownership rules, and preserves source references for downstream reconciliation. |
Authentication and security considerations
Credential management
Confirm whether the Payhawk tenant uses an API key, bearer credential, OAuth 2.0, or a partner-specific authorization flow. The available method depends on the API product, tenant configuration, and integration type.
Least-privilege access
Use a dedicated integration identity with only the permissions required for the selected organization, legal entities, objects, and operations.
Secrets and transport
- Store Payhawk credentials in Martini secrets or environment configuration.
- Use authenticated HTTPS requests and separate credentials by environment and organization.
- Do not embed credentials in workflows, source code, logs, or payloads.
- Protect financial and employee data and retain only the source metadata required for reconciliation.
Operational considerations for Payhawk integrations
Synchronization controls
- Implement pagination and documented filters for collection endpoints.
- Use durable checkpoints with an overlap window for late-arriving updates and clock differences.
- Treat webhook delivery as at-least-once unless Payhawk documents stronger guarantees.
- Use stable Payhawk identifiers and downstream references for idempotency.
Reliability and limits
- Confirm Payhawk rate limits, endpoint-specific limits, and API-version behavior.
- Use bounded exponential backoff for transient failures and do not blindly retry permission or validation errors.
- Reconcile totals by period, legal entity, currency, and status.
- Monitor schema, enumeration, supplier, tax, and accounting-dimension changes.
Attachments and testing
Verify whether receipt and invoice endpoints return binary content, signed URLs, or metadata only. Validate file size, MIME type, and filename, and test amended, rejected, cancelled, duplicated, and late-arriving objects before production deployment.
Why use Martini instead of scripts or point-to-point integrations?
Centralized orchestration
Martini coordinates Payhawk API calls, selected webhook callbacks, schedules, transformations, business rules, and downstream writes in maintainable workflows rather than scattering logic across scripts.
Reusable integration assets
Teams can expose controlled APIs, reuse mappings and validation logic, and preserve canonical identifiers and checkpoints across multiple destinations.
Operational control
Martini provides a place to implement idempotency, retries, reconciliation, exception routing, secrets management, and monitoring for financially significant data flows.
Flexible implementation
Because Payhawk’s primary interface is standards-based REST, Martini can consume documented endpoints directly and adapt to tenant-specific resources without requiring a dedicated connector.
Frequently asked questions
Payhawk can be integrated primarily through its REST APIs for Expenses, Cards, Reimbursements, Bills, Suppliers, and Employees. Selected webhook-style notifications may support event-assisted processing, while scheduled pagination and incremental retrieval provide reconciliation coverage. Attachment operations and authentication methods must be confirmed for the specific tenant and API version.
Yes. Martini can consume Payhawk REST APIs, receive supported Payhawk webhook callbacks, run scheduled synchronization workflows, transform financial data, and expose normalized APIs to downstream systems. A native Martini Payhawk connector is not documented in the supplied materials.
No dedicated Payhawk connector is required. Martini can integrate using Payhawk’s confirmed native mechanisms, including REST APIs, selected webhook callbacks, supported attachment endpoints, and the authentication method enabled for the tenant.
Lonti does not charge an additional per-connector or per-vendor fee to integrate Payhawk. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from Payhawk, cloud infrastructure, or other third-party systems based on subscription, usage, and deployment model.
Use the Payhawk REST API as the primary method for retrieval and synchronization. Use webhook-style notifications for selected events when the required object coverage is confirmed, and use scheduled incremental workflows for reconciliation or objects without reliable event support. Payhawk GraphQL and SOAP APIs were not confirmed.
Payhawk supports webhook-style notifications for selected objects or lifecycle events where enabled, but coverage is selective rather than universal. Martini can receive the notification, validate it, retrieve the authoritative Payhawk object, apply idempotency, and use scheduled reconciliation for missed or duplicated events.
Martini can paginate through Payhawk collections, apply filters and durable checkpoints, map objects into canonical models, and route them to accounting, ERP, HR, payroll, reporting, or other APIs. Business rules can distinguish approval, rejection, payment, coding, legal-entity, currency, and supplier states.
A Martini workflow can use bounded exponential backoff for transient failures, avoid retrying authentication or validation errors without changing the request, and use Payhawk object or event identifiers as idempotency keys. Checkpoints, downstream references, reconciliation totals, and exception paths help prevent duplicate financial postings and support recovery.
Related Martini documentation
Payhawk APIs
Workflows
Data processing
Connect Payhawk to your enterprise systems
Use Martini to build reliable Payhawk integrations for expenses, bills, reimbursements, cards, suppliers, and employees across your finance and business applications.