Authorize/Settle

Using this API allows you to simply send a json request with a token to just reserve (authorize) or charge (settle) an amount.

Reserve an amount
Charge cardholder

When you reserve an amount on a stored card, the monthly allowance of the cardholder is reduced by the authorised amount, no matter whether the transaction will be settled later or not. The authorised amount is reserved for the merchant and should be settled within the period agreed with the acquirer. The issuer returns an authorisation code which serves as the reference of the authorisation. Once a transaction has been successfully authorised it can be settled.

Important: the cardholder will not be charged without settlement. Authorisation and settlement can also be processed in one single step. Please continue here with deferred settlement API if you just authorized the transaction.

When you charge a stored card, the authorization and settlement will be processed in one single step. The settlement is often also referred to as “capture” or “clearing”. Once you sent a charge request, the authorized amount is reduced from the monthly allowance of the cardholder and will be automatically settled, which means that the cardholder will be actually charged.

Stored cards can be used multiple times for recurring transactions or One-Click payments.

1. Add acquirer to your account

For this feature, you need an existing acquiring contract.

You can choose from a list of Supported Acquirer and contact us at setup@pci-proxy.com

2. Authorize a stored card

The service requires HTTP basic authentication. The required credentials can be found in our dashboard. Please refer to API authentication data for more information.

post
AUTH method

https://api.sandbox.datatrans.com/v1/transactions/authorize
Request
Response
Headers
Authentication
required
string
Basic MTEwMDAwNzAwNjpLNnFYMXUkIQ== see Setup
Content-Type
required
string
application/json; charset=UTF-8
Body Parameters
currency
required
string
3 letter ISO-4217 character code. E.g. EUR or USD
refno
required
string
Your unique reference number (AN 1..20)
amount
required
integer
The amount of the transaction in the currency's smallest unit. For example use 1000 for EUR 10.00.
autoSettle
optional
boolean
Wheter to automatically settle the transaction after an authorization or not. Default is false.
card
required
object
Card object must contain following parameters below
alias
required
string
Token received from a previous PCI Proxy integration
expiryMonth
required
string
The expiry month of the token (2 characters)
expiryYear
required
string
The expiry year of the token (2 characters)
3D
optional
object
If 3D authentication data is available, the 3D object can be used to send the relevant 3D paramters.
200: OK
Successful authorization response
{
"transactionId": "191023102544373504",
"acquirerAuthorizationCode": "102544",
"card": {
"masked": "424242xxxxxx4242"
}
}
400: Bad Request
Failed authorization response
{
"error": {
"code": "see table below for detailed error messages",
"message": "see table below for detailed error messages"
},
"transactionId": "191023112022175523"
}

In test mode, only test credit cards are allowed.

Examples

Reserve amount (authorize)
Charge amount (auth+settle)
Request
curl -X POST \
https://api.sandbox.datatrans.com/v1/transactions/authorize \
-H 'Authorization: Basic MTAwMDAwMTExMTpwWUU4bFE2TlBiM2thRXpR' \
-H 'Content-Type: application/json; charset=UTF-8' \
-d '{
"currency": "EUR",
"refno": "vptJ07xyr",
"amount": 1000,
"card": {
"alias": "424242SKMPRI4242",
"expiryMonth": "12",
"expiryYear": "21"
}
}
Response (successful)
{
"transactionId": "191023111742635093",
"acquirerAuthorizationCode": "111742",
"card": {
"masked": "490000xxxxxx0086"
}
}
Charge
curl -X POST \
https://api.sandbox.datatrans.com/v1/transactions/authorize \
-H 'Authorization: Basic MTAwMDAwMTExMTpwWUU4bFE2TlBiM2thRXpR' \
-H 'Content-Type: application/json; charset=UTF-8' \
-d '{
"currency": "EUR",
"refno": "vptJ07xyr",
"amount": 1000,
"autoSettle": "true",
"card": {
"alias": "424242SKMPRI4242",
"expiryMonth": "12",
"expiryYear": "21"
}
}
Response (successful)
{
"transactionId": "191023113146339569",
"acquirerAuthorizationCode": "113146",
"card": {
"masked": "424242xxxxxx4242"
}
}

Error table

If the authorisation failed, you receive one of the of the following error codes.

"UNKNOWN_ERROR", "UNRECOGNIZED_PROPERTY", "INVALID_PROPERTY", "INVALID_TRANSACTION_STATUS", "TRANSACTION_NOT_FOUND", "INVALID_JSON_PAYLOAD", "UNAUTHORIZED", "EXPIRED_CARD", "INVALID_CARD", "UNSUPPORTED_CARD", "DUPLICATED_REFNO", "DECLINED", "BLOCKED_BY_VELOCITY_CHECKER", "CLIENT_ERROR" , "SERVER_ERROR"