Payment Features / Authorise & Capture

Authorise

What is an authorisation?

The amount that needs to be paid by the cardholder is in most cases known when a payment is initiation.
In retail for example, the cashier knows the amount when the customer wants to pay. The transaction amount is authorised and automatically captured.

There are other solutions where the amount that needs to be paid is unknown when a payment gets initiated.
An amount gets authorised from the beginning and later in time the amount is known and the transactions will be finished with a capture.

Basically, the authorisation reserves some money on a bank account and the capture finished the transaction.

Use cases

EV Charging - The battery of an electric car is almost empty and the owner wants to charge the battery.
At a public charging point, the owner starts a charging session. The charging stations needs to be sure that the cardholder will pay for the charging session.
There is an authorisation with the max. amount for a charging session.
When the sessions is stopped by the card holder, the amount that needs to be charged is known and the transaction is finalised with a capture.

Make an authorisation request

The api-method to achieve this is the HTTP.POST with url /terminal/payment

Request headers

• Content-Type: application/json

Request parameters

Example authorisation request

{
  "paymentType": "AUTHORISE",
  "requestId": "123456",
  "amount": 50.00,
  "currency": "EUR",
  "minimumCaptureAmount": 1.00,
  "tokenType": "CARD",
  "terminalOperatingEnvironment": "UNATTENDED",
  "terminalAccessProtocol": "OPI_NL",
  "terminalLanguage": "ENG",
  "terminalEnvironment": "EVCHARGING"
}

Response parameters

Example authorisation response

{
  "status": "SUCCESS",
  "authReference": "H4sIAAAAAAAAA6tWcs7PLchJLUlNCShKdSwt",
  "authReferenceVersion": "1",
  "token": "993525316521889183",
  "journalReceipt": "[ \"Kopie Merchant\", \"\", \"******* PAS OP: TEST SYSTEEM *******\", "..."]",
  "eJournal": "<?xml version=\"1.0\"?>\n<E-Journal>\n...</E-Journal>"
}

Here is a more detailed description what you should do with the response values.

authReference and authRefenreceVersion
The authorisationReferense is necessary to make a capture. Both the reference and the version needs to be passed through to the terminal with the capture request.

token
If you set the tokenType in the request to ‘CARD’, there will be a token in the response. You can store this token in your own database and use it later.

Accept a Mifare card

If your solution also supports closed loop payment like membership cards, you can accept Mifare Cards as well.

Extra parameter for the Authorisation request

Example authorisation request

{
  "paymentType": "AUTHORISE",
  "amount": 50.00,
  "currency": "EUR",
  "minimumCaptureAmount": 1.00,
  "tokenType": "CARD",
  "terminalOperatingEnvironment": "UNATTENDED",
  "terminalAccessProtocol": "OPI_NL",
  "terminalLanguage": "ENG",
  "terminalEnvironment": "EVCHARGING",
  "supportMifareCards" : true
}

If the cardholder presents a Mifare card instead of a bank card. The response will contain a mifareCardUid.
Response parameters

Example authorisation response

{
  "status": "SUCCESS",
  "authReference": "H4sIAAAAAAAAA6tWcs7PLchJLUlNCShKdSwt",
  "authReferenceVersion": "1",
  "token": "993525316521889183",
  "journalReceipt": "[ \"Kopie Merchant\", \"\", \"******* PAS OP: TEST SYSTEEM *******\", "..."]",
  "eJournal": "<?xml version=\"1.0\"?>\n<E-Journal>\n...</E-Journal>",
  "mifareCardUid" : "1111222233334444"
}

Followup manuals

• Capture