payload

package
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 19, 2026 License: MIT Imports: 5 Imported by: 0

Documentation

Overview

Package payload provides convenience builder functions for constructing validated payload instances. Each builder validates its inputs before returning, making them the recommended way to create payload objects.

Builder functions that accept variable options (Contact, Event) use the functional options pattern with ContactOption and EventOption respectively.

Package payload provides 30+ typed payload structures for encoding various kinds of data into QR codes. Each payload type implements the Payload interface and produces a standards-compliant string representation suitable for embedding in a QR code symbol.

The package covers a wide range of QR code use cases:

  • Plain text and URLs
  • WiFi network credentials (WIFI:T:WPA;S:...;P:...;; format)
  • Electronic business cards (vCard 2.1/3.0/4.0 and MeCard formats)
  • Messaging: SMS, MMS, WhatsApp, email (mailto: / smsto: URIs)
  • Phone numbers (tel: URI)
  • Geographic locations (geo: URI, Google Maps, Apple Maps)
  • Calendar events (iCalendar VEVENT format)
  • Social media profile links (Twitter/X, LinkedIn, Instagram, Facebook, Telegram, YouTube)
  • Media streaming links (Spotify tracks/playlists, Apple Music, YouTube videos)
  • App store download links (Google Play, Apple App Store)
  • Payments: PayPal.me links and cryptocurrency payment URIs (BTC, ETH, LTC)
  • Swiss QR-bill payment instructions (PID format)
  • NTP time server configurations (ntp:// URI)
  • Video conferencing: Zoom meeting join links
  • Bluetooth beacon configurations: iBeacon (beacon registry URL format)

Usage

Every payload type offers both a convenience builder function and direct struct construction. Builder functions (e.g. Text, URL, WiFi, Contact, Event) validate their inputs before returning, making them the recommended approach: 

// Plain text
p, err := payload.Text("Hello, world!")
data, err := p.Encode() // "Hello, world!"

// URL with optional title fragment
p, err := payload.URL("https://example.com")
data, err := p.Encode() // "https://example.com"

// WiFi credentials
p, err := payload.WiFi("MyNetwork", "s3cret", "WPA2")
data, err := p.Encode() // "WIFI:T:WPA2;S:MyNetwork;P:s3cret;;"

// vCard contact with functional options
p, err := payload.Contact("Jane", "Doe",
    payload.WithPhone("+1-555-0123"),
    payload.WithEmail("jane@example.com"),
    payload.WithOrganization("Acme Inc"),
)
data, err := p.Encode() // "BEGIN:VCARD\r\nVERSION:3.0\r\n..."

// Calendar event with options
p, err := payload.Event("Team Standup", "Room 42", start, end,
    payload.WithAllDay(),
    payload.WithDescription("Weekly sync"),
)
data, err := p.Encode() // "BEGIN:VEVENT\r\nSUMMARY:Team Standup\r\n..."

The Payload Interface

All payload types satisfy the Payload interface, which requires four methods:

  • Encode() (string, error) — returns the encoded QR code data string
  • Validate() error — checks that all fields are well-formed
  • Type() string — returns a short identifier (e.g. "text", "url", "wifi")
  • Size() int — returns the byte length of the encoded data

BasePayload provides default no-op implementations for Type and Size, which individual payload types may embed and override as needed.

Index

Constants

View Source 
const CryptoBTC = "BTC"

CryptoBTC represents Bitcoin. The encoded URI scheme is "bitcoin:". Used as the CryptoType field in CryptoPayload.

View Source 
const CryptoETH = "ETH"

CryptoETH represents Ethereum. The encoded URI scheme is "ethereum:". Used as the CryptoType field in CryptoPayload.

View Source 
const CryptoLTC = "LTC"

CryptoLTC represents Litecoin. The encoded URI scheme is "litecoin:". Used as the CryptoType field in CryptoPayload.

View Source 
const DefaultPayPalCurrency = "USD"

DefaultPayPalCurrency is the default currency for PayPal payment links. Used when the Currency field is empty. Value: "USD".

View Source 
const EncryptionNoPass = "nopass"

EncryptionNoPass indicates an open network with no password.

View Source 
const EncryptionSAE = "SAE"

EncryptionSAE represents SAE (Simultaneous Authentication of Equals) encryption.

View Source 
const EncryptionWEP = "WEP"

EncryptionWEP represents WEP encryption.

View Source 
const EncryptionWPA = "WPA"

EncryptionWPA represents WPA encryption.

View Source 
const EncryptionWPA2 = "WPA2"

EncryptionWPA2 represents WPA2 encryption.

View Source 
const EncryptionWPA3 = "WPA3"

EncryptionWPA3 represents WPA3 encryption.

View Source 
const MarketAppleApp = "apple"

MarketAppleApp represents the Apple App Store. Used as the Platform field in MarketPayload.

View Source 
const MarketGooglePlay = "google"

MarketGooglePlay represents the Google Play Store. Used as the Platform field in MarketPayload.

View Source 
const TravelModeBicycling = "bicycling"

TravelModeBicycling represents bicycling directions. Used as the TravelMode field in GoogleMapsDirectionsPayload.

View Source 
const TravelModeDriving = "driving"

TravelModeDriving represents driving directions. Used as the TravelMode field in GoogleMapsDirectionsPayload.

View Source 
const TravelModeTransit = "transit"

TravelModeTransit represents public transit directions. Used as the TravelMode field in GoogleMapsDirectionsPayload.

View Source 
const TravelModeWalking = "walking"

TravelModeWalking represents walking directions. Used as the TravelMode field in GoogleMapsDirectionsPayload.

Variables

This section is empty.

Functions

This section is empty.

Types

type AppleMapsPayload 

type AppleMapsPayload struct {
	// Latitude is the center latitude.
	Latitude float64
	// Longitude is the center longitude.
	Longitude float64
	// Query is an optional search query.
	Query string
	// Zoom is an optional zoom level.
	Zoom int
}

AppleMapsPayload encodes an Apple Maps location or search query. Coordinates are encoded as the ll (latitude/longitude) query parameter. An optional search query can be appended as the q parameter, and an optional zoom level as the t parameter.

Example encoded output: 

https://maps.apple.com/maps?ll=37.7749,-122.4194

func AppleMaps 

func AppleMaps(lat, lng float64) (*AppleMapsPayload, error)

AppleMaps creates a validated AppleMapsPayload from coordinates, producing a maps.apple.com URL with the ll (lat/lng) query parameter.

Example: 

p, err := payload.AppleMaps(37.7749, -122.4194)
data, _ := p.Encode() // "https://maps.apple.com/maps?ll=37.7749,-122.4194"

func (*AppleMapsPayload) Encode 

func (a *AppleMapsPayload) Encode() (string, error)

Encode returns an Apple Maps URL with coordinates (ll parameter), optional search query (q parameter), and optional zoom (t parameter).

func (*AppleMapsPayload) Size 

func (a *AppleMapsPayload) Size() int

Size returns the byte length of the encoded URL.

func (*AppleMapsPayload) Type 

func (a *AppleMapsPayload) Type() string

Type returns "apple_maps".

func (*AppleMapsPayload) Validate 

func (a *AppleMapsPayload) Validate() error

Validate checks that the coordinates are within valid ranges: latitude in [-90, 90], longitude in [-180, 180].

type AppleMusicTrackPayload 

type AppleMusicTrackPayload struct {
	// AlbumID is the Apple Music album ID.
	AlbumID string
	// SongID is the Apple Music song ID.
	SongID string
	// StoreFront is the optional regional storefront identifier.
	StoreFront string
}

AppleMusicTrackPayload encodes a link to an Apple Music track. The URL requires an AlbumID and SongID. An optional StoreFront parameter specifies the regional storefront (e.g. "us").

Example encoded output: 

https://music.apple.com/album/1234567890?i=1234567891

func (*AppleMusicTrackPayload) Encode 

func (a *AppleMusicTrackPayload) Encode() (string, error)

Encode returns an Apple Music album URL with the song parameter. If StoreFront is set, the regional storefront path segment is included. AlbumID and SongID are path/query-encoded respectively.

func (*AppleMusicTrackPayload) Size 

func (a *AppleMusicTrackPayload) Size() int

Size returns the byte length of the encoded URL.

func (*AppleMusicTrackPayload) Type 

func (a *AppleMusicTrackPayload) Type() string

Type returns "apple_music".

func (*AppleMusicTrackPayload) Validate 

func (a *AppleMusicTrackPayload) Validate() error

Validate checks that both album ID and song ID are non-empty.

type BasePayload 

type BasePayload struct{}

BasePayload provides default no-op implementations for the Payload interface. Individual payload types may embed BasePayload and override only the methods they need, reducing boilerplate for Type() and Size().

func (*BasePayload) Size 

func (b *BasePayload) Size() int

Size returns 0.

func (*BasePayload) Type 

func (b *BasePayload) Type() string

Type returns "unknown".

type CalendarPayload 

type CalendarPayload struct {
	// Title is the event summary.
	Title string
	// Description is the event description.
	Description string
	// Location is the event location.
	Location string
	// Start is the event start time.
	Start time.Time
	// End is the event end time.
	End time.Time
	// AllDay indicates whether this is an all-day event.
	AllDay bool
}

CalendarPayload encodes a calendar event using the iCalendar VEVENT format (RFC 5545). The output is a self-contained VEVENT block with SUMMARY, DESCRIPTION, LOCATION, and DTSTART/DTEND properties.

Dates are always encoded in UTC. For all-day events (AllDay=true), the date-only format YYYYMMDD is used. For timed events, the full YYYYMMDDTHHMMSSZ format is used.

Example encoded output: 

BEGIN:VEVENT\r\nSUMMARY:Team Standup\r\nLOCATION:Room 42\r\nDTSTART:20250715T090000Z\r\nDTEND:20250715T100000Z\r\nEND:VEVENT

func Event 

func Event(title, location string, start, end time.Time, opts ...EventOption) (*CalendarPayload, error)

Event creates a validated CalendarPayload using the iCalendar VEVENT format (RFC 5545). Dates are encoded in UTC. By default, the event uses date-time format (YYYYMMDDTHHMMSSZ); use WithAllDay() for date-only events.

Example: 

start := time.Date(2025, 7, 15, 9, 0, 0, 0, time.UTC)
end := time.Date(2025, 7, 15, 10, 0, 0, 0, time.UTC)
p, err := payload.Event("Standup", "Room 42", start, end,
    payload.WithDescription("Daily sync"),
)
data, _ := p.Encode() // "BEGIN:VEVENT\r\nSUMMARY:Standup\r\n..."

func (*CalendarPayload) Encode 

func (c *CalendarPayload) Encode() (string, error)

Encode returns an iCalendar VEVENT string with CRLF line endings. Date-time values are in UTC using YYYYMMDDTHHMMSSZ format, or YYYYMMDD for all-day events.

func (*CalendarPayload) Size 

func (c *CalendarPayload) Size() int

Size returns the byte length of the encoded iCalendar string.

func (*CalendarPayload) Type 

func (c *CalendarPayload) Type() string

Type returns "calendar".

func (*CalendarPayload) Validate 

func (c *CalendarPayload) Validate() error

Validate checks that the title is non-empty and that the end time is strictly after the start time.

type ContactOption 

type ContactOption func(*VCardPayload)

ContactOption is a functional option that configures a VCardPayload during construction via the Contact builder function.

func WithAddress 

func WithAddress(addr string) ContactOption

WithAddress sets the postal address on a VCardPayload. The value is encoded as an ADR property in the vCard output.

func WithEmail 

func WithEmail(email string) ContactOption

WithEmail sets the email address on a VCardPayload. The value is encoded as an EMAIL property in the vCard output.

func WithNote 

func WithNote(note string) ContactOption

WithNote sets the free-text note on a VCardPayload. The value is encoded as a NOTE property in the vCard output.

func WithOrganization 

func WithOrganization(org string) ContactOption

WithOrganization sets the organization name on a VCardPayload. The value is encoded as an ORG property in the vCard output.

func WithPhone 

func WithPhone(phone string) ContactOption

WithPhone sets the phone number on a VCardPayload. The value is encoded as a TEL property in the vCard output.

func WithTitle 

func WithTitle(title string) ContactOption

WithTitle sets the job title on a VCardPayload. The value is encoded as a TITLE property in the vCard output.

func WithURL 

func WithURL(url string) ContactOption

WithURL sets the website URL on a VCardPayload. The value is encoded as a URL property in the vCard output.

type CryptoPayload 

type CryptoPayload struct {
	// Address is the wallet address.
	Address string
	// Amount is the optional payment amount.
	Amount string
	// Label is an optional label for the transaction.
	Label string
	// Message is an optional message for the transaction.
	Message string
	// CryptoType is the cryptocurrency type (BTC, ETH, or LTC).
	CryptoType string
}

CryptoPayload encodes a cryptocurrency payment request as a URI following the BIP21 Bitcoin URI scheme (adapted for ETH and LTC). When scanned by a crypto wallet app, the user is prompted to send the specified amount to the given address.

Example encoded output: 

bitcoin:1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa?amount=0.01&label=Tip&message=Thanks

func (*CryptoPayload) Encode 

func (c *CryptoPayload) Encode() (string, error)

Encode returns a cryptocurrency URI with optional amount, label, and message query parameters. Format: <scheme>:<address>[?amount=...&label=...&message=...].

func (*CryptoPayload) Size 

func (c *CryptoPayload) Size() int

Size returns the byte length of the encoded crypto URI.

func (*CryptoPayload) Type 

func (c *CryptoPayload) Type() string

Type returns "crypto".

func (*CryptoPayload) Validate 

func (c *CryptoPayload) Validate() error

Validate checks that the address is non-empty and the crypto type is one of BTC, ETH, or LTC.

type EmailPayload 

type EmailPayload struct {
	// To is the recipient email address.
	To string
	// Subject is the email subject line.
	Subject string
	// Body is the email body text.
	Body string
	// CC is a list of carbon-copy recipients.
	CC []string
}

EmailPayload encodes an email message as a mailto: URI per RFC 6068. The recipient, subject, body, and CC addresses are encoded as URL parameters. Most smartphone QR readers will open the device's email client with these fields pre-populated.

Example encoded output: 

mailto:alice@example.com?subject=Hello&body=World&cc=bob@example.com

func Email 

func Email(to, subject, body string, cc ...string) (*EmailPayload, error)

Email creates a validated EmailPayload encoded as a RFC 6068 mailto: URI. The subject, body, and CC addresses are URL-encoded in the query string.

Example: 

p, err := payload.Email("alice@example.com", "Hello", "World", "bob@example.com")
data, _ := p.Encode() // "mailto:alice@example.com?subject=Hello&body=World&cc=bob@example.com"

func (*EmailPayload) Encode 

func (e *EmailPayload) Encode() (string, error)

Encode returns a mailto: URI with optional subject, body, and cc parameters. All parameter values are URL-encoded using url.QueryEscape.

func (*EmailPayload) Size 

func (e *EmailPayload) Size() int

Size returns the byte length of the encoded mailto URI.

func (*EmailPayload) Type 

func (e *EmailPayload) Type() string

Type returns "email".

func (*EmailPayload) Validate 

func (e *EmailPayload) Validate() error

Validate checks that the recipient (To) address is non-empty.

type EventOption 

type EventOption func(*CalendarPayload)

EventOption is a functional option that configures a CalendarPayload during construction via the Event builder function.

func WithAllDay 

func WithAllDay() EventOption

WithAllDay marks a CalendarPayload as an all-day event, causing dates to be encoded in date-only format (YYYYMMDD) instead of date-time format.

func WithDescription 

func WithDescription(desc string) EventOption

WithDescription sets the description on a CalendarPayload. The value is encoded as a DESCRIPTION property in the VEVENT output.

type EventPayload 

type EventPayload struct {
	// EventID is the unique event identifier.
	EventID string
	// EventName is the name of the event.
	EventName string
	// Venue is the event venue.
	Venue string
	// StartTime is the event start time.
	StartTime time.Time
	// Category is the event category.
	Category string
	// Seat is the seat assignment.
	Seat string
	// Organizer is the event organizer.
	Organizer string
	// Description is the event description.
	Description string
	// URL is a link to the event page.
	URL string
}

EventPayload encodes a generic event ticket using the EVENT-TICKET format. Fields are pipe-separated after the "EVENT-TICKET:" prefix. Only non-empty fields are included. This format is useful for conference tickets, concert passes, and similar event admissions.

Example encoded output: 

EVENT-TICKET:evt-001|GopherCon 2025|San Francisco|20250715T090000Z|Conference|A12|Go Team

func (*EventPayload) Encode 

func (e *EventPayload) Encode() (string, error)

Encode returns an EVENT-TICKET: string with pipe-separated fields. Only non-empty fields (EventID, EventName, Venue, StartTime, Category, Seat, Organizer, Description, URL) are appended.

func (*EventPayload) Size 

func (e *EventPayload) Size() int

Size returns the byte length of the encoded event string.

func (*EventPayload) Type 

func (e *EventPayload) Type() string

Type returns "event".

func (*EventPayload) Validate 

func (e *EventPayload) Validate() error

Validate checks that the event ID is non-empty.

type FacebookPayload 

type FacebookPayload struct {
	// PageURL is the full HTTPS URL to the Facebook page.
	PageURL string
}

FacebookPayload encodes a link to a Facebook page. The PageURL must be the full HTTPS URL to the Facebook page.

Example encoded output: 

https://www.facebook.com/golang

func Facebook 

func Facebook(pageURL string) (*FacebookPayload, error)

Facebook creates a validated FacebookPayload from a full Facebook page URL. The URL must start with https://.

Example: 

p, err := payload.Facebook("https://www.facebook.com/golang")
data, _ := p.Encode() // "https://www.facebook.com/golang"

func (*FacebookPayload) Encode 

func (f *FacebookPayload) Encode() (string, error)

Encode returns the Facebook page URL.

func (*FacebookPayload) Size 

func (f *FacebookPayload) Size() int

Size returns the byte length of the encoded URL.

func (*FacebookPayload) Type 

func (f *FacebookPayload) Type() string

Type returns "facebook".

func (*FacebookPayload) Validate 

func (f *FacebookPayload) Validate() error

Validate checks that the page URL is non-empty and starts with https://.

type GeoPayload 

type GeoPayload struct {
	// Latitude is the latitude in decimal degrees (-90 to 90).
	Latitude float64
	// Longitude is the longitude in decimal degrees (-180 to 180).
	Longitude float64
}

GeoPayload encodes a geographic location as a geo: URI per RFC 5870. The URI contains latitude and longitude in decimal degrees. When scanned by a mapping application, the device will typically open a pin at the specified coordinates.

Example encoded output: 

geo:37.7749,-122.4194

func Geo 

func Geo(lat, lng float64) (*GeoPayload, error)

Geo creates a validated GeoPayload encoded as a geo: URI (RFC 5870). Coordinates are in decimal degrees. Latitude must be in [-90, 90] and longitude in [-180, 180].

Example: 

p, err := payload.Geo(37.7749, -122.4194)
data, _ := p.Encode() // "geo:37.7749,-122.4194"

func (*GeoPayload) Encode 

func (g *GeoPayload) Encode() (string, error)

Encode returns a geo: URI with latitude and longitude coordinates. Trailing zeros in the decimal representation are trimmed for compactness. Format: geo:<lat>,<lng>.

func (*GeoPayload) Size 

func (g *GeoPayload) Size() int

Size returns the byte length of the encoded geo URI.

func (*GeoPayload) Type 

func (g *GeoPayload) Type() string

Type returns "geo".

func (*GeoPayload) Validate 

func (g *GeoPayload) Validate() error

Validate checks that the latitude is within [-90, 90] and the longitude is within [-180, 180].

type GoogleMapsDirectionsPayload 

type GoogleMapsDirectionsPayload struct {
	// Origin is the starting location.
	Origin string
	// Destination is the ending location.
	Destination string
	// TravelMode is the mode of transportation (defaults to "driving").
	TravelMode string
}

GoogleMapsDirectionsPayload encodes Google Maps turn-by-turn directions between two points. It uses the Google Maps Directions API URL format with origin, destination, and optional travel mode.

Supported travel modes: driving, walking, bicycling, transit.

Example encoded output: 

https://maps.google.com/maps/dir/?api=1&origin=San+Francisco&destination=Los+Angeles&travelmode=driving

func (*GoogleMapsDirectionsPayload) Encode 

func (g *GoogleMapsDirectionsPayload) Encode() (string, error)

Encode returns a Google Maps directions URL with origin, destination, and travel mode. Origin and destination are URL-encoded.

func (*GoogleMapsDirectionsPayload) Size 

func (g *GoogleMapsDirectionsPayload) Size() int

Size returns the byte length of the encoded URL.

func (*GoogleMapsDirectionsPayload) Type 

func (g *GoogleMapsDirectionsPayload) Type() string

Type returns "google_maps_directions".

func (*GoogleMapsDirectionsPayload) Validate 

func (g *GoogleMapsDirectionsPayload) Validate() error

Validate checks that both origin and destination are non-empty.

type GoogleMapsPayload 

type GoogleMapsPayload struct {
	// Latitude is the center latitude.
	Latitude float64
	// Longitude is the center longitude.
	Longitude float64
	// Query is an optional search query (overrides coordinates when set).
	Query string
	// Zoom is an optional zoom level.
	Zoom int
}

GoogleMapsPayload encodes a Google Maps location or search query. When a Query is set, it takes precedence over coordinates and produces a maps.google.com/maps?q=<query> URL. Otherwise, the coordinates are encoded as a loc:<lat>,<lng> parameter.

Example encoded output (coordinates): 

https://maps.google.com/maps?q=loc:37.7749,-122.4194

Example encoded output (query): 

https://maps.google.com/maps?q=coffee+shop

func GoogleMaps 

func GoogleMaps(lat, lng float64) (*GoogleMapsPayload, error)

GoogleMaps creates a validated GoogleMapsPayload from coordinates, producing a maps.google.com URL with the loc: query parameter.

Example: 

p, err := payload.GoogleMaps(37.7749, -122.4194)
data, _ := p.Encode() // "https://maps.google.com/maps?q=loc:37.7749,-122.4194"

func GoogleMapsQuery 

func GoogleMapsQuery(query string) (*GoogleMapsPayload, error)

GoogleMapsQuery creates a validated GoogleMapsPayload from a search query, producing a maps.google.com URL that opens the search results.

Example: 

p, err := payload.GoogleMapsQuery("coffee shop near central park")
data, _ := p.Encode() // "https://maps.google.com/maps?q=coffee+shop+near+central+park"

func (*GoogleMapsPayload) Encode 

func (g *GoogleMapsPayload) Encode() (string, error)

Encode returns a Google Maps URL for the location or query. If Query is non-empty, it is used as the q parameter. Otherwise, coordinates are formatted as loc:<lat>,<lng>. An optional Zoom level is appended as &zoom=N.

func (*GoogleMapsPayload) Size 

func (g *GoogleMapsPayload) Size() int

Size returns the byte length of the encoded URL.

func (*GoogleMapsPayload) Type 

func (g *GoogleMapsPayload) Type() string

Type returns "google_maps".

func (*GoogleMapsPayload) Validate 

func (g *GoogleMapsPayload) Validate() error

Validate checks that either a query is non-empty or valid coordinate ranges are used (latitude in [-90, 90], longitude in [-180, 180]).

type GoogleMapsPlacePayload 

type GoogleMapsPlacePayload struct {
	// PlaceName is the place or business name to search for.
	PlaceName string
}

GoogleMapsPlacePayload encodes a Google Maps place search query. The PlaceName is URL-encoded and used as the q parameter in the maps.google.com/maps?q= URL.

Example encoded output: 

https://maps.google.com/maps?q=Eiffel+Tower

func (*GoogleMapsPlacePayload) Encode 

func (g *GoogleMapsPlacePayload) Encode() (string, error)

Encode returns a Google Maps search URL for the place name. The PlaceName is URL-encoded as the q query parameter.

func (*GoogleMapsPlacePayload) Size 

func (g *GoogleMapsPlacePayload) Size() int

Size returns the byte length of the encoded URL.

func (*GoogleMapsPlacePayload) Type 

func (g *GoogleMapsPlacePayload) Type() string

Type returns "google_maps_place".

func (*GoogleMapsPlacePayload) Validate 

func (g *GoogleMapsPlacePayload) Validate() error

Validate checks that the place name is non-empty.

type IBeaconPayload 

type IBeaconPayload struct {
	// UUID is the iBeacon proximity UUID.
	UUID string
	// Major is the iBeacon major value.
	Major uint16
	// Minor is the iBeacon minor value.
	Minor uint16
	// Manufacturer is the optional manufacturer identifier (defaults to "beacon").
	Manufacturer string
}

IBeaconPayload encodes an iBeacon Bluetooth Low Energy (BLE) beacon configuration as a URL following the open beacon registry format (https://github.com/google/beacon). The URL points to <manufacturer>.github.io/beacon/ with UUID, major, and minor as query parameters. When scanned, the beacon data can be extracted and used by beacon-aware applications.

The UUID must be in the standard format: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX. Major and Minor are 16-bit unsigned integers used for proximity identification.

Example encoded output: 

https://beacon.github.io/beacon/?uuid=A1B2C3D4-E5F6-7890-ABCD-EF1234567890&major=1&minor=42

func IBeacon 

func IBeacon(uuid string, major, minor uint16) (*IBeaconPayload, error)

IBeacon creates a validated IBeaconPayload that encodes an iBeacon configuration as a beacon registry URL (https://beacon.github.io/beacon/). The UUID must be in the format XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX. Major and minor values are 16-bit unsigned integers.

Example: 

p, err := payload.IBeacon("A1B2C3D4-E5F6-7890-ABCD-EF1234567890", 1, 42)
data, _ := p.Encode() // "https://beacon.github.io/beacon/?uuid=...&major=1&minor=42"

func (*IBeaconPayload) Encode 

func (ib *IBeaconPayload) Encode() (string, error)

Encode returns an iBeacon URL following the beacon registry format. Format: https://<manufacturer>.github.io/beacon/?uuid=<UUID>&major=<N>&minor=<N> The manufacturer defaults to "beacon" if not specified.

func (*IBeaconPayload) Size 

func (ib *IBeaconPayload) Size() int

Size returns the byte length of the encoded iBeacon URL.

func (*IBeaconPayload) Type 

func (ib *IBeaconPayload) Type() string

Type returns "ibeacon".

func (*IBeaconPayload) Validate 

func (ib *IBeaconPayload) Validate() error

Validate checks that the UUID is non-empty and matches the format XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX (32 hex digits with hyphens).

type InstagramPayload 

type InstagramPayload struct {
	// Username is the Instagram username.
	Username string
}

InstagramPayload encodes a link to an Instagram profile.

Example encoded output: 

https://instagram.com/natgeo

func Instagram 

func Instagram(username string) (*InstagramPayload, error)

Instagram creates a validated InstagramPayload that encodes an instagram.com profile link for the given username.

Example: 

p, err := payload.Instagram("natgeo")
data, _ := p.Encode() // "https://instagram.com/natgeo"

func (*InstagramPayload) Encode 

func (i *InstagramPayload) Encode() (string, error)

Encode returns an instagram.com profile URL.

func (*InstagramPayload) Size 

func (i *InstagramPayload) Size() int

Size returns the byte length of the encoded URL.

func (*InstagramPayload) Type 

func (i *InstagramPayload) Type() string

Type returns "instagram".

func (*InstagramPayload) Validate 

func (i *InstagramPayload) Validate() error

Validate checks that the username is non-empty.

type LinkedInPayload 

type LinkedInPayload struct {
	// ProfileURL is the full HTTPS URL to the LinkedIn profile.
	ProfileURL string
}

LinkedInPayload encodes a link to a LinkedIn profile. The ProfileURL must be the full HTTPS URL to the profile page.

Example encoded output: 

https://www.linkedin.com/in/johndoe

func LinkedIn 

func LinkedIn(profileURL string) (*LinkedInPayload, error)

LinkedIn creates a validated LinkedInPayload from a full LinkedIn profile URL. The URL must start with https://.

Example: 

p, err := payload.LinkedIn("https://www.linkedin.com/in/johndoe")
data, _ := p.Encode() // "https://www.linkedin.com/in/johndoe"

func (*LinkedInPayload) Encode 

func (l *LinkedInPayload) Encode() (string, error)

Encode returns the LinkedIn profile URL.

func (*LinkedInPayload) Size 

func (l *LinkedInPayload) Size() int

Size returns the byte length of the encoded URL.

func (*LinkedInPayload) Type 

func (l *LinkedInPayload) Type() string

Type returns "linkedin".

func (*LinkedInPayload) Validate 

func (l *LinkedInPayload) Validate() error

Validate checks that the profile URL is non-empty and starts with https://.

type MMSPayload 

type MMSPayload struct {
	// Phone is the recipient phone number.
	Phone string
	// Message is the MMS body text.
	Message string
	// Subject is the MMS subject line.
	Subject string
}

MMSPayload encodes an MMS message using the mms: URI scheme. The phone number and optional subject/body are encoded as a URI with query parameters. This format is primarily supported by Android devices.

Example encoded output: 

mms:+14155552671?subject=Check%20this&body=Hello!

func MMS 

func MMS(phone, message string) (*MMSPayload, error)

MMS creates a validated MMSPayload encoded as an mms: URI with optional subject and body query parameters. The phone number must contain at least one digit.

Example: 

p, err := payload.MMS("+14155552671", "Check this out!")
data, _ := p.Encode() // "mms:+14155552671?body=Check this out!"

func (*MMSPayload) Encode 

func (m *MMSPayload) Encode() (string, error)

Encode returns an mms: URI with optional subject and body parameters. Format: mms:<phone>[?subject=...&body=...].

func (*MMSPayload) Size 

func (m *MMSPayload) Size() int

Size returns the byte length of the encoded MMS URI.

func (*MMSPayload) Type 

func (m *MMSPayload) Type() string

Type returns "mms".

func (*MMSPayload) Validate 

func (m *MMSPayload) Validate() error

Validate checks that the phone number is non-empty and contains at least one digit (formatting characters are allowed).

type MarketPayload 

type MarketPayload struct {
	// Platform is the store platform ("google" or "apple").
	Platform string
	// PackageID is the app's package ID or App Store ID.
	PackageID string
	// AppName is the app name (used as a search fallback).
	AppName string
	// Campaign is an optional UTM campaign parameter.
	Campaign string
}

MarketPayload encodes an app store download link for either Google Play or Apple App Store. If PackageID is set, a direct app page URL is produced. If only AppName is set, a store search URL is used as a fallback.

An optional Campaign field appends UTM tracking parameters (utm_source=qr&utm_medium=scan&utm_campaign=...) to the URL.

Example encoded output (Google Play, package ID): 

https://play.google.com/store/apps/details?id=com.example.app

Example encoded output (Apple, with campaign): 

https://apps.apple.com/app/1234567890?utm_source=qr&utm_medium=scan&utm_campaign=launch

func AppStore 

func AppStore(appID string) (*MarketPayload, error)

AppStore creates a validated MarketPayload for the Apple App Store. The appID is the App Store numeric ID used in the apps.apple.com/app/ URL.

Example: 

p, err := payload.AppStore("1234567890")
data, _ := p.Encode() // "https://apps.apple.com/app/1234567890"

func PlayStore 

func PlayStore(packageID string) (*MarketPayload, error)

PlayStore creates a validated MarketPayload for the Google Play Store. The packageID is the application package name (e.g. "com.example.app").

Example: 

p, err := payload.PlayStore("com.example.app")
data, _ := p.Encode() // "https://play.google.com/store/apps/details?id=com.example.app"

func (*MarketPayload) Encode 

func (m *MarketPayload) Encode() (string, error)

Encode returns a store URL for the specified platform and app. For Google Play: play.google.com/store/apps/details?id=... or /search?q=... For Apple: apps.apple.com/app/... or /search?term=... UTM campaign parameters are appended if Campaign is set.

func (*MarketPayload) Size 

func (m *MarketPayload) Size() int

Size returns the byte length of the encoded store URL.

func (*MarketPayload) Type 

func (m *MarketPayload) Type() string

Type returns "market".

func (*MarketPayload) Validate 

func (m *MarketPayload) Validate() error

Validate checks that at least PackageID or AppName is set, and that Platform (if set) is either "google" or "apple".

type MeCardPayload 

type MeCardPayload struct {
	// Name is the contact's full name.
	Name string
	// Phone is the phone number.
	Phone string
	// Email is the email address.
	Email string
	// URL is the website address.
	URL string
	// Birthday is the birthday in YYYYMMDD format.
	Birthday string
	// Note is a free-text note.
	Note string
	// Address is the postal address.
	Address string
	// Nickname is the contact's nickname.
	Nickname string
}

MeCardPayload encodes a contact in the MeCard format, a lightweight alternative to vCard originally developed by NTT DoCoMo for mobile phones. MeCard is widely supported by Japanese QR readers and many international scanner apps. It uses a compact semicolon-delimited format.

Special characters (\, ;, :) in field values are backslash-escaped.

Example encoded output: 

MECARD:N:Jane Doe;TEL:+1-555-0123;EMAIL:jane@example.com;;

func (*MeCardPayload) Encode 

func (m *MeCardPayload) Encode() (string, error)

Encode returns a MECARD: formatted string with semicolon-delimited fields. Special characters in values are backslash-escaped.

func (*MeCardPayload) Size 

func (m *MeCardPayload) Size() int

Size returns the byte length of the encoded MeCard string.

func (*MeCardPayload) Type 

func (m *MeCardPayload) Type() string

Type returns "mecard".

func (*MeCardPayload) Validate 

func (m *MeCardPayload) Validate() error

Validate checks that the contact name is non-empty.

type NTPLocalePayload 

type NTPLocalePayload struct {
	// Host is the NTP server hostname or IP address.
	Host string
	// Port is the server port (defaults to 123).
	Port string
	// Version is the NTP protocol version (3 or 4).
	Version int
	// Description is an optional human-readable description.
	Description string
}

NTPLocalePayload encodes an NTP time server configuration as an ntp:// URI. This is used in QR codes for configuring network time synchronization on devices. The default NTP port (123) is omitted from the URI.

Example encoded output: 

ntp://time.google.com#NIST%20Time%20Server

func (*NTPLocalePayload) Encode 

func (n *NTPLocalePayload) Encode() (string, error)

Encode returns an ntp:// URI for the time server. The default port 123 is omitted. An optional description is appended as a URL fragment.

func (*NTPLocalePayload) Size 

func (n *NTPLocalePayload) Size() int

Size returns the byte length of the encoded ntp URI.

func (*NTPLocalePayload) String 

func (n *NTPLocalePayload) String() string

String returns a human-readable representation of the NTP configuration including the protocol version if set.

func (*NTPLocalePayload) Type 

func (n *NTPLocalePayload) Type() string

Type returns "ntp".

func (*NTPLocalePayload) Validate 

func (n *NTPLocalePayload) Validate() error

Validate checks that the host is non-empty, the port (if set) is a valid number in [1, 65535], and the version (if set) is 3 or 4.

type PIDPayload 

type PIDPayload struct {
	// PIDType is the payment instruction type (QRR, SCOR, or NON).
	PIDType string
	// CreditorName is the creditor's name.
	CreditorName string
	// IBAN is the international bank account number.
	IBAN string
	// Reference is the payment reference.
	Reference string
	// Amount is the payment amount.
	Amount string
	// Currency is the three-letter currency code.
	Currency string
	// DebtorName is the debtor's name.
	DebtorName string
	// RemittanceInfo is additional remittance information.
	RemittanceInfo string
}

PIDPayload encodes a Swiss QR-bill payment instruction in the PID format. The structured creditor data is encoded as a pipe-separated string after the "PID:" prefix. This is used in the Swiss payment infrastructure.

Supported PID types: QRR (QR-referenz, default), SCOR (creditor reference), and NON (no structured reference).

Example encoded output: 

PID:QRR|Acme Corp|CH9300762011623852957|RF12345678|150.00|CHF|John Doe|Invoice 2025

func (*PIDPayload) Encode 

func (p *PIDPayload) Encode() (string, error)

Encode returns a PID: string with pipe-separated fields. The IBAN has spaces removed. Only non-empty fields are included. PIDType defaults to "QRR" if not set.

func (*PIDPayload) Size 

func (p *PIDPayload) Size() int

Size returns the byte length of the encoded PID string.

func (*PIDPayload) Type 

func (p *PIDPayload) Type() string

Type returns "pid".

func (*PIDPayload) Validate 

func (p *PIDPayload) Validate() error

Validate checks that the IBAN is non-empty and the PID type (if set) is one of QRR, SCOR, or NON.

type PayPalPayload 

type PayPalPayload struct {
	// Username is the PayPal.me username.
	Username string
	// Amount is the payment amount.
	Amount string
	// Currency is the three-letter currency code (defaults to USD).
	Currency string
	// Reference is an optional payment reference note.
	Reference string
}

PayPalPayload encodes a PayPal.me payment link. When scanned, the QR code opens the PayPal payment page pre-filled with the specified username, amount, and currency. The currency defaults to USD if not specified.

Example encoded output: 

https://paypal.me/johndoe/25.00/USD&note=Invoice%2042

func Payment 

func Payment(username, amount, currency string) (*PayPalPayload, error)

Payment creates a validated PayPalPayload that encodes a paypal.me payment link with the given username, amount, and three-letter currency code.

Example: 

p, err := payload.Payment("johndoe", "25.00", "USD")
data, _ := p.Encode() // "https://paypal.me/johndoe/25.00/USD"

func (*PayPalPayload) Encode 

func (p *PayPalPayload) Encode() (string, error)

Encode returns a paypal.me URL with amount, currency (defaults to USD), and optional reference note. Format: https://paypal.me/<user>/<amount>/<currency>.

func (*PayPalPayload) Size 

func (p *PayPalPayload) Size() int

Size returns the byte length of the encoded PayPal URL.

func (*PayPalPayload) Type 

func (p *PayPalPayload) Type() string

Type returns "paypal".

func (*PayPalPayload) Validate 

func (p *PayPalPayload) Validate() error

Validate checks that the username and amount are non-empty.

type Payload 

type Payload interface {
	// Encode returns the encoded string representation of the payload data.
	// The returned string is ready to be passed directly to a QR code encoder.
	Encode() (string, error)
	// Type returns a short identifier for the payload kind (e.g. "text", "url").
	Type() string
	// Validate checks that the payload fields are well-formed.
	Validate() error
	// Size returns the length of the encoded data in bytes.
	Size() int
}

Payload is the interface that all QR code data types must implement.

Each method serves a specific purpose in the payload lifecycle:

  • Encode produces the final string that gets embedded in the QR code symbol.
  • Validate checks structural integrity (e.g. non-empty fields, valid ranges).
  • Type identifies the payload category for logging, serialization, or routing.
  • Size reports the encoded byte length, useful for QR version selection.

type PhonePayload 

type PhonePayload struct {
	// Number is the phone number to encode.
	Number string
}

PhonePayload encodes a phone number as a tel: URI (RFC 3966). When scanned by a smartphone QR reader, the device will typically prompt the user to initiate a phone call to the encoded number.

Example encoded output: 

tel:+1-555-0123

func Phone 

func Phone(number string) (*PhonePayload, error)

Phone creates a validated PhonePayload encoded as a tel: URI (RFC 3966). The phone number must contain at least one digit.

Example: 

p, err := payload.Phone("+1-555-0123")
data, _ := p.Encode() // "tel:+1-555-0123"

func (*PhonePayload) Encode 

func (p *PhonePayload) Encode() (string, error)

Encode returns a tel: URI for the phone number. The number is included verbatim (no digit stripping or normalization is performed).

func (*PhonePayload) Size 

func (p *PhonePayload) Size() int

Size returns the byte length of the encoded tel URI.

func (*PhonePayload) Type 

func (p *PhonePayload) Type() string

Type returns "phone".

func (*PhonePayload) Validate 

func (p *PhonePayload) Validate() error

Validate checks that the number is non-empty and contains at least one digit. Formatting characters (spaces, dashes, parentheses, +) are allowed.

type SMSPayload 

type SMSPayload struct {
	// Phone is the recipient phone number.
	Phone string
	// Message is the SMS body text.
	Message string
}

SMSPayload encodes an SMS message using the smsto: URI scheme. This is a widely supported format for QR code SMS initiation. When scanned, most smartphones will open the SMS composer with the recipient and optional message body pre-filled.

Example encoded output: 

smsto:+14155552671:Hi there!

func SMS 

func SMS(phone, message string) (*SMSPayload, error)

SMS creates a validated SMSPayload encoded as an smsto: URI. If a message is provided, it is appended after a colon separator.

Example: 

p, err := payload.SMS("+14155552671", "Hi there!")
data, _ := p.Encode() // "smsto:+14155552671:Hi there!"

func (*SMSPayload) Encode 

func (s *SMSPayload) Encode() (string, error)

Encode returns an smsto: URI with the phone number and optional message. Format: smsto:<phone>[:<message>].

func (*SMSPayload) Size 

func (s *SMSPayload) Size() int

Size returns the byte length of the encoded SMS URI.

func (*SMSPayload) Type 

func (s *SMSPayload) Type() string

Type returns "sms".

func (*SMSPayload) Validate 

func (s *SMSPayload) Validate() error

Validate checks that the phone number is non-empty.

type SpotifyPlaylistPayload 

type SpotifyPlaylistPayload struct {
	// PlaylistID is the Spotify playlist ID.
	PlaylistID string
}

SpotifyPlaylistPayload encodes a link to a Spotify playlist using the open.spotify.com/playlist/ deep link format.

Example encoded output: 

https://open.spotify.com/playlist/37i9dQZF1DXcBWIGoYBM5M

func (*SpotifyPlaylistPayload) Encode 

func (s *SpotifyPlaylistPayload) Encode() (string, error)

Encode returns a Spotify open.spotify.com/playlist/ URL.

func (*SpotifyPlaylistPayload) Size 

func (s *SpotifyPlaylistPayload) Size() int

Size returns the byte length of the encoded URL.

func (*SpotifyPlaylistPayload) Type 

func (s *SpotifyPlaylistPayload) Type() string

Type returns "spotify_playlist".

func (*SpotifyPlaylistPayload) Validate 

func (s *SpotifyPlaylistPayload) Validate() error

Validate checks that the playlist ID is non-empty.

type SpotifyTrackPayload 

type SpotifyTrackPayload struct {
	// TrackID is the Spotify track ID.
	TrackID string
}

SpotifyTrackPayload encodes a link to a Spotify track using the open.spotify.com/track/ deep link format.

Example encoded output: 

https://open.spotify.com/track/4cOdK2wGLETKBW3PvgPWqT

func SpotifyTrack 

func SpotifyTrack(trackID string) (*SpotifyTrackPayload, error)

SpotifyTrack creates a validated SpotifyTrackPayload that encodes an open.spotify.com/track/ deep link for the given track ID.

Example: 

p, err := payload.SpotifyTrack("4cOdK2wGLETKBW3PvgPWqT")
data, _ := p.Encode() // "https://open.spotify.com/track/4cOdK2wGLETKBW3PvgPWqT"

func (*SpotifyTrackPayload) Encode 

func (s *SpotifyTrackPayload) Encode() (string, error)

Encode returns a Spotify open.spotify.com/track/ URL.

func (*SpotifyTrackPayload) Size 

func (s *SpotifyTrackPayload) Size() int

Size returns the byte length of the encoded URL.

func (*SpotifyTrackPayload) Type 

func (s *SpotifyTrackPayload) Type() string

Type returns "spotify_track".

func (*SpotifyTrackPayload) Validate 

func (s *SpotifyTrackPayload) Validate() error

Validate checks that the track ID is non-empty.

type TelegramPayload 

type TelegramPayload struct {
	// Username is the Telegram username (without the @ prefix).
	Username string
}

TelegramPayload encodes a link to a Telegram user or group. The username should not include the @ prefix.

Example encoded output: 

https://t.me/golang

func Telegram 

func Telegram(username string) (*TelegramPayload, error)

Telegram creates a validated TelegramPayload that encodes a t.me profile link for the given username (without the @ prefix).

Example: 

p, err := payload.Telegram("golang")
data, _ := p.Encode() // "https://t.me/golang"

func (*TelegramPayload) Encode 

func (t *TelegramPayload) Encode() (string, error)

Encode returns a t.me profile URL.

func (*TelegramPayload) Size 

func (t *TelegramPayload) Size() int

Size returns the byte length of the encoded URL.

func (*TelegramPayload) Type 

func (t *TelegramPayload) Type() string

Type returns "telegram".

func (*TelegramPayload) Validate 

func (t *TelegramPayload) Validate() error

Validate checks that the username is non-empty.

type TextPayload 

type TextPayload struct {
	// Text is the content to encode.
	Text string
}

TextPayload encodes arbitrary plain text into a QR code. The text is stored as-is with no transformation, making it the simplest payload type. The maximum allowed length is 4296 characters, which corresponds to the QR code version 40, low error correction capacity.

func Text 

func Text(text string) (*TextPayload, error)

Text creates a validated TextPayload for encoding arbitrary plain text into a QR code. The text must be non-empty and at most 4296 characters (the maximum data capacity of a QR code at version 40 with low error correction).

Example: 

p, err := payload.Text("Hello, world!")
if err != nil { /* handle error */ }
data, _ := p.Encode() // "Hello, world!"

func (*TextPayload) Encode 

func (t *TextPayload) Encode() (string, error)

Encode returns the text content as the QR code data string. The returned string is the raw Text value, unmodified.

func (*TextPayload) Size 

func (t *TextPayload) Size() int

Size returns the byte length of the text.

func (*TextPayload) Type 

func (t *TextPayload) Type() string

Type returns "text".

func (*TextPayload) Validate 

func (t *TextPayload) Validate() error

Validate checks that the text is non-empty and within the maximum length of 4296 characters (QR version 40, EC level L).

type TwitterFollowPayload 

type TwitterFollowPayload struct {
	// ScreenName is the screen name of the user to follow.
	ScreenName string
}

TwitterFollowPayload encodes a link to a Twitter (X) user profile on x.com (the current Twitter domain). The screen name should not include the @ prefix.

Example encoded output: 

https://x.com/golang

func (*TwitterFollowPayload) Encode 

func (t *TwitterFollowPayload) Encode() (string, error)

Encode returns an x.com profile URL.

func (*TwitterFollowPayload) Size 

func (t *TwitterFollowPayload) Size() int

Size returns the byte length of the encoded URL.

func (*TwitterFollowPayload) Type 

func (t *TwitterFollowPayload) Type() string

Type returns "twitter_follow".

func (*TwitterFollowPayload) Validate 

func (t *TwitterFollowPayload) Validate() error

Validate checks that the screen name is non-empty.

type TwitterPayload 

type TwitterPayload struct {
	// Username is the Twitter username (without the @ prefix).
	Username string
}

TwitterPayload encodes a link to a Twitter (X) user profile. The username should not include the @ prefix.

Example encoded output: 

https://twitter.com/golang

func Twitter 

func Twitter(username string) (*TwitterPayload, error)

Twitter creates a validated TwitterPayload that encodes a twitter.com profile link for the given username (without the @ prefix).

Example: 

p, err := payload.Twitter("golang")
data, _ := p.Encode() // "https://twitter.com/golang"

func (*TwitterPayload) Encode 

func (t *TwitterPayload) Encode() (string, error)

Encode returns a twitter.com profile URL.

func (*TwitterPayload) Size 

func (t *TwitterPayload) Size() int

Size returns the byte length of the encoded URL.

func (*TwitterPayload) Type 

func (t *TwitterPayload) Type() string

Type returns "twitter".

func (*TwitterPayload) Validate 

func (t *TwitterPayload) Validate() error

Validate checks that the username is non-empty.

type URLPayload 

type URLPayload struct {
	// URL is the target URL to encode.
	URL string
	// Title is an optional fragment title appended to the URL.
	Title string
}

URLPayload encodes a URL into a QR code. The URL is normalized to HTTPS if no scheme is provided. An optional Title field is appended as a URL fragment (#title) to provide a human-readable label in some QR reader apps.

Supported schemes are http and https. If the input has no scheme, https is automatically prepended.

func URL 

func URL(rawURL string) (*URLPayload, error)

URL creates a validated URLPayload for encoding a web link into a QR code. The URL is normalized to HTTPS if no scheme is provided. Only http and https schemes are supported.

Example: 

p, err := payload.URL("https://example.com")
data, _ := p.Encode() // "https://example.com"

p, err = payload.URL("example.com")
data, _ = p.Encode() // "https://example.com" (auto-prefixed)

func (*URLPayload) Encode 

func (u *URLPayload) Encode() (string, error)

Encode returns a normalized HTTPS URL, optionally with a title fragment. If the URL has no scheme, https:// is prepended. If Title is set, it is URL-encoded and appended as a fragment (#title).

func (*URLPayload) Size 

func (u *URLPayload) Size() int

Size returns the byte length of the encoded URL.

func (*URLPayload) Type 

func (u *URLPayload) Type() string

Type returns "url".

func (*URLPayload) Validate 

func (u *URLPayload) Validate() error

Validate checks that the URL is non-empty and has a supported scheme. Only http and https schemes are accepted.

type VCardPayload 

type VCardPayload struct {
	// Version is the vCard version (defaults to "3.0").
	Version string
	// FirstName is the given name.
	FirstName string
	// LastName is the family name.
	LastName string
	// Phone is the telephone number.
	Phone string
	// Email is the email address.
	Email string
	// Organization is the company or organization name.
	Organization string
	// Title is the job title.
	Title string
	// URL is the website address.
	URL string
	// Address is the postal address.
	Address string
	// Note is a free-text note.
	Note string
}

VCardPayload encodes a contact as a vCard electronic business card. By default, version 3.0 is used, which offers broad compatibility across QR readers, contact apps, and email clients. Supported versions are:

  • "2.1" — legacy vCard format
  • "3.0" — RFC 6350 predecessor (default)
  • "4.0" — RFC 6350 current standard

The encoded output uses CRLF line endings and includes BEGIN:VCARD / END:VCARD delimiters. Optional fields (phone, email, organization, etc.) are included only when non-empty.

Example encoded output: 

BEGIN:VCARD\r\nVERSION:3.0\r\nN:Doe;Jane\r\nFN:Jane Doe\r\nEND:VCARD

func Contact 

func Contact(firstName, lastName string, opts ...ContactOption) (*VCardPayload, error)

Contact creates a validated VCardPayload (vCard 3.0 by default) with optional functional options for adding phone, email, organization, title, address, URL, and notes. The vCard format follows RFC 6350 (with backward compatibility for versions 2.1 and 3.0).

Example: 

p, err := payload.Contact("Jane", "Doe",
    payload.WithPhone("+1-555-0123"),
    payload.WithEmail("jane@example.com"),
    payload.WithOrganization("Acme Inc"),
)
data, _ := p.Encode() // "BEGIN:VCARD\r\nVERSION:3.0\r\nN:Doe;Jane\r\n..."

func (*VCardPayload) Encode 

func (v *VCardPayload) Encode() (string, error)

Encode returns a vCard formatted string with CRLF line endings. Only non-empty optional fields (TEL, EMAIL, ORG, TITLE, URL, ADR, NOTE) are included in the output.

func (*VCardPayload) Size 

func (v *VCardPayload) Size() int

Size returns the byte length of the encoded vCard.

func (*VCardPayload) Type 

func (v *VCardPayload) Type() string

Type returns "vcard".

func (*VCardPayload) Validate 

func (v *VCardPayload) Validate() error

Validate checks that at least FirstName or LastName is provided and that the version (if set) is one of "2.1", "3.0", or "4.0".

type WhatsAppPayload 

type WhatsAppPayload struct {
	// Phone is the phone number in international format.
	Phone string
	// Message is an optional pre-filled message.
	Message string
}

WhatsAppPayload encodes a WhatsApp chat link using the wa.me deep link API. The phone number is cleaned to digits only before being appended to the URL. An optional pre-filled message is added as a ?text= query parameter. When scanned, the QR code opens a WhatsApp chat with the specified number.

Example encoded output: 

https://wa.me/14155552671?text=Hello%20there

func WhatsApp 

func WhatsApp(phone, message string) (*WhatsAppPayload, error)

WhatsApp creates a validated WhatsAppPayload that encodes a wa.me chat link. The phone number is cleaned to digits only (leading + is stripped). An optional pre-filled message is appended as a ?text= query parameter.

Example: 

p, err := payload.Whatsapp("+1-415-555-2671", "Ready?")
data, _ := p.Encode() // "https://wa.me/14155552671?text=Ready%3F"

func (*WhatsAppPayload) Encode 

func (w *WhatsAppPayload) Encode() (string, error)

Encode returns a wa.me link with an optional text parameter. The phone number is stripped of non-digit characters. The message, if present, is URL-encoded and appended as ?text=...

func (*WhatsAppPayload) Size 

func (w *WhatsAppPayload) Size() int

Size returns the byte length of the encoded wa.me link.

func (*WhatsAppPayload) Type 

func (w *WhatsAppPayload) Type() string

Type returns "whatsapp".

func (*WhatsAppPayload) Validate 

func (w *WhatsAppPayload) Validate() error

Validate checks that the phone number is non-empty and contains at least one digit after cleaning (non-digit characters are stripped).

type WiFiPayload 

type WiFiPayload struct {
	// SSID is the network name.
	SSID string
	// Password is the network passphrase.
	Password string
	// Encryption is the encryption type (WEP, WPA, WPA2, WPA3, SAE, nopass).
	Encryption string
	// Hidden indicates whether the SSID is hidden.
	Hidden bool
}

WiFiPayload encodes a WiFi network configuration into a QR code using the standard WIFI:T:...;S:...;P:...;; format. This format is recognized by Android (since Android 10), iOS (since iOS 11), and many other QR readers.

Special characters in the SSID and password (\, ;, ,, ", :) are escaped using backslash-hex notation (\XX) per the barcode specification.

The following encryption types are supported as constants:

  • EncryptionWEP ("WEP")
  • EncryptionWPA ("WPA")
  • EncryptionWPA2 ("WPA2")
  • EncryptionWPA3 ("WPA3")
  • EncryptionSAE ("SAE")
  • EncryptionNoPass ("nopass") — for open networks

Example encoded output: 

WIFI:T:WPA2;S:MyNetwork;P:s\3Acret;;

func WiFi 

func WiFi(ssid, password, encryption string) (*WiFiPayload, error)

WiFi creates a validated WiFiPayload using the standard WIFI:T:...;S:...;P:...;; QR code format recognized by most smartphones. Special characters in the SSID and password are escaped using hex encoding (\XX).

The encryption parameter must be one of: WEP, WPA, WPA2, WPA3, SAE, or nopass. For open networks, use "nopass" and an empty password.

Example: 

p, err := payload.WiFi("MyNetwork", "s3cret", "WPA2")
data, _ := p.Encode() // "WIFI:T:WPA2;S:MyNetwork;P:s3cret;;"

func WiFiWithHidden 

func WiFiWithHidden(ssid, password, encryption string) (*WiFiPayload, error)

WiFiWithHidden creates a validated WiFiPayload with the hidden SSID flag set. This adds ;H:true to the encoded string, indicating that the network does not broadcast its SSID.

Example: 

p, err := payload.WiFiWithHidden("HiddenNet", "p@ss", "WPA3")
data, _ := p.Encode() // "WIFI:T:WPA3;S:HiddenNet;P:p@ss;H:true;;"

func (*WiFiPayload) Encode 

func (w *WiFiPayload) Encode() (string, error)

Encode returns the WIFI:... string representation of the network configuration. Special characters in SSID and Password are hex-escaped. The password field is omitted when encryption is "nopass".

func (*WiFiPayload) Size 

func (w *WiFiPayload) Size() int

Size returns the byte length of the encoded WiFi string.

func (*WiFiPayload) Type 

func (w *WiFiPayload) Type() string

Type returns "wifi".

func (*WiFiPayload) Validate 

func (w *WiFiPayload) Validate() error

Validate checks that the SSID is non-empty, the encryption type is one of the supported values, and a password is provided when encryption is not "nopass".

type YouTubeChannelPayload 

type YouTubeChannelPayload struct {
	// ChannelID is the YouTube channel ID.
	ChannelID string
}

YouTubeChannelPayload encodes a link to a YouTube channel.

Example encoded output: 

https://youtube.com/channel/UC_x5XG1OV2P6uZZ5FSM9Ttw

func (*YouTubeChannelPayload) Encode 

func (y *YouTubeChannelPayload) Encode() (string, error)

Encode returns a youtube.com/channel/ URL.

func (*YouTubeChannelPayload) Size 

func (y *YouTubeChannelPayload) Size() int

Size returns the byte length of the encoded URL.

func (*YouTubeChannelPayload) Type 

func (y *YouTubeChannelPayload) Type() string

Type returns "youtube_channel".

func (*YouTubeChannelPayload) Validate 

func (y *YouTubeChannelPayload) Validate() error

Validate checks that the channel ID is non-empty.

type YouTubeVideoPayload 

type YouTubeVideoPayload struct {
	// VideoID is the YouTube video ID.
	VideoID string
}

YouTubeVideoPayload encodes a link to a YouTube video.

Example encoded output: 

https://youtube.com/watch?v=dQw4w9WgXcQ

func YouTubeVideo 

func YouTubeVideo(videoID string) (*YouTubeVideoPayload, error)

YouTubeVideo creates a validated YouTubeVideoPayload that encodes a youtube.com/watch?v= URL for the given video ID.

Example: 

p, err := payload.YouTubeVideo("dQw4w9WgXcQ")
data, _ := p.Encode() // "https://youtube.com/watch?v=dQw4w9WgXcQ"

func (*YouTubeVideoPayload) Encode 

func (y *YouTubeVideoPayload) Encode() (string, error)

Encode returns a YouTube watch URL.

func (*YouTubeVideoPayload) Size 

func (y *YouTubeVideoPayload) Size() int

Size returns the byte length of the encoded URL.

func (*YouTubeVideoPayload) Type 

func (y *YouTubeVideoPayload) Type() string

Type returns "youtube_video".

func (*YouTubeVideoPayload) Validate 

func (y *YouTubeVideoPayload) Validate() error

Validate checks that the video ID is non-empty.

type ZoomPayload 

type ZoomPayload struct {
	// MeetingID is the Zoom meeting ID.
	MeetingID string
	// Password is the optional meeting password.
	Password string
	// DisplayName is the optional display name for the joiner.
	DisplayName string
}

ZoomPayload encodes a Zoom meeting join link. When scanned, the QR code opens the Zoom app or web client and prompts the user to join the specified meeting. An optional password and display name can be pre-filled.

Example encoded output: 

https://zoom.us/j/1234567890?pwd=secret&uname=Jane%20Doe

func Zoom 

func Zoom(meetingID, password string) (*ZoomPayload, error)

Zoom creates a validated ZoomPayload that encodes a zoom.us/j/ meeting join link with an optional password (pwd) and display name (uname).

Example: 

p, err := payload.Zoom("1234567890", "secret")
data, _ := p.Encode() // "https://zoom.us/j/1234567890?pwd=secret"

func (*ZoomPayload) Encode 

func (z *ZoomPayload) Encode() (string, error)

Encode returns a zoom.us/j/ URL with optional password (pwd) and display name (uname) query parameters.

func (*ZoomPayload) Size 

func (z *ZoomPayload) Size() int

Size returns the byte length of the encoded Zoom URL.

func (*ZoomPayload) Type 

func (z *ZoomPayload) Type() string

Type returns "zoom".

func (*ZoomPayload) Validate 

func (z *ZoomPayload) Validate() error

Validate checks that the meeting ID is non-empty.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.