Skip to content

Invite Customer API

Use this endpoint to mint a Pyng signup link for one of the partner's customers.

The partner supplies its own identifier for the customer (customerReference). The endpoint returns a signupUrl that the partner delivers to the customer through its own customer channel (SMS, email, in-app message). When the customer completes Pyng signup using the link, the customer becomes available for inclusion in subsequent debit batches.

URL path - /billing/sites/{siteId}/customers/invitations

Method - POST

Overview

This endpoint is the entry point for partner-driven customer onboarding. The partner does not share the customer's contact details with Pyng — delivery of the signup link is the partner's responsibility.

Request Headers

Header Name Header Value Notes
Content-Type application/json
Authorization Bearer access_token Access token must include scope billing:customers:invite
Pyng-Api-Version urn:pyng:api:billing:version:v1 Required. See API Versions.

Path Parameters

Parameter Key Parameter Data Type Notes
siteId string Unique identifier of the Site under which the customer is being invited. The Site must belong to the calling Organisation.

Body Parameters

Parameter Key Parameter Data Type Required Notes
customerReference string Y Partner-supplied identifier for the customer. Unique within the partner.

Response

Status Code - 201 Created

Parameter Key Parameter Data Type Required Notes
data object Y object of InvitationResponse type
traceId string Y Unique identifier of the request

InvitationResponse

Parameter Key Parameter Data Type Required Notes
customerReference string Y Partner-supplied identifier echoed back
signupUrl string Y URL to deliver to the customer to complete Pyng signup
expiresAt integer Y Unix timestamp in milliseconds, after which the signup link is no longer valid
state string Y One of LinkState. Always invited immediately after a freshly minted invitation.

LinkState

Value Notes
invited An invitation has been minted; the customer has not yet signed up.
linked The customer has completed Pyng signup using the invitation link. The link is debit-eligible.
expired The invitation expired before the customer completed signup. A new invitation may be minted.
revoked The link was revoked, by either the customer or the partner. A new invitation may be minted.

Examples

Request

POST /billing/sites/{siteId}/customers/invitations HTTP/1.1
Host: sample.pyng.com.au
Authorization: Bearer access_token
Content-Type: application/json
Pyng-Api-Version: urn:pyng:api:billing:version:v1

{
  "customerReference": "ACME-001"
}

Response

HTTP/1.1 201 Created
Content-Type: application/json;charset=UTF-8

{
  "data": {
    "customerReference": "ACME-001",
    "signupUrl": "https://sample.pyng.com.au/signup?token=eyJhbGciOi...",
    "expiresAt": 1778457600000,
    "state": "invited"
  },
  "traceId": "9ae2e340-b983-4274-b400-c974a9ab40ab"
}

Error Response — Duplicate Invitation

HTTP/1.1 409 Conflict
Content-Type: application/json;charset=UTF-8

{
  "errors": [
    {
      "code": "urn:pyng:platform:billing:error:customer-link:already-exists",
      "displayMessage": "An active invitation or link already exists for this customerReference.",
      "target": "customerReference"
    }
  ],
  "traceId": "9ae2e340-b983-4274-b400-c974a9ab40ab"
}

Error Response — Validation

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8

{
  "errors": [
    {
      "code": "urn:pyng:platform:billing:error:customer-link:invalid-reference",
      "displayMessage": "customerReference must be 1–64 characters and contain only alphanumeric characters, hyphens, and underscores.",
      "target": "customerReference"
    }
  ],
  "traceId": "9ae2e340-b983-4274-b400-c974a9ab40ab"
}