Save cards

🚧
Early release
Online payments is in early development (MVP). This section may change.

A saved card (a stored payment instrument, or "card on file") lets a returning shopper pay without typing their card details again. Saved cards are also the basis for recurring payments.

You need the Store payment instrument service on your merchant account. Without it, Aera ignores the save settings.

Identify the shopper

To save, show or pre-select cards, tell Aera who the shopper is in paymentInstrumentsProfileData. Send one of these:

Field	What it is
`merchantShopperId`	Your own ID for the shopper, for example a customer number, loyalty number or phone number
`pspShopperId`	Aera's ID for the shopper (UUID). You get it in `details.pspShopperId` from Get payment status after the first payment

Let the shopper save a card

Create a hosted or embedded checkout session with the shopper's ID and storePaymentInstrument:

Example request: let the shopper save the card

{
  "transactionData": {
    "merchantReference": "order-1234",
    "storePaymentInstrument": "OPTIONAL",
    "amountDetails": { "amount": 10000, "currency": "NOK" }
  },
  "paymentInstrumentsProfileData": {
    "merchantShopperId": "LOYAL-70018882"
  }
}

`storePaymentInstrument`	On the checkout page
`OPTIONAL` (default)	A "save card" box. The shopper chooses.
`MANDATED`	The box is ticked and greyed out. The card is always saved.
`NONE`	The card is never saved.

When a shopper saves a card, they always authenticate, for example with 3-D Secure.

After the payment, Get payment status shows the shopper's pspShopperId and the card's paymentInstrumentReference.

Show only saved cards

To make the shopper pay with a saved card, with no option to type in a new one, set allowStoredInstrumentsOnly to true:

Example paymentInstrumentsProfileData: saved cards only

"paymentInstrumentsProfileData": {
  "merchantShopperId": "LOYAL-70018882",
  "allowStoredInstrumentsOnly": true
}

The checkout page shows only the shopper's saved cards. Typical uses:

Returning shoppers who are logged in and have a saved card
Subscriptions or memberships where payment must use an approved card on file
Loyalty or membership programmes, where purchases belong to a known customer account
One-click checkouts designed to reduce friction

allowStoredInstrumentsOnly is ignored when you send paymentInstrumentReference.

Pre-select a saved card (one-click)

Send the card's paymentInstrumentReference. The shopper doesn't choose a card on the checkout page. If no authentication is needed (a low-value exemption or frictionless authentication), the payment completes in one click.

Example paymentInstrumentsProfileData: pre-selected card

"paymentInstrumentsProfileData": {
  "merchantShopperId": "LOYAL-70018882",
  "paymentInstrumentReference": "0192a7c4-5e1b-7d2a-8f3c-4b5a6c7d8e9f"
}

To pay with a saved card from your own checkout, without the checkout page, use Direct payments.

List a shopper's saved cards

GET /v1/payment-instruments/{merchantShopperId}

See Get payment instruments.

Example Get payment instruments response

{
  "merchantShopperId": "LOYAL-70018882",
  "paymentInstruments": [
    {
      "paymentInstrumentReference": "0192a7c4-5e1b-7d2a-8f3c-4b5a6c7d8e9f",
      "scheme": "MASTERCARD_CREDIT",
      "maskedPan": "548016******7897",
      "expiryDate": "2029-12",
      "cardOnFileReason": "CONVENIENCE"
    }
  ]
}

Field	Description
`paymentInstrumentReference`	Aera's ID for the saved card
`scheme`	The card scheme
`maskedPan`	The card number, with most digits hidden. Cards only
`expiryDate`	The expiry date, as yyyy-mm. Cards only
`cardOnFileReason`	Why the card was saved. `CONVENIENCE`: to pay again without typing the card. `UNSCHEDULED` or `SCHEDULED`: for recurring payments

One card, several references

A card saved for several reasons (for example for convenience and for a recurring agreement, or for two recurring agreements) has one paymentInstrumentReference for each. You manage each one separately: deleting one doesn't delete the others.

Delete a saved card

When the shopper removes a card in your app or site, delete it:

DELETE /v1/merchant-admin/card-on-file/{merchantShopperId}/{paymentInstrumentReference}

See Delete payment instrument.