Aera PSP API documentation

❗️

Please note that this page is only temporary. It will be moved to a separate Aera PSP space in readme once it is ready.

📘

See API reference for a more human readable version: Aera PSP

Overview

Accepting a wallet payment requires the ECR to handle three types of interaction with the Aera PSP: initiating the payment, receiving the outcome, and optionally querying or cancelling a transaction in progress. The payment flow is asynchronous — the ECR sends a request and gets an immediate acknowledgement, but the final outcome arrives later via callback.

The sequence below shows the complete flow and the points at which the ECR is involved.

sequenceDiagram
    participant ECR as ECR / POS
    participant PSP as Aera PSP
    participant WLW as Wallet
    participant Consumer

    ECR->>PSP: POST /wallet/sale
    PSP-->>ECR: 200 OK · pspReference (acknowledgement)

    PSP->>WLW: Route payment request
    WLW->>Consumer: Prompt authorization
    Consumer-->>WLW: Authorize / Decline / Expire

    WLW-->>PSP: Transaction result
    PSP->>ECR: POST {callbackUrl} · outcome
    ECR-->>PSP: HTTP 200

    opt No callback received
        ECR->>PSP: GET /wallet/status/pspReference/{ref}
        PSP-->>ECR: Current transaction state
    end

The ECR is responsible for three things:

1. Initiate — send the sale request and store the pspReference returned in the acknowledgement.
2. Receive — implement a callback endpoint and process the outcome when Aera posts it.
3. Recover — poll the status endpoint if the callback is not received, or cancel the transaction if the consumer abandons the checkout before signing.

Everything in between — consumer authentication, instrument selection, authorization against the payment provider — is handled by the Wallet infrastructure and requires no action from the ECR.

Payment Lifecycle

A wallet payment follows an asynchronous lifecycle. The ECR initiates the transaction and receives an immediate acknowledgement; the final outcome is delivered later via callback.

1. The ECR sends a payment request to Aera PSP, including the basket amount and a callback URL.
2. Aera PSP validates the request and returns a synchronous acknowledgement containing a pspReference and the merchantReference. This is not a payment confirmation — it means the request was accepted and processing has begun.
3. Aera PSP routes the payment request to the consumer's wallet application. The consumer reviews and authorizes the payment on their mobile device.
4. Once the transaction reaches a terminal state — authorized, declined, or expired — Aera sends the outcome to the callbackUrl provided in the request.
5. The ECR processes the callback, records the result, and responds with HTTP 200 to acknowledge receipt.

Two additional operations are available at any point after initiation:

• Status check — if the callback is not received within the expected window, the ECR can query the current transaction state using the Wallet status endpoint.
• Cancel — if the payment needs to be voided before the consumer has authorized it, the ECR can call the Wallet cancel endpoint.

Payment Initiation

The ECR initiates a wallet payment by sending a sale request to Aera. The request must identify the consumer, the wallet application, the basket amount, and the endpoint where the outcome should be delivered.

Required fields

Optional fields

Response

Aera responds synchronously with an acknowledgement. The response contains:

• pspReference — Aera's internal transaction identifier. Store this immediately; it is required for status queries and cancellations.
• merchantReference — echoed back from the request for confirmation.

The actual authorization outcome is delivered asynchronously via the callback described in the next section.

Callback

When a wallet transaction reaches a terminal state, Aera sends an HTTP POST to the callbackUrl provided in the sale request.

Requirements

• The callback endpoint must be reachable over HTTPS.
• Respond with HTTP 200 to acknowledge receipt. Aera treats any other response as a delivery failure.
• Process callbacks idempotently — use pspReference to detect and safely ignore duplicates.
• Implement status polling as a fallback for cases where the callback is not received.

Status

The ECR can query the current state of a wallet payment at any time using the pspReference returned at initiation.

GET /v1/wallet/status/pspReference/{pspReference}

The response mirrors the callback payload, so both can be handled by the same logic. If the transaction is still in progress, responseCode: 68616 is returned — retry after a short wait.

Use the status endpoint as a fallback when a callback has not been received within the expected window, or for end-of-day reconciliation.

Cancellation

A pending wallet payment can be cancelled by the ECR using the pspReference.

POST /v1/wallet/cancel/pspReference/{pspReference}

Cancellation is only possible while the transaction is still pending — once the consumer has confirmed the payment on their device (status: SIGNED), the transaction is locked and cancellation will be rejected with responseCode: 68605. In that case, wait for the callback to arrive instead.

A successful cancellation returns responseCode: 68607.