Skip to main content

Sales API

API docs by Redocly

ReconHub Sales API (v1)

Abrantix AG: info@abrantix.com URL: https://abrantix.com License: Proprietary License

The Sales API provides actions to upload, list and get sales transactions from/to ReconHub.

Here you can find some help on getting started before implementing this.

General

Test access

This route can be used to test the access to the Sales API. An emtpy response with status 200 (OK) will be provided when authenticated and authorized successfully.

Authorizations:
basic
query Parameters
customerId
string <uuid>

Id of the customer.

Note: Must only be provided if the user has access to multiple customers. If the user cannot be determined without providing the customerId, the request will be denied with status 401 (Unauthorized).

tenantId
string <uuid>

Id of the tenant.

Note: Must only be provided if the user has access to multiple tenants. If the user cannot be determined without providing the tenantId, the request will be denied with status 401 (Unauthorized).

Responses

Response samples

Content type
{
  "errors": {
    "transactions[0].businessDate": [
      "Error converting value \"2023-01-16xx\" to type 'System.Nullable`1[System.DateOnly]'. Path 'transactions[0].businessDate', line 10, position 34."
    ]
  },
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400
}

Transactions

Upload transactions

Upload sales transactions which will be processed by ReconHub.

The uploaded transactions will be staged to be imported in ReconHub use GET /upload/{uploadId} to get the processing state of the uploaded transactions or use GET /?uploadId={uploadId} to get processed transactions from ReconHub.

For more details, please refer to Additional information.

Note: It is recommended to send transactions in batches instead of sending every transaction in an own request. An example would be to send 1000 transactions per request every hour instead of sending a request with 1 transaction every second. If this is an issue for you, please contact our support team.

Authorizations:
basic
query Parameters
importConfigurationId
string <uuid>

Id of the import configuration to use for the staging process.

Note: Generally, the importConfigurationId is not required and must only be provided if a specific import configuration for transactions of this kind must be used. If a specific configuration must be used, please contact our support team.

customerId
string <uuid>

Id of the customer to upload data to.

Note: Must only be provided if the user has access to multiple customers. If the user cannot be determined without providing the customerId, the request will be denied with status 401 (Unauthorized).

tenantId
string <uuid>

Id of the tenant to upload data to.

Note: Must only be provided if the user has access to multiple tenants. If the user cannot be determined without providing the tenantId, the request will be denied with status 401 (Unauthorized).

Request Body schema: application/json

Transactions to upload.

A maximum of 1000 transactions can be uploaded per request. Use multiple requests if you need to send more than 1000 transactions.

required
Array of objects (TransactionUpload)

A list of transactions to upload.

Array
amount
required
number <double>

Amount of the transaction.

Amount, with a total of 19 digits and 4 fraction digits.
Amounts are always specified in the interface as decimal values in the main unit of the corresponding currency. The subunit is a decimal fraction (usually one hundredth) of the value of the main unit. '.' (dot) must be used as the decimal separator.
All amounts in the interface must always be interpreted with a +/- sign, where

  • positive amounts are in favour of the merchant
  • negative amounts are at the expense of the merchant
currency
required
string = 3 characters

3-letter currency code of the amount according to [ISO4217].

transactionDate
required
string($date-time)yyyy-MM-ddTHH:mm:ssK
Example: "2023-09-19T11:23:58+02:00"

Date and time of the transaction on the cash register (Sale).

Note: It is recommended to provide timezone information. If no timezone information is provided, the value will be imported in the ReconHub default timezone (W. Europe Standard Time).

The date must not be more than 10 years in the past and not be more than 2 years in the future.

acquirerId
string or null [ 0 .. 30 ] characters

Payment processor of the transaction.

Note: Either the id or the name can be provided. By default, if the value is unknown to ReconHub, the request will be rejected. If you need ReconHub to support a new id, please contact our support team.

Possible values

  • 31 - Accarda

  • 15 - Adyen

  • 19 - AirPlus

  • 130 - AlphaCard

  • 53 - Amazon

  • 11 - AmericanExpress

  • 140 - AmericanExpress DE AT

  • 144 - AmericanExpress ES

  • 147 - AmericanExpress FI

  • 143 - AmericanExpress FR

  • 149 - AmericanExpress HU

  • 141 - AmericanExpress IT

  • 142 - AmericanExpress NL

  • 148 - AmericanExpress PL

  • 145 - AmericanExpress SE

  • 146 - AmericanExpress UK

  • 68 - ANGEL

  • 77 - AP-Energy

  • 36 - Aplauz

  • 78 - Austrocard

  • 128 - Bank WIR

  • 86 - Bartolini

  • 7 - BonCard

  • 125 - BonusCard.ch

  • 51 - Breuninger

  • 9 - BsPayone

  • 74 - Byjuno

  • 70 - Cash Logistik

  • 30 - CCC

  • 129 - Cembra Money Bank

  • 122 - Cetelem

  • 46 - COD

  • 33 - Coinify

  • 8 - Concardis

  • 40 - Divoora

  • 79 - DKV Euro Service

  • 27 - EatCh

  • 90 - eBay

  • 26 - Edenred

  • 22 - EGuma

  • 10 - Elavon

  • 50 - Engelhorn

  • 154 - Epassi

  • 89 - Epay

  • 69 - First Data

  • 71 - foodora

  • 32 - Galaxus

  • 58 - Gamanza

  • 47 - GLS

  • 61 - Goetz

  • 150 - GSA

  • 60 - GWS

  • 124 - Innocard

  • 81 - IQ Card

  • 41 - Justeat

  • 92 - Kaufland

  • 45 - Klarna

  • 56 - Lieferando

  • 29 - Loomis

  • 91 - ManoMano

  • 23 - Menu

  • 21 - MfGroup

  • 102 - Migros Bank

  • 16 - Miinto

  • 87 - MobilePay

  • 72 - Mollie

  • 120 - Monizze

  • 44 - Neteller

  • 83 - Nexi

  • 96 - Nova

  • 94 - Novofleet

  • 35 - otto

  • 95 - Park.Aero

  • 55 - PAYBACK

  • 20 - PayLife

  • 101 - Payone AT

  • 14 - PayPal

  • 34 - Paysafe

  • 65 - Payyo

  • 66 - Planet

  • 4 - Postfinance

  • 152 - PowerPay

  • 48 - PPL

  • 37 - PPRO

  • 59 - Prosegur

  • 6 - REKA

  • 93 - Riverty

  • 42 - SafeCharge

  • 84 - Satispay

  • 155 - SBB

  • 126 - Shell CH

  • 127 - Shell TPN

  • 43 - Skrill

  • 85 - Smartum

  • 39 - Smood

  • 25 - Sodexo

  • 12 - Sonect

  • 52 - SportScheck

  • 97 - S-Public Services

  • 24 - Stripe

  • 63 - SwedbankPay

  • 75 - Swish

  • 5 - Swisscard

  • 103 - TeleCash

  • 0 - TestAcquirer

  • 64 - Ticketcorner

  • 76 - Too Good To Go

  • 17 - Twint

  • 28 - UberEats

  • 82 - Union Tank Eckstein

  • -1 - Unknown

  • 151 - Unzer

  • 67 - UPS

  • 88 - Vipps

  • 73 - Volksbank eG

  • 54 - VR Payment

  • 80 - W.A.G. Payment Solutions

  • 153 - Wallee

  • 121 - Winarco

  • 13 - Wirecard

  • 123 - WL Petrol

  • 57 - Wolt

  • 2 - Worldline

  • 100 - Worldline BC

  • 98 - Worldline INT

  • 99 - Worldline NV

  • 38 - Worldpay

  • 62 - WSN

  • 18 - Zalando

  • 49 - Zasilkovna

  • 104 - Ziemann

applicationId
string or null [ 0 .. 32 ] characters

Application identifier (AID).

Note: By default, if the brandId and the applicationId are unknown to ReconHub the request will be rejected. If you need ReconHub to support a new applicationId, please contact our support team.

Possible values

  • 4D620D4C0203 - Twint

  • A00000000111010505 - Postcard

  • A0000000031010 - Visa

  • A0000000032010 - Visa

  • A0000000032020 - VPAY

  • A0000000041010 - MasterCard

  • A0000000043060 - MaestroDomestic

  • A00000002501 - Amex

  • A0000000651010 - JCB

  • A0000001110101 - Postcard

  • A0000001110110 - Postcard

  • A0000001110201 - Postcard

  • A0000001110210 - Postcard

  • A0000001110505 - Postcard

  • A0000001110510 - Postcard

  • A0000001523010 - Discover

  • A0000001524010 - Discover

  • A0000001570010 - Amex

  • A0000001570020 - MasterCard

  • A0000001570021 - MaestroInternational

  • A0000001570022 - MaestroDomestic

  • A0000001570030 - Visa

  • A0000001570031 - Visa

  • A0000001570040 - JCB

  • A0000001570051 - Postcard

  • A000000157010D - Powercard

  • A000000157010E - RekaCard

  • A0000001574443 - Diners

  • A0000001574445 - Postcard

  • A0000001574446 - Postcard

  • A0000001574450 - M-Card

  • A0000001574452 - VPAY

  • A0000001574455 - BoncardPoints

  • A0000001574458 - Amex

  • A000000157445B - BoncardPay

  • A0000001574460 - UnionPay

  • A0000001574464 - RekaCard

  • A0000001574473 - PostFinanceEFinance

  • A0000001574476 - Powercard

  • A0000001574478 - Powercard

  • A0000001574479 - Powercard

  • A000000157447C - VPAY

  • A000000157447D - LunchCheck

  • A000000157447F - EKZCard

  • A0000001574486 - LunchCheck

  • A0000001574495 - RekaCard

  • A0000001574497 - RekaCard

  • A000000157449E - Twint

  • A00000015744BD - SwissPay

  • A00000015744FB - PF Pay

  • A0000003330101 - UnionPay

  • A0000004360100 - Edenred

  • A0000008010001 - SwissPay

  • A0000008221010 - MasterCard

  • D7560000010102 - RekaCard

  • D7560000011111 - RekaCard

  • D7560000011112 - RekaCard

  • D7560000011113 - RekaCard

  • D7560001150001 - LunchCheck

authorisationCode
string or null [ 0 .. 50 ] characters

Authorisation code of the transaction.

brandId
string or null [ 0 .. 30 ] characters

Brand of the transaction.

Note: Either the id or the name can be provided. By default, if the brandId and the applicationId are unknown to ReconHub the request will be rejected. If you need ReconHub to support a new brandId, please contact our support team.

Possible values

  • 0 - Unknown

  • 1 - MaestroDomestic

  • 2 - MaestroInternational

  • 3 - Postcard

  • 4 - Visa

  • 5 - MasterCard

  • 6 - Amex

  • 7 - Diners

  • 9 - JCB

  • 10 - VPAY

  • 11 - UnionPay

  • 12 - LunchCheck

  • 13 - RekaCard

  • 14 - Paydirekt

  • 15 - Girocard

  • 16 - Twint

  • 17 - Alipay

  • 18 - MyOne

  • 19 - PayPal

  • 20 - BoncardPoints

  • 21 - BoncardPay

  • 22 - EKZCard

  • 23 - SwissPay

  • 24 - Sonect

  • 25 - Discover

  • 26 - AmazonPay

  • 27 - Bancontact

  • 28 - Eps

  • 29 - Ideal

  • 30 - Invoice

  • 31 - KlarnaPayNow

  • 32 - PayInAdvance

  • 33 - Prezelewy24

  • 34 - SepaCredits

  • 35 - SepaLsv

  • 36 - Miinto

  • 37 - Zalando

  • 38 - WePay

  • 39 - Amazon

  • 40 - Powercard

  • 41 - Paycard

  • 42 - EGuma

  • 43 - Usemenu

  • 44 - Sodexo

  • 45 - Edenred

  • 46 - BlueCode

  • 47 - EatCh

  • 48 - UberEats

  • 49 - Wechat

  • 50 - Cash

  • 51 - FuelCard

  • 52 - Galaxus

  • 53 - PostFinanceEFinance

  • 54 - Cryptocurrencies

  • 55 - paysafecard

  • 56 - otto

  • 57 - Debit Mastercard

  • 58 - Visa Debit

  • 59 - Aplauz

  • 60 - Smood

  • 61 - Divoora

  • 62 - Justeat

  • 63 - SkrillDigitalWallet

  • 64 - Neteller

  • 65 - Wolt

  • 66 - Credit Card

  • 67 - Debit Card

  • 68 - Lieferando

  • 69 - Liefery

  • 70 - DB Gutschein

  • 71 - Voucher

  • 72 - bonVito

  • 73 - TooGoodToGo

  • 74 - foodticket

  • 75 - BillPay

  • 76 - COD

  • 77 - GLS

  • 78 - PPL

  • 79 - Zasilkovna

  • 80 - Engelhorn

  • 81 - Breuninger

  • 82 - SportScheck

  • 83 - PAYBACK

  • 84 - VR Payment

  • 85 - Ticketcorner

  • 86 - Payyo

  • 87 - UPS

  • 88 - ANGEL

  • 89 - UBS KeyClub

  • 90 - Klarna Pay Later

  • 91 - foodora

  • 92 - Delivery Service

  • 93 - Sixt

  • 94 - PAYBACK PAY

  • 95 - Swish

  • 96 - Giftcard

  • 97 - Innocard

  • 98 - AP

  • 99 - Austrocard

  • 100 - DKV

  • 101 - Eurowag

  • 102 - IQ Card

  • 103 - UTA

  • 104 - Moneta

  • 105 - Pagobancomat

  • 106 - Satispay

  • 107 - Klarna Slice It

  • 108 - MobilePay

  • 109 - Dankort

  • 110 - Vipps

  • 111 - Visa Electron

  • 112 - eBay

  • 113 - ManoMano

  • 114 - Kaufland

  • 115 - Novofleet-Card

  • 116 - LOEB Card

  • 117 - LOEB Voucher

  • 118 - Smartum

  • 119 - Park.Aero

  • 120 - Cash FX

  • 121 - Visa Migros Bank

  • 122 - PlusCard

  • 123 - Nova

  • 124 - M-Card

  • 140 - AVIA CARD

  • 141 - BCMC

  • 143 - boncard CO2NeutralPay

  • 144 - boncard Coop EKZ

  • 145 - boncard Geschenkkarte

  • 146 - boncard GroupCard

  • 147 - boncard HV

  • 148 - boncard LoyaltyCARD

  • 149 - boncard LunchCheck

  • 151 - boncard Swiss PAY

  • 152 - Bonus Card

  • 153 - CapsCard

  • 154 - DCB

  • 156 - ENI Plus

  • 157 - Esso CRT

  • 158 - Esso Fleet

  • 159 - euroShell CRT

  • 160 - euroShell Fleet

  • 161 - euroShell Prepaid

  • 162 - euroShell Private

  • 163 - IKEA Credit Card

  • 164 - IKEA Temp Card

  • 165 - Innocard Bonus

  • 166 - Innocard Gift

  • 167 - Innocard Loyality

  • 168 - Innocard Prepaid

  • 169 - Lipo Standard

  • 170 - Lipo TempCard

  • 171 - LOMO

  • 172 - LUKOIL

  • 173 - Maes Oil

  • 174 - Migrolcard

  • 175 - Monizze Card

  • 176 - Moveri Oelpool

  • 177 - Payconic

  • 178 - Paymit

  • 179 - Q8

  • 180 - RekaLunch

  • 181 - RekaRail

  • 182 - Routex

  • 183 - SBB Kundenkarte

  • 184 - Shell

  • 185 - SOCAR Classic

  • 186 - SOCAR Winarco

  • 187 - Swiss Cadeau

  • 188 - TEXACO

  • 189 - TravelCard

  • 191 - Voegtlin-Meyer

  • 192 - Winarco Oel-Pool Card

  • 193 - Winarco Tamoil Card

  • 194 - Winardo Transcard

  • 195 - WIR

  • 196 - CEINT

  • 197 - CENAT

  • 198 - Unzer Bank Transfer

  • 199 - Unzer

  • 200 - SwissPass

  • 201 - Half Fare Travelcard PLUS

  • 202 - Wallet

  • 203 - Free of charge

  • 204 - Riverty

  • 205 - Epassi

  • 206 - PF Pay

businessDate
string or null <date> yyyy-MM-dd
Example: "2023-09-19"

The day when the transaction was made and when it will occur as a sale in the accounting system.

Note: Depending on the day-end closing, the business date may differ from the transaction date.

The date must not be more than 10 years in the past and not be more than 2 years in the future.

cardNumberMasked
string or null [ 0 .. 20 ] characters

Masked PAN where only the last 4 digits are available.

Note: Please do not submit any unmasked cardnumbers.

eftTransactionDate
string($date-time) or nullyyyy-MM-ddTHH:mm:ssK
Example: "2023-09-19T11:23:58+02:00"

Date on which the transaction was executed on the EFT/POS terminal.

This value is transmitted from the terminal to the cash register after a successful authorization.

Note: It is recommended to provide timezone information. If no timezone information is provided, the value will be imported in the ReconHub default timezone (W. Europe Standard Time).

The date must not be more than 10 years in the past and not be more than 2 years in the future.

locationId
string or null [ 0 .. 30 ] characters

Used to identify the location where the transaction was made.

Note: Can be the number or name of the cash register, for example.
Either the terminal ID or the location ID must be provided. The request will be rejected if both are missing.

The upload won't be rejected if the terminal ID or location ID does not exist, but the transactions won't be imported either. The transactions can be reimported using the ReconHub UI as soon as the location was created.

To get a list of possible terminal IDs or location IDs please refer to the ReconHub UI until an appropriate API is available.

orderId
string or null [ 0 .. 50 ] characters

The merchant’s reference number. This is typically generated by the merchant’s ordering system. Also known as Merchant Order ID.

panEncrypted
string or null [ 0 .. 32 ] characters

The PAN encrypted of a transaction.

Encrypted primary account numbers of the cardholder. This is not available for every system.

Note: ReconHub does not store the corresponding key material (see https://learn.reconhub.cloud/portal/en/kb/articles/pci-dss).

terminalId
string or null [ 0 .. 50 ] characters

Identifier of the terminal.

Note: Either the terminal ID or the location ID must be provided. The request will be rejected if both are missing.

The upload won't be rejected if the terminal ID or location ID does not exist, but the transactions won't be imported either. The transactions can be reimported using the ReconHub UI as soon as the location was created.

To get a list of possible terminal IDs or location IDs please refer to the ReconHub UI until an appropriate API is available.

transactionReference
string or null [ 0 .. 50 ] characters

Acquirer Reference Number (ARN).

transactionSequenceCounter
string or null [ 0 .. 50 ] characters

Transaction sequence number maintained by the terminal, which is increased by one for each transaction. The terminal guarantees that this counter is unique per terminal. This field can also be used for the system traced audit number (STAN).

transactionTypes
Array of strings or null (TransactionType)
Enum: "Purchase" "Credit" "Chargeback" "DoubleCharge" "Reversal" "FinancialAdjustment"

Types for the transaction.

Possible values

  • Purchase
  • Credit
  • Chargeback
  • DoubleCharge
  • Reversal
  • FinancialAdjustment

The transaction type is purely indicative and does not define the direction of the cash flow or the sign of amounts.
In the case of a reversal, the transaction reference of the original transaction should be inserted in TransactionReference.
This enables the reference from the reversal to the original transaction to be created.

Array of objects or null (AdditionalData) <= 10 items

Additional data related to the transaction.

Note: This can be used to provide custom data by the merchant for their transactions. For example merchant specific IDs.

These values can later be used for the reconciliation and posting of this transaction.

Responses

Request samples

Content type
application/json
{
  • "transactions": [
    ]
}

Response samples

Content type
application/json
{
  • "uploadId": "722fd2e4-caaf-462c-937f-7756caf3772f"
}

Get upload state

Get the state of a specific upload by providing the uploadId obtained by the POST /upload action.

Authorizations:
basic
path Parameters
uploadId
required
string

Id of the transaction upload.

Is obtained when uploading transactions using the POST /upload route.

query Parameters
customerId
string <uuid>

Id of the customer to retrieve the data from.

Note: Must only be provided if the user has access to multiple customers. If the user cannot be determined without providing the customerId, the request will be denied with status 401 (Unauthorized).

tenantId
string <uuid>

Id of the tenant to retrieve the data from.

Note: Must only be provided if the user has access to multiple tenants. If the user cannot be determined without providing the tenantId, the request will be denied with status 401 (Unauthorized).

Responses

Response samples

Content type
application/json
{
  • "date": "2023-09-19T11:23:58+02:00",
  • "status": "Processing",
  • "summary": "string",
  • "errors": [
    ]
}

Get transactions

Query transactions in ReconHub. Provide filter, sorting and paging criterias in the request.

Authorizations:
basic
query Parameters
customerId
string <uuid>

Id of the customer to retrieve the data from.

Note: Must only be provided if the user has access to multiple customers. If the user cannot be determined without providing the customerId, the request will be denied with status 401 (Unauthorized).

tenantId
string <uuid>

Id of the tenant to retrieve the data from.

Note: Must only be provided if the user has access to multiple tenants. If the user cannot be determined without providing the tenantId, the request will be denied with status 401 (Unauthorized).

terminalId
string

Filters transactions by terminal id.

brandId
string

Filters transactions by brand id.

currency
string

Filters transactions by currency.

amountFrom
number <double>

Excludes transactions below the specified amount.

amountTo
number <double>

Excludes transactions above the specified amount.

transactionDateFrom
string <date-time> yyyy-MM-ddTHH:mm:ssK
Example: transactionDateFrom=2023-09-19T11:23:58+02:00

Excludes transactions created before the specified date.

transactionDateTo
string <date-time> yyyy-MM-ddTHH:mm:ssK
Example: transactionDateTo=2023-09-19T11:23:58+02:00

Excludes transactions created after the specified date.

transactionState
string (TransactionState)
Enum: "Unprocessed" "Processed"

Filters transactions by the transaction state.

transactionMatchState
string (TransactionMatchState)
Enum: "NotApplicable" "Unmatched" "Match" "Skip"

Filters transactions by the transaction match state.

uploadId
string

Filters transactions by the operation id.

pageSize
integer <int32> [ 1 .. 500 ]
Default: 30

Limits the maximum number of items that can be returned. The value can range between 1 and 500.

pageNumber
integer <int32> [ 1 .. 2147483647 ]

Page number.

sorting.key
string (TransactionListSortKey)
Enum: "TransactionDate" "Amount"

Sorting key.

sorting.direction
string (ListSortDirection)
Enum: "Ascending" "Descending"

Sorting direction.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "hasMore": true
}

Get transaction by id

Get the details of a specific transaction.

Authorizations:
basic
path Parameters
id
required
string <uuid>

Id of transaction.

query Parameters
customerId
string <uuid>

Id of the customer to retrieve the data from.

Note: Must only be provided if the user has access to multiple customers. If the user cannot be determined without providing the customerId, the request will be denied with status 401 (Unauthorized).

tenantId
string <uuid>

Id of the tenant to retrieve the data from.

Note: Must only be provided if the user has access to multiple tenants. If the user cannot be determined without providing the tenantId, the request will be denied with status 401 (Unauthorized).

Responses

Response samples

Content type
application/json
{
  • "additionalData": [
    ],
  • "comment": "This is a comment",
  • "transactionId": "e88e0db7-4fd9-47b4-b2e9-1a7f81ea980d",
  • "transactionState": "Processed",
  • "transactionMatchState": "Match",
  • "transactionTypes": [
    ],
  • "acquirerId": "WorldLine",
  • "amount": 123.45,
  • "applicationId": "A0000000041010",
  • "authorisationCode": "XYZ123456789",
  • "brandId": "MasterCard",
  • "businessDate": "2023-09-19",
  • "cardNumberMasked": "1234XXXXXXXXXXXX",
  • "currency": "CHF",
  • "eftTransactionDate": "2023-09-19T08:42:05+02:00",
  • "locationId": "100900901",
  • "orderId": "987654",
  • "panEncrypted": "7823-1264-7835-9424",
  • "terminalId": "90010001",
  • "transactionDate": "2023-09-19T08:45:00+02:00",
  • "transactionReference": "abcd1234",
  • "transactionSequenceCounter": "1234567890"
}