MOTO Authorization
Test this endpoint live
Open the same request directly in API Explorer.
Server URL
:::warning 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.*
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
Transaction processing result
TypeScript Definitions
Use the request body type in TypeScript.
Id of the point of sale to associate the payment with.
uuid"01924737-9c18-71c0-ab1a-88698eaceabf"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. **Worldline specific**: `-` is removed if present and if the value is longer than 12 position, the left most part is used.
^[A-Za-z0-9-]{1,36}$1 <= length <= 36"reference-1"The amount must be defined in minor units. E.g. 2,50 DKK must be set as 250. If amount is set to 0 a token will be created only and returned to the integrator.
100The currency code of the payment. For Danish Kroner defined as DKK. ISO 4217 alpha-3 (e.g., DKK)
^[A-Z]{3}$"DKK"If the payment should be captured instantly or not.
OFFindicates that the payment should not be captured instantly.VOIDindicates that the payment should be captured instantly and if somehow the instant capture fails the payment is voided.NO_VOIDindicates that the payment should be captured instantly and if the capture fails the authorization is kept (no void is made)
"OFF""VOID""NO_VOID""OFF"**DEPRECATED:** *This parameter will soon be removed and will no longer have any effect. The functionality has been replaced by routing rules in the ePay back office.* List of processors to use. This is the routing of the payment. The value can be `shift4`, `clearhaus` and `nets`.<br/><br/>Processor priority follows the order in the list. If the first processor fails or declines, the next processor in the list will be attempted, and so on until all processors have been tried. Note that the actual processing order is not guaranteed and may depend on external factors, such as the specific payment card used by the cardholder.
[
"shift4"
]This is the text set on the transaction in the bank viewed by the card holder. That can be e.g. "order 123". Defaults to the ePay transaction id. Some providers does not support long texts, ePay will automatically cut the text to fit the providers requirements.
1 <= length <= 39"order 123"A list of pass through attributes that is sent back to the merchant on webhooks. Max size is 1kb.
An optional merchant defined customer id used to uniquely identify a user in the merchant system. This field is required to enable stored payment methods and enhanced age verification.
"User159"Customer info. These data points are used during SCA/3DS and is required for some schemes. These data may also be sent to the specific payment provider, if required to complete the payment such as Klarna. It is recommended to send all the info that is available to improve the approval rate.
{
"firstName": "Peter",
"lastName": "Nielsen",
"email": "email@example.com"
}If not null then pre-authorization webhook are enabled for all transaction attempts for the session. Max length is 1024.
uri1 <= length <= 1024"https://example.com/preAuth"The array containing list of line items that are part of this order. Maximum of 1000 line items could be processed in a single order. This is used by some payment methods, such as Klarna.
items <= 1000Note scaMode is always set to FORCE when initializing a subscription due to EU PSD2 regulations.
To create a subscription, allowing you to process MIT transactions in the future, you must send the subscription object. To process MIT transactions you must ensure your acquirer agreement has recurring payments enabled.
Response Body
application/json
application/json
application/json
application/json
MIT Batch Authorization
Rate limits Please review our rate limits before you begin your implementation. Create multiple MIT (Merchant-Initiated Transaction) authorizations in a single request. Each entry mirrors the single MIT endpoint and is processed asynchronously, supporting partial success across the batch. Each transaction is processed individually, if the transaction passes initial validation then a transaction is created for background processing and a transaction is returned. If the initial validation fails, instead an error is returned. You will receive one callback for each individual transaction. You’ll receive the outcome of each payment on the notificationUrl you provide within the request, making it the primary way to track the result of these payments. Webhooks can be used separately if you need broader, system-wide updates. Use a MIT authorization when the customer has agreed to let the merchant charge them automatically. For example, monthly subscription payments must be handled using MIT. MIT is not suitable when the customer starts the payment themselves, like clicking a “Pay Now” button. For more information about the differences between CIT (Customer-Initiated Transaction) and MIT, see our Core Concepts page. All MIT transactions are processed asynchronously and cannot run in real time. Most are completed within a few seconds, but ePay does not guarantee processing times. Some payment methods, such as Vipps MobilePay, may take several days to complete, depending on the method’s processing rules. When you match the returned transaction results back to your original batch request, the transaction order is preserved from request to response. This means you can always correlate each result to the original request item by using the array index. You can also provide a reference on each transaction in your request. When present, the same reference value is included in the returned result for that transaction, which gives you an explicit way to link results back to your own records. If you choose to rely on reference for correlation, make sure you send transaction.reference for every transaction in the batch. Otherwise, use the array index as the correlation key. If you want to offer your customers the ability to store their cards for faster checkout in the future, you must use CIT transactions. In such cases, you are required to provide a customerId when creating the payment. This ID links the stored card to the customer and enables quick-checkout functionality in future sessions. We recommend a minimum timeout of 10 seconds.
Physical Sale
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.