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"
  }
}

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)

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 )

paymentMethod

String

Underlying Payment method (see)

transactionType

String

Type of Transaction

Allowed values

  PURCHASE
  RETURN

cardDetails

String

Payment Card details in case of an underlying Card Payment (see )

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 )

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

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 Specification NextFinvoice XML eReceipt

Last updated 7 days ago