Pay Ops cookbook

Applies to:DevelopersPartnersPaypoints

Use these recipes to get started with Pay Ops features and functions. See Pay Ops overview for more.

New to the API? Start with the authentication guide on the cookbooks home.

/// Overview

Register a webhook so Payabli notifies your server in real time when an event occurs. This recipe creates a single subscription for one event type.

/// Prerequisites

Before you start, make sure you have the following:

A publicly accessible URL that accepts POST requests. Supported ports are 80, 443, 8080, and 4443. For local development, see the webhook quickstart for tunneling setup.
An eventType to subscribe to. See the webhooks reference for all available events.
The ownerId of the paypoint or organization that owns the notification, plus its matching ownerType: 0 for organization or 2 for paypoint.

/// Step 1: Create the webhook subscription

Send a POST request to /api/Notification.

curl -X POST "https://api.payabli.com/api/Notification" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "content": {
      "eventType": "approvedpayment"
    },
    "frequency": "untilcancelled",
    "method": "web",
    "ownerId": 236,
    "ownerType": 0,
    "status": 1,
    "target": "https://your-server.example.com/webhook"
  }'

The response returns the notificationId in responseData. Save this — you need it to update or delete the subscription later.

{
  "isSuccess": true,
  "responseCode": 1,
  "responseData": 1717,
  "responseText": "Success"
}

See Create notification for the full API reference.

/// What’s next

You’re now subscribed. Trigger the event to see a payload land on your server. Learn more about webhook payloads and managing notifications.

Recipe: Handle return and chargeback webhooks

/// Overview

Get notified when an ACH debit is returned or a card payment is charged back by subscribing to the receivedachreturn and receivedchargeback webhooks. Payabli posts a payload to your server for each event so you can respond.

/// Prerequisites

Before you start, make sure you have the following:

A publicly accessible URL that accepts POST requests. Supported ports are 80, 443, 8080, and 4443. For local development, see the webhooks quickstart for tunneling setup.
The ownerId of the organization or paypoint that owns the transactions, plus its matching ownerType: 0 for organization or 2 for paypoint.

/// Step 1: Subscribe to the ACH return and chargeback events

Register a webhook for each event. Send the request once with eventType set to receivedachreturn, then again with receivedchargeback.

Send a POST request to /api/Notification.

curl -X POST "https://api.payabli.com/api/Notification" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "content": {
      "eventType": "receivedachreturn"
    },
    "frequency": "untilcancelled",
    "method": "web",
    "ownerId": 236,
    "ownerType": 0,
    "status": 1,
    "target": "https://your-server.example.com/webhook"
  }'

Each call returns its notificationId in responseData. Save both so you can update or delete the subscriptions later.

{
  "responseCode": 1,
  "pageIdentifier": null,
  "roomId": 0,
  "isSuccess": true,
  "responseText": "Success",
  "responseData": 385009
}

See Create notification for the full API reference.

/// Step 2: Handle the payloads

Payabli sends the ReceivedAchReturn payload when an ACH debit is returned, and the ReceivedChargeBack payload when a card payment is charged back. In both, ReasonCode and Reason carry the return or chargeback reason, transId references the original transaction, and chargebackID identifies the case.

An ACH return payload carries the Nacha return code in ReasonCode (for example, R01 for insufficient funds), and the case ID in chargebackID.

-8,14

{
  "Event": "ReceivedAchReturn",
  "Paypoint": "Gruzya Adventure Outfitters",
  "AccountType": "checking",
  "Text": "ACH Return Received",
  "Method": "ACH",
  "ReasonCode": "R01",
  "Reason": "Insufficient Funds",
  "transId": "10000-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
  "NetAmount": "150.00",
  "chargebackTime": "6/10/2025 2:22:45 PM",
  "CustomerId": "4440",
  "CustomerNumber": "C-90010",
  "chargebackID": 4401,
  "ExternalPaypointId": "ext-pp-001"
}

A chargeback payload carries the card network’s reason code in ReasonCode, a description in Reason, and the case ID in chargebackID.

-9,15

{
  "Event": "ReceivedChargeBack",
  "Paypoint": "Gruzya Adventure Outfitters",
  "AccountType": "mastercard",
  "Text": "Chargeback Received",
  "Method": "card",
  "WalletType": null,
  "ReasonCode": "4853",
  "Reason": "Cardholder Dispute",
  "transId": "10000-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
  "NetAmount": "3.88",
  "chargebackTime": "2/15/2026 12:00:00 AM",
  "CustomerId": "4440",
  "CustomerNumber": "C-90010",
  "chargebackID": 52094,
  "ExternalPaypointId": "ext-pp-001"
}

Respond with a 200 status code to acknowledge receipt. If your server doesn’t acknowledge, Payabli retries delivery.

See the webhooks reference for the full API reference.

/// What’s next

You’re now notified of returns and chargebacks in real time. Next, retrieve and manage chargebacks with the API, or learn how to respond to ACH returns.

Recipe: Set up payment notification webhooks

/// Overview

Get notified as a payment moves through its lifecycle by subscribing to Payabli’s payment webhooks. Payabli posts a payload to your server for each event, so you can track approvals, declines, settlement, and funding in real time.

/// Prerequisites

Before you start, make sure you have the following:

A publicly accessible URL that accepts POST requests. Supported ports are 80, 443, 8080, and 4443. For local development, see the webhooks quickstart for tunneling setup.
The ownerId of the organization or paypoint that owns the transactions, plus its matching ownerType: 0 for organization or 2 for paypoint.

/// Step 1: Subscribe to each payment event

Register a webhook for each event you want to receive. Send the request once per eventType. The core payment lifecycle events are:

approvedpayment — a payment is approved
declinedpayment — a payment is declined
settledpayment — a payment settles in a batch
fundedpayment — Payabli deposits the funds to the paypoint

Send a POST request to /api/Notification.

curl -X POST "https://api.payabli.com/api/Notification" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "content": {
      "eventType": "approvedpayment"
    },
    "frequency": "untilcancelled",
    "method": "web",
    "ownerId": 236,
    "ownerType": 0,
    "status": 1,
    "target": "https://your-server.example.com/webhook"
  }'

Each call returns its notificationId in responseData. Save these so you can update or delete the subscriptions later.

{
  "responseCode": 1,
  "pageIdentifier": null,
  "roomId": 0,
  "isSuccess": true,
  "responseText": "Success",
  "responseData": 385012
}

See Create notification for the full API reference.

/// Step 2: Handle the payload

Payabli sends a payload matching each event. Branch on the Event field to tell which lifecycle stage fired, and use transId to reference the transaction. Approval and decline payloads also carry ResultCode (A0000 means approved). This example shows the ApprovedPayment payload.

,18

{
  "Event": "ApprovedPayment",
  "Paypoint": "Gruzya Adventure Outfitters",
  "Text": "Payment Approved!",
  "transId": "10000-1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
  "NetAmount": "5.64",
  "Fee": "0.00",
  "TotalAmount": "5.64",
  "transTime": "5/22/2026 8:02:39 AM",
  "CustomerId": "4440",
  "CustomerNumber": "C-90010",
  "Method": "card",
  "WalletType": null,
  "EntryPoint": "8cfec329267",
  "ExternalPaypointId": "ext-pp-001",
  "ResponseCode": "100",
  "ResponseCodeText": "Operation successful.",
  "ResultCode": "A0000",
  "ResultCodeText": "Approved"
}

Respond with a 200 status code to acknowledge receipt. If your server doesn’t acknowledge, Payabli retries delivery.

See the webhooks reference for the full API reference.

/// What’s next

You’re now tracking payments in real time. Subscribe to related events such as authorizedpayment and refundedpayment the same way, or manage your notifications.

Recipe: Retrieve ACH returns

/// Overview

Retrieve a list of ACH returns for a paypoint to monitor failed ACH debits and respond to return codes. The disputes endpoint returns both card chargebacks and ACH returns, so this recipe filters by payment method to return ACH-side records only.

/// Prerequisites

Before you start, make sure you have the following:

Your paypoint’s entrypoint identifier
An API token with access to the paypoint. See the authentication recipe for help

/// List ACH returns for the paypoint

Query the disputes endpoint with a method filter of ach to exclude card chargebacks from the results. Filtering on method (instead of status) keeps the request robust to the different status values an ACH return can carry, including R29 returns and any legacy records.

Send a GET request to /api/Query/chargebacks/{entry}.

curl -X GET "https://api.payabli.com/api/Query/chargebacks/your-entry-point?method(eq)=ach&limitRecord=20&fromRecord=0" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

The response includes one record per ACH return. The ReasonCode field contains the Nacha return code (for example, R01 for insufficient funds), Reason contains the human-readable explanation, and Transaction contains the original ACH transaction details.

-18,30-36

{
  "Summary": {
    "totalRecords": 1,
    "totalAmount": 250.00,
    "totalNetAmount": 250.00,
    "totalPages": 1,
    "pageSize": 20
  },
  "Records": [
    {
      "Id": 612,
      "Method": "ach",
      "Status": 4,
      "ChargebackDate": "2026-04-22T00:00:00Z",
      "CreatedAt": "2026-04-22T14:18:03Z",
      "NetAmount": 250.00,
      "Reason": "Insufficient Funds",
      "ReasonCode": "R01",
      "AccountType": "XXXXXX1234",
      "LastFour": "XXXXXX1234",
      "PaymentTransId": "10-bfcd5a17861d4a8690ca53c00000X",
      "PaypointEntryname": "your-entry-point",
      "PaypointDbaname": "Big Sky Imports",
      "Customer": {
        "customerId": 1324,
        "FirstName": "Janis",
        "LastName": "Berzins",
        "BillingEmail": "janis.berzins@example.com"
      },
      "Transaction": {
        "Method": "ach",
        "Operation": "Sale",
        "TotalAmount": 250.00,
        "NetAmount": 250.00,
        "TransactionTime": "2026-04-18T09:32:11Z",
        "PaymentTransId": "10-bfcd5a17861d4a8690ca53c00000X"
      }
    }
  ]
}

See List disputes by paypoint for the full API reference, including all available filters and pagination options.

/// What’s next

You’ve retrieved ACH returns for a paypoint. To resolve them, see Managing merchant ACH debit failures and returns and the ACH return codes reference. To get notified when a return comes in, subscribe to the ReceivedAchReturn webhook event.

Recipe: Roll up stats across an organization

/// Overview

Roll up aggregate statistics for an organization in a single call. The response covers transaction counts and volume by method, chargebacks, returns, and new vs existing customers. Then drill into a single paypoint using the same endpoint. This recipe is for parent organizations managing multiple paypoints.

/// Prerequisites

Before you start, make sure you have the following:

Your orgId (the Payabli identifier for the organization)
An API token with access to the organization. See the authentication recipe for help.
A paypointId for one of the paypoints in the organization, if you plan to drill in (Step 2)

The endpoint uses a single path that flips between scopes via the level path parameter: 0 for an organization, 2 for a paypoint. The entryId segment is the corresponding orgId or paypointId.

/// Step 1: Get organization-level stats

Send a GET request to /api/Statistic/basic/{mode}/{freq}/{level}/{entryId} with level=0 and your orgId. This example pulls last month’s totals as a single bucket (mode=lastm, freq=m).

curl -X GET "https://api.payabli.com/api/Statistic/basic/lastm/m/0/236" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

The response is an array with one entry per bucket. The in* fields aggregate Pay In activity across every paypoint in the organization; the out* fields aggregate Pay Out activity. Use these to compare volume by method, spot chargebacks and ACH returns, or feed dashboards.

[
  {
    "statX": "2026-04",
    "inTransactions": 168204,
    "inTransactionsVolume": 104795896.94,
    "inCardVolume": 41085285.13,
    "inACHVolume": 63706101.81,
    "inCardChargeBacks": 17,
    "inCardChargeBackVolume": 15455.75,
    "inACHReturns": 0,
    "inACHReturnsVolume": 0.0,
    "outTransactions": 3319,
    "outTransactionsVolume": 13111741.78,
    "inCustomers": 2561522,
    "inNewCustomers": 44846
  }
]

Other modes you can swap in for lastm:

ytd (year to date)
m12 (last 12 months)
d30 (last 30 days)
lastw (last week)
yesterday
custom with startDate and endDate query parameters

Change freq to w, d, or h to break the same range into smaller buckets.

See Get stats for an org or paypoint for the full API reference.

/// Step 2: Drill into a single paypoint

For example, to investigate the paypoint driving most of the chargeback volume, change level to 2 and pass that paypoint’s paypointId as entryId. Every other parameter stays the same.

curl -X GET "https://api.payabli.com/api/Statistic/basic/lastm/m/2/1000000" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

The response shape is identical to Step 1, scoped to the single paypoint. Compare values against the org-level roll-up to see how much of the total comes from this paypoint.

[
  {
    "statX": "2026-04",
    "inTransactions": 8420,
    "inTransactionsVolume": 5212450.30,
    "inCardChargeBacks": 12,
    "inCardChargeBackVolume": 9840.50
  }
]

See Get stats for an org or paypoint for the full API reference.

/// What’s next

You’ve rolled up org-level stats and drilled into one paypoint. To learn how the statistics and query endpoints fit together, see Use reporting endpoints. For record-level investigation, try Query transactions with filters.

Recipe: Track processing stats over time

/// Overview

Pull processing statistics over time for an organization or paypoint. The Basic statistics endpoint returns one row per time bucket, covering approved-transaction counts and volume (net of fees), so you can build a processing trend.

/// Prerequisites

Before you start, make sure you have the following:

Your orgId (for level=0) or paypointId (for level=2)
An OAuth2 access token for the organization or paypoint. See the authentication recipe for help.
A mode for the date range (such as m12 for the last 12 months) and a freq to group the buckets (m, w, d, or h)

/// Get processing stats over time

Send a GET request to /api/Statistic/basic/{mode}/{freq}/{level}/{entryId}. This example pulls monthly buckets for the last 12 months of an organization (mode=m12, freq=m, level=0).

curl -X GET "https://api.payabli.com/api/Statistic/basic/m12/m/0/236" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

The response is an array with one object per time bucket. Each bucket carries about 40 fields. The abbreviated example below shows the key ones. statX is the bucket label (YYYY-MM for monthly), the in* fields cover Pay In counts and volume, and the out* fields cover Pay Out.

-7

[
  {
    "outTransactions": 2,
    "outTransactionsVolume": 94,
    "statX": "2025-09",
    "inTransactions": 56,
    "inTransactionsVolume": 32740.76,
    "inCardTransactions": 56,
    "inACHTransactions": 0,
    "inCardChargeBacks": 0,
    "inACHReturns": 0
  }
]

The array continues with one bucket per period: m12 returns 13 (the last 12 months plus the current partial month). Sort or chart the buckets by statX to plot the trend.

See Get stats for an org or paypoint for the full API reference.

/// What’s next

Switch level to 2 with a paypointId to trend a single paypoint, or change freq to d or w for finer buckets. For a single-period snapshot instead, see Roll up stats across an organization.

Recipe: Subscribe to webhooks

Recipe: Handle return and chargeback webhooks

Recipe: Set up payment notification webhooks

Recipe: Retrieve ACH returns

Recipe: Roll up stats across an organization

Recipe: Track processing stats over time