Receipt Service API (1.0.0)

Key Concepts

Two Receipt Types

• Invoice-Based: Payment applied to one or more invoices
• Payment-Only: Standalone payment (e.g., one-time service fee) with no invoices

Receipt Generation

• Branded with merchant configuration using Liquid templates
• Delivered via email through OSI Push Notification Service
• MVP: HTML rendering on-demand (PDF generation and S3 storage are post-MVP)

Error Handling

All API responses use HTTP status 200. Success and failure are expressed in the NPS response envelope.

• responseCode A100 indicates success; the payload is in the object field when present.
• responseCode values E4xx (and E500) indicate errors; responseMessage carries details.
• E422 (VALIDATION_ERROR) is returned for standard request validation failures.

Additional application error codes include E400_VALIDATION (request validation failure, for example malformed entityId), E403_ACCESS (caller lacks permission for the requested resource), and E403_TENANT (entity ID is outside the caller's hierarchy).

Exception to HTTP 200 convention: Requests with a syntactically invalid entityId (non-numeric or negative) receive HTTP 400 with a minimal JSON body (responseCode: "E400_VALIDATION") before reaching the application layer. This is enforced by the tenant isolation interceptor and does not use the standard NPS envelope.

Null field omission: Success and error responses use @JsonInclude(NON_NULL). Fields with null values (including object on void successes and responseDetails when absent) are omitted from the JSON response rather than serialized as explicit null.

Authentication Note

OpenAPI security schemes in this specification reference OAuth2 for documentation tooling compatibility. In deployed environments, all service-to-service authentication uses S2S JWT (signed JWTs from the hierarchy key tree).