Skip to main content

Payroll Advance

Enable the feature​

info

Your financial accounts must have PayrollAdvanceFinancialAccountFeature enabled to use Payroll Advance.

The Highnote team will assist with setting up and enabling the payroll advance feature for your card product.

In addition to enabling the feature, you must integrate with a payroll data source partner to access employment data with your customer's consent and if necessary, determine a pre-funding amount.

Create an employer financial account​

Before initiating an advance, you must create an employer financial account. This account is used to initiate a transfer from your product funding account to the employee financial account.

Use the following mutation to issue an employer financial account:

IssueEmployerFinancialAccountForCardProduct​
Query
mutation IssueEmployerFinancialAccountForCardProduct(
  $input: IssueEmployerFinancialAccountForCardProductInput!
) {
  issueEmployerFinancialAccountForCardProduct(input: $input) {
    ... on EmployerFinancialAccount {
      id
      name
      createdAt
      updatedAt
      application {
        id
        createdAt
      }
      cardProduct {
        id
        vertical
      }
      owner {
        __typename
        ... on Organization {
          id
        }
      }
      features {
        __typename
        enabled
        createdAt
        updatedAt
      }
    }
  }
}
Variables
{
  "input": {
    "cardProductId": "CARD_PRODUCT_ID",
    "name": "EMPLOYER_NAME",
    "companyIdentifier": "1234567890"
  }
}
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
  "data": {
    "issueEmployerFinancialAccountForCardProduct": {
      "id": "EMPLOYER_FINANCIAL_ACCOUNT_ID",
      "companyIdentifier": "1234567890",
      "name": "EMPLOYER_NAME",
      "createdAt": "2021-12-28T18:20:49.932Z",
      "updatedAt": "2021-12-28T18:20:49.960Z",
      "cardProduct": {
        "id": "CARD_PRODUCT_ID",
        "vertical": "CONSUMER_DEBIT"
      },
      "owner": {
        "__typename": "Organization",
        "id": "ORGANIZATION_ID"
      },
      "features": {
        "__typename": "PayrollEmployerAdvanceFinancialAccountFeature",
        "enabled": true,
        "createdAt": "2021-12-28T18:20:49.933Z",
        "updatedAt": "2021-12-28T18:20:49.933Z"
      }
    }
  }
}

Initiate advance​

Payroll advances start with retrieving payroll data from a partner source. Once this data is retrieved, an account holder can request an advance for their employee financial account. Payroll advance transfers are internal transfers between Highnote financial accounts.

Use the following mutation to initiate a payroll advance after a request is received:

initiatePayrollAdvance​
Query
mutation initiatePayrollAdvance($input: InitiatePayrollAdvanceInput!) {
  initiatePayrollAdvance(input: $input) {
    __typename
    ... on Transfer {
      id
      status
      statusReason
      createdAt
      updatedAt
      amount {
        value
        currencyCode
      }
      ledgers {
        name
      }
    }
    ... on UserError {
      errors {
        code
      }
    }
    ... on AccessDeniedError {
      message
    }
  }
}
Variables
{
  "input": {
    "toFinancialAccountId": "EMPLOYEE_FINANCIAL_ACCOUNT",
    "fromFinancialAccountId": "EMPLOYER_FINANCIAL_ACCOUNT",
    "memo": "employee ID",
    "amount": {
      "value": 10000,
      "currencyCode": "USD"
    }
  }
}
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
  "data": {
    "initiatePayrollAdvance": {
      "__typename": "Transfer",
      "id": "INTERNAL_TRANSFER_ID",
      "status": "PENDING",
      "statusReason": null,
      "createdAt": "2021-12-27T22:26:55.102Z",
      "updatedAt": "2021-12-27T22:26:55.127Z",
      "amount": {
        "value": 10000,
        "currencyCode": "USD"
      },
      "ledgers": null
    }
  }
}

List payroll advance ledgers​

Use the following query to list all payroll advance payable and receivable ledgers, their outstanding balances, and additional relevant data:

FindAccount​
Query
query FindAccount($id: ID!) {
  node(id: $id) {
    ... on FinancialAccount {
      __typename
      id
      name
      ledgers {
        id
        name
        normalBalance
        asOf
        debitBalance {
          value
          currencyCode
        }
        creditBalance {
          value
          currencyCode
        }
      }
    }
  }
}
Variables
{
  "id": "EMPLOYER_FINANCIAL_ACCOUNT_ID"
}
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
  "data": {
    "node": {
      "__typename": "FinancialAccount",
      "id": "EMPLOYER_FINANCIAL_ACCOUNT_ID",
      "name": "John Doe - Account",
      "ledgers": [
        {
          "id": "LEDGER_ID",
          "name": "DEPOSIT_HOLD",
          "normalBalance": "CREDIT",
          "asOf": "2022-04-20T14:34:39.948Z",
          "debitBalance": {
            "value": 0,
            "currencyCode": "USD"
          },
          "creditBalance": {
            "value": 0,
            "currencyCode": "USD"
          }
        },
        {
          "id": "LEDGER_ID",
          "name": "REFUND_HOLD",
          "normalBalance": "CREDIT",
          "asOf": "2022-04-20T14:34:39.948Z",
          "debitBalance": {
            "value": 0,
            "currencyCode": "USD"
          },
          "creditBalance": {
            "value": 0,
            "currencyCode": "USD"
          }
        },
        {
          "id": "LEDGER_ID",
          "name": "FUND_IN_HOLD",
          "normalBalance": "CREDIT",
          "asOf": "2022-04-20T14:34:39.948Z",
          "debitBalance": {
            "value": 0,
            "currencyCode": "USD"
          },
          "creditBalance": {
            "value": 0,
            "currencyCode": "USD"
          }
        },
        {
          "id": "LEDGER_ID",
          "name": "AVAILABLE_CASH",
          "normalBalance": "CREDIT",
          "asOf": "2022-04-20T14:34:39.948Z",
          "debitBalance": {
            "value": 0,
            "currencyCode": "USD"
          },
          "creditBalance": {
            "value": 0,
            "currencyCode": "USD"
          }
        },
        {
          "id": "LEDGER_ID",
          "name": "DEPOSIT_AUTHORIZATION",
          "normalBalance": "CREDIT",
          "asOf": "2022-04-20T14:34:39.948Z",
          "debitBalance": {
            "value": 0,
            "currencyCode": "USD"
          },
          "creditBalance": {
            "value": 0,
            "currencyCode": "USD"
          }
        },
        {
          "id": "LEDGER_ID",
          "name": "REFUND_AUTHORIZATION",
          "normalBalance": "CREDIT",
          "asOf": "2022-04-20T14:34:39.948Z",
          "debitBalance": {
            "value": 0,
            "currencyCode": "USD"
          },
          "creditBalance": {
            "value": 0,
            "currencyCode": "USD"
          }
        },
        {
          "id": "LEDGER_ID",
          "name": "CASH",
          "normalBalance": "DEBIT",
          "asOf": "2022-04-20T14:34:39.948Z",
          "debitBalance": {
            "value": 0,
            "currencyCode": "USD"
          },
          "creditBalance": {
            "value": 0,
            "currencyCode": "USD"
          }
        },
        {
          "id": "LEDGER_ID",
          "name": "AUTHORIZATION",
          "normalBalance": "CREDIT",
          "asOf": "2022-04-20T14:34:39.948Z",
          "debitBalance": {
            "value": 0,
            "currencyCode": "USD"
          },
          "creditBalance": {
            "value": 0,
            "currencyCode": "USD"
          }
        },
        {
          "id": "LEDGER_ID",
          "name": "FEE_AUTHORIZATION",
          "normalBalance": "CREDIT",
          "asOf": "2022-04-20T14:34:39.948Z",
          "debitBalance": {
            "value": 0,
            "currencyCode": "USD"
          },
          "creditBalance": {
            "value": 0,
            "currencyCode": "USD"
          }
        }
      ]
    }
  }
}

Repay payroll advance​

Payroll advance repayment is received using deposit initiated via a non-originated ACH transfer. Repayment occurs in the following order of events:

  1. The employee provides demand deposit account (DDA) details for their employee financial account to their payroll provider.
  2. Employee initiates the payroll advance repayment deposit.
  3. Once Highnote receives the payroll advance repayment deposit, you must send an API call to confirmPayrollDeposit and provide the employer financial account ID. You must confirm payroll advance repayment deposits by 11:00 AM Eastern Standard Time (EST), one business day before the AchExternallyInitatedEvent settlement date.
  4. If the repayment deposit is confirmed, it processes as a payroll advance repayment.
  5. If the repayment deposit is not confirmed, Highnote deposits the funds into the employee financial account without advance repayment.

You can monitor and confirm payroll deposits using the Payroll advance repayment status notification. This notification triggers when a repayment processes and provides the status of the repayment.

For step three in the repayment process, use the following mutation to confirm a payroll advance repayment deposit. Use isPayrollDeposit as an input variable:

confirmPayrollDeposit​
Query
mutation confirmPayrollDeposit($input: ConfirmPayrollDepositInput!) {
  confirmPayrollDeposit(input: $input) {
    ... on PayrollTransfer {
      id
      status {
        __typename
        ... on NonFailureExternallyInitiatedACHStatus {
          status
        }
        ... on FailureExternallyInitiatedACHStatus {
          status
          statusReasonCode
        }
      }
      createdAt
      updatedAt
      amount {
        value
        currencyCode
      }
    }
    ... on CreditFunds {
      id
      status {
        __typename
        ... on NonFailureExternallyInitiatedACHStatus {
          status
        }
        ... on FailureExternallyInitiatedACHStatus {
          status
          statusReasonCode
        }
      }
      createdAt
      updatedAt
      amount {
        value
        currencyCode
      }
    }
    ... on UserError {
      errors {
        code
      }
    }
    ... on AccessDeniedError {
      message
    }
  }
}
Variables
{
  "input": {
    "id": "ELECTRONIC_FUNDS_TRANSFER_ID",
    "isPayrollDeposit": true,
    "employerFinancialAccountId": "EMPLOYER_FINANCIAL_ACCOUNT_ID"
  }
}
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
  "data": {
    "confirmPayrollDeposit": {
      "__typename": "PayrollTransfer",
      "id": "INTERNAL_TRANSFER_ID",
      "status": {
        "__typename": "NonFailureExternallyInitiatedACHStatus",
        "status": "PENDING"
      },
      "createdAt": "2021-12-27T22:26:55.102Z",
      "updatedAt": "2021-12-27T22:26:55.127Z",
      "amount": {
        "value": 2000,
        "currencyCode": "USD"
      }
    }
  }
}