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": {
      "transactionType": "PURCHASE",
      "MID": "12346543",
      "timeStamp": "2022-09-01T12:35:34.678+02:00",
      "terminalId": "BS-4545F9",
      "referenceNumber": "220901015555",
      "authorizationCode": "HIU456",
      "transactionId": "05555",
      "receiptNumber": "12923",
      "maskedPAN": "525400******9876",
      "APP": "MASTERCARD DEBIT",
      "cardType": "DEBIT",
      "cardProgram": "Nordic Tech Bank — MC Debit",
      "transactionRawText": "CARD TRANSACTION\n\nCard: Debit Mastercard\n **** **** **** 9876 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",
      "ENTRY": "Contactless ICC (07)",
      "ARC": "APPROVED (00)",
      "TVR": "8000008000",
      "TSI": "E800",
      "AID": "A0000000031010",
      "AC": "9F270180",
      "CID": "0x80 (ARQC)",
      "CVM": "Online PIN"
    }
}

Card Payment Fields

Key

Type

Description

Required

ISO 8583 Field

EMV Tag

type

String

Payment type (CARD)

amount

Integer

Paid amount in fractional unit

attributes

Object

Card Payment attributes

〰️transactionType

String

Type of Transaction

Allowed values

PURCHASE
REFUND
REVERSAL
RETURN (deprecated)

〰️ MID

String

Merchant Identification Number (sometimes referred to as Card Acceptor ID)

〰️ timeStamp

String

Payment ISO 8601 datetime with offset

〰️terminalId

String

Card Acceptor Terminal Identifier

DE 41

〰️ referenceNumber

String

Retrieval Reference Number, RRN

DE 37

〰️ authorizationCode

String

Authorization Code (6 characters, alphanumeric)

DE 38

〰️ transactionId

String

Transaction ID

〰️ receiptNumber

String

Card Holder Receipt Number

〰️ maskedPAN

String

Payment Card Masked PAN. At least 4 last digits.

〰️ APP

String

Application Label (e.g. VISA CREDIT)

〰️ cardType

String

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

〰️ cardProgram

String

Card Program free text (e.g. Chase Sapphire Preferred)

〰️ transactionRawText

String

Card holder receipt copy as raw text (including newlines as \n)

〰️ preAuthorizedAmount

Number

Amount of the related pre-authorization

〰️ ENTRY

String

Point Of Service (POS) Entry Mode

DE 22

〰️ ARC

String

Authorization Response Code

DE 39

〰️ TVR

String

Terminal Verification Results

〰️ TSI

String

Transaction Status Information

〰️ AID

String

Application Identifier

9F06

〰️ AC

String

Application Cryptogram

9F26

〰️ CID

String

Cryptogram Information Data

9F27

〰️ CVM

String

Cardholder Verification Method Results

Examples

  ONLINE PIN  
  SIGNATURE VERIFIED  
  NO CVM REQUIRED

9F34

〰️ ~~authorizationMethodType~~

String

Deprecated (CVM should be used instead)

〰️ currency

Currency Object

Foreign currency information

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": 39998,
  "attributes": {
    "handedAmount": 40000,
    "roundingAmount": 2
  }
}

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

〰️ roundingAmount

Integer

Amount rounded

〰️ currency

Currency Object

Foreign currency information

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

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

Foreign Currency Mapping

Foreign currency mapping is used when a customer pays with cash or a card in a currency different from the merchant’s local currency, requiring the payment amount to be converted using an exchange rate.

Foreign currency details are mapped as a currency object within the payment attributes; see the Currency Object section for full documentation.

{
  "type": "CARD|CASH",
  "amount": 1100,
  "attributes": {
    ...
    "currency": {
      "currencyISOCode": "DKK",
      "amount": 8216,
      "exchangeRate": "0.13389"
    }
  }
}

Currency Object

Key

Type

Description

Required

currencyISOCode

String

ISO 4217 Currency Code

amount

Integer

Foreign currency amount in fractional unit

exchangeRate

String

Rate used to convert the foreign currency amount into the merchant’s local currency.

PreviousHeroJSON Specification NextFinvoice XML eReceipt

Last updated 4 days ago