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 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

AuthorizationBearer <token>

In: header

Header Parameters

Idempotency-Keystring

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.

idstring

Required

The ID of the terminal to target. The terminal must belong to the provided point of sale.

Default:

null

Format:

uuid

Example:

"0197c07b-3f6d-7be2-b848-702b08958128"

suppressAppNotificationsboolean

Nullable

If true no notification is sent to the SoftPay terminal, this might be relevant on "same-device" POS systems, where a App Switch initiates the payment. If the SoftPay app is always in the foreground, then it is recommended to use false, as this makes the SoftPay terminal more responsive.

Default:

false

Example:

false

switchBackTimeoutinteger

Nullable

The number of milliseconds the SoftPay terminal waits, before switching back to the origin app / activity. A null indicates no switch back. A 0 indicates "as fast as allowed". SoftPay enforces a minimum of 1 second for successful payments and 2 seconds for failed payments, due to scheme regulations. This can also be controlled in the intent redirect from a POS app to the SoftPay app.

Default:

null

Example:

0

activityToResumestring

Nullable

ComponentName, e.g. package name / activity class to switch back to, once the payment is completed. This can also be controlled in the intent redirect from a POS app to the SoftPay app.

Default:

null

surchargeboolean

Nullable

Specify if surcharge should be applied to the transaction, if applicable.

Default:

null

Example:

false

dccboolean

Nullable

Specify if dynamic currency conversion (DCC) should be applied to the transaction, if applicable.

Default:

null

Example:

false

Physical sale data used to create the terminal transaction.

pointOfSaleIdstring

DeprecatedNullable

DEPRECATED - Use terminal.id instead

The ID of the Softpay point of sale to associate the physical sale with.

Format:

uuid

Example:

"01924737-9c18-71c0-ab1a-88698eaceabf"

typestring

Nullable

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.

Default:

"PAYMENT"

Possible values:

"PAYMENT""PAYOUT"

Example:

"PAYMENT"

amountinteger

Required

The amount must be defined in minor units. E.g. 2,50 DKK must be set as 250.

Example:

1000

currencystring

Required

The currency code of the payment. For Danish Kroner defined as DKK. ISO 4217 alpha-3 (e.g., DKK)

Match:

^[A-Z]{3}$

Example:

"DKK"

notificationUrlstring

Required

The URL to receive the webhook with the final transaction result.

Format:

uri

Length:

length <= 1024

Example:

"https://example.com/notification"

referencestring

Nullable

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.

Match:

^[A-Za-z0-9-]{1,36}$

Length:

1 <= length <= 36

Example:

"store-sale-1"

A list of pass through attributes that is sent back to the merchant on webhooks. Max size is 1kb.

customerIdstring

Nullable

An optional merchant defined customer id used to uniquely identify a user in the merchant system.

Example:

"User159"

Customer info associated with the sale. It is recommended to send all the info that is available.

firstNamestring

Nullable

The first name of the paying customer.

Length:

1 <= length

Example:

"Peter"

lastNamestring

Nullable

The last name of the paying customer.

Length:

1 <= length

Example:

"Nielsen"

birthdatestring

Nullable

The date of birth of the cardholder in YYYY-MM-DD format.

Format:

date

Example:

"2000-07-25"

emailstring

Nullable

The email of the paying customer.

Length:

1 <= length

Example:

"email@example.com"

phoneNumberstring

Nullable

E.164 phone number format with a single space between country code and local number. No additional spaces allowed.

Format: "+[countryCode] [number]".

Match:

^\+\d{1,3} \d+$

Example:

"+45 12345678"

The shipping address of the purchase. If no wares are shipped, leave this empty. If billing and shipping address is the same, then fill both properties with identical information.

countryCodestring

Nullable

ISO 3166-1 alpha-2 country code

Length:

2 <= length <= 2

Example:

"DK"

postalCodestring

Nullable

The local postal code of the address

Length:

1 <= length <= 16

Example:

"1400"

citystring

Nullable

The city

Length:

1 <= length <= 50

Example:

"København"

line1string

Nullable

The first address line. Most address only has a singular line.

Length:

1 <= length <= 50

Example:

"Torvegade 45"

line2string

Nullable

Second address line. Only use if address contains multiple lines. Always start with line1.

Length:

1 <= length <= 50

Example:

"2. th."

line3string

Nullable

Third address line. Only use if address contains multiple lines. Always start with line1 and line2.

Length:

1 <= length <= 50

Example:

"Christianshavn"

The billing address of the customer. Often the personal address of the customer or the business address of paying company. If billing and shipping address is the same, then fill both properties with identical information.

countryCodestring

Nullable

ISO 3166-1 alpha-2 country code

Length:

2 <= length <= 2

Example:

"DK"

postalCodestring

Nullable

The local postal code of the address

Length:

1 <= length <= 16

Example:

"1400"

citystring

Nullable

The city

Length:

1 <= length <= 50

Example:

"København"

line1string

Nullable

The first address line. Most address only has a singular line.

Length:

1 <= length <= 50

Example:

"Torvegade 45"

line2string

Nullable

Second address line. Only use if address contains multiple lines. Always start with line1.

Length:

1 <= length <= 50

Example:

"2. th."

line3string

Nullable

Third address line. Only use if address contains multiple lines. Always start with line1 and line2.

Length:

1 <= length <= 50

Example:

"Christianshavn"

Response Body

`application/json`

curl -X POST "https://example.com/public/api/v1/sale" \  -H "Idempotency-Key: c4f5e8d2-1234-5678-90ab-cdef12345678" \  -H "Content-Type: application/json" \  -d '{    "terminal": {      "id": "0197c07b-3f6d-7be2-b848-702b08958128"    },    "transaction": {      "amount": 1000,      "currency": "DKK",      "notificationUrl": "https://example.com/notification"    }  }'

{  "transaction": {    "id": "LDG7M4WW44G",    "subscriptionId": "0197c07b-3f6d-7be2-b848-702b08958128",    "billingAgreementChargeId": "019a727b-987f-7768-a59e-71af920ef81f",    "state": "PENDING",    "errorCode": "string",    "externalStatusCodes": {      "terminal": "string",      "acquirer": "string",      "network": "string",      "sca": "string"    },    "createdAt": "2019-08-24T14:15:22Z",    "sessionId": "string",    "paymentMethodId": "b6df8625-cd25-4123-b345-638aa7b5d011",    "paymentMethodType": "CARD",    "paymentMethodSubType": "Visa",    "paymentMethodExpiry": "2019-08-24",    "paymentMethodDisplayText": "string",    "paymentMethodHolderName": "string",    "scaMode": "SKIP",    "customerId": "string",    "amount": 0,    "fee": 0,    "currency": "string",    "instantCapture": "OFF",    "notificationUrl": "http://example.com",    "pointOfSaleId": "be6bff4f-7fac-43c0-9f6b-cf2cd45ed7d1",    "reference": "string",    "textOnStatement": "string",    "exemptions": [      "LVT",      "TRA"    ],    "attributes": {      "property1": null,      "property2": null    },    "clientIp": "52.212.176.122",    "clientCountry": "DK",    "type": "PAYMENT"  }}

{  "errorCode": "SERVER_ERROR",  "message": "An unexpected system error"}

{  "errorCode": "VALIDATION_ERROR",  "message": "Input validation errors",  "errors": {    "amount": [      "[required]: Is a required non-nullable field",      "[int]: Must be an integer",      "[min:0]: Must be greater than 0",      "[max:999999999]: Must be less than 999999999"    ]  }}

{  "errorCode": "SERVER_ERROR",  "message": "An unexpected system error"}

Refunds

Notification

Authorization

Header Parameters

Request Body

Response Body

200application/json

400application/json

422application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`