Physical Sale
Test this endpoint live
Open the same request directly in API Explorer.
Server URL
Starts an in-person sale on a physical payment terminal connected to a Softpay point of sale. Physical transactions are processed using operation type `SALE`, which functions as an instant capture making sales function as both an `AUTHORIZATION` and `CAPTURE` in a single atomic operation. These transactions therefor cannot be voided. This endpoint creates the transaction immediately. The `transaction` returned in the response confirms that the sale request was accepted and created, but not that the cardholder has completed the payment yet. If `terminal.id` is provided, ePay targets that specific terminal. If `terminal` is omitted, ePay automatically routes the sale to the fallback terminal for the given point of sale. The `pointOfSaleId` must refer to a physical Softpay point of sale that belongs to your account. ### Refunds Physical transactions does not support card-not-present online refunds. Meaing the refund operation is not supported for physical transactions. To refund a previous purchase a `PAYOUT` transaction must be initiated instead by setting `"type": "PAYOUT"`, which will initiate a transaction on the terminal sending funds to the card placed on the terminal. ### Notification You’ll receive the outcome of the payment on the `notificationUrl` you provide within the request, making it the primary way to track the result of this payment. [Webhooks](/api/webhooks/create-webhook) can be used separately if you need broader, system-wide updates. Early rejections, such as the SoftPay terminal being wrongly configured or blocked by another transaction will return a transaction response with state `FAILED`. If the transaction fails due to early rejections, the final state is returned in the response and no notification is sent to the `notificationUrl`.
Authorization
BearerAuth In: header
Header Parameters
Ensures that a request can be safely retried without causing duplicate operations. Typically used for actions like payment creation and operations such as refund and void to prevent accidental double processing. - If a response is replayed due to using the same key, the response will include the header `Idempotent-Replayed: true`. - Idempotency keys are scoped by **[Key, Endpoint, HTTP Verb]**; the same key on a different endpoint or method will not replay the original response. - Responses are cached for **24 hours**. After that, the cache is cleared, so idempotency is only guaranteed within 24 hours of the initial request.
Request Body
application/json
Physical sale request payload.
TypeScript Definitions
Use the request body type in TypeScript.
Physical sale data used to create the terminal transaction.
The ID of the Softpay point of sale to associate the physical sale with.
uuid"01924737-9c18-71c0-ab1a-88698eaceabf"The transaction type to process. Use PAYMENT for purchases and PAYOUT for refunds. Defaults to PAYMENT if not given.
Note that PAYOUT requires the feature to be enabled by SoftPay.
"PAYMENT""PAYMENT""PAYOUT""PAYMENT"The amount must be defined in minor units. E.g. 2,50 DKK must be set as 250.
1000The currency code of the payment. For Danish Kroner defined as DKK. ISO 4217 alpha-3 (e.g., DKK)
^[A-Z]{3}$"DKK"The URL to receive the webhook with the final transaction result.
urilength <= 1024"https://example.com/notification"This is the transaction reference, similar to an order ID.
The reference SHOULD be unique for each payment, as some acquirers enforce per-payment uniqueness.
Using a duplicate reference may result in failed payments or make reconciliation difficult.
Only ASCII alphanumeric characters and dashes are allowed.
^[A-Za-z0-9-]{1,36}$1 <= length <= 36"store-sale-1"A list of pass through attributes that is sent back to the merchant on webhooks. Max size is 1kb.
{
"orderId": "order-123",
"cashRegisterId": "register-7"
}An optional merchant defined customer id used to uniquely identify a user in the merchant system.
"User159"Customer info associated with the sale. It is recommended to send all the info that is available.
Response Body
application/json
application/json
application/json
application/json
MOTO Authorization
PCI-DSS Compliance As this endpoint receives raw payment data, the integrator is required to provide documentation for PCI-DSS compliance before access can be granted. This endpoint creates and processes an online MOTO transaction and returns the authorization result in the response. This is typically used within the travel industry, where it is more common for customers to provide their card info over the phone when booking a vacation. This can be used by merchants to automate authorizations when receiving card info from brokers such as hotels.com and booking.com. We recommend a minimum timeout of 60 seconds.
Capture Payment
Capture a payment by finalizing a previously authorized transaction and moving the funds from the customer’s card to your account. When a payment is first authorized, the customer’s bank sets aside the money but doesn’t transfer it yet. Capturing the payment completes the process and transfers those funds to you. We recommend a minimum timeout of 60 seconds. Operations are processed synchronously All operations such as CAPTURE, VOID and REFUND are processed synchronously and the outcome is returned directly in the response, meaning webhooks are not required. We strongly recommend using the Idempotency-Key header, to ensure safe retries in case of network failure.