Skip to main content
When a Payroll is approved, Nmbr automatically generates a set of payments that represent every scheduled money movement for that Payroll. Payments give you full visibility into the flow of funds — from the employer’s bank account, through Nmbr, and out to employees and tax agencies.

​
How payments are generated

You do not create payments directly. When you call the approve endpoint, Nmbr calculates the amounts owed and generates a payment for each destination:
  • Funding (payroll float) — A debit from the employer’s bank account to fund the entire Payroll. This is always the first payment to be processed.
  • Employee payments — A credit to each employee’s or contractor’s bank account for their net pay.
  • Remittances — Credits to the Canada Revenue Agency (CRA), Revenu Québec (RQ), or other remittance accounts for statutory withholdings and employer contributions.
Each payment includes a process_at date (when Nmbr submits the payment to the banking network) and an expected_at date (when the funds are expected to arrive).

​
Payment lifecycle

Every payment moves through a series of statuses as it is processed:

​
pending

The payment has been generated but has not yet been submitted to the banking network.

​
processing

Nmbr has submitted the payment to the banking network. The funds are in transit and the payment can no longer be modified. The payment has settled successfully. Funds have arrived at their destination.

​
failed

The payment was returned by the banking network. Common causes include non-sufficient funds (NSF) or an invalid bank account. When a funding payment fails, Nmbr will cancel the associated employee and remittance payments for that Payroll to prevent further issues.
When a payment fails, the parent Payroll’s status is updated to reflect the failure. You can monitor payroll-level status changes via webhooks or by polling the payroll endpoint.

​
overdue

A payment that was held past its process_at date transitions to overdue. Overdue payments cannot be released through the API and must be resolved through Nmbr support.

​
Holding and releasing payments

Partners can place a hold on any payment. What a hold means depends on when it is placed:
  • Before processing (pending payments) — The payment is blocked from being submitted to the banking network. It will not process until released.
  • After settlement (paid payments) — The payment itself is not reversed — it has already settled. However, holding a settled funding payment blocks all downstream payments (employee, CRA, RQ) from being processed. This is useful for verification before releasing funds to employees.

​
Placing a hold

Any payment can be held regardless of its status or destination. 
curl --request POST \
     --url https://sandbox.nmbr.co/services/payroll/payments/:payment_id/hold \
     --header 'Authorization: Bearer <access_token>' \
     --header 'accept: application/json'

​
Releasing a hold

Any held payment can be released. Once released, the payment returns to normal processing and pending payments will be submitted in the next processing window. 
curl --request POST \
     --url https://sandbox.nmbr.co/services/payroll/payments/:payment_id/release \
     --header 'Authorization: Bearer <access_token>' \
     --header 'accept: application/json'

​
Automatic verification holds

Business Entities can be configured with hold_funding_for_verification to automatically hold funding payments after they settle. This gives bank partners time for internal monitoring before downstream payments proceed. Downstream payments remain blocked until the hold is released.

​
Querying payments

Retrieve all payments for a Business Entity using the list payments endpoint. You can filter by status, destination, method, payroll_id, and is_held to narrow down results. 
curl --request GET \
     --url 'https://sandbox.nmbr.co/services/payroll/payments?business_entity_id=:id&status=pending' \
     --header 'Authorization: Bearer <access_token>' \
     --header 'accept: application/json'

​
Key concepts for integrators

  • Payments are read-only. You cannot create, update, or delete payments directly. They are generated and managed by Nmbr as part of the payroll lifecycle.
  • Funding must settle first. Employee and remittance payments are only processed after the funding payment has settled and is not held.
  • Failed funding cascades. If the employer’s funding payment fails, all related employee and remittance payments for that Payroll are automatically canceled.
  • Monitor status via webhooks. Subscribe to payroll status webhooks to be notified when payments move through processing stages, rather than polling the API.