{"openapi":"3.1.0","info":{"title":"QR+ Payee Service Provider API","version":"1.2.0","description":"This API definition captures the Payee Service Provider API specification. The PeSP hosts this API for orchestration of enrichment flows.\n\nThis API does not cover the interfaces between the PeSP and their respective Payees and Payers. The API assumes that the following exchanges have been successfully completed before ths API is used:\n\n- **Paylink generation:** A new Paylink was generated by a Paylink Provider at the request of a Payer or Payee.\n- **Paylink presentment:** The Paylink was presented for scanning.\n- **Paylink scanning:** The Paylink was scanned and presented to a QR+ Service Provider for processing.\n\nTo contextualize how QR+ fits into a complete payment, the sequence diagram below also includes **placeholder steps for processes that fall outside the QR+ API surface**. These placeholders are not specified by QR+ and will vary by payment rail and participant — they are shown only to make the integration points with rail-specific infrastructure explicit.\n\nThe non-QR+ placeholders are:\n\n- **Rail Selection** — the PrSP and Payer decide which of the acceptance options presented by the PeSP will be used for this payment.\n- **Prior to Approval** (rail-specific) — rail infrastructure may be used to gather additional information used during the Payer's approval of the payment.\n- **Push Payment Initiation** (rail-specific).\n- **Pull Payment Initiation** (rail-specific).\n\nIn the diagram, treat these placeholders as black boxes: their internal exchanges are out of scope for this specification, but their entry/exit points anchor where QR+ flows hand off to and resume from the underlying rail.\n\nA high-level sequence diagram of the subsequent exchange:\n\n\n","x-logo":{"url":"https://imagedelivery.net/ipmJ55bBDVfBJxiG3wVbtg/c6121c60-dcc9-4bf5-f7d1-72b607507c00/public"}},"servers":[{"url":"http://localhost:3000"}],"tags":[{"name":"Copyright and Liability Disclaimer","description":"\nFull Copyright and Liability Disclaimer
\n\nThe QR+ Standard has been developed by the South African Reserve Bank for use by participants in the National Payment System. All intellectual property rights, including copyright and any related rights in and to the QR+ Standard, are owned by, or vest in, the South African Reserve Bank. No participant or other person acquires any ownership right, title or interest in the QR+ Standard by virtue of its access to, implementation of or use of the QR+ Standard. The QR+ Standard may not be copied, reproduced, adapted, amended, transferred, ceded, assigned, sublicensed, published, distributed or otherwise made available to any third party, in whole or in part, without the prior written consent of the South African Reserve Bank, except to the extent expressly permitted by the South African Reserve Bank.\n\nParticipants are responsible for developing, implementing, maintaining and operating their own systems, processes and controls to ensure compliance with the QR+ Standard and with all applicable laws, regulatory requirements and industry standards. The South African Reserve Bank does not warrant that the QR+ Standard, or any implementation thereof by a participant, will be error-free, uninterrupted, fit for any particular purpose or suitable for any participant’s specific operational or commercial requirements.\n\nTo the fullest extent permitted by law, the South African Reserve Bank shall not be liable for any loss, damage, claim, cost or expense, whether direct, indirect, special, incidental or consequential, arising from or in connection with a participant’s access to, reliance on, implementation of, or use of the QR+ Standard, including any failure by a participant to comply with the QR+ Standard or any applicable legal or regulatory requirement.\n\n \n"},{"name":"Version History","description":"\n Version: 1.2.0 (2026-06-05)
\n\nRelease candidate 1.2.0-rc2 approved for publication\n\n \n"},{"name":"Pep Paylink Resolution","description":"Use the Pep 'resolve' endpoint as the starting point of a flow when your customer has scanned a PeP Paylink. The PeSP returns the following information after you have submitted a valid Paylink for resolution:\n\n- Payee identity information which can be presented to the Payer when establishing informed approval.\n- Tracking details to facilitate session management and audit traceability.\n"},{"name":"Payment Reply","description":"Use the 'Payment Reply' endpoint to respond to a Payment Request logged to you by the PeSP.\n"},{"name":"Loyalty Reply","description":"Use the 'Loyalty Reply' endpoint to respond to a Loyalty Request logged to you by the Payee SP.\n"},{"name":"Identity Reply","description":"Use the 'Identity Reply' endpoint to respond to a Identity Request logged to you by the Payee SP.\n"},{"name":"Implementation Requirements","description":"### API Extensibility\n\nThe QR+ standard makes provision for Service Providers to extend the functionality of standard API's to enable industry innovation. These extensions must, however, comply to strict requirements and not broaden a Service Providers capabilities beyond what they are legally allowed to do. SARB retains the right to disallow any extension deemed to contravene this guideline.\n\nAny server side extension of this API MUST:\n\n- Provide a standard compliant responses to any standard compliant call from a client\n- NOT expose any additional endpoints, not specified in this standard, or implement additional or alternative APIs using the QR+ authentication and authorization framework\n- Implement all endpoints and provide relevant error messages for all unsupported capabilities\n- Extend functionality only by providing new discriminated union options in existing payloads\n- Remain compliant to all flow reporting requirements across both standard and extended endpoints\n\n### Flow Session Status Management\n\n- The PrSP is the authority of flow session status. The flow session status can be either `OPEN`, `EXPIRED` or `TERMINATED` with both `EXPIRED` and `TERMINATED` being considered closed. The PrSP processes PeSP Requests only while the flow session status is `OPEN`.\n- The PrSP opens a session upon receipt, and successful processing, of either (i) a PrP Paylink resolution request or (ii) a response to a PeP Paylink resolution request. The initial session expiry deadline must be 15s after the session is opened.\n- The PrSP may terminate a flow session at will following, for example:\n - A Payer’s request to terminate the session\n - Loss of connectivity to the Payer\n - Processing errors\n- The flow session expiry deadline is communicated through an `expiresAt` timestamp sent by the PrSP to the PeSP in the tracking object of every interaction.\n- The PrSP may extend the flow session expiry deadline following, for example:\n - Receipt of an explicit request from the PeSP to do so (through the `/request-session-extension` endpoint)\n - Additional time required to interact with the Payer\n - A need to resolve ambiguous flow state. (e.g. awaiting a payment conclusion from the PeSP)\n- The PrSP must not expire a flow session while there is an outstanding Reply pending to the PeSP and must extend the expiry deadline by at least 5 seconds after making the Reply call to allow the PeSP enough time to process the Reply and optionally send further Requests. The PrSP must make a Reply call to the PeSP for every Request that was accepted irrespective of flow session status.\n- When a flow session is `TERMINATED` or had `EXPIRED`, the PrSP must return the final flow status with the appropriate error to all subsequent Requests for at least 240 minutes after the final status change. Thereafter the session context may be purged from the system (see Flow Record section for retention requirements).\n- The PeSP must use the `expiresAt` timestamp to manage its activity but must not consider a session closed until formal confirmation to the fact is received from the PrSP.\n\n### Recording Flow Interactions\n\nAll QR+ Service Providers MUST maintain a record of flow interactions for compliance, traceability, and operational purposes. This record also serves as the foundation for Retry idempotency (see Retry and Idempotency section).\n\n**Core Principle**: All SP interactions linked to a flow MUST be captured as part of the Flow Record. This includes all ingress payloads (incoming requests and responses) and egress payloads (outgoing requests, responses and replies). All interactions, where a valid flow context exists, MUST be included in a Flow Interaction Record while Interactions (responses) where an Error is returned without a firm flow context being established (e.g. Unauthorized, Forbidden, Flow sequence violations etc.) should not be included .\n\n#### Structure\n\nWhen exposing or presenting a Flow Record, its structure must comply to the FlowInteractionRecord schema defined below. This allows consistent formatting by all flow participants and easy comparison of Records between PrSP and PeSP.\n\n```typescript\nconst FlowInteractionRecord = z.object({\n payerSpFlowId: PayerSpFlowId, // Mandatory PrSP Flow ID\n payeeSpFlowId: PayeeSpFlowId, // Mandatory PeSP Flow ID\n extractedAt: TimeStampRo, // Instant when record was extracted (flow may still be in progress)\n flowStatus: z.enum(['OPEN', 'EXPIRED', 'TERMINATED']), // Flow status at instant of extraction\n interactions: z.array(z.discriminatedUnion('reqOrRes', [\n z\n .object({\n reqOrRes: z.literal('REQUEST'), // Request (from Http perspective)\n authCtx: z.object({ // JWT Authorization context\n iss: AuthzAuthorityId, // JWT issuer\n sub: ServiceId, // JWT source service (subscriber)\n aud: ServiceId, // JWT target service (audience)\n }),\n loggedAt: TimeStamp,\n sourceServiceId: ServiceId, // The service which was the source of the request\n targetServiceId: ServiceId, // The service which was the target/destination of the request\n direction: z.enum(['PeSP<=PrSP', 'PeSP=>PrSP']), // Direction of the request\n payload: z.discriminatedUnion('operation', [ // Any request payload from any Payer or Payee SP API as defined by API schemas\n ...PayeeProviderInteractionRequests.options,\n ...PayerProviderInteractionRequests.options,\n ]),\n })\n z\n .object({\n reqOrRes: z.literal('RESPONSE'), // Response (from Http perspective)\n loggedAt: TimeStampRo,\n sourceServiceId: ServiceId, // The service which was the source of the response\n targetServiceId: ServiceId, // The service which was the target/destination of the response\n direction: z.enum(['PeSP<=PrSP', 'PeSP=>PrSP']), // Direction of the request\n payload: z.discriminatedUnion('operation', [ // Any response from any Payer or Payee SP API as defined by API schemas (includes http status value)\n ...PayeeProviderInteractionResponses.options,\n ...PayerProviderInteractionResponses.options,\n ]),\n })\n ])),\n})\n```\n\n#### Other Requirements\n\nFlow Interaction Records MUST be retained for at least five years. Flow Interaction Records serve as an audit record and MUST comply to relevant standards and practices.\n\n### Retry and Idempotency\n\nQR+ APIs are designed for high-reliability, low-latency server-to-server communication in a distributed peer-to-peer environment. Both PrSP and PeSP implementations must handle transient failures gracefully through Retry mechanisms while preventing duplicate processing through idempotency guarantees.\n\n#### Client Retries\n\nIn the context of this specification, a Retry is defined as an attempt by a client to complete a network exchange that did not receive an official response from the server. This should be seen in contrast to a Re-execute which is an attempt by the client to have the server re-evaluate a previously declined request.\n\nThe client, when executing a Retry, MUST use the same tracking sequences it used in the original request. When the intent is to do a Re-execute, it MUST use a different tracking sequence with a value larger than numbers previously used within the Flow context. The server will return a response to a Retry only if the new request is considered equivalent to that originally received. (See server Idempotency requirements)\n\nA client MAY execute a Retry on any timeout condition or Error response but SHOULD limit Retries to errors consistent with communication failures. Retries MUST NOT be captured in in Flow Record to avoid duplicate entries against a specific flow sequence.\n\n**Timeout Configuration:**\n\n- Clients MUST implement a fixed 3-second timeout for all requests\n- This timeout is based on a target p99 latency of less than 1 second across the QR+ ecosystem\n- Clients MUST abandon requests that exceed the timeout and treat them as failures eligible for Retry\n- Service providers whose services cannot meet the 3-second timeout requirement are considered non-compliant\n\n**Circuit Breaker Policy:**\n\n- Clients MUST implement circuit breaker protection to prevent cascading failures and enable fast-fail behavior\n- Circuit breaker states:\n - **Closed (Normal):** All requests pass through normally; error rates are tracked continuously\n - **Open (Rate-Limited Probing):** Requests are rate-limited to one every 3 seconds (2s + random 0-1s); on first successful probe return to closed state; failed probes keep circuit open\n- Circuit breaker configuration:\n\n - **Error Rate Threshold:** Open circuit when failure rate exceeds 50% over the measurement window\n - **Measurement Window:** 10 seconds (track success/failure rates over rolling 10-second window)\n - **Minimum Request Threshold:** 5 requests minimum within window before circuit can open (prevents tripping on sporadic errors under low load)\n\n- When a probe request during open state receives HTTP 503 with a `Retry-After` header, the circuit breaker SHOULD wait for the indicated duration before the next probe (overriding the 3-second default)\n- Circuit breaker state SHOULD be tracked per target service endpoint to isolate failures\n- Circuit breaker measurement window stats MUST be cleared when circuit breaker opens to avoid flapping\n\n**Retry Strategy:**\n\n- Retry logic applies AFTER circuit breaker evaluation (circuit breaker provides first layer of protection)\n- Clients SHOULD Retry failed requests immediately (no delay) for the following transient error conditions:\n - HTTP 502 (Bad Gateway) - transient gateway/proxy error\n - HTTP 503 (Service Unavailable) - temporary overload or maintenance\n - HTTP 504 (Gateway Timeout) - upstream timeout\n - HTTP 408 (Request Timeout) - server-side timeout\n - HTTP 429 (Too Many Requests) - rate limiting\n - Network connectivity failures (connection refused, timeout, DNS resolution failure)\n- Clients SHOULD NOT Retry for the following permanent error conditions (though servers will handle Retries with Idempotency if they occur):\n - HTTP 400 (Bad Request) - malformed request\n - HTTP 401 (Unauthorized) - authentication failure\n - HTTP 403 (Forbidden) - authorization failure\n - HTTP 404 (Not Found) - resource not found\n - HTTP 422 (Semantic Error) - business rule violation\n - HTTP 500 (Internal Server Error) - non-transient server bug/exception\n - Circuit breaker open errors (do not perform Retries while circuit breaker is open)\n- Maximum of 3 total attempts per request (1 initial attempt + up to 2 retries)\n- Retries occur immediately after timeout (no backoff delay) - circuit breaker provides cascade protection\n- When a 503 or 429 response includes a `Retry-After` header, clients SHOULD wait for the indicated duration before attempting a Retry\n\n**Idempotency for Retries:**\n\n- Clients MUST use the tracking mechanism for idempotency rather than introducing additional headers\n- When Retrying, clients MUST send an IDENTICAL request body with the same tracking values\n\n#### Server-Side Idempotency\n\nServers MUST use the Flow Record as the foundation for Retry idempotency. The Flow Record serves as both a compliance record and a response cache for safe Retry handling. When a request is received which is found to be Equivalent to an interaction on the Flow Record, then the corresponding response on the Record MUST be returned.\n\n**Request Equivalence:**\n\nServers determine request equivalence using the following criteria (all must match):\n\n1. **Authenticated Identity:** Requests with successfully validated JWT where the subject (`sub`) and audience (`aud`) claims match. Retries from different issuer or with different keys are allowed to accommodate token expiry\n2. **Endpoint:** The API operation must be identical. The operation is a combination of http path and method\n3. **Full Request Body:** The complete request body (including tracking object) must be identical when compared as canonical JSON\n\n**Idempotency Detection and Processing:**\n\nWhen a request arrives, servers MUST:\n\n1. **Establish flow context**: Authenticate request and retrieve/create flow context\n2. **Evaluate tracking sequences**: Establish whether the request is new (remote message sequence larger than last received). If new, continue with request processing.\n3. **Retrieve Matching Interaction Record**: If the request is not new, retrieve the corresponding Interaction Record from the Flow Record.\n4. **Evaluate match**:\n - **No Interaction Record found**: This is a flow violation. Return `TRACKING:FLOW_SEQUENCE_VIOLATION` error response\n - **Record found, request bodies match**: This is a legitimate Retry. Return response from Interaction Record\n - **Record found, request bodies differ**: This is NOT a legitimate Retry. Return `TRACKING:FLOW_SEQUENCE_VIOLATION`\n\nCached responses must be available for return for a period of 240 minutes after the original request was processed. Sequence violations MUST NOT be logged to the Flow Record because they are request integrity failures, not legitimate Flow Interactions.\n\n**Handling Retries During Request Processing:**\n\nWhen a Retry arrives while the original request is still being processed, the Interaction Record entry will exist (request logged) but be incomplete (response not yet logged). In this scenario, servers MUST abandon the request and not send a response. Because the system cannot certify the outcome of the in-flight original request, the fail-safe approach is to trigger a client timeout for future Retry.\n\n**Session Expiry Interaction:**\n\n- **Cached Retries after expiry**: Servers MUST continue to return cached responses from the Flow Record for previously processed requests even after session expiry (Flow Record persists beyond session lifetime)\n- **New requests after expiry**: For new requests (not cached Retries) received after session expiry, servers MUST return the appropriate session closure error\n- **Benefit**: Client Retries of in-flight requests during session closure are handled correctly without client needing to track session state.\n\n**Server Error Response Guidance:**\n\n- Servers SHOULD return HTTP 503 (not 500) for temporary/transient conditions:\n - Service overload or backpressure\n - Downstream service unavailable\n - Maintenance mode\n - Resource exhaustion (connection pool full, queue full, etc.)\n- Servers SHOULD include `Retry-After` header with 503 responses indicating recovery time in seconds\n- Use HTTP 500 only for unexpected bugs or exceptions that may not resolve on Retry\n\n### Bearer Token Validation\n\nThis API uses a JWT based (RFC7519), http bearer token security scheme. The JWT MUST be signed by an authorization authority registered to the QR+ Registry against a Service Provider profile. The API user identity is derived from the JWT issuer, key id and subject claim.\n\n#### JWT claims\n\nThe JWT MUST contain the following Claims:\n\n- `iss` : Issuer Claim containing the `authzAuthorityId` as allocated by the QR+ Registry\n- `sub` : Subject Claim containing the originating (source) service id. This service must be linked to the Authorization Authority identified by `iss`.\n- `aud` : Audience Claim containing the target service id this token was created to access. The target service MUST be **complementary** to the source service: same `flowType` (e.g. `pep-general`) and opposite `kind` (one `PAYER`, one `PAYEE`). For example, a `pep-general` `PAYER` source service may only target a `pep-general` `PAYEE` service.\n- `exp` : Expiration time Claim defining a time of expiry for this token\n- `permissions` : An array of token permissions for authorizations from:\n - `enrich` - Can execute enrichment flows against the SP APIs\n\n#### JWT header\n\nThe JWT header must contain the following parameters:\n\n- `alg` : The JOSE algorithm used for JWT generation\n- `kid` : The key id of the authorization authority key used to generate the JWT\n\n#### JWT Validation\n\nImplementers of this API must satisfy the following minimum requirements when validating a presented JWT:\n\n- **Best Practice:** Follow best practices as outlined in RFC8725 and related standards\n- **User Identity:** The API user identity MUST be determined as the service (`sub`) only when (i) the Issuer claim (`iss`) matches an Authorization Authority for this service (linked by the Registry) and (ii) The key id of the key used matches a key id used by the authorization authority (`kid` header parameter)\n- **Algorithms:** JWT MUST fail if the `alg` property in the header is set to 'none' or if it does not align with the key type of the referenced Authorization Authority\n- **Audience validation:** The service id referenced in the `aud` Claim MUST match the service id of the service being accessed.\n- **Complementary services:** The source service (`sub`) and target service (`aud`) MUST be complementary — both services MUST exist on the Registry Cache, share the same `flowType`, and have opposite `kind` (one `PAYER`, one `PAYEE`). A token where source and target are not complementary (e.g. both `PAYEE`, or different `flowType`) MUST be rejected with HTTP 403 Forbidden. This guarantees that only services intended to interact with each other can authenticate against each other.\n- **Action flowType authorization:** For Paylink resolution, the target service (`aud`) MUST have a `flowType` equal to the flowType decoded from the Paylink's `flowTypeIndicator`. A request whose target service's flowType does not match the Paylink's flowType MUST be rejected with HTTP 403 Forbidden. This prevents a token issued for a service of one flow type from being used to act on a Paylink of a different flow type (the complementary rule above guarantees the source service's flowType matches transitively).\n\n#### Flow Participation\n\nFor all post-Paylink-resolution endpoints (i.e. every endpoint other than Paylink resolution), the calling service MUST be a participant in the flow being acted upon. Implementers MUST enforce:\n\n- The source service (`sub`) MUST match the flow's recorded remote service id, AND\n- The target service (`aud`) MUST match the flow's recorded local service id.\n\nA request whose JWT identifies services that are not the recorded participants of the flow MUST be rejected with HTTP 403 Forbidden, irrespective of whether the request would otherwise be a new request or a legitimate Retry. This ensures that, for example, only the same source service that resolved a Paylink may subsequently issue requests against that flow.\n"},{"name":"Glossary","description":"| Term | Description |\n| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Acceptance Option | A payload specifying a payment rail supported by a Payee for payment. (Option Payload) |\n| Anchor Domain | The common domain used for all Paylink web URIs, allowing deep linking through officially registered mobile applications. |\n| Authorization Authority | An entity, managed on the QR+ Registry, which represents a Service Provider IdP that issues bearer tokens to authenticate API calls. A Service Provider manages Authorization Authorities according to their governance and security policies. |\n| Extended Number Encoded Paylink | A 27-character alphanumeric Paylink format (ZA-FTI-SPII-PLV) optimized for Code128 barcode scanning with extended PLV namespace for medium lifespan experiences. |\n| Facilitated Experience | The experience where the Scanner uses a Paylink Facilitator Application to start a QR+ Flow. |\n| Flow | A Flow is the set of actions executed between a PrSP and PeSP as part of one QR+ session. |\n| Flow Record | An audit trail record, created by both PrSP and PeSP, capturing all Service Provider Interactions exchanged as part of a unique Flow. |\n| Flow Session | A time-bound session that tracks the lifecycle of a Flow with states OPEN, TERMINATED, or EXPIRED. A PrSP only process PeSP Requests while a Flow Session is OPEN. |\n| Flow Tracker | A structured object within Service Provider Interactions containing Flow identifiers and Message Sequence Numbers to coordinate and track messages within a Flow. |\n| Flow Type | A classification of QR+ Flows which govern use case requirements, Paylink lifespan constraints, supported encodings, and security requirements (e.g., pep-general, pep-shortcode, prp-connected, prp-disconnected). Service Providers are licensed for individual Flow Types. |\n| Flow Type Indicator | An encoding-specific identifier that indicates which Flow Type is being used (e.g., 'general' representing the pep-general Flow Type in URI encoded Paylinks and '1' representing the prp-shortcode Flow TYpe in number encoded Paylinks). |\n| Identity Request | A QR+ Request for Payer identity information initiated by the PeSP on behalf of the Payee. |\n| Loyalty Request | A QR+ Request for Payer loyalty membership information initiated by the PeSP on behalf of the Payee. |\n| Message Sequence Number | An incrementing counter maintained by each Service Provider to track the ordering and uniqueness of messages sent within a Flow. Used for audit, idempotency and replay detection. |\n| Number Encoded Paylink | A 13-digit numeric Paylink format (FTI-SPII-PLV-Luhn) optimized for human reproduction via voice or manual keypad entry with built-in error detection. |\n| Payee (actor) | A party who interacts with a Paylink with the intention of receiving payment. The Payee can be either a Scanner or a Presenter depending on the use case. |\n| Payee Service Provider (PeSP) | A registered organization that executes QR+ enrichment flows on behalf of a Payee. The PeSP may deploy Paylink Provider and/or Paylink Facilitator functionality depending on its supported experiences. |\n| Payer (actor) | A party who interacts with a Paylink with intention to pay. The Payer can be either a Scanner or a Presenter depending on the use case. |\n| Payer Service Provider (PrSP) | A registered organization that executes QR+ enrichment flows on behalf of a Payer. The PrSP may deploy Paylink Provider and/or Paylink Facilitator functionality depending on its supported experiences. |\n| Paylink | A structured identifier, encoded and presented in various formats, used by Payers and Payees to initiate a financial interaction. |\n| Paylink actioning | The Scanner scanning the Paylink and submitting it to its Service Provider for processing. |\n| Paylink Encoding Format | A Paylink Encoding Format is a specific way the Paylink attributes are encoded. For example, URI encoded format. |\n| Paylink Facilitator (role) | A PrSP or PeSP organization registered to process Paylinks for Scanners. |\n| Paylink generation | An exchange between the Presenter (Payee or Payer) and the Service Provider (PeSP or PrSP) to generate a new Paylink. |\n| Paylink presentment | The Presenter presenting the Paylink to the Scanner for scanning. |\n| Paylink Presentment Format | A Paylink presentment format specifies the technology used to present the Paylink for scanning. For example, QR code, Barcode and web click. |\n| Paylink Provider (role) | A PrSP or PeSP registered to create Paylinks for Presenters. |\n| Paylink Quarantine Period | The period, after a Paylink has been cancelled, during which the PLV must not be used for a new Paylink. |\n| Paylink resolution | The Paylink Facilitator presenting the Paylink to the Paylink Provider to initiate a QR+ flow. |\n| Paylink Value (PLV) | The cryptographically secure random identifier component within a Paylink that uniquely identifies a specific Paylink instance. |\n| Payment Confirmation | A rail-specific payload passed by the PrSP to the PeSP confirming successful initiation of a Push Payment, without claiming settlement status. |\n| Payment Conclusion | A rail-specific payload passed by the PeSP to the PrSP to provide its view on the outcome of a Payment Request. |\n| Payment Delegation | A rail-specific payload passed by the PrSP to the PeSP containing Pull Payment credentials and transaction details, delegating payment initiation to the PeSP. |\n| Payment Request | A QR+ Request for payment initiated by the PeSP on behalf of the Payee. |\n| Presenter (role) | A Payer or Payee who presents a Paylink to a Scanner party to action. The Presenter interacts with her Service Provider to create the Paylink according to her requirements. |\n| Pull Payment | A payment mechanism that is initiated by a PeSP. |\n| Push Payment | A payment mechanism that is initiated by a PrSP. |\n| QR+ Flow Orchestration | The process of coordinating actions between the PrSP, PeSP, Payer and Payee to achieve a successful transaction outcome. |\n| QR+ Registry Service | A service operated by NPU to enable service discovery of registered Service Providers and Services. |\n| QR+ Service Provider | An organization registered to take part in QR+ flows on behalf of Payers and/or Payees. |\n| Scanner (role) | A party who actions a Paylink by submitting it to their chosen Paylink Facilitator. |\n| Service Provider Indicator | An encoding-specific identifier, assigned by SARB to a registered Service Provider, which allows all Service Providers to identify them as the creator of a Paylink. |\n| Service Provider Interaction | A request and response exchange between a PrSP and a PeSP during a Flow, captured for audit trail, Flow analysis, and idempotency purposes. |\n| Signed CBOR Encoded Paylink | A cryptographically signed Concise Binary Object Representation (CBOR) Paylink format using ECDSA signatures for high-security use cases requiring cryptographic attestation. |\n| URI Encoded Paylink | A non-URL, RFC3986-compliant URI format for Paylinks (`qr-plus:///v1///`) supporting deep linking and extended lifespans. |\n"}],"security":[{"bearerAuth":["enrich"]}],"paths":{"/resolve-pep-paylink":{"post":{"operationId":"resolvePaylink","summary":"Resolve a PeP Paylink","description":"Use this endpoint to resolve a Payee-presented Paylink (PeP) and retrieve the payee identification information. This is called by the Payer Service Provider when a Payer scans or submits a PeP paylink.","tags":["Pep Paylink Resolution"],"security":[{"bearerAuth":["enrich"]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tracking":{"$ref":"#/components/schemas/NewPrSpTracker"},"paylink":{"oneOf":[{"$ref":"#/components/schemas/PeP_URI_ENCODED_Paylink"},{"$ref":"#/components/schemas/NUMBER_ENCODED_Paylink"}],"discriminator":{"propertyName":"kind","mapping":{"URI_ENCODED":"#/components/schemas/PeP_URI_ENCODED_Paylink","NUMBER_ENCODED":"#/components/schemas/NUMBER_ENCODED_Paylink"}},"description":"Information on the Paylink that was scanned by the Payer"}},"required":["tracking","paylink"]}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PepPaylinkResolutionResponse"}}}},"422":{"description":"Unprocessable Entity (Semantic Error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PepPaylinkResolutionSemanticErrorResponse"}}}},"default":{"description":"error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultErrorResponse"}}}}}}},"/reply-payment":{"post":{"operationId":"replyPayment","summary":"Reply to a Payment Request","description":"Use this endpoint to send a payment reply from the Payer Service Provider to the Payee Service Provider during an open flow.\n\n**Request structure:**\n\n| Reply Type | Description |\n|------------|-------------|\n| CONFIRM | Confirming a successful push payment |\n| DELEGATE | Delegating a pull payment to the PeSP |\n| DECLINE | The Payment Request was declined by the Payer |\n| FAILED | The PrSP could not successfully initiate the payment|","security":[{"bearerAuth":["enrich"]}],"tags":["Payment Reply"],"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/PaymentReplyConfirm"},{"$ref":"#/components/schemas/PaymentReplyDelegate"},{"$ref":"#/components/schemas/PaymentReplyDecline"},{"$ref":"#/components/schemas/PaymentReplyFail"}],"discriminator":{"propertyName":"kind","mapping":{"CONFIRM":"#/components/schemas/PaymentReplyConfirm","DELEGATE":"#/components/schemas/PaymentReplyDelegate","DECLINE":"#/components/schemas/PaymentReplyDecline","FAILED":"#/components/schemas/PaymentReplyFail"}}}}},"required":true},"responses":{"204":{"description":"No Content"},"422":{"description":"Unprocessable Entity (Semantic Error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentReplySemanticErrorResponse"}}}},"default":{"description":"error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultErrorResponse"}}}}}}},"/reply-loyalty":{"post":{"operationId":"replyLoyalty","summary":"Reply to a loyalty request","description":"Use this endpoint to send a loyalty information reply from the Payer Service Provider to the Payee Service Provider during an open flow.\n\n**Request structure:**\n- APPROVE - Approve loyalty membership request and provide membership reference\n- DECLINE - Decline loyalty membership request","security":[{"bearerAuth":["enrich"]}],"tags":["Loyalty Reply"],"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/LoyaltyReplyApprove"},{"$ref":"#/components/schemas/LoyaltyReplyDecline"}],"discriminator":{"propertyName":"kind","mapping":{"APPROVE":"#/components/schemas/LoyaltyReplyApprove","DECLINE":"#/components/schemas/LoyaltyReplyDecline"}}}}},"required":true},"responses":{"204":{"description":"No Content"},"422":{"description":"Unprocessable Entity (Semantic Error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LoyaltyReplySemanticErrorResponse"}}}},"default":{"description":"error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultErrorResponse"}}}}}}},"/reply-identity":{"post":{"operationId":"replyIdentity","summary":"Reply to an identity request","description":"Use this endpoint to send an identity information reply from the Payer Service Provider to the Payee Service Provider during an open flow.\n\n**Request structure:**\n- APPROVE - Approve identity request and provide Payer identification\n- DECLINE - Decline request ","security":[{"bearerAuth":["enrich"]}],"tags":["Identity Reply"],"requestBody":{"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/IdentityReplyApprove"},{"$ref":"#/components/schemas/IdentityReplyDecline"}],"discriminator":{"propertyName":"kind","mapping":{"APPROVE":"#/components/schemas/IdentityReplyApprove","DECLINE":"#/components/schemas/IdentityReplyDecline"}}}}},"required":true},"responses":{"204":{"description":"No content"},"422":{"description":"Unprocessable Entity (Semantic Error)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdentityReplySemanticErrorResponse"}}}},"default":{"description":"error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DefaultErrorResponse"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"AuthzAuthority signed API token"}},"schemas":{"NewPrSpTracker":{"type":"object","properties":{"payerSpFlowId":{"allOf":[{"$ref":"#/components/schemas/PayerSpFlowId"}],"description":"A PrSP assigned unique identifier for this flow. The PeSP must echo this value back to the PrSP on every message related to this flow","example":"823b24e1-cccc-4276-b80b-37b3e14d05ae"},"payerSpMessageSeq":{"type":"integer","minimum":1,"description":"A PrSP assigned sequence number for the message sent. The PeSP must echo the sequence back when responding to the message. The PrSP increments this value on each message sent","example":1}},"required":["payerSpFlowId","payerSpMessageSeq"],"description":"A new PrSP message tracking object submitted by the PrSP when initiating a new flow"},"PayerSpFlowId":{"type":"string","format":"uuid","description":"Payer Service Provider Flow Id"},"PeP_URI_ENCODED_Paylink":{"type":"object","properties":{"kind":{"type":"string","const":"URI_ENCODED"},"anchorDomain":{"$ref":"#/components/schemas/DomainName","description":"The anchor domain for the Paylink deployment"},"flowTypeIndicator":{"$ref":"#/components/schemas/UriFlowTypeIndicator"},"spIndicator":{"$ref":"#/components/schemas/UriSpIndicator"},"paylinkValue":{"$ref":"#/components/schemas/UriPaylinkValue"},"presentmentFormat":{"anyOf":[{"$ref":"#/components/schemas/QrPresentment"},{"$ref":"#/components/schemas/WebClickPresentment"}]}},"required":["kind","anchorDomain","flowTypeIndicator","spIndicator","paylinkValue","presentmentFormat"],"description":"A Payee presented, opaque, rail agnostic, long-form encoded Paylink for web click uri and QR presentment."},"DomainName":{"type":"string","pattern":"^((?!-)[A-Za-z0-9-]{1,63}(?