Payment Types

This page lists supported HeroJSON payment types with their structure and key attributes for integration.

Card Payment

Represents a payment made using a physical payment card via a payment terminal.

For the ReceiptHero Card Linking feature, it’s important to accurately map values for all required fields.

Card Payment Example

{
  "type": "CARD",
  "amount": 20720,
  "attributes": {
    "cardType": "Debit Mastercard",
    "maskedPAN": "557760******3201",
    "timeStamp": "2022-09-01T12:35:34.678+02:00",
    "terminalId": "BS-4545F9",
    "referenceNumber": "220901015555",
    "authorizationCode": "HIU456",
    "authorizationMethodType": "CHIP_AND_PIN",
    "transactionId": "05555",
    "transactionType": "PURCHASE",
    "transactionRawText": "CARD TRANSACTION\n\nCard: Debit Mastercard\n **** **** **** 3201 LN\nApplication: A0000000041010\nTr.Nr/Auth: 05555/HIU456\nPayee/business: 0029432413000/0001\n\nReference: 220901015555\n\nCredit/Charge 207,20 EUR\nPayPass Contactless \n\n",
    "applicationIdentifier": "A0000000031010",
    "merchantId": "412300886123",
    "receiptNumber": "12923",
    "preAuthorizedAmount": 30000
  }
}

Card Payment Fields

Key
Type
Description
Required

type

String

Payment type (CARD)

amount

Integer

Paid amount in fractional unit

(POINT ECR API Amount, field 14)

attributes

Object

Card Payment attributes

〰️ cardType

String

Card type description if available. (e.g. Debit Mastercard)

〰️ maskedPAN

String

Payment Card Masked PAN. At least 4 last digits.

(POINT ECR API Card Number field 6)

〰️ timeStamp

String

Payment ISO 8601 datetime with offset

(POINT ECR API Date and time of transaction field 13)

〰️terminalId

String

Terminal ID

(POINT ECR API Reader serial number, field 16)

〰️ referenceNumber

String

Retrieval Reference Number, RRN

(POINT ECR API Filing code, field 12)

〰️ authorizationCode

String

Payment Authorization code (6 characters, alphanumeric)

〰️ authorizationMethodType

String

Payment authorization method free text

Examples
  CHIP_AND_PIN  
  CONTACTLESS  
  CONTACTLESS_WITH_PIN

〰️ transactionId

String

Transaction ID

(POINT ECR API TransactionID, field 11)

〰️transactionType

String

Type of Transaction

Allowed values
PURCHASE
RETURN

〰️ transactionRawText

String

Card holder transaction receipt copy as raw text including newlines.

(POINT ECR API Payer’s receipt texts, field 19)

〰️ applicationIdentifier

String

Application Identifier

〰️ merchantId

String

Merchant ID (sometimes referred to as Card Acceptor ID)

〰️ receiptNumber

String

Card Holder Receipt Number

〰️ preAuthorizedAmount

Number

Amount of the related pre-authorization

Cash Payment

Represents a payment made in cash, including the amount handed over by the customer for calculating change.

Cash Payment Example

{
  "type": "CASH",
  "amount": 34920,
  "attributes": {
    "handedAmount": 40000
  }
}

Cash Payment Fields

Key
Type
Description

type

String

CASH

amount

Integer

Paid amount in fractional unit

attributes

Object

Cash payment attributes

〰️ handedAmount

Integer

Amount that is handed in cash in fractional unit

Online Payment

Represents a payment processed through an online payment service provider (PSP), such as Paytrail, Stripe, or Klarna.

Online Payment Example

{
  "amount": 4590,
  "type": "ONLINE_PAYMENT",
  "attributes": {
    "provider": "PAYTRAIL",
    "paymentMethod": "APPLE_PAY",
    "cardDetails": {
      "type": "CREDIT",
      "panLastFour": "1234",
      "bin": "535555",
      "brand": "MASTERCARD",
      "countryCode": "FI"
    },
    "filingCode": "1A2B3C4D5E6F7G8H9I0J1K2L3M4N5O6P",
    "orderReference": "4940046476",
    "timeStamp": "2025-04-03T15:30:00+02:00",
    "authorizationCode": "A1B2C3",
    "retrievalReferenceNumber": "250403123456",
    "settlementReference": "45667372",
    "transactionId": "7d781f54-ebbb-450e-852b-7ff133caa6c6",
    "transactionType": "PURCHASE"
  }
}

Online Payment Fields

Key
Type
Description
Required

type

String

ONLINE_PAYMENT

amount

Integer

Paid amount in fractional unit

attributes

Object

Online Payment details

〰️ provider

String

Online Payment provider (see Online Payment Providers)

〰️ paymentMethod

String

Underlying Payment method (seeOnline Payment Methods)

〰️ transactionType

String

Type of Transaction

Allowed values
  PURCHASE
  RETURN

〰️ cardDetails

String

Payment Card details in case of an underlying Card Payment (see Online Payment Card Details Object)

〰️ filingCode

String

Bank Transfer filing code (relevant mostly for bank transfers in Finland)

〰️ orderReference

String

Reference number of online order / purchase

〰️ timeStamp

String

Transaction timestamp as ISO 8601 datetime with offset

〰️ authorizationCode

String

Payment Authorization code (6 characters, alphanumeric)

〰️ retrievalReferenceNumber

String

Payment Retrieval Reference Number

〰️ settlementReferenceNumber

String

Settlement Reference Number

〰️ transactionId

String

Transaction identifier

Online Payment Providers

Supported provider values are listed below. This list is subject to change, and new providers can be introduced upon request.

  ADYEN
  AUTHORIZE_NET
  KLARNA
  NETS
  PAYPAL
  PAYTRAIL
  STRIPE
  TRUSTLY
  VISMA_PAY
  VIVA

Online Payment Methods

Supported paymentMethod values are listed below. This list is subject to change, and new methods can be introduced upon request.

  CARD
  BANK_TRANSFER
  APPLE_PAY
  GOOGLE_PAY
  MOBILEPAY
  PAYPAL
  SIIRTO
  SWISH
  INVOICE

Online Payment Card Details Object

Key
Type
Description
Required

cardDetails

Object

Payment Card details in case of an underlying Card Payment

〰️ brand

String

Card brand (see Known Card Brands)

〰️ panLastFour

String

Payment Card last four digits

〰️ bin

String

Payment Card Bank Identification Number

〰️ countryCode

String

ISO 3166-1 alpha-2 country code

〰️ type

String

Payment Card type

Allowed values
  CREDIT
  DEBIT
  PREPAID

Known Card Brands

  AMERICAN_EXPRESS
  DINERS_CLUB
  DISCOVER
  ELO
  HIPER
  HIPERCARD
  JCB
  MAESTRO
  MASTERCARD
  MIR
  UNIONPAY
  VISA

Gift Card Payment

Represents a payment made using a prepaid or store-issued gift card, optionally including issuer, balance, and reference details.

Gift Card Payment Example

{
  "amount": 2500,
  "type": "GIFT_CARD",
  "attributes": {
    "id": "GC-987654321",
    "issuer": "StoreBrand",
    "name": "Holiday Gift Card",
    "referenceNumber": "REF1234567890",
    "expirationDate": "2025-12-31T23:59:59+02:00",
    "balanceBefore": 5000,
    "balanceAfter": 2500
  }
}

Gift Card Payment Fields

Key
Type
Description
Required

type

String

GIFT_CARD

amount

Integer

Paid amount in fractional unit

attributes

Object

Gift Card details

〰️ id

String

Gift Card ID

〰️ issuer

String

Gift Card issuer name

〰️ name

String

Gift Card title or name

〰️ referenceNumber

String

Purchase or Order reference number

〰️ expirationDate

String

Gift Card expiration date as ISO 8601 datetime with offset

〰️ balanceBefore

Number

Gift Card balance before purchase in fractional unit

〰️ balanceAfter

Number

Gift Card balance after purchase in fractional unit

Voucher Payment

Represents a payment made using a voucher or coupon, identified by a reference number or id.

Voucher Payment Example

{
  "type": "VOUCHER",
  "amount": 20720,
  "attributes": {
    "referenceNumber": "1234567890"
  }
}

Voucher Payment Fields

Key
Type
Description
Required

type

String

VOUCHER

amount

Integer

Paid amount in fractional unit

attributes

Object

Payment details

〰️ referenceNumber

String

Voucher reference number or id

Loyalty Payment

Represents a payment or partial payment made using a loyalty or bonus program, such as a store-issued loyalty card.

Loyalty Payment Example

{
  "type": "LOYALTY",
  "amount": 20720,
  "attributes": {
    "cardType": "Plussa",
    "maskedPAN": "1881"
  },
  "customAttributes": [{ "Earned Bonus": "234 points" }]
}

Loyalty Payment Fields

Key
Type
Description
Required

type

String

LOYALTY

amount

Integer

Paid amount in fractional unit

attributes

Object

Loyalty card details

〰️ cardType

String

Free text card type / name

〰️ maskedPAN

String

Masked Loyalty Card number

Other Payment

Represents a non-standard payment method not covered by predefined types, including an external type identifier for classification.

Other Payment Example

{
  "type": "OTHERPAYMENT",
  "amount": 20720,
  "attributes": {
    "externalType": "Mobile Carrier Billing"
  }
}

Other Payment Fields

Key
Type
Description
Required

type

String

OTHERPAYMENT

amount

Integer

Paid amount in fractional unit

attributes

Object

Payment details

〰️ externalType

String

Payment type free text

Payment Custom Attributes

All payment objects support custom attributes to allow including data that is not covered by the core specification.

"customAttributes": [
   { "Earned Bonus": "234 points" }
]
Key
Type
Description
Required

customAttributes

Array

Key value pair list

〰️ Key

String

Free text key

〰️ Value

String

Free text value

PreviousHeroJSON SpecificationNextFinvoice XML eReceipt

Last updated