How a PayID address gets built

Every PayID you create gets an address your customer pays to, returned in the PayID field of the PayID response. You can't set the address directly. It's built from the merchant's PayID Format setting and the customer's details, using the rules on this page.

[email protected]
│ │       │       └─ domain: pad.live, or the merchant's custom domain
│ │       └─ customer code, added after a customer value
│ └─ reference: the customer's CustomRef or ExternalID, a payment request code, a Xero invoice number, or a random code
└─ persistent marker: only on persistent PayIDs

Fields that shape the address

🚧

The request's ExternalID is not part of the address

ExternalID on the POST /pay_ids request is your own reference for that payment. It's stored and returned on the PayID, but it never appears in the address. To shape the address, set ExternalID or CustomRef on the customer.

How the address is chosen

PayAdvantage checks these in order and uses the first one that applies.

1. PayID Format is Unique: a random 6-character code, e.g. [email protected]. Nothing else is checked.
2. The customer has a value for the chosen field (CustomRef or ExternalID, after cleaning): the value plus the customer code, e.g. [email protected].
3. The payment came from a PayAdvantage payment request page: the payment request code, e.g. [email protected].
4. The payment came from a PayAdvantage Xero invoice link: the Xero invoice number, e.g. [email protected].
5. Otherwise: a random 6-character code, e.g. [email protected].

Persistent PayIDs add p- to the front of whichever rule applies. They're never linked to a payment request or invoice, so steps 3 and 4 never apply to them.

Steps 3 and 4 only apply to payments made through PayAdvantage's hosted payment request and Xero invoice pages. A one-off PayID created with POST /pay_ids for a customer with no value in the chosen field gets a random code.

Cleaning and length

The value is cleaned before it's used:

• Only letters, numbers, - and _ are kept. Everything else is removed.
• Any - or _ left at the start or end is trimmed.
• The whole address is lower case.
• If nothing is left after cleaning, the value counts as empty and the next rule is used.

A PayID is at most 50 characters. When the address would be longer, only the reference part is shortened. The p- prefix, the customer code and the domain are always kept in full.

Examples

For a customer with code HX42TQ, CustomRef of SMITH01 and ExternalID of CRM-10042, on the pad.live domain:

Because the address is built from the customer, every one-off PayID for a customer with a value in the chosen field has the same address. Use the PayID Code from the response, not the address, to tell individual PayIDs apart.

One-off PayIDs

Create one with POST /pay_ids and an Amount greater than zero.

{
  "Amount": 150.00,
  "Description": "Invoice 1042",
  "ExternalID": "order-1042",
  "Customer": { "Code": "HX42TQ" }
}

• The customer pays the exact amount, once.
• It expires 25 hours after creation. The time is returned in DateExpires.

Persistent PayIDs

A persistent PayID belongs to one customer. The customer can pay any amount into it, any number of times, until you delete it. Persistent PayIDs must be enabled for the merchant before you can create them.

There are three ways to create one:

{
  "Amount": 0,
  "Description": "PayID for Smith Co",
  "Persistent": true,
  "Customer": { "Code": "HX42TQ" }
}

To remove one, use DELETE /pay_ids/{code} or POST /customers/{code}/deletepayidref. The PayID stops accepting payments.

Errors

Changing the PayID Format

The address is worked out once, when the PayID is created, and saved. Changing the merchant's PayID Format, or a customer's CustomRef or ExternalID, only affects PayIDs created afterwards. Existing PayIDs, including persistent ones, keep their address.