Load your first book

A book is all the open Receivables in your source system. This guide loads a small book with one batch. It uses the sandbox and synthetic data. Finish the quickstart first so you have a key and a clientCode. Terms are in the glossary.

Before you load

Choose a stable, opaque external ID for every Customer and Receivable. Do not use member numbers or loan numbers.
Plan the order. A Receivable can reference only Customers that already exist, so list Customers first.
Decide your retry rule. A batch is safe to resend with the same ID and body. See Safe retries.

Step 1: Queue a batch

A batch holds up to 100 records. Each record is { recordId, kind, externalId, body }. The body is exactly the body of the matching single-record PUT. Use dependsOn so a Receivable runs only if its Customer succeeded.

curl --include \
  --request PUT \
  --url "$PAYPATHIQ_BASE_URL/v1/clients/$PAYPATHIQ_CLIENT_CODE/batches/BAT_FIRST_LOAD" \
  --header "Authorization: Bearer $PAYPATHIQ_SANDBOX_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "records": [
      {
        "recordId": "r1",
        "kind": "customer",
        "externalId": "CUS_B001",
        "body": {
          "type": "person",
          "name": { "firstName": "Avery", "lastName": "Example" }
        }
      },
      {
        "recordId": "r2",
        "kind": "receivable",
        "externalId": "REC_B001",
        "dependsOn": ["r1"],
        "body": {
          "financialType": "loan_balance",
          "sourceRevision": 1,
          "sourceReference": "receivable-ref-b001",
          "responsibleCustomers": [{ "externalCustomerId": "CUS_B001", "role": "primary" }],
          "recoverableAmount": { "amount": "1250.00", "currency": "EUR" },
          "dueDate": "2026-08-01",
          "creditUnion": {
            "loanAccountReference": "loan-ref-b001",
            "loanType": "personal_loan",
            "arrearsAmount": { "amount": "1250.00", "currency": "EUR" }
          }
        }
      }
    ]
  }'

const base = "https://api.sandbox.paypathiq.com";
const clientCode = process.env.PAYPATHIQ_CLIENT_CODE;
const headers = {
  Authorization: `Bearer ${process.env.PAYPATHIQ_SANDBOX_API_KEY}`,
  "Content-Type": "application/json",
};

const response = await fetch(`${base}/v1/clients/${clientCode}/batches/BAT_FIRST_LOAD`, {
  method: "PUT",
  headers,
  body: JSON.stringify({
    records: [
      {
        recordId: "r1",
        kind: "customer",
        externalId: "CUS_B001",
        body: { type: "person", name: { firstName: "Avery", lastName: "Example" } },
      },
      {
        recordId: "r2",
        kind: "receivable",
        externalId: "REC_B001",
        dependsOn: ["r1"],
        body: {
          financialType: "loan_balance",
          sourceRevision: 1,
          sourceReference: "receivable-ref-b001",
          responsibleCustomers: [{ externalCustomerId: "CUS_B001", role: "primary" }],
          recoverableAmount: { amount: "1250.00", currency: "EUR" },
          dueDate: "2026-08-01",
          creditUnion: {
            loanAccountReference: "loan-ref-b001",
            loanType: "personal_loan",
            arrearsAmount: { amount: "1250.00", currency: "EUR" },
          },
        },
      },
    ],
  }),
});
console.log(response.status, await response.json());

import os
import requests

base = "https://api.sandbox.paypathiq.com"
client_code = os.environ["PAYPATHIQ_CLIENT_CODE"]
headers = {"Authorization": f"Bearer {os.environ['PAYPATHIQ_SANDBOX_API_KEY']}"}

response = requests.put(
    f"{base}/v1/clients/{client_code}/batches/BAT_FIRST_LOAD",
    headers=headers,
    json={
        "records": [
            {
                "recordId": "r1",
                "kind": "customer",
                "externalId": "CUS_B001",
                "body": {"type": "person", "name": {"firstName": "Avery", "lastName": "Example"}},
            },
            {
                "recordId": "r2",
                "kind": "receivable",
                "externalId": "REC_B001",
                "dependsOn": ["r1"],
                "body": {
                    "financialType": "loan_balance",
                    "sourceRevision": 1,
                    "sourceReference": "receivable-ref-b001",
                    "responsibleCustomers": [{"externalCustomerId": "CUS_B001", "role": "primary"}],
                    "recoverableAmount": {"amount": "1250.00", "currency": "EUR"},
                    "dueDate": "2026-08-01",
                    "creditUnion": {
                        "loanAccountReference": "loan-ref-b001",
                        "loanType": "personal_loan",
                        "arrearsAmount": {"amount": "1250.00", "currency": "EUR"},
                    },
                },
            },
        ]
    },
    timeout=30,
)
print(response.status_code, response.json())

Expect 202 Accepted. That means the batch is durably queued. It does not mean any record was accepted. The batch needs the write scope for every kind of record in it, here customers:write and receivables:write. A connection can have at most 2 queued or running batches at once.

Step 2: Check progress

Send a GET to the same URL until the batch status is no longer queued or running.

curl --url "$PAYPATHIQ_BASE_URL/v1/clients/$PAYPATHIQ_CLIENT_CODE/batches/BAT_FIRST_LOAD" \
  --header "Authorization: Bearer $PAYPATHIQ_SANDBOX_API_KEY"

The final status is succeeded, partially_succeeded or failed. Each record reports succeeded, failed (with the httpStatus and problem.type a single request would return), dependency_failed or pending.

Step 3: Fix failures

Fix the data for any failed record. Send it again in a new batch, or through its single-record PUT. A record marked dependency_failed was not attempted, because the record it depends on did not succeed.

Step 4: Declare the book complete (optional)

Leaving a Receivable out of a batch changes nothing. If you want PayPathIQ to flag open Receivables that are missing from your book, declare it complete after every batch has succeeded. See Complete books and missing records. A declaration needs the batch IDs and the exact Receivable count, and a failed or partial load is refused with 409 book_completion_unverified.

Getting started

Integration guides

Reliability and sync

Going live

Error reference

Before you load

Step 1: Queue a batch

Step 2: Check progress

Step 3: Fix failures

Step 4: Declare the book complete (optional)

Next steps

​Before you load

​Step 1: Queue a batch

​Step 2: Check progress

​Step 3: Fix failures

​Step 4: Declare the book complete (optional)

​Next steps

Before you load

Step 1: Queue a batch

Step 2: Check progress

Step 3: Fix failures

Step 4: Declare the book complete (optional)

Next steps