acpdiscovery

Documentation

Overview

Package acpdiscovery serves the public ACP discovery document.

Mount Handler at the origin root. It responds only to GET /.well-known/acp.json, requires no authentication, and advertises stable seller capabilities before a checkout session is created.

Index

• Constants
• type Capabilities
• type Document
• type Extension
• type Handler
  • func NewHandler(document Document) (*Handler, error)
  • func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type InterventionType
• type Protocol
• type Service
• type Transport

Examples

• NewHandler

Constants

const (
	// Path is the RFC 8615 well-known location for ACP discovery.
	Path = "/.well-known/acp.json"
	// ProtocolName is the required ACP protocol identifier.
	ProtocolName = "acp"
)

Types

type Capabilities

type Capabilities struct {
	Services            []Service          `json:"services"`
	Extensions          []Extension        `json:"extensions,omitempty"`
	InterventionTypes   []InterventionType `json:"intervention_types,omitempty"`
	SupportedCurrencies []string           `json:"supported_currencies,omitempty"`
	SupportedLocales    []string           `json:"supported_locales,omitempty"`
}

Capabilities contains seller capabilities that are stable across sessions.

type Document

type Document struct {
	Protocol     Protocol     `json:"protocol"`
	APIBaseURL   string       `json:"api_base_url"`
	Transports   []Transport  `json:"transports"`
	Capabilities Capabilities `json:"capabilities"`
}

Document is the response served from Path.

type Extension

type Extension struct {
	Name   string  `json:"name"`
	Spec   *string `json:"spec,omitempty"`
	Schema *string `json:"schema,omitempty"`
}

Extension declares a seller-supported ACP extension.

type Handler

type Handler struct {
	// contains filtered or unexported fields
}

Handler serves an immutable discovery document.

func NewHandler

func NewHandler(document Document) (*Handler, error)

NewHandler validates and serializes document for concurrent serving.

Example

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"net/http/httptest"

	"github.com/sumup/acp"
	"github.com/sumup/acp/acpdiscovery"
)

func main() {
	handler, err := acpdiscovery.NewHandler(acpdiscovery.Document{
		Protocol: acpdiscovery.Protocol{
			Name:              acpdiscovery.ProtocolName,
			Version:           acp.APIVersion,
			SupportedVersions: []string{acp.APIVersion},
		},
		APIBaseURL: "https://merchant.example/acp",
		Transports: []acpdiscovery.Transport{acpdiscovery.TransportREST},
		Capabilities: acpdiscovery.Capabilities{
			Services: []acpdiscovery.Service{
				acpdiscovery.ServiceCheckout,
				acpdiscovery.ServiceCarts,
			},
		},
	})
	if err != nil {
		panic(err)
	}

	recorder := httptest.NewRecorder()
	handler.ServeHTTP(recorder, httptest.NewRequest(http.MethodGet, acpdiscovery.Path, nil))

	var document acpdiscovery.Document
	if err := json.NewDecoder(recorder.Body).Decode(&document); err != nil {
		panic(err)
	}
	fmt.Println(recorder.Code, document.Protocol.Version, document.Capabilities.Services)
}

Output:
200 2026-04-17 [checkout carts]

func (*Handler) ServeHTTP

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP serves the discovery document at Path.

type InterventionType

type InterventionType string

InterventionType is a buyer-intervention capability.

const (
	Intervention3DS                 InterventionType = "3ds"
	InterventionBiometric           InterventionType = "biometric"
	InterventionAddressVerification InterventionType = "address_verification"
)

type Protocol

type Protocol struct {
	Name              string   `json:"name"`
	Version           string   `json:"version"`
	SupportedVersions []string `json:"supported_versions"`
	DocumentationURL  *string  `json:"documentation_url,omitempty"`
}

Protocol identifies ACP versions supported by the seller.

type Service

type Service string

Service is an ACP service advertised by a seller.

const (
	ServiceCheckout        Service = "checkout"
	ServiceOrders          Service = "orders"
	ServiceDelegatePayment Service = "delegate_payment"
	ServiceCarts           Service = "carts"
)

type Transport

type Transport string

Transport is a supported ACP transport binding.

const (
	TransportREST Transport = "rest"
	TransportMCP  Transport = "mcp"
)