Receipts
Generate, email, print, and customise receipts for in-store transactions using the Surfboard Receipts API.
Overview
After a payment is completed, Surfboard gives you several ways to deliver receipts to customers. You can attach cash register details for regulatory compliance, email a digital copy, retrieve a shareable link, print directly on a Surfboard terminal, or send fully custom ESC/POS commands for branded receipt output.
All receipt endpoints accept a Transaction ID, Payment ID, or Order ID as the identifier, so you can work with whichever reference suits your integration.
Prerequisites
Before working with receipts, make sure you have:
- A Surfboard developer account with valid API credentials (
API-KEYandAPI-SECRET) - At least one completed transaction, payment, or order
- For printing: a registered Surfboard terminal with printing capability (SurfTouch with dock or SurfPrint)
Adding Receipt Information
Use this endpoint to store cash register-specific details against an order. This data is used when generating receipt output and is often required for fiscal compliance in Nordic markets.
PUT /receipts/{orderId}Request body:
{
"sequenceNumber": "1234567",
"cashRegisterName": "Kassa 1",
"controlUnitSerialNumber": "9876543",
"cashierName": "Amanda",
"customerName": "Tom"
}Request parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
sequenceNumber | string | Yes | Receipt sequence number from your cash register. |
cashRegisterName | string | Yes | Cash register designation or name. |
controlUnitSerialNumber | string | Yes | Control unit or control system manufacturing number. |
cashierName | string | No | Name of the cashier handling the transaction. |
customerName | string | No | Name of the customer. |
Response:
{
"status": "SUCCESS",
"message": "Receipt information added successfully"
}| Parameter | Type | Description |
|---|---|---|
status | string | SUCCESS or ERROR. |
message | string | Human-readable status message. |
Emailing Receipts
Send a digital receipt directly to a customer’s email address. This is the simplest way to deliver post-payment confirmation without any printing hardware.
PUT /receipts/{id}/emailThe {id} path parameter accepts a Transaction ID, Payment ID, or Order ID.
Request body:
{
"email": "customer@example.com"
}| Parameter | Type | Required | Description |
|---|---|---|---|
email | string | Yes | Email address to deliver the receipt to. |
Response:
{
"status": "SUCCESS",
"message": "Receipt email sent successfully"
}| Parameter | Type | Description |
|---|---|---|
status | string | Status of the request. |
message | string | Description of the result. |
Tip: You can call this endpoint multiple times with different email addresses if the customer or merchant both need a copy.
Fetching a Receipt Link
Retrieve a URL that points to a hosted digital receipt. This is useful when you want to display a QR code on the terminal screen, include a link in an SMS, or embed it in your own notification flow.
GET /receipts/{id}/linkThe {id} path parameter accepts a Transaction ID, Payment ID, or Order ID.
Request body: None (empty GET request).
Response:
{
"status": "SUCCESS",
"data": {
"receiptURL": "https://receipts.surfboardpayments.com/r/abc123xyz"
},
"message": "Receipt link fetched successfully"
}| Parameter | Type | Description |
|---|---|---|
status | string | SUCCESS or ERROR. |
data.receiptURL | string | URL to access the hosted digital receipt. |
message | string | Description of the result. |
Printing Receipts on a Terminal
Print a receipt directly from a Surfboard terminal that has printing capability. Surfboard supports printing through SurfTouch (which features a dock with a printer for checkout) and SurfPrint (which has a built-in printer for on-floor payments).
PUT /receipts/{id}/printThe {id} path parameter accepts a Transaction ID, Payment ID, or Order ID.
Request body:
{
"templateId": "default",
"terminalId": "trm_abc123",
"language": "sv"
}| Parameter | Type | Required | Description |
|---|---|---|---|
templateId | string | No | Select from Surfboard’s default set of receipt templates. |
terminalId | string | No | Target a specific printing-enabled terminal. If omitted, prints on the terminal that handled the transaction. |
language | string | No | Receipt language. Available: sv, da, fi, en. Defaults to the merchant’s configured language. |
Response:
{
"status": "SUCCESS",
"message": "Receipt print command sent successfully"
}| Parameter | Type | Description |
|---|---|---|
status | string | Status of the request. |
message | string | Description of the result. |
Note: A
SUCCESSresponse means the print command was dispatched to the terminal. The terminal must be online and not processing another command for the receipt to print.
Custom ESC/POS Printing
For full control over receipt layout and branding, send raw ESC/POS commands to a terminal’s built-in printer. This lets you design completely custom receipts — including logos, formatted tables, barcodes, and styled text — using the industry-standard ESC/POS command set.
PUT /receipts/{terminalId}/escposNote that this endpoint uses the terminalId directly in the path, not a transaction or order ID.
Request body:
{
"escposCommands": "G0AbYQEbRQFTdXBlciBNYXJ0CjEyMyBNYWluIFN0ChtFABthAERhdGU6IDIwMjQvMTAvMDgKVGltZTogMTI6MDAgUE0KG0UBLS0tLS0tLS0tLQobRQAbYQBJdGVtIEE6IFdhdGVyClByaWNlOiAkMS4wMApJdGVtIEI6IEJyZWFkClByaWNlOiAkMi4wMAobRQEtLS0tLS0tLS0tClRvdGFsOiAkMy4wMAobRQAbYQFUaGFuayB5b3UhCgoKHVYA"
}| Parameter | Type | Required | Description |
|---|---|---|---|
escposCommands | string | Yes | A stream of ESC/POS commands encoded as a Base64 string. |
Response:
{
"status": "SUCCESS",
"message": "ESC/POS receipt sent to terminal"
}| Parameter | Type | Description |
|---|---|---|
status | string | Status of the request. |
message | string | Description of the result. |
Building ESC/POS Commands
ESC/POS is a command protocol originally developed by Epson and now supported by most thermal receipt printers. Common commands include:
| Command | Hex | Description |
|---|---|---|
| Initialize printer | 1B 40 | Reset printer to default settings. |
| Bold on | 1B 45 01 | Enable bold text. |
| Bold off | 1B 45 00 | Disable bold text. |
| Center align | 1B 61 01 | Center-align subsequent text. |
| Left align | 1B 61 00 | Left-align subsequent text. |
| Cut paper | 1D 56 00 | Full cut of the receipt paper. |
Workflow:
- Compose your ESC/POS byte stream (text interspersed with control commands).
- Encode the entire byte stream as a Base64 string.
- Send the Base64 string in the
escposCommandsfield.
Tip: Most ESC/POS libraries (e.g.,
escposfor Python,node-escposfor Node.js) can generate the byte stream for you. Encode the output buffer to Base64 before sending it to Surfboard.
API Quick Reference
| Operation | Method | Endpoint |
|---|---|---|
| Add receipt information | PUT | /receipts/{orderId} |
| Email a receipt | PUT | /receipts/{id}/email |
| Fetch receipt link | GET | /receipts/{id}/link |
| Print receipt on terminal | PUT | /receipts/{id}/print |
| Print custom ESC/POS receipt | PUT | /receipts/{terminalId}/escpos |
For full endpoint details, see the Receipts API reference documentation.
Other Guides
Tap to Pay on iPhone SDK
Accept contactless payments directly on iPhone. Complete integration guide for Surfboard's iOS SoftPOS SDK -- from setup to production.
Android SoftPOS SDK
Turn Android devices into payment terminals with the Surfboard Android SoftPOS SDK. Complete integration guide from setup to production.
EMV Terminal Integration
Integrate traditional card-present terminals through Surfboard's unified API. From account setup to live payments in one guide.
Payment Page
Redirect customers to a Surfboard-hosted checkout page. The fastest way to accept online payments with minimal integration effort.
Inter-App Integration
Integrate your POS app with CheckoutX using native app switch. Register terminals, process payments, and scan NFC tags through a bi-directional deep link flow.
Self-Hosted Checkout
Embed a payment form directly in your web app with the Surfboard Online SDK. Full UI control with Surfboard handling PCI compliance.
Server-to-Server API
Process online payments entirely from your backend with Merchant Initiated Transactions. Full control over recurring payments, subscriptions, and tokenized card flows.
Create an Order
Learn how to create orders with line items, tax, customer details, and control functions. The starting point for accepting payments with the Surfboard API.
Merchant Onboarding
Set up merchants and stores on the Surfboard platform. Walk through the full onboarding flow from merchant creation to KYB completion and store setup.
Payment Lifecycle
Manage the full payment lifecycle from order creation through capture, void, cancel, and refund operations using the Surfboard Payments API.
Capture a Payment
Finalize a previously authorized payment by capturing funds. Covers delay capture and pre-authorization flows with step-by-step API examples.
Terminal & Device Management
Manage payment terminals and devices via the Surfboard API. Register in-store and online terminals, configure settings, and handle device operations.
Cancel a Payment
Stop an in-progress payment before it completes. Use cancellation when a customer abandons checkout or a payment needs to be halted mid-process.
Webhooks & Notifications
Receive real-time event notifications via webhooks, email, Slack, and SFTP. Subscribe to payment events and settlement reports for merchants and partners.
Recurring Payments
Implement subscription billing and recurring charges using tokenization, recurring payment configuration, and Merchant Initiated Transactions.
Void a Payment
Reverse a completed payment before settlement. Voiding stops funds from transferring to the merchant's account, avoiding incorrect transactions.
Refund an Order
Process a full refund by creating a return order with negative quantities. Covers the complete refund flow with API examples and payment method requirements.
Partial Refund
Refund specific items or a reduced amount from a completed order. Process partial returns by creating a return order with only the items to be refunded.
Tips Configuration
Configure tipping on Surfboard payment terminals at the merchant, store, or terminal level using a hierarchical override model.
NFC Tag Reading
Use the NFC Reading API to create tag-reading sessions on payment terminals, scan NFC/RFID-tagged products, and retrieve scanned tag data.
Partial Payments
Split an order across multiple payment methods or transactions. Accept card, cash, and Swish in any combination to settle a single order.
Multi-Merchant Terminals
Set up shared payment terminals for multiple merchants using the Multi-Merchant Group API. Ideal for food courts, events, and co-located businesses.
Store Management
Create, update, verify, and manage in-store and online stores using the Surfboard Payments Store APIs.
Gift Cards & Promotions
Issue and manage gift cards, track transactions, and create marketing promotions using the Surfboard Payments APIs.
Product Catalog
Create and manage product catalogs, products, variants, inventory levels, and analytics through the Catalog API.
Settlements & Reporting
Retrieve settlement reports, view adjustments, manage merchant charges, and register customer profiles for reconciliation and billing.
Account & Service Provider Management
Create merchant and partner accounts, manage user roles, register service providers, and configure external notifications via the Surfboard API.
Payment Methods
Activate, deactivate, and list payment methods for a merchant. Manage card, Swish, Klarna, AMEX, Vipps, MobilePay, and more via the API or Partner Portal.
Client Auth Tokens
Generate client-side authentication tokens for secure API access from browsers and mobile apps without exposing your API key or secret.
Partner Branding
Configure white-label branding for terminals and payment pages. Set colors, fonts, logos, and cover images at the partner level via API or Partner Portal.
Ready to get started?
Create a sandbox account and start building your integration today.