Partial Authorization

Partial authorization allows a payment to be partially approved for a lesser amount than requested, typically when the card balance is insufficient. Merchants can choose how to handle such scenarios.

Quick Reference

• Partial Authorization: Approves less than the requested amount if full funds are not available.
• API Endpoints:
  • POST v1/sessions — Initiate a session with partial authorization flag
  • POST v1/payments — Initiate a payment with partial authorization flag
• API Scopes: user merchant merchant-pci
• Allowed Session Modes: PAYMENT , PAYMENT_WITH_WALLET
• Supported Payment Method: CARD
• Key Fields:
  • partialAuthorization, authorizeCard, amount, authorizedAmount, status
• Common Statuses: AUTHORIZED, COMPLETED, FAILED
• Error Codes: See Payment Error Codes

Handling Partial Authorization

When a partial authorization is returned, merchants can:

• Treat it as a decline and follow the declined workflow
• Use split tender (request another payment method for the remaining balance)
• Adjust the transaction (e.g., remove items and retry)

Payment Request with Partial Authorization

To enable partial authorization, set the partialAuthorization flag in the /sessions or /payments API request.

/sessions Request Example

Sample /sessions request with partialAuthorization

{
  "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,
    "partialAuthorization": true
  }
}

/payments Request Example

Sample /payments request with partialAuthorization

{
  "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,
  "partialAuthorization": true,
  "paymentMethodId": ""
}

Payment Response with Partial Authorization

A successful partial authorization returns:

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

Sample /sessions response: partially 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": "",
      "partialAuthorization": true,
      "metadata": {},
      "paymentMethod": {},
      "agent": {}
    }
  }
}

Sample /payments response: partially 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": "",
    "partialAuthorization": true,
    "metadata": {},
    "paymentMethod": {}
  }
}

Error Handling

See Payment Error Codes