Modern software providers need to operate seamlessly across both physical devices and online channels. At Surfboard Payments, our platform is designed to streamline the integration process, allowing you to implement secure, cross-channel (omni-payment) solutions quickly and efficiently. In this post, we’ll cover the basic flows—from creating an order to initiating a payment. We also explain how you can start a transaction online and complete it in-person, with practical code examples to help you get started.
Overview
Our platform provides a consistent integration experience regardless of the payment channel. Whether you’re connecting to a physical payment terminal or integrating online payments, the underlying processes share similar endpoints and security standards. Our solution supports omni-payments, enabling scenarios where a customer can reserve an amount online and then complete the full payment in-person.
In-Person Payment Integration
In-person payment integration involves managing transactions across various physical devices — from countertop terminals to mobile SoftPOS devices. Our guides and APIs ensure that the process is straightforward, secure, and consistent.
Step 1: Creating an Order
Begin by creating an order using our API. The endpoint accepts order details such as the order ID, amount, currency, and list of items.
cURL Example
curl -d '{
"terminal$id": "813bee989f08500405",
"type": "purchase",
"referenceId": "orderabc",
"orderLines": [
{
"id": "1234",
"name": "Bucket hat",
"quantity": 1,
"itemAmount": {
"regular": 2000,
"total": 2000,
"currency": "SEK",
"tax": [
{
"amount": 200,
"percentage": 10,
"type": "vat"
}
]
}
}
]
}'
-H 'Content-Type: application/json' \
-H 'API-KEY: YOUR_API_KEY' \
-H 'API-SECRET: YOUR_API_SECRET' \
-H 'MERCHANT-ID: YOUR_MERCHANT_ID' \
YOUR_API_URL/orders
Step 2: Initiating the Payment
Once the order is created, initiate the payment for an in-person transaction. This process communicates with the designated payment terminal and handles the transaction details.
cURL Example
curl -d '{
"orderId": "o_RelSnor1A6gqgKzZxrbM7",
"paymentMethod": "CARD"
}' \
-H 'Content-Type: application/json' \
-H 'API-KEY: YOUR_API_KEY' \
-H 'API-SECRET: YOUR_API_SECRET' \
-H 'MERCHANT-ID: YOUR_MERCHANT_ID' \
YOUR_API_URL/payments
Omni-Payments: Bridging Online and In-Person Experiences
A powerful feature of our platform is the ability to support omni-payments. This approach allows a customer to begin a payment online and complete it in-person. For example, you might reserve an amount online via an order creation and partial payment process, then finalize the transaction using a physical terminal when the customer visits your location. This flexibility ensures that your business can offer a seamless and adaptable payment experience across all channels.
The flow is similar, but with initiating a partial payment instead of a full one. You simply update the order, and initiate another partial payment.
Update order
cURL Example
curl -d '{
"terminal$id": "813bee989f08500405",
"type": "purchase",
"orderLines": [
{
"id": "1234",
"name": "Bucket hat",
"quantity": 1,
"itemAmount": {
"regular": 2000,
"total": 2000,
"currency": "SEK",
"tax": [
{
"amount": 200,
"percentage": 10,
"type": "vat"
}
]
}
}
]
}' \
-H 'Content-Type: application/json' \
-H 'API-KEY: YOUR_API_KEY' \
-H 'API-SECRET: YOUR_API_SECRET' \
-H 'MERCHANT-ID: YOUR_MERCHANT_ID' \
YOUR_API_URL/orders/:orderId
Initiate a partial payment
- Start by making a POST request to the Initiate a Payment API.
- Include the following key parameters:
- orderId: The unique identifier for the order you're initiating a partial payment for.
- paymentMethod: Specify the method by which the payment will be processed. Default payment method is ’CARD’
- amount: Input the partial sum that the customer agrees to pay at this time.
- You will get a response containing the paymentId. This ID is required to fetch payment status, performing a refund etc.
- Store the Payment ID securely and associate it with an identifiable record in your system for easy retrieval.
- Merchants can now accept payments from customers using the selected payment method. For card payments, merchants can accept payments through our payment acceptance terminals.
- Repeat the aforementioned steps for initiating partial payments until the total order amount is fully paid. Keep in mind that the order will only be completed when all the initiated partial payments are processed and their sum equals the total order amount.
curl -d '{
"orderId": "o_RelSnor1A6gqgKzZxrbM7",
"paymentMethod": "CARD"
"amount": 1000
}' \
-H 'Content-Type: application/json' \
-H 'API-KEY: YOUR_API_KEY' \
-H 'API-SECRET: YOUR_API_SECRET' \
-H 'MERCHANT-ID: YOUR_MERCHANT_ID' \
YOUR_API_URL/payments
Key Benefits
- Unified Integration Experience: Use a consistent API approach for both in-person and online payments.
- Omni-Payments Capability: Enable customers to switch between online and in-person channels effortlessly.
- Ease of Integration: Comprehensive documentation and code examples reduce development time.
- Cross-Channel Compatibility: Seamlessly support various hardware devices and online payment methods.
- Scalability and Security: Our platform is designed to grow with your business while maintaining high security standards.