API Endpoints
This page contains an explanation of our API endpoints. Please refer to our API reference for more information on each endpoint. For production, you may simply remove the .sandbox
part of the URLs.
basicAuth credentials & TLS 1.2
Your
basicAuth
settings can be found in yourmerchantId
configuration within the tabsecurity
. Depending on your account setup, you may need to send your calls to a differentmerchantId
depending on which API endpoint you are trying to call. Usually onemerchantId
is dedicated to customer-initiated transactions and another to merchant-initiated transactions.Please make sure to always use TLS version 1.2 when interacting with our endpoints.
API Endpoint | URL |
---|---|
Redirect URL | https://pay.sandbox.datatrans.com/v1/start/{{transactionId}} |
init | https://api.sandbox.datatrans.com/v1/transactions |
secureFieldsInit | https://api.sandbox.datatrans.com/v1/transactions/secureFields |
authorize | https://api.sandbox.datatrans.com/v1/transactions/authorize |
authorize-split | https://api.sandbox.datatrans.com/v1/transactions/{{transactionId}}/authorize |
validate | https://api.sandbox.datatrans.com/v1/transactions/validate |
settle | https://api.sandbox.datatrans.com/v1/transactions/{{transactionId}}/settle |
cancel | https://api.sandbox.datatrans.com/v1/transactions/{{transactionId}}/cancel |
refund | https://api.sandbox.datatrans.com/v1/transactions/{{transactionId}}/credit |
status | https://api.sandbox.datatrans.com/v1/transactions/{{transactionId}} |
health-check | https://api.sandbox.datatrans.com/upp/check |
Idempotency
To retry identical requests with the same effect without accidentally performing the same operation more than needed, you can add the header Idempotency-Key
to your requests. This is useful when API calls are disrupted or you did not receive a response. In other words, retrying identical requests with our idempotency key will not have any side effects. We will return the same response for any identical request that includes the same idempotency key.
If your request failed to reach our servers, no idempotent result is saved because no API endpoint processed your request. In such cases, you can simply retry your operation safely. Idempotency keys remain stored for 60 minutes. After 60 minutes have passed, sending the same request together with the previous idempotency key will create a new operation.
Please note that the idempotency key has to be unique for each request and has to be defined by yourself. We recommend assigning a random value as your idempotency key and using UUID v4. Idempotency is only available for POST
requests.
Scenario | Condition | Expectation |
---|---|---|
First time request | Idempotency key has not been seen during the past 60 minutes. | The request is processed normally. |
Repeated request | The request was retried after the first time request completed. | The response from the first time request will be returned. |
Repeated request | The request was retried before the first time request completed. | 409 Conflict. It is recommended that clients time their retries using an exponential backoff algorithm. |
Repeated request | The request body is different than the one from the first time request. | 422 Unprocessable Entity. |
curl 'https://api.sandbox.datatrans.com/v1/transactions/authorize' \
--header 'Authorization: Basic {basicAuth}' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: {idempotencyKey}' \
--data-raw '{
"currency" : "CHF",
"refno" : "Test-1234",
"amount" : 1000
}'
init
To use either the Redirect or Lightbox integration, you will need to initialize a transaction first. Call our init endpoint with your desired parameters and we'll return a transactionId
ready to be used with our Redirect or Lightbox. Please note that a transactionId
is only valid for 30 minutes. More information on the Redirect & Lightbox integration can be found here.
curl 'https://api.sandbox.datatrans.com/v1/transactions' \
--header 'Authorization: Basic {basicAuth}' \
--header 'Content-Type: application/json' \
--data-raw '{
"currency": "CHF",
"refno": "Test-1234",
"amount": 1000,
"paymentMethods": ["VIS","ECA","PAP,"TWI"],
"autoSettle": true,
"option": {
"createAlias": true
},
"redirect": {
"successUrl": "{successUrl}",
"cancelUrl": "{cancelUrl}",
"errorUrl": "{errorUrl}"
},
"theme": {
"name": "DT2015",
"configuration": {
"brandColor": "#FFFFFF",
"logoBorderColor": "#A1A1A1",
"brandButton": "#A1A1A1",
"payButtonTextColor": "#FFFFFF",
"logoSrc": "{svg}",
"logoType": "circle",
"initialView": "list",
}
}
}
{
"transactionId": "{transactionId}"
"3D": {
"enrolled": true
}
}
secureFieldsInit
To create a payment with Secure Fields, you will need to initialize a transactionId
. Call our secureFieldsInit endpoint with your desired parameters and we'll return a transaction identifier ready to be used with our Secure Fields. The parameter returnUrl
specifies where the browser should be redirected to after a 3D Secure authentication. Please note that a transactionId
is only valid for 30 minutes. If you wish to do a dedicated registration, you must omit the parameter amount
. Please read our section saving payment information for more details. More information on the Secure Fields integration can be found here.
curl 'https://api.sandbox.datatrans.com/v1/transactions/secureFields' \
--header 'Authorization: Basic {basicAuth}' \
--header 'Content-Type: application/json' \
--data-raw '{
"currency": "CHF",
"amount": 100,
"returnUrl": "{returnUrl}"
}'
{
"transactionId": "{transactionId}"
}
authorize
The API endpoint authorize can be called to do merchant initiated transactions. If you wish to do merchant initiated transactions, you will first have to save your customers' payment details with a customer-initiated transaction. Please read our section saving payment information for more details. More information on merchant initiated payments can be found here.
curl 'https://api.sandbox.datatrans.com/v1/transactions/authorize' \
--header 'Authorization: Basic {basicAuth}' \
--header 'Content-Type: application/json' \
--data-raw '{
"currency": "CHF",
"refno": "Test-1234",
"amount": 100,
"card": {
"alias": "424242SKMPRI42423",
"expiryMonth": 12,
"expiryYear": 21
},
"autoSettle": false
}'
{
"transactionId": "{transactionId}",
"acquirerAuthorizationCode": "172105",
"card": {
"masked": "424242xxxxxx4242"
}
}
authorize-split
The API endpoint authorize-split can be used to authorize a previously authenticated transaction. This request type is required for Secure Fields transactions. More information on the Secure Fields integration can be found here.
curl 'https://api.sandbox.datatrans.com/v1/transactions/{transactionId}/authorize' \
--header 'Authorization: Basic {basicAuth}' \
--header 'Content-Type: application/json' \
--data-raw '{
"refno": "Test-1234",
"amount": 100,
"autoSettle": true
}'
{
"acquirerAuthorizationCode": "172115"
}
validate
The API endpoint validate can be used to validate an existing alias at any time. No amount will be blocked on the customers account. Only credit cards, Apple Pay, Google Pay, PostFinance Card, Klarna and PayPal support validation of an existing alias.
curl 'https://api.sandbox.datatrans.com/v1/transactions/validate' \
--header 'Authorization: Basic {basicAuth}' \
--header 'Content-Type: application/json' \
--data-raw '{
"refno": "Test-1234",
"card": {
"alias": "{cardAlias}",
"expiryMonth": "12",
"expiryYear": "21"
}
}'
{
"transactionId": "{transactionId}",
"acquirerAuthorizationCode": "172052",
"card": {
"masked": "424242xxxxxx4242"
}
}
settle
The API endpoint settle can be used to settle an authorized transaction. More information on Deferred Settlements can be found here.
curl 'https://api.sandbox.datatrans.com/v1/transactions/{transactionId}/settle' \
--header 'Authorization: Basic {basicAuth}' \
--header 'Content-Type: application/json' \
--data-raw '{
"currency": "CHF",
"amount": 100,
"refno": "Test-1234-settled"
}'
We respond with an HTTP status 204 if the transaction was successfully settled.
cancel
The API endpoint cancel can be used to cancel an authorized transaction.
curl 'https://api.sandbox.datatrans.com/v1/transactions/{transactionId}/cancel' \
--header 'Authorization: Basic {basicAuth}' \
--header 'Content-Type: application/json' \
--data-raw '{
"refno": "Test-1234-cancelled"
}'
We respond with an HTTP status 204 if the transaction was successfully canceled.
refund
The API endpoint refund can be used to refund a transaction. Refund requests create a new transactionId
.
curl 'https://api.sandbox.datatrans.com/v1/transactions/{transactionId}/credit' \
--header 'Authorization: Basic {basicAuth}' \
--header 'Content-Type: application/json' \
--data-raw '{
"amount": 100,
"currency": "CHF",
"refno": "Test-1234-credit"
}'
{
"transactionId": "{transactionId}",
"acquirerAuthorizationCode": "172051"
}
status
The API endpoint status can be used to check the status of any transaction, see its history, and retrieve the card information.
curl 'https://api.sandbox.datatrans.com/v1/transactions/{transactionId}' \
--header 'Authorization: Basic {basicAuth}' \
--header 'Content-Type: application/json'
{
"transactionId": "{transactionId}",
"type": "payment",
"status": "authorized",
"currency": "CHF",
"refno": "Yhhnse53e",
"paymentMethod": "VIS",
"detail": {
"authorize": {
"amount": 1000,
"acquirerAuthorizationCode": "172053"
}
},
"receiptUrl": "{receiptUrl}",
"card": {
"masked": "424242xxxxxx4242",
"expiryMonth": "12",
"expiryYear": "21",
"info": {
"brand": "VISA CREDIT",
"type": "credit",
"usage": "consumer",
"country": "GB",
"issuer": "DATATRANS"
}
},
"history": [
{
"action": "authorize",
"amount": 1000,
"source": "api",
"date": "YYYY-MM-DDT15:20:53Z",
"success": true,
"ip": "{{ip}}"
},
{
"action": "settle",
"amount": 1000,
"source": "api",
"date": "YYYY-MM-DDT07:54:01Z",
"success": true,
"ip": "{{ip}}"
}
]
}
health-check
health-check returns the status of our payment platform. Please bear in mind that third-party systems are not included in this check. If our platform is operational we will return a status 200 and the string ok
.
curl 'https://api.sandbox.datatrans.com/upp/check'
Updated 8 months ago