Skip to main content

Pre-authorization

info

This page is about the new Dojo Pay at Counter Websockets API. If you're unsure which API is best for your integration, contact your Partnership Development Manager (PDM).

Reserve funds using the Pay at Counter API

A pre-authorized payment (or "pre-auth") temporarily reserves funds in a cardholder's account. These funds technically remain in the cardholder's account until "capture", which occurs later and triggers the actual movement of funds. However, between pre-auth creation and capture, the cardholder will be unable to use the pre-authorized funds. These funds have been reserved by the merchant.

Merchants commonly use pre-authorization when they want to guarantee (but not take) payment before delivering goods or services, particularly in situations where the final amount remains uncertain. Examples include opening a tab at a bar, or checking into a hotel that offers in-house paid extras like room service or spa treatments.

Using pre-authorization​

There are four actions associated with pre-authorization:

  • Create: The pre-auth is created, and an initial amount is reserved in the cardholder's account.
  • Update: The authorized amount is increased, so additional funds are reserved in the cardholder's account.
  • Reverse: This is used to cancel, or reverse, a pre-auth before it has been finalized. The hold on all or part of the authorized amount is released and available to the cardholder again.
  • Capture: All or part of the authorized amount is captured, and the movement of funds is initiated as per a typical sale.

CreatePayment​

To set up a pre-authorized payment, you first need to send a CreatePayment request with the captureMode parameter set to MANUAL. This is the first step in the pre-authorization process. It reserves the specified amount in the cardholder's account, ensuring that the funds are available for later capture.

The CreatePayment request's parameters are as follows:

  • paymentId: A unique identifier for the payment. This will be generated by the EPOS. It is recommended that EPOS providers use a UUID.
  • terminalId: This is the terminal you are using to process the pre-authorization.
  • amount: This is the estimated value of the transaction. It's written in ISO-4217 alpha-3 standard minor units.
  • currency: Define currencies using the ISO-4217 standard. For example, Euros are EUR, and British Pounds are GBP.
  • reference: An optional reference which can be set as any string.
  • captureMode: For pre-authorized payments, the captureMode is MANUAL. Conventional, immediate payments (without a hold period) are considered AUTO payments.
    • captureModeOptions: Currently, only AUTO payments can be configured with options.
      • captureModeOptionsAuto: These amounts are written in ISO-4217 standard minor units.
        • cashbackAmount
        • gratuityAmount
      • captureModeOptionsManual: This field is currently unused and should be set to null.

This request example is a pre-auth reserving 25000 units of GBP, which is equal to £250 (British Pounds Sterling):

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "createPayment",
  "params": {
    "amount": 25000,
    "captureMode": "MANUAL",
    "captureModeOptions": {
      "captureModeOptionsManual": null
    },
    "paymentId": "c00157c1-1b41-4a7e-8f01-ff413b23f8f0",
    "terminalId": "01234567",
    "currency": "GBP",
    "reference": "MyPreAuthPayment"
  }
}

UpdatePayment​

You can increase existing pre-auth payments in the time between creation and capture. For example, a corporate party host at a bar might need to reserve more pre-auth funds to meet the needs of their guests.

To accomplish this, you provide the paymentId as a parameter and include the desired new total amount amountTo in minor units.

{
  "id": 2,
  "jsonrpc": "2.0",
  "method": "UpdatePayment",
  "params": {
    "amountTo": 26500,
    "paymentId": "c00157c1-1b41-4a7e-8f01-ff413b23f8f0"
  }
}

ReversePayment​

Reversing a pre-auth means releasing the funds between creation and capture. It reverses the hold on payment, and releases the reserved funds back to the cardholder.

{
  "id": 2,
  "jsonrpc": "2.0",
  "method": "ReversePayment",
  "params": {
    "paymentId": "c00157c1-1b41-4a7e-8f01-ff413b23f8f0"
  }
}

CapturePayment​

The CapturePayment request finalizes the pre-authorization flow. The parameters here include the full amount including any updates, along with the gratuityAmount.

The amount and gratuityAmount combined must not exceed the pre-auth spending limit. If they do, the pre-auth must be updated to include the extra funds. In our example, £265 was pre-authorized in the update for a £260 amount and a £5 gratuityAmount.

{
  "id": 2,
  "jsonrpc": "2.0",
  "method": "capturePayment",
  "params": {
    "amount": 26000,
    "gratuityAmount": 500,
    "paymentId": "c00157c1-1b41-4a7e-8f01-ff413b23f8f0"
  }
}

RecordPayment​

This notification is sent to the EPOS shortly before the paymentTimeoutAt expiry. It includes detailed information about the transaction, including the captured and held amounts, and some high-level details about the customer's card. This notification allows the EPOS system to record and process the payment before the pre-authorization expires.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "RecordPayment",
  "result": {
    "baseCapturedAmount": 26000,
    "baseHeldAmount": 25000,
    "captureMode": "MANUAL",
    "cardPresentPaymentInfo": {
      "authCode": "1121121",
      "entryMode": "ENTRY_MODE_MANUAL_ENTRY",
      "card": {
        "expiryDate": "01/01",
        "fundingType": "CARD_FUNDING_TYPE_CREDIT",
        "last4PAN": "1234",
        "scheme": "VISA"
      },
      "cardholderVerificationMethod": "CARDHOLDER_VERIFICATION_METHOD_PIN",
      "acquirerPaymentId": "365351",
      "terminalId": "0123467"
    },
    "cardPresentPaymentStatus": "CARD_PRESENT_PAYMENT_STATUS_SUCCESSFUL",
    "currency": "GBP",
    "defaultCaptureMode": "MANUAL",
    "expiresAt": "2023-07-07T15:30:00Z",
    "gratuityCapturedAmount": 500,
    "merchantId": "12341234",
    "paymentId": "c00157c1-1b41-4a7e-8f01-ff413b23f8f0",
    "receiptLines": [
      {
        "receiptLineType": "RECEIPT_LINE_TYPE_HORIZONTAL_LINE",
        "receiptHorizontalLine": {
          "type": "HORIZONTAL_LINE_DOUBLE"
        }
      },
      {
        "receiptLineType": "RECEIPT_LINE_TYPE_TEXT",
        "receiptText": {
          "align": "ALIGN_CENTER",
          "size": "SIZE_BODY",
          "value": "Thanks for shopping with us!"
        }
      }
    ],
    "terminalId": "01234567"
  }
}

The baseHeldAmount of 25000 (or £250) was set at the creation stage. This differs from the baseCapturedAmount of 26000 (or £260) because the pre-auth was updated.

The baseCapturedAmount is the spend total. It includes the gratuityCapturedAmount added by an updatePayment request.

Authorization validity​

An authorization is only valid for a specific period of time, and cannot be captured once this validity period has expired. The default validity period is set by the card schemes and cannot be adjusted. The period varies according to the Merchant's Category Code (MCC).

Introduction Return to the introduction page.

API reference Discover the full WebSockets API reference for the Dojo-only PAC API.

Changelog Detailed information on recent changes to the API.

Support Our support team is always happy to help with any questions you have.

Last updated on