Skip to main content

Guidelines

Portal API​

This API is used for getting automated feedback from Samport systems.

Clearing report​

Approved and captured transactions sent to processor. The general use of this file is an automatically generated comparison with bank statements, the cash register and/or order system. The report is static after it is compiled and cannot change. If you use several processors a specific batch will be generated for each individual processor. All the transactions in the clearing report have been approved in authorization, but the processor can reject transactions when cleared.

Transaction report​

Shows all transactions in a day, including actions on the terminal. This report is used to overview daily usage or troubleshoot. This report is not affected by clearing hour.

Authentication​

You pass the API-Key as a HTTP header like so:

GET api/v1/report/clearings?Date=2025-04-05&MerchantId=65432100 HTTP/1.1
Host: portal.samport.com:443
API-Key: ZJsU9N6UVW7N5NxTJFgXiTtzGP2kUP0Ty1sdBOHAaz1gYyAI06besEFN4lESjxy3

Generating a key​

Log into the portal and select the merchant or partner account you want to manage.

Navigate to: API Keys -> Create API Key, give it a name, access level and optionally set an expiry date.

Important!

Once you click "Create" this is the only time your key will be visible, If you lose it you will need to generate a new one.

Decommissioning a key​

If you suspect that a key has been compromised or is about to expire it is up to you to decommission it. Make sure that you generate a new key and replace it in any applications where it's used and then delete the old key, once deleted a key will stop working immediately.

Implementation recommendations​

  • The reports should be fetched for the previous day.
  • The reports should be fetched one at a time per merchant per day.

Rate limits​

  • 1 request per minute per API-key

Timeouts​

Client session timeout - 120 seconds
Your HTTP Client should have a session timeout of 120 seconds for best results. If timeout occurs while fetching a large dataset (15k+ records) the cache will be able to pickup close to where it left off, if for some reason this would still timeout wait another 3 minutes before trying again.

Successful - Empty - 30 minutes
If clearing report returns HTTP:200 but results in an empty set there is no clearing file available yet, delay your request with 30 minutes before trying again.

Clearing errors​

Sometimes unforeseen circumstances or a service window from a processor can cause the clearing to fail. In these cases this will be reflected in the returned dataset where the clearing might be marked with response codes PR (partially rejected) or TR (totally rejected).

Depending on the nature of the disruption the clearing file might receive a new ClearingID once corrected, or the existing ClearingID might be reused but with an updated response code. TransactionID's will always remain the same so that they can be matched to each transaction.

The Worldline Network operations team will attempt to correct these as soon as possible and should usually be available on the next day.

All 36 files have been successfully fetched from the GitLab repository samiss/developer.samport.com. The content includes comprehensive documentation for the Samport Terminal API and Portal API, covering topics such as authentication, connection models, payment processing, receipt printing, integration guidelines, and support resources.