AppendPaymentIdentifierToExtensions appends a payment identifier to the extensions object if the server declared support for the payment-identifier extension.

This function reads the server's payment-identifier declaration from the extensions, and appends the client's ID to it. If the extension is not present (server didn't declare it), the extensions are returned unchanged.

Args:

• extensions: The extensions object from PaymentRequired (will be modified in place)
• id: Optional custom payment ID. If empty, a new ID will be generated.

Returns:

• Error if the provided ID is invalid

Example:

// Get extensions from server's PaymentRequired response
extensions := paymentRequired.Extensions
if extensions == nil {
    extensions = make(map[string]interface{})
}

// Append a generated ID (only if server declared payment-identifier)
err := paymentidentifier.AppendPaymentIdentifierToExtensions(extensions, "")

// Or use a custom ID
err := paymentidentifier.AppendPaymentIdentifierToExtensions(extensions, "pay_my_custom_id_12345")

DeclarePaymentIdentifierExtension creates a payment-identifier extension declaration for inclusion in PaymentRequired.extensions.

Resource servers call this function to advertise support for payment identifiers. The declaration indicates whether a payment identifier is required and includes the schema that clients must follow.

Args:

• required: Whether clients must provide a payment identifier. When true, clients must provide an id or receive a 400 Bad Request.

Returns:

• A PaymentIdentifierExtension object ready for PaymentRequired.extensions

Example:

// Include in PaymentRequired response (optional identifier)
extensions := map[string]interface{}{
    paymentidentifier.PAYMENT_IDENTIFIER: paymentidentifier.DeclarePaymentIdentifierExtension(false),
}

// Require payment identifier
extensions := map[string]interface{}{
    paymentidentifier.PAYMENT_IDENTIFIER: paymentidentifier.DeclarePaymentIdentifierExtension(true),
}

ExtractAndValidatePaymentIdentifier extracts and validates the payment identifier from a PaymentPayload.

Args:

• payload: The payment payload to extract from

Returns:

• The ID (or empty string if not present)
• ValidationResult with any errors

ExtractPaymentIdentifier extracts the payment identifier from a PaymentPayload.

Args:

• payload: The payment payload to extract from
• validate: Whether to validate the ID before returning

Returns:

• The payment ID string, or empty string if not present
• Error if extraction fails or validation fails (when validate is true)

ExtractPaymentIdentifierFromBytes extracts the payment identifier from raw PaymentPayload bytes.

This is useful for facilitators that receive the payload as raw bytes. Returns empty string for V1 payloads (which don't support extensions).

Args:

• payloadBytes: Raw JSON bytes of the payment payload
• validate: Whether to validate the ID before returning

Returns:

• The payment ID string, or empty string if not present or V1 payload
• Error if extraction fails

ExtractPaymentIdentifierFromPaymentRequired extracts the required flag from a PaymentRequired response.

This is useful for clients to determine if they need to provide a payment identifier.

Args:

• paymentRequiredBytes: Raw JSON bytes of the 402 PaymentRequired response

Returns:

• Whether the server requires a payment identifier
• Error if extraction fails

GeneratePaymentID generates a unique payment identifier with the given prefix. If prefix is empty, "pay_" is used as the default prefix.

The generated ID format is: prefix + UUID v4 without hyphens (32 hex chars) Example: "pay_7d5d747be160e280504c099d984bcfe0"

HasPaymentIdentifier checks if a PaymentPayload contains a payment-identifier extension.

Args:

• payload: The payment payload to check

Returns:

• True if the extension is present

IsPaymentIdentifierExtension checks if an object is a valid payment-identifier extension structure.

This checks for the basic structure (info object with required boolean), but does not validate the id format if present.

Args:

• extension: The object to check

Returns:

• True if the object has the expected payment-identifier extension structure

IsPaymentIdentifierRequired checks if the server requires a payment identifier based on the extension info.

Args:

• extension: The payment-identifier extension from PaymentRequired or PaymentPayload

Returns:

• True if the server requires a payment identifier

IsValidPaymentID validates that a payment ID meets the format requirements. Returns true if the ID is valid, false otherwise.

Validation rules:

• Length must be between 16 and 128 characters (inclusive)
• Must contain only alphanumeric characters, hyphens, and underscores

PaymentIdentifierSchema returns the JSON Schema for validating payment identifier info. The schema is compliant with JSON Schema Draft 2020-12.

ValidatePaymentIdentifier validates a payment-identifier extension object.

Checks both the structure (using JSON Schema) and the ID format.

Args:

• extension: The extension object to validate

Returns:

• ValidationResult with errors if invalid

ValidatePaymentIdentifierRequirement validates that a payment identifier is provided when required.

Use this to check if a client's PaymentPayload satisfies the server's requirement.

Args:

• payload: The client's payment payload
• serverRequired: Whether the server requires a payment identifier (from PaymentRequired)

Returns:

• ValidationResult - invalid if required but not provided