Business Logic

Client Integration Guide

This guide walks you through the complete flow required to integrate your system with the LAW API — from authentication to submitting payroll data and receiving real-time file notifications via webhooks.

Prerequisites

Before you begin, your integration must meet the following requirements:

  • Credentials: Your Client ID and Client Secret are issued by us during onboarding. Contact our Partner Success team if you have not received them yet.
  • IP Whitelisting: Our Sandbox environment is IP-restricted. You must provide your outbound IP address(es) to our team so we can whitelist them before your first API call.
  • Webhook Endpoint: A publicly reachable HTTPS endpoint on your side is required to receive file processing notifications.

Step 1: Authenticate

All API requests require a Bearer token obtained through OAuth 2.0 client credentials flow.

For a detailed explanation of the authentication mechanism, see the Authentication guide.

Request

POST https://sandbox.bmgmoney.com/oauth/v1/access-token
Authorization: Basic <base64(client_id:client_secret)>
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

Response

{
  "access_token": "<your_token>",
  "token_type": "Bearer",
  "expires_in": 3600
}

Use the returned access_token as a Bearer token in the Authorization header of every subsequent request.

Step 2: Create a Webhook Subscription

Before uploading any data, register a webhook so your system is notified when LAW processes files on your behalf.

Request

POST https://sandbox.bmgmoney.com/law/api/v1/subscriptions
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "targetUrl": "https://my-system.employer.com/webhooks",
  "secret": "<your_webhook_secret>",
  "events": ["file"],
  "description": "File notification webhook"
}
Field Description
targetUrl The HTTPS URL on your side that will receive webhook payloads.
secret A secret string used to sign the webhook payload so you can verify its authenticity.
events Array of event types to subscribe to. Use "file" to receive file processing notifications.
description A human-readable label for this subscription.

Listing Your Subscriptions

You can verify your registered subscriptions at any time:

GET https://sandbox.bmgmoney.com/law/api/v1/subscriptions
Authorization: Bearer <access_token>
X-Context-Key: <employer_context_id>

Step 3: Upload Employee Census

The census represents your active employee roster. This data allows LAW to match employees when processing payroll loans.

Request

POST https://sandbox.bmgmoney.com/law/api/v1/census
Authorization: Bearer <access_token>
Content-Type: application/json

[
  {
    "lastName": "Senna",
    "firstName": "Ayrton",
    "employeeRegistration": "RG-123",
    "hireDate": "2024-01-15",
    "employeeStatus": "Active",
    "eligibleForBenefits": true,
    "payCycle": "Biweekly",
    "periodsPerYear": 26,
    "grossAnnualSalary": 85000.00,
    "salaryPerPeriod": 3269.23,
    "standardHours": 80,
    "hourlyRate": 25.50,
    "timeType": "Salaried",
    "payrollGroup": "HQ",
    "payrollArea": "US-FL",
    "personnelSubArea": "MIAMI"
  }
]
Field Type Description
lastName / firstName string Employee's full name.
employeeRegistration string Your internal employee ID or registration number.
hireDate string (ISO 8601) Date the employee was hired (YYYY-MM-DD).
employeeStatus string Current status: Active or Inactive.
eligibleForBenefits boolean Whether the employee is eligible for payroll loan benefits.
payCycle string Pay frequency: e.g., Biweekly, Monthly, Weekly.
periodsPerYear integer Number of pay periods per year.
grossAnnualSalary number Total gross annual salary.
salaryPerPeriod number Gross pay per pay period.
standardHours number Standard hours worked per pay period.
hourlyRate number Hourly rate (applicable for hourly employees).
timeType string Compensation type: Salaried or Hourly.
payrollGroup string Payroll group identifier.
payrollArea string Payroll area or region code.
personnelSubArea string Personnel sub-area or office location.

The body is an array — you can submit multiple employees in a single request.

Step 4: Upload Payroll Receipt

The receipt contains the actual payment records for a given pay period. LAW uses this data to confirm loan repayment deductions were processed.

Request

POST https://sandbox.bmgmoney.com/law/api/v1/receipt
Authorization: Bearer <access_token>
Content-Type: application/json

[
  {
    "LastName": "Inacio",
    "FirstName": "Paulo",
    "Ssn": "470352718",
    "EmployeeRegistration": "30000",
    "PaymentDate": "2026-01-02",
    "Amount": 20323.20
  }
]
Field Type Description
LastName / FirstName string Employee's full name as it appears in payroll.
Ssn string Employee's Social Security Number (digits only).
EmployeeRegistration string Your internal employee ID, must match the census record.
PaymentDate string (ISO 8601) The date the payment was made (YYYY-MM-DD).
Amount number Net disbursed amount for this pay period.

The body is an array — submit all employees for the pay period in a single request.

Step 5: Monitor Deliveries

After uploading files, you can poll the deliveries endpoint to track processing status.

Request

GET https://sandbox.bmgmoney.com/law/api/v1/deliveries?limit=20
Authorization: Bearer <access_token>
Query Parameter Description
limit Maximum number of records to return per page.

This endpoint returns a list of file delivery records, including their current processing status.

Complete Integration Flow

Sandbox vs Production

All examples in this guide use the Sandbox base URL:

https://sandbox.bmgmoney.com

Once your integration is validated, your partner contact will provide the Production base URL and credentials.

Previous
Authentication
Next
Overview