Skip to content
Global Payments Oceania API Global Payments Oceania API

Partner Lead API Integration Guide

This page contains the detailed, step-by-step integration reference for creating a lead, including the request and response shapes, a flow diagram, and error handling guidance.

Steps: Create a Lead

Step 1: Create a Lead

Submit the merchant’s business and contact details to create a lead against your partner configuration.

Endpoint: POST https://sandbox.api.gpaunz.com/leads

For complete field documentation, see Request Fields. For the interactive reference, see OpenAPI Reference.

Headers:

HeaderRequiredDescription
x-api-keyYesYour unique API Key to authenticate against the API.
x-idempotency-keyYesA unique value used to ensure idempotency and prevent retries of the same request.

Example Request:

{
    "reference": "HVolqMiv1kikVDL_pqtlMA",
    "externalReference": "INV001",
    "firstName": "John",
    "lastName": "Smith",
    "businessRegistration": {
        "value": "78406955710",
        "type": "abn"
    },
    "website": "https://www.example.com/",
    "phoneNumber": "0412345678",
    "company": "Amazing Company",
    "email": "john.smith@example.com",
    "country": "australia",
    "postcode": "4321",
    "priceTierCode": "TIER1",
    "servicesRequested": [
        "direct_debit",
        "ecommerce"
    ],
    "software": "ACME"
}

Note: software must match a partner configuration provisioned during onboarding, and priceTierCode must be a valid tier issued to you. A csaUrl is only returned when the lead qualifies for self-serve onboarding.

Example Response:

{
    "updatedDateTime": "2026-06-23T03:32:03Z",
    "result": {
        "status": "ok"
    },
    "id": "e945e8vh0a9szsxig9pohvs9i3lrmw",
    "csaUrl": "https://ezidebit--ezifull.sandbox.my.site.com/application/quicksignup?id=00Q8r00000SuB5rEAF",
    "reference": "HVolqMiv1kikVDL_pqtlMA",
    "externalReference": "INV001",
    "createdDateTime": "2026-06-23T03:31:59Z"
}

Create Lead Flow (Diagram)

This diagram shows the flow from your application submitting the lead through to a referred merchant completing self-serve signup.

sequenceDiagram
    autonumber
    participant Partner as Partner Application
    participant API as Single API
    participant Merchant

    Partner->>API: POST /leads (business + contact details)
    API->>API: Validate fields against partner configuration
    alt valid and not duplicate
        API-->>Partner: 200 result.status = ok, id, csaUrl
        opt self-serve
            Partner-->>Merchant: Share csaUrl
            Merchant->>API: Complete signup via csaUrl
        end
    else duplicate reference
        API-->>Partner: result.status = validation_error (reference_duplicated)
    else validation failure
        API-->>Partner: result.status = validation_error (field codes)
    end

Response Fields

FieldTypeNotes
idstringThe unique SAPI identifier returned by the gateway.
csaUrlstringSelf-serve signup URL for the merchant. Only returned when the lead qualifies for self-serve onboarding.
referencestringThe reference supplied in the request.
externalReferencestringThe external reference supplied in the request, if any.
createdDateTimestringWhen the lead was created (ISO 8601, UTC).
updatedDateTimestringWhen the lead was last updated (ISO 8601, UTC).
resultobjectThe standard result object indicating the status of the request.

Error Handling

When a request cannot be processed, the result.status is validation_error and result.codes lists each issue. Inspect every entry in codes — multiple validation failures are returned together.

Duplicate Reference

If the reference has already been used, the lead is rejected.

{
    "result": {
        "mode": "sandbox",
        "status": "validation_error",
        "codes": [
            {
                "id": "V10024",
                "message": "reference_duplicated"
            }
        ]
    }
}

Field Validation

Missing or invalid fields are returned together in result.codes.

{
    "result": {
        "status": "validation_error",
        "codes": [
            {
                "message": "lastname_required",
                "id": "V40001"
            },
            {
                "message": "invalid_country",
                "id": "V40005"
            },
            {
                "message": "phone_required",
                "id": "V40004"
            },
            {
                "message": "price_tier_code_required",
                "id": "V40010"
            },
            {
                "message": "software_required",
                "id": "V40014"
            }
        ]
    }
}

Validation Codes

CodeMessageTrigger
V40001lastname_requiredlastName is missing.
V40002email_requiredemail is missing.
V40003company_requiredcompany is missing.
V40004phone_requiredphoneNumber is missing.
V40005invalid_countrycountry is missing or not australia/new_zealand.
V40007invalid_phone_formatphoneNumber does not match the format for the supplied country.
V40008invalid_email_formatemail is not a valid email address.
V40010price_tier_code_requiredpriceTierCode is missing.
V40011services_requested_requiredservicesRequested is missing or empty.
V40012invalid_services_requested_valueA value in servicesRequested is not supported.
V40013reference_requiredreference is missing.
V40014software_requiredsoftware is missing.
V40015invalid_softwaresoftware does not match a configured partner.
V40016firstname_too_longfirstName exceeds 40 characters.
V40017lastname_too_longlastName exceeds 40 characters.
V40018company_too_longcompany exceeds 255 characters.
V40019price_tier_code_too_longpriceTierCode exceeds 255 characters.
V40020phone_contains_alphaphoneNumber contains alphabetic characters.
V40021invalid_business_registration_typebusinessRegistration.type is missing or unsupported.
V40022invalid_abnbusinessRegistration.value is not a valid ABN (11 digits).
V40023invalid_nzbnbusinessRegistration.value is not a valid NZBN (13 digits).
V40024invalid_acnbusinessRegistration.value is not a valid ACN (9 digits).
V10024reference_duplicatedreference has already been used.