Partial Authorization

What is Partial authorization?

Partial authorization offers a solution for handling transactions when there aren't enough funds in the card's balance to approve the full amount. Issuers can approve a portion of the requested sum, leaving the rest to be paid using other means.

Common business scenarios where this may occur

Card product where the available balance is less than the requested amount.

• Example: prepaid card with a balance of $50. Merchant requests authorization for $75. Issuer may either decline the transaction or return a partial authorization where the amount authorized is less than the requested amount, perhaps $50 in this case.

Card product with specific restrictive spending rules.

• Example: substantiated FSA card where a merchant requests authorization for a $75 purchase, and includes IIAS information showing a healthcare subtotal of $50 and an Rx subtotal of $50 - this customer might be purchasing a $50 prescription and $25 non-medical items. The issuer might return a partial authorization for $50 in this use case.

Handling partial authorization

When a partial authorization is returned, the merchant needs to choose how to handle it. Merchant options include:

• Treat the partial authorization as a decline and follow existing declined authorization workflow
• Split tender - get another payment method to be used for the remaining (unauthorized) balance
• Adjust transaction - edit the shopping cart (for example, remove items) to build a new transaction and attempt authorization again

Payment request with partial authorization

Merchants can indicate partial auth, via partialAuthorization flag through /sessions or /payments API(s)

• sessionRequest.payment.partialAuthorization
• paymentRequest.partialAuthorization

Sample /sessions request: partialAuthorization

## /POST sessions request
curl --location --request POST 'https://api.uhg.com/api/financial/commerce/nonprodcheckout/v1/sessions' \
--header 'X-Merchant-Id: <x-merchant-id>' \
--header 'X-Upstream-Env: <x-upstream-env>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <authorization-token>' \
--data-raw '{
    "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
    }
}'

Sample /payments request: partialAuthorization

## /POST payments request
curl --location -g --request POST 'https://api.uhg.com/api/financial/commerce/nonprodcheckout/v1/payments' \
--header 'X-Merchant-Id: <x-merchant-id>' \
--header 'X-Upstream-Env: <x-upstream-env>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <authorization-token>' \
--data-raw '{
    "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

Successful partial auth payment returns response with:

• data.payment.amount: Initial requested amount
• data.payment.authorizedAmount: Amount partially/fully authorized for capture
• data.payment.status: reflects AUTHORZIED status

With a valid authorizedAmount, merchant's can proceed to capture the authorizedAmount

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

API Request would error, if incorrect combination of flags are passed.

• partial auth is applicable only for PRE_AUTH (i.e. authorizeCard=true) payments involving 'card' payment method type.

paymentMethodChannel Type requested in session	paymentMethodChannel Type configured	authorizeCard	partialAuthorization	create session error response	create payment error response
card	card	no	yes	400 BAD_REQUEST	400 BAD_REQUEST
(empty)	card	no	yes	400 BAD_REQUEST	400 BAD_REQUEST

Invalid partial authorization request error: 400 BAD_REQUEST

{
    "title": "INVALID_REQUEST",
    "status": 400,
    "detail": "Partial authorization not allowed for authorizeCard = false",
    "errorDetails": null
}