Sandbox quickstart

This quickstart makes a keyless call to check the API is reachable. Then it creates a Customer and Receivable, records a Payment received outside PayPathIQ, and pauses the Receivable. Use synthetic data only. For source-system mapping and expected balances at each step, see the credit-union walkthrough. New to the terms? See the glossary.

Before you start, you need:

A PayPathIQ login with API access, to create a sandbox key. See Get a sandbox key.
Your clientCode. It is shown next to the Client name when you create the key.
A shell with curl, or Node.js 18 or later, or Python 3 with requests.

Set up

Store the key in your secret manager and inject it as PAYPATHIQ_SANDBOX_API_KEY. Set your Client code as PAYPATHIQ_CLIENT_CODE. Sandbox keys have every scope this quickstart needs. Run the steps one at a time. Each key can run only one request at a time, and a second concurrent request returns 429 rate_limit_exceeded. The suffix keeps the immutable Payment observation and other resources independent from earlier runs. Run the setup once for each walkthrough.

export PAYPATHIQ_BASE_URL=https://api.sandbox.paypathiq.com
export PAYPATHIQ_CLIENT_CODE=YOUR_CLIENT_CODE
PAYPATHIQ_RUN_SUFFIX="$(date -u +%Y%m%dT%H%M%SZ)-$$"
PAYPATHIQ_CUSTOMER_ID="CUS_$PAYPATHIQ_RUN_SUFFIX"
PAYPATHIQ_RECEIVABLE_ID="REC_$PAYPATHIQ_RUN_SUFFIX"
PAYPATHIQ_PAYMENT_ID="PAY_$PAYPATHIQ_RUN_SUFFIX"

// Save as quickstart.mjs and run: node quickstart.mjs
const base = "https://api.sandbox.paypathiq.com";
const clientCode = process.env.PAYPATHIQ_CLIENT_CODE;
const suffix = new Date().toISOString().replace(/[-:.]/g, "");
const customerId = `CUS_${suffix}`;
const receivableId = `REC_${suffix}`;
const paymentId = `PAY_${suffix}`;

// Sends one request, prints the status and request ID, returns the JSON body.
async function call(method, path, body) {
  const response = await fetch(`${base}/v1${path}`, {
    method,
    headers: {
      Authorization: `Bearer ${process.env.PAYPATHIQ_SANDBOX_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: body && JSON.stringify(body),
  });
  console.log(response.status, response.headers.get("x-request-id"));
  return response.json();
}

# Save as quickstart.py and run: python quickstart.py
import os
from datetime import datetime, timezone

import requests

base = "https://api.sandbox.paypathiq.com"
client_code = os.environ["PAYPATHIQ_CLIENT_CODE"]
suffix = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
customer_id = f"CUS_{suffix}"
receivable_id = f"REC_{suffix}"
payment_id = f"PAY_{suffix}"


def call(method, path, body=None):
    """Send one request, print the status and request ID, return the JSON body."""
    response = requests.request(
        method,
        f"{base}/v1{path}",
        headers={"Authorization": f"Bearer {os.environ['PAYPATHIQ_SANDBOX_API_KEY']}"},
        json=body,
        timeout=30,
    )
    print(response.status_code, response.headers.get("x-request-id"))
    return response.json()

Do not use member numbers, loan or account numbers, contact details, or other sensitive values as URL identifiers. Use stable opaque IDs from your integration mapping.

Check the API is reachable

The OpenAPI contract needs no API key. This call proves you can reach the sandbox.

curl --include "$PAYPATHIQ_BASE_URL/v1/openapi.json"

const hello = await fetch(`${base}/v1/openapi.json`);
console.log(hello.status, (await hello.json()).info.title);

hello = requests.get(f"{base}/v1/openapi.json", timeout=30)
print(hello.status_code, hello.json()["info"]["title"])

Expect 200 OK and a paypathiq-api-version: v1 header. The body is the OpenAPI document, which begins:

{ "openapi": "3.1.0", "info": { "title": "PayPathIQ Inbound Receivables API", "version": "1.0.0" } }

Create a Customer

A Customer must exist before a Receivable can reference it.

curl --include \
  --request PUT \
  --url "$PAYPATHIQ_BASE_URL/v1/clients/$PAYPATHIQ_CLIENT_CODE/customers/$PAYPATHIQ_CUSTOMER_ID" \
  --header "Authorization: Bearer $PAYPATHIQ_SANDBOX_API_KEY" \
  --header 'Content-Type: application/json' \
  --data "$(cat <<JSON
  {
    "type": "person",
    "name": { "firstName": "Avery", "lastName": "Example" },
    "sourceReference": "member-ref-$PAYPATHIQ_RUN_SUFFIX",
    "contacts": [{
      "externalContactId": "CON_$PAYPATHIQ_RUN_SUFFIX",
      "fullName": "Avery Example",
      "isCustomerSelf": true,
      "isMain": true,
      "email": { "address": "avery@example.test", "type": "personal" }
    }]
  }
JSON
)"

console.log(await call("PUT", `/clients/${clientCode}/customers/${customerId}`, {
  type: "person",
  name: { firstName: "Avery", lastName: "Example" },
  sourceReference: `member-ref-${suffix}`,
  contacts: [{
    externalContactId: `CON_${suffix}`,
    fullName: "Avery Example",
    isCustomerSelf: true,
    isMain: true,
    email: { address: "avery@example.test", type: "personal" },
  }],
}));

print(call("PUT", f"/clients/{client_code}/customers/{customer_id}", {
    "type": "person",
    "name": {"firstName": "Avery", "lastName": "Example"},
    "sourceReference": f"member-ref-{suffix}",
    "contacts": [{
        "externalContactId": f"CON_{suffix}",
        "fullName": "Avery Example",
        "isCustomerSelf": True,
        "isMain": True,
        "email": {"address": "avery@example.test", "type": "personal"},
    }],
}))

Expect 201 Created and the saved Customer (trimmed):

{ "externalCustomerId": "CUS_20261016T101500Z", "type": "person", "name": { "firstName": "Avery", "lastName": "Example" }, "updatedAt": "2026-10-16T10:15:00Z" }

Repeating the identical request returns 200 OK without creating another revision. See Safe retries.

Create a Receivable

recoverableAmount is the posted source obligation balance. Importing it does not grant recovery authority. Use an approved loan-profile connection for this example.

curl --include \
  --request PUT \
  --url "$PAYPATHIQ_BASE_URL/v1/clients/$PAYPATHIQ_CLIENT_CODE/receivables/$PAYPATHIQ_RECEIVABLE_ID" \
  --header "Authorization: Bearer $PAYPATHIQ_SANDBOX_API_KEY" \
  --header 'Content-Type: application/json' \
  --data "$(cat <<JSON
  {
    "financialType": "loan_balance",
    "sourceRevision": 1,
    "sourceReference": "receivable-ref-$PAYPATHIQ_RUN_SUFFIX",
    "responsibleCustomers": [{
      "externalCustomerId": "$PAYPATHIQ_CUSTOMER_ID",
      "role": "primary"
    }],
    "recoverableAmount": { "amount": "1250.00", "currency": "EUR" },
    "dueDate": "2026-08-01",
    "creditUnion": {
      "loanAccountReference": "loan-ref-$PAYPATHIQ_RUN_SUFFIX",
      "loanType": "personal_loan",
      "arrearsAmount": { "amount": "1250.00", "currency": "EUR" }
    }
  }
JSON
)"

console.log(await call("PUT", `/clients/${clientCode}/receivables/${receivableId}`, {
  financialType: "loan_balance",
  sourceRevision: 1,
  sourceReference: `receivable-ref-${suffix}`,
  responsibleCustomers: [{ externalCustomerId: customerId, role: "primary" }],
  recoverableAmount: { amount: "1250.00", currency: "EUR" },
  dueDate: "2026-08-01",
  creditUnion: {
    loanAccountReference: `loan-ref-${suffix}`,
    loanType: "personal_loan",
    arrearsAmount: { amount: "1250.00", currency: "EUR" },
  },
}));

print(call("PUT", f"/clients/{client_code}/receivables/{receivable_id}", {
    "financialType": "loan_balance",
    "sourceRevision": 1,
    "sourceReference": f"receivable-ref-{suffix}",
    "responsibleCustomers": [{"externalCustomerId": customer_id, "role": "primary"}],
    "recoverableAmount": {"amount": "1250.00", "currency": "EUR"},
    "dueDate": "2026-08-01",
    "creditUnion": {
        "loanAccountReference": f"loan-ref-{suffix}",
        "loanType": "personal_loan",
        "arrearsAmount": {"amount": "1250.00", "currency": "EUR"},
    },
}))

Expect 201 Created and the saved Receivable (trimmed):

{ "externalReceivableId": "REC_20261016T101500Z", "financialType": "loan_balance", "sourceRevision": 1, "recoverableAmount": { "amount": "1250.00", "currency": "EUR" }, "status": "active" }

A missing Customer returns 409 dependency_missing. PayPathIQ does not guess or queue the relationship.

Record a Payment observation

Use a Payment observation only for money received outside PayPathIQ. It is immutable evidence, not an instruction to collect a payment.

curl --include \
  --request PUT \
  --url "$PAYPATHIQ_BASE_URL/v1/clients/$PAYPATHIQ_CLIENT_CODE/payment-observations/$PAYPATHIQ_PAYMENT_ID" \
  --header "Authorization: Bearer $PAYPATHIQ_SANDBOX_API_KEY" \
  --header 'Content-Type: application/json' \
  --data "$(cat <<JSON
  {
    "type": "payment",
    "amount": { "amount": "250.00", "currency": "EUR" },
    "allocations": [{
      "externalReceivableId": "$PAYPATHIQ_RECEIVABLE_ID",
      "amount": { "amount": "250.00", "currency": "EUR" }
    }],
    "effectiveAt": "2026-09-21T12:00:00Z",
    "method": "bank_transfer",
    "sourceReference": "payment-ref-$PAYPATHIQ_RUN_SUFFIX"
  }
JSON
)"

console.log(await call("PUT", `/clients/${clientCode}/payment-observations/${paymentId}`, {
  type: "payment",
  amount: { amount: "250.00", currency: "EUR" },
  allocations: [{
    externalReceivableId: receivableId,
    amount: { amount: "250.00", currency: "EUR" },
  }],
  effectiveAt: "2026-09-21T12:00:00Z",
  method: "bank_transfer",
  sourceReference: `payment-ref-${suffix}`,
}));

print(call("PUT", f"/clients/{client_code}/payment-observations/{payment_id}", {
    "type": "payment",
    "amount": {"amount": "250.00", "currency": "EUR"},
    "allocations": [{
        "externalReceivableId": receivable_id,
        "amount": {"amount": "250.00", "currency": "EUR"},
    }],
    "effectiveAt": "2026-09-21T12:00:00Z",
    "method": "bank_transfer",
    "sourceReference": f"payment-ref-{suffix}",
}))

Expect 201 Created and the accepted observation (trimmed):

{ "externalPaymentObservationId": "PAY_20261016T101500Z", "type": "payment", "amount": { "amount": "250.00", "currency": "EUR" }, "allocations": [{ "externalReceivableId": "REC_20261016T101500Z", "amount": { "amount": "250.00", "currency": "EUR" } }] }

An allocation larger than the locked current balance fails atomically with 409 allocation_exceeds_balance. Unallocated money stays unapplied.

Pause the Receivable

Lifecycle changes use explicit commands rather than ordinary status fields.

curl --include \
  --request POST \
  --url "$PAYPATHIQ_BASE_URL/v1/clients/$PAYPATHIQ_CLIENT_CODE/receivables/$PAYPATHIQ_RECEIVABLE_ID/pause" \
  --header "Authorization: Bearer $PAYPATHIQ_SANDBOX_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{ "effectiveAt": "2026-09-21T12:05:00Z", "reason": "client_instruction" }'

console.log(await call("POST", `/clients/${clientCode}/receivables/${receivableId}/pause`, {
  effectiveAt: "2026-09-21T12:05:00Z",
  reason: "client_instruction",
}));

print(call("POST", f"/clients/{client_code}/receivables/{receivable_id}/pause", {
    "effectiveAt": "2026-09-21T12:05:00Z",
    "reason": "client_instruction",
}))

Expect 200 OK and the Receivable with "status": "paused".Clear-pause, close, and reopen are separate commands. Clearing a pause or reopening never resumes recovery automation automatically.

Verify the resulting record

Read the Integration-facing Receivable back with GET.

curl --include --silent --show-error \
  --url "$PAYPATHIQ_BASE_URL/v1/clients/$PAYPATHIQ_CLIENT_CODE/receivables/$PAYPATHIQ_RECEIVABLE_ID" \
  --header "Authorization: Bearer $PAYPATHIQ_SANDBOX_API_KEY"

console.log(await call("GET", `/clients/${clientCode}/receivables/${receivableId}`));

print(call("GET", f"/clients/{client_code}/receivables/{receivable_id}"))

Expect 200 OK, "status": "paused" and a recoverableAmount of "1000.00" EUR, which is the EUR 1,250.00 obligation less the EUR 250.00 payment (trimmed):

{ "externalReceivableId": "REC_20261016T101500Z", "status": "paused", "recoverableAmount": { "amount": "1000.00", "currency": "EUR" } }

Save each response’s X-Request-Id for support correlation. Do not send PayPathIQ an API key or full personal-data payload when reporting a problem.

Safer for shared shells: pass the key on standard input

A Bearer header in a curl argument can show in the process list on a shared machine. To keep the key out of curl’s arguments, pass it through standard input as curl config. This is the Customer step; change the URL and body for the other steps.

printf 'oauth2-bearer = "%s"\n' "$PAYPATHIQ_SANDBOX_API_KEY" | \
curl --disable --config - \
  --include \
  --request PUT \
  --url "$PAYPATHIQ_BASE_URL/v1/clients/$PAYPATHIQ_CLIENT_CODE/customers/$PAYPATHIQ_CUSTOMER_ID" \
  --header 'Content-Type: application/json' \
  --data '{"type":"person","name":{"firstName":"Avery","lastName":"Example"}}'

Turn off shell tracing (set +x) so the key is not printed.

Retrying requests

Lose a response after a Customer PUT, or after recording a Payment? Repeat the identical request. For an uncertain lifecycle-command outcome, GET the Receivable before deciding what to do next. See Safe retries and idempotency.

An exact replay is duplicate-safe. Changed descriptions require a newer source revision; descriptive writes cannot replace financial balances. After a Payment observation, an old representation is rejected rather than restoring paid debt. Read and reconcile before deciding on another operation.

Next steps

Load your first book, report a payment and stay in sync.
The API reference has the complete schemas, lifecycle commands, status codes, and typed error responses.
When you are ready for production, use the go-live checklist.

Getting started

Integration guides

Reliability and sync

Going live

Error reference

Set up

Check the API is reachable

Retrying requests

Next steps

​Set up

​Check the API is reachable

​Retrying requests

​Next steps

Set up

Check the API is reachable

Retrying requests

Next steps