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