# Payment Types ## Card Payment Represents a payment made using a physical payment card via a payment terminal. {% hint style="info" %} For the ReceiptHero Card Linking feature, it’s important to accurately map values for all required fields. {% endhint %} ### Card Payment Example ```json { "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", "cardNetwork": "MASTERCARD", "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", "cryptogramType": "ARQC", "CVM": "Online PIN" } } ``` ### Card Payment Fields

Key	Type	Description	Required	ISO 8583 Field	EMV Tag
type	String	Payment type (CARD)	true
amount	Integer	Paid amount in fractional unit	true
attributes	Object	Card Payment attributes	true
〰️transactionType	String	Type of Transaction `PURCHASE REFUND REVERSAL RETURN (deprecated)`	true
〰️ MID	String	Merchant Identification Number (sometimes referred to as Card Acceptor ID)	false
〰️ timeStamp	String	Payment ISO 8601 datetime with offset	true
〰️terminalId	String	Card Acceptor Terminal Identifier	true	DE 41
〰️ referenceNumber	String	Retrieval Reference Number, RRN	true	DE 37
〰️ authorizationCode	String	Authorization Code (6 characters, alphanumeric)	true	DE 38
〰️ transactionId	String	Transaction ID	false
〰️ receiptNumber	String	Card Holder Receipt Number	false
〰️ maskedPAN	String	Payment Card Masked PAN. At least 4 last digits.	true
〰️ APP	String	Application Label (e.g. VISA CREDIT)	false		50
〰️ cardNetwork	String	Card Network `AMERICAN_EXPRESS BANCONTACT CARTES_BANCAIRES DANKORT DINERS_CLUB DISCOVER EFTPOS ELO GIROCARD HIPERCARD HIPER INTERAC JCB MAESTRO MASTERCARD MIR RUPAY UNIONPAY VISA VERVE`	false
〰️ cardType	String	Card type (e.g. DEBIT, CREDIT or PREPAID)	false
〰️ cardProgram	String	Card Program free text (e.g. Chase Sapphire Preferred)	false
〰️ transactionRawText	String	Card holder receipt copy as raw text (including newlines as `\n)`	false
〰️ preAuthorizedAmount	Number	Amount of the related pre-authorization	false
〰️ ENTRY	String	Point Of Service (POS) Entry Mode	false	DE 22
〰️ ARC	String	Authorization Response Code	false	DE 39	8A
〰️ TVR	String	Terminal Verification Results	false		95
〰️ TSI	String	Transaction Status Information	false		9B
〰️ AID	String	Application Identifier	false		9F06
〰️ AC	String	Application Cryptogram	false		9F26
〰️ CID	String	Cryptogram Information Data	false		9F27
〰️ cryptogramType	String	`AAC TC ARQC`	false
〰️ CVM	String	Cardholder Verification Method Results `ONLINE PIN SIGNATURE VERIFIED NO CVM REQUIRED`	false		9F34
〰️ ~~authorizationMethodType~~	String	Deprecated (`CVM` should be used instead)	false
〰️ currency	#currency-object	Foreign currency information	false

## Cash Payment Represents a payment made in cash, including the amount handed over by the customer for calculating change. ### Cash Payment Example ```json { "type": "CASH", "amount": 39998, "attributes": { "handedAmount": 40000, "roundingAmount": 2 } } ``` ### Cash Payment Fields

Key	Type	Description
type	String	CASH	true
amount	Integer	Paid amount in fractional unit	true
attributes	Object	Cash payment attributes	true
〰️ handedAmount	Integer	Amount that is handed in cash in fractional unit	true
〰️ roundingAmount	Integer	Amount rounded	false
〰️ currency	#currency-object	Foreign currency information	false

## Online Payment Represents a payment processed through an online payment service provider (PSP), such as Paytrail, Stripe, or Klarna. ### Online Payment Example ```json { "amount": 4590, "type": "ONLINE_PAYMENT", "attributes": { "provider": "PAYTRAIL", "paymentMethod": "APPLE_PAY", "transactionType": "PURCHASE", "timeStamp": "2025-04-03T15:30:00+02:00", "cardType": "VISA DEBIT", "maskedPAN": "411111******1111", "authorizationCode": "A1B2C3", "referenceNumber": "250403123456", "filingCode": "1A2B3C4D5E6F7G8H9I0J1K2L3M4N5O6P", "orderReference": "4940046476", "transactionId": "7d781f54-ebbb-450e-852b-7ff133caa6c6", } } ``` ### Online Payment Fields

Key	Type	Description	Required
type	String	ONLINE_PAYMENT	true
amount	Integer	Paid amount in fractional unit	true
attributes	Object	Online Payment details	true
〰️ provider	String	Online Payment provider (see #online-payment-providers)	true
〰️ paymentMethod	String	Underlying Payment method (see#online-payment-methods)	true
〰️ transactionType	String	Type of Transaction `PURCHASE RETURN`	true
〰️ timeStamp	String	Transaction timestamp as ISO 8601 datetime with offset	false
〰️ cardType	String	Card type description if available. (e.g. Debit Mastercard)	false
〰️ maskedPAN	String	Payment Card Masked PAN. At least 4 last digits.	false
〰️ authorizationCode	String	Payment Authorization code (6 characters, alphanumeric)	false
〰️ referenceNumber	String	Payment Retrieval Reference Number	false
〰️ filingCode	String	Bank Transfer filing code (relevant mostly for bank transfers in Finland)	false
〰️ orderReference	String	Reference number of online order / purchase	false
〰️ transactionId	String	Transaction identifier	false

#### Online Payment Providers {% hint style="info" %} Supported `provider` values are listed below. This list is subject to change, and new providers can be introduced upon request. {% endhint %}

  ADYEN
  AUTHORIZE_NET
  KLARNA
  NETS
  PAYPAL
  PAYTRAIL
  STRIPE
  TRUSTLY
  VISMA_PAY
  VIVA

#### Online Payment Methods {% hint style="info" %} Supported `paymentMethod` values are listed below. This list is subject to change, and new methods can be introduced upon request. {% endhint %}

  CARD
  BANK_TRANSFER
  APPLE_PAY
  GOOGLE_PAY
  MOBILEPAY
  PAYPAL
  SIIRTO
  SWISH
  INVOICE

## 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 ```json { "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	true
amount	Integer	Paid amount in fractional unit	true
attributes	Object	Gift Card details	true
〰️ id	String	Gift Card ID	true
〰️ issuer	String	Gift Card issuer name	false
〰️ name	String	Gift Card title or name	false
〰️ referenceNumber	String	Purchase or Order reference number	false
〰️ expirationDate	String	Gift Card expiration date as ISO 8601 datetime with offset	false
〰️ balanceBefore	Number	Gift Card balance before purchase in fractional unit	false
〰️ balanceAfter	Number	Gift Card balance after purchase in fractional unit	false

## Voucher Payment Represents a payment made using a voucher or coupon, identified by a reference number or id. ### Voucher Payment Example ```json { "type": "VOUCHER", "amount": 20720, "attributes": { "referenceNumber": "1234567890" } } ``` ### Voucher Payment Fields

Key	Type	Description	Required
type	String	VOUCHER	true
amount	Integer	Paid amount in fractional unit	true
attributes	Object	Payment details	false
〰️ referenceNumber	String	Voucher reference number or id	false

## 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 ```json { "type": "LOYALTY", "amount": 20720, "attributes": { "cardType": "Plussa", "maskedPAN": "1881" }, "customAttributes": [{ "Earned Bonus": "234 points" }] } ``` ### Loyalty Payment Fields

Key	Type	Description	Required
type	String	LOYALTY	true
amount	Integer	Paid amount in fractional unit	true
attributes	Object	Loyalty card details	true
〰️ cardType	String	Free text card type / name	true
〰️ maskedPAN	String	Masked Loyalty Card number	true

## Other Payment Represents a non-standard payment method not covered by predefined types, including an external type identifier for classification. ### Other Payment Example ```json { "type": "OTHERPAYMENT", "amount": 20720, "attributes": { "externalType": "Mobile Carrier Billing" } } ``` ### Other Payment Fields

Key	Type	Description	Required
type	String	OTHERPAYMENT	true
amount	Integer	Paid amount in fractional unit	true
attributes	Object	Payment details	true
〰️ externalType	String	Payment type free text	false

## Payment Custom Attributes All payment objects support custom attributes to allow including data that is not covered by the core specification. ```json "customAttributes": [ { "Earned Bonus": "234 points" } ] ``` | Key | Type | Description | Required | | ---------------------- | ------ | ------------------- | :------: | | customAttributes | Array | Key value pair list | | | :wavy\_dash: **Key** | String | Free text key | | | :wavy\_dash: **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. ```json { "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	true
amount	Integer	Foreign currency amount in fractional unit	true
exchangeRate	String	Rate used to convert the foreign currency amount into the merchant’s local currency.	true