Events API

Overview

The Events API allows external integrations to push data updates into Paystar. This is useful for syncing customer information changes or managing autopay enrollment from your own systems.

Two event types are currently supported:

• Accounts.ManageCustomer — Create or update customer account information
• Accounts.UnenrollAutopay — Unenroll a customer from autopay

Authentication

All requests must include your API key in the X-Paystar-Api-Key header.

X-Paystar-Api-Key: your-api-key-here

Endpoints

Environment	URL
PROD	https://gateway.paystar.io/integrations/events
DEV	https://dev-gateway.paystar.io/integrations/events

Request Format

All requests are sent as POST with a JSON body containing three fields:

Field	Type	Description
eventType	string	The event type (e.g. Accounts.ManageCustomer)
payload	string	A serialized JSON string containing event data
businessUnitSlug	string	The slug identifying the target business unit

info

The payload field must be a serialized JSON string, not a raw JSON object. You must JSON.stringify() (or equivalent) your payload object before including it in the request body.

Accounts.ManageCustomer

Creates or updates a customer account in Paystar. If an account with the given accountNumber already exists, it will be updated; otherwise, a new account is created.

Payload Fields

Field	Type	Required	Description
accountNumber	string	Yes	The customer's account number
subAccountNumber	string	Yes	Sub-account number (use empty string "" if not applicable)
firstName	string	Yes	Customer's first name
lastName	string	Yes	Customer's last name
emailAddress	string	Yes	Customer's email address
originalEmailAddress	string	No	Previous email address (used when updating an email)

note

originalEmailAddress is only needed when changing a customer's email. It identifies the existing record to update. Omit it when creating a new customer or when the email is not changing.

Accounts.UnenrollAutopay

Unenrolls a customer from autopay for a given account.

Payload Fields

Field	Type	Required	Description
accountNumber	string	Yes	The customer's account number
subAccountNumber	string	Yes	Sub-account number (use empty string "" if not applicable)

note

If the business unit does not use sub-account numbers, pass an empty string "" for subAccountNumber.

Examples

cURL

Accounts.ManageCustomer

curl -X POST https://gateway.paystar.io/integrations/events \
  -H "Content-Type: application/json" \
  -H "X-Paystar-Api-Key: your-api-key-here" \
  -d '{
    "eventType": "Accounts.ManageCustomer",
    "businessUnitSlug": "water-bill-pay",
    "payload": "{\"accountNumber\":\"12345\",\"subAccountNumber\":\"\",\"firstName\":\"John\",\"lastName\":\"Smith\",\"emailAddress\":\"[email protected]\"}"
  }'

Accounts.UnenrollAutopay

curl -X POST https://gateway.paystar.io/integrations/events \
  -H "Content-Type: application/json" \
  -H "X-Paystar-Api-Key: your-api-key-here" \
  -d '{
    "eventType": "Accounts.UnenrollAutopay",
    "businessUnitSlug": "water-bill-pay",
    "payload": "{\"accountNumber\":\"12345\",\"subAccountNumber\":\"\"}"
  }'

C#

Accounts.ManageCustomer

using System.Net.Http;
using System.Text;
using System.Text.Json;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-Paystar-Api-Key", "your-api-key-here");

var payload = JsonSerializer.Serialize(new
{
    accountNumber = "12345",
    subAccountNumber = "",
    firstName = "John",
    lastName = "Smith",
    emailAddress = "[email protected]"
});

var body = JsonSerializer.Serialize(new
{
    eventType = "Accounts.ManageCustomer",
    businessUnitSlug = "water-bill-pay",
    payload = payload
});

var response = await client.PostAsync(
    "https://gateway.paystar.io/integrations/events",
    new StringContent(body, Encoding.UTF8, "application/json")
);

Accounts.UnenrollAutopay

var payload = JsonSerializer.Serialize(new
{
    accountNumber = "12345",
    subAccountNumber = ""
});

var body = JsonSerializer.Serialize(new
{
    eventType = "Accounts.UnenrollAutopay",
    businessUnitSlug = "water-bill-pay",
    payload = payload
});

var response = await client.PostAsync(
    "https://gateway.paystar.io/integrations/events",
    new StringContent(body, Encoding.UTF8, "application/json")
);

---

See the Events API Spec for the full OpenAPI specification.