Skip to content

B2B Receivables API

The Pyng B2B Receivables API enables partners to invite their customers to Pyng and submit batches of debits against linked customers' Pyng payment agreements.

Overview

Partners use this API to:

  • invite a customer to sign up to Pyng with a partner-supplied identifier
  • list invited and linked customers with their current state
  • submit a batch of debits to be executed against linked customers
  • poll the status of a submitted batch and retrieve per-row outcomes

The integration model is server-to-server. Partners obtain an access token, mint a signup link for the customer, deliver the link to the customer through their own channel, and once the customer has completed Pyng signup the partner can submit batches that include that customer.

Flow

sequenceDiagram
    autonumber
    participant P as Partner
    participant C as Customer
    participant API as Pyng B2B Receivables API
    participant A as Pyng App

    P->>API: POST /billing/sites/{siteId}/customers/invitations
    API-->>P: signupUrl
    P-->>C: Deliver signupUrl (partner channel)
    C->>A: Open signupUrl, complete Pyng signup
    A-->>API: Customer linked
    P->>API: POST /billing/sites/{siteId}/batches
    API-->>P: 202 Accepted
    loop until settled (≤ 24h)
        P->>API: GET /billing/sites/{siteId}/batches/{batchReference}
        API-->>P: state and per-row outcomes
    end

Identifiers

A partner Organisation may operate one or more Sites. Every API call targets a specific Site identified by the {siteId} path segment. A single set of API credentials can act on any Site that belongs to the calling Organisation; calls that target a Site outside the Organisation are rejected.

siteId values are provided to your Organisation by Pyng during onboarding. The v1 API does not expose an endpoint to enumerate Sites — your account manager supplies the identifiers when the integration is provisioned.

Partners assign their own customer identifier — customerReference — when minting an invitation. The customerReference is opaque to Pyng and unique within a Site. The same customerReference value may exist under different Sites, and a value may be reused on the same Site once the prior link has reached expired or revoked state. Each active (siteId, customerReference) pair is a distinct link.

Pyng's internal customer identity and the customer's payment agreement are not exposed to the partner. The partner refers to its customer using customerReference for the lifetime of the integration.

Conventions

  • Timestamps — every timestamp on the wire is an integer Unix timestamp in milliseconds, in UTC.
  • Currency — every monetary amount is an integer in the minor unit of the Site's configured currency (cents for AUD). All Sites are configured in AUD at launch.
  • Field naming — request and response fields use camelCase. Optional fields are omitted from responses when they have no value, rather than returned as null.
  • Enum values — every enum value on the wire uses camelCase (invited, linked, inProgress, customerNotActive, insufficientFunds). Single-word values are lowercase; multi-word values lowercase the first word and capitalise subsequent words. No PascalCase, no SCREAMING_SNAKE_CASE, no kebab-case.

Batch Semantics

  • A batch contains 1 to 1000 rows.
  • Each row identifies the target customer by customerReference and carries a partner-supplied rowReference and an amount in the Site's minor currency unit.
  • Submission is asynchronous. The API returns 202 Accepted immediately and processes the batch in the background.
  • Every row reaches a terminal state within 24 hours of submission.
  • Submission is idempotent on batchReference. Resubmitting the same batchReference with an identical body returns the original receipt. Resubmitting with a different body returns 409 Conflict. A batchReference is retained for 90 days from first submission; values older than 90 days may be reused for a fresh batch.
  • Each rowReference must be unique within a batch.

URLs

Sandbox - https://sample.pyng.com.au — see Sandbox.

Production - https://app.pyng.com.au