Cards

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

Card payments start with a payment session. The shopper pays on the hosted checkout or the embedded checkout, and you redirect them to the paymentSessionUrl. Cards follow an authorise and capture model.

What you can do with cards

Flow	How	Read more
Authorise now, capture the full amount later	`immediateCapture` `false`, then capture	Below
Authorise and capture in one step	`immediateCapture` `true`	Below
Capture in several parts (split shipment)	`splitShipment` `true`, then partial captures	Below
Check a card without charging it	Amount `0` and `storePaymentInstrument` `MANDATED`	Below
Let the shopper save the card	`paymentInstrumentsProfileData` and `storePaymentInstrument`	Save cards
Accept only saved cards	`allowStoredInstrumentsOnly` `true`	Save cards
One-click payment with a saved card	Create direct payment session	Direct payments
Save the card for recurring payments	Create recurring payment session	Recurring payments
Charge a saved card without the shopper	Authorize recurring payment	Recurring payments

Authorise now, capture later

The shopper authorises the payment on the checkout page. You capture the full amount later, for example when you ship.

sequenceDiagram
    autonumber
    participant S as Shopper
    participant M as Your server
    participant A as Aera
    S->>M: Go to checkout
    M->>A: Create payment session (CARD, immediateCapture false)
    A-->>M: pspReference, paymentSessionUrl
    M-->>S: Redirect to paymentSessionUrl
    Note over S,A: Shopper pays on Aera's checkout page
    A-->>S: Redirect to your success, cancel or error URL
    A-->>M: Notification: CHECKOUT_SESSION_COMPLETED
    M->>A: Get payment status
    A-->>M: Status and operations
    M->>A: Capture (full amount)
    A-->>M: Capture result

1. Create the session. Offer only cards with paymentMethodWhitelist:

Example request: cards only

{
  "merchantData": {
    "successRedirectUrl": "https://shop.example.com/success",
    "cancelRedirectUrl": "https://shop.example.com/cancel",
    "errorRedirectUrl": "https://shop.example.com/error",
    "callbackUrl": "https://shop.example.com/aera/notifications"
  },
  "transactionData": {
    "merchantReference": "12344333",
    "immediateCapture": false,
    "amountDetails": { "amount": 10000, "currency": "NOK" }
  },
  "paymentMethodInfo": {
    "paymentMethodWhitelist": ["CARD"]
  }
}

2. Redirect the shopper to the paymentSessionUrl and wait for the notification.

3. Check the result when the notification comes:

Example notification

{
  "eventType": "CHECKOUT_SESSION_COMPLETED",
  "status": "0",
  "pspReference": "01J9Z8X7W6V5T4S3R2Q1P0N9M8",
  "merchantReference": "12344333",
  "paymentMethod": "CARD",
  "paymentScheme": "VISA"
}

4. Capture. POST /v1/{pspReference}/capture with no body captures the full amount. See Capture a payment.

Immediate capture

Set immediateCapture to true. Authorisation and capture happen in one step, so you don't call capture.

Example transactionData: immediate capture

"transactionData": {
  "merchantReference": "12344333",
  "immediateCapture": true,
  "amountDetails": { "amount": 10000, "currency": "NOK" }
}

The status then shows both AUTHORIZATION and CAPTURE. If the capture fails, the payment is reversed.

Split shipment

Set splitShipment to true if you may ship the order in several parts. You can then capture each part separately.

Example transactionData: split shipment

"transactionData": {
  "merchantReference": "12344333",
  "immediateCapture": false,
  "splitShipment": true,
  "amountDetails": { "amount": 10000, "currency": "NOK" }
}

Capture part of the amount:

Example partial capture request

{
  "amountDetails": { "amount": 5000, "currency": "NOK" }
}

You can capture more parts until the full amount is captured. See Capture a payment.

Card verification (zero amount)

Check that a card is valid without charging the shopper. Send amount 0 and make saving the card mandatory:

Example transactionData: card verification

"transactionData": {
  "merchantReference": "12344333",
  "immediateCapture": false,
  "storePaymentInstrument": "MANDATED",
  "amountDetails": { "amount": 0, "currency": "NOK" }
}

This is a zero-amount authorisation, and the card is saved. Because the card is saved, the shopper must authenticate.

Limit the card schemes

To accept only some card schemes in a session, send cardSchemeWhitelist:

Example paymentMethodInfo: card schemes

"paymentMethodInfo": {
  "paymentMethodDetails": [
    { "method": "CARD", "card": { "cardSchemeWhitelist": ["VISA", "MASTERCARD"] } }
  ]
}

Values: VISA, MASTERCARD, AMEX, BANCONTACT. Leave it out to accept all schemes enabled for your merchant account.

Strong Customer Authentication

The issuer, the acquirer or Aera decides whether the shopper must authenticate, for example with 3-D Secure. To always ask the shopper to authenticate, set forcedAuthentication to true. When the shopper saves the card, they always authenticate.

Before you can accept cards

At least one acquirer is set up for your merchant account.
At least one card scheme is enabled.
The acquirer supports your service, your MCC (merchant category code) and the operation.

What works also depends on the acquirer's capabilities, the scheme rules and your merchant configuration.