Pre Authorization

Pre authorization allows a payment to be temporarily approved for a lesser amount than requested, typically when the card balance is insufficient. This process places a hold on the customer's account for the authorized amount, but does not immediately transfer funds to the merchant.

Quick Reference

• Pre Authorization: Temporarily places a hold on the customer's account for the pre-authorized amount, but does not immediately transfer funds to the merchant.
• API Endpoints:
  • POST v1/sessions — Initiate a session with Pre authorization flag
  • POST v1/payments — Initiate a payment with Pre authorization flag
• API Scopes: user, merchant, merchant-pci
• Allowed Session Modes: PAYMENT, PAYMENT_WITH_WALLET
• Supported Payment Method: CARD
• Key Fields: authorizeCard, amount, authorizedAmount, status
• Common Statuses: AUTHORIZED, COMPLETED, FAILED, CANCELLED
• Error Codes: See Payment Error Codes

Handling Pre Authorization

• When a pre authorization is successful, merchants can:
  • Capture the payment within 7 days
  • Cancel the payment if needed
• If the capture is not performed within the hold period, the authorization will expire and the hold will be released automatically.

Payment Request with Pre Authorization

To enable pre authorization, set the authorizeCard flag to true in the /sessions or /payments API request.

/sessions Request Example

Sample /sessions request with PreAuthorization

{
  "customer": {
    "firstName": "foo",
    "lastName": "bar",
    "email": "foo.bar@email.com",
    "ssnLastFour": "1234",
    "dateOfBirth": "1970-31-12",
    "phoneNumber": {
      "number": "9876543210",
      "countryCode": "1"
    },
    "zip5": "54321",
    "hsid": "120c5730-e796-4448-8da9-081fde4e3e79",
    "metadata": {}
  },
  "payment": {
    "merchantTransactionId": "f32736c8-266a-4da1-af16-293fa02a351a",
    "amount": 1200,
    "authorizeCard": true
  }
}

/payments Request Example

Sample /payments request with PreAuthorization

{
  "customer": {
    "firstName": "foo",
    "lastName": "bar",
    "email": "foo.bar@email.com",
    "ssnLastFour": "1234",
    "dateOfBirth": "1970-31-12",
    "phoneNumber": {
      "number": "9876543210",
      "countryCode": "1"
    },
    "zip5": "54321",
    "hsid": "120c5730-e796-4448-8da9-081fde4e3e79",
    "metadata": {}
  },
  "merchantTransactionId": "f32736c8-266a-4da1-af16-293fa02a351a",
  "amount": 1200,
  "authorizeCard": true,
  "paymentMethodId": ""
}

Payment Response with Pre Authorization

A successful pre authorization returns:

• amount: Initial requested amount
• authorizedAmount: Amount partially/fully authorized
• status: AUTHORIZED

Sample /sessions response: Pre-authorized payment

{
  "data": {
    "sessionId": "",
    "status": "COMPLETED",
    "payment": {
      "id": "",
      "amount": 183,
      "authorizedAmount": 128,
      "capturedAmount": 0,
      "description": "",
      "merchantTransactionId": "",
      "merchantId": "",
      "paymentType": "PRE_AUTH",
      "currencyCode": "usd",
      "status": "AUTHORIZED",
      "paymentMethodId": "",
      "statementDescriptorSuffix": "",
      "authorizeCard": true,
      "metadata": {},
      "paymentMethod": {},
      "agent": {}
    }
  }
}

Sample /payments response: Pre-authorized payment

{
  "data": {
    "id": "95bec1ab-9762-4fe7-a4cd-fcf92b20d5c5",
    "amount": 183,
    "authorizedAmount": 128,
    "capturedAmount": 0,
    "description": "",
    "merchantTransactionId": "",
    "merchantId": "",
    "paymentType": "PRE_AUTH",
    "currencyCode": "usd",
    "status": "AUTHORIZED",
    "customerId": "",
    "vendor": "",
    "vendorPaymentId": "",
    "vendorMerchantId": "",
    "statementDescriptorSuffix": "",
    "authorizeCard": true,
    "metadata": {},
    "paymentMethod": {}
  }
}

Pre Authorization Statuses

Status	Description
AUTHORIZED	The pre-authorization hold is placed successfully
COMPLETED	The payment has been captured
FAILED	The pre-authorization failed
CANCELLED	The pre-authorization was cancelled

Error Handling

See Payment Error Codes