Partial Authorization Service (PAS) - Hosted Checkout
Partial authorization allows a transaction to be split across multiple card payments when a single card does not have sufficient funds to cover the full amount. When a card is partially authorized, Checkout will collect the approved portion and then prompt the customer to pay the remaining balance with another card.
As a merchant, you integrate with Checkout V2 using the paysafe.checkout.setup() SDK call. The partial authorization flow is an extension of your existing result callback — no additional callbacks are required.
How It Works
-
The customer completes a card payment in Checkout.
-
Your backend processes the payment handle and receives a partial authorization response.
-
You call instance.showPartialAuthScreen() to prompt the customer to pay the remaining balance.
-
The result callback fires again for the next card payment. Repeat until fully paid.
-
Once fully paid, call instance.showSuccessScreen().
Integration
paysafe.checkout.setup(
API_KEY,
options,
function (instance, error, result) { // result callback
if (error) {
// Handle errors — see Error Handling section below
instance?.showFailureScreen('An error occurred during payment.');
return;
}
processPayment(result).then((response) => {
if (response?.partialAuth?.processedAsPartialAuth) {
// Card was partially authorized — collect the remaining amount
instance?.showPartialAuthScreen({
merchantRefNum: 'unique-ref-for-next-payment',
partialAuth: {
amount: response.partialAuth.approvedAmount, // amount approved, in minor units
groupId: response.partialAuth.groupId // returned by Paysafe Payments API
}
});
} else {
// Transaction fully authorized
instance.showSuccessScreen();
}
});
},
function (stage, expired) {
// Handle close callback
},
function (instance, amount, paymentMethod) {
// Handle risk callback
}
);
The result callback is invoked once for each partial authorization attempt, not just the first. Your processing logic should handle multiple invocations.
Handling user cancellation during partial authorization
If the customer cancels after at least one partial authorization has already been captured, error code 9152 is returned. At this point, you must roll back any already processed partial payments on your backend.
if (error) {
if (error.code === 9152) {
const completedPartialAuths = instance.getPartialAuths();
if (completedPartialAuths.length > 0) {
// Roll back all previously captured partial authorizations
rollbackProcessedPayments(completedPartialAuths).then(() => {
instance?.showFailureScreen('Your payment could not be completed.');
});
return;
}
}
instance?.showFailureScreen('An error occurred during payment.');
}
Result callback parameters
The result object is passed to your callback on each successful payment handle creation.
| Parameter | Type | Description |
|---|---|---|
result.paymentHandleToken | string | The payment handle token to include in your Payments API call. |
result.paymentMethod | string | The payment method used (e.g., CARD). |
result.amount | number | The amount used to create this payment handle, in minor units. |
result.customerOperation | string | Customer operation for the card: ADD, EDIT, or DELETE. |
error | object | Present when payment handle creation fails. Contains code and message. |
Instance methods
showPartialAuthScreen(params)
Call this when your backend confirms the payment was partially authorized. Opens a screen in Checkout for the customer to pay the remaining amount with another card.
Parameters:
| Field | Type | Required | Description |
|---|---|---|---|
merchantRefNum | string | Yes | A unique reference number for the next payment handle. |
partialAuth.amount | number | Yes | The amount approved in this partial authorization, in minor units. |
partialAuth.groupId | string | Yes | The group ID returned by the Paysafe Payments API for this partial auth. Links all partial payments in the transaction together. |
Example
instance.showPartialAuthScreen({
merchantRefNum: 'order-001-attempt-2',
partialAuth: {
amount: 700,
groupId: 'fef0304b-21de-411a-97f5-058e18b1cf75'
}
});
If the screen cannot be shown (e.g., due to validation failure), your result callback will be invoked with an error instead.
getPartialAuths()
Returns an array of all partial authorization attempts that have been completed in the current session. Use this to determine how many partial payments have been captured and to roll them back if needed.
Returns
[
{
"attempt": 1,
"amount": 700,
"merchantRefNum": "order-001-attempt-1",
"paymentHandle": "PHY6iBujO9l8NZ38",
"groupId": "fef0304b-21de-411a-97f5-058e18b1cf75",
"paymentMethod": "CARD"
},
{
"attempt": 2,
"amount": 300,
"merchantRefNum": "order-001-attempt-2",
"paymentHandle": "PHY6iBujO9l8NZ39",
"groupId": "fef0304b-21de-411a-97f5-058e18b1cf75",
"paymentMethod": "CARD"
}
]
| Field | Description |
|---|---|
attempt | Attempt number, starting at 1. |
amount | Amount authorized in this partial payment, in minor units. |
merchantRefNum | The merchant reference used for this payment handle. |
paymentHandle | The payment handle token. Pass this to your Payments API call. |
groupId | The group ID linking all partial payments in this transaction. |
paymentMethod | The payment method used (currently always CARD). |
showFailureScreen
Displays a failure screen to the customer inside Checkout.
| Parameter | Type | Required | Description |
|---|---|---|---|
message | string | No | A message displayed to the customer beneath the failure title. |
Code example
instance.showFailureScreen(); // Generic failure screen
instance.showFailureScreen('Your payment could not be completed.');
Error reference
| Code | Display Message | When It Occurs |
|---|---|---|
9152 | The user aborted partial authorization. | The customer clicked Cancel or closed the partial authorization screen. Check getPartialAuths().length to determine if any payments were already captured and need to be reversed. |
Complete flow (code example)
paysafe.checkout.setup(
API_KEY,
options,
function (instance, error, result) {
// --- Error handling ---
if (error) {
if (error.code === 9152) {
const completedPartialAuths = instance.getPartialAuths();
if (completedPartialAuths.length > 0) {
rollbackProcessedPayments(completedPartialAuths).then(() => {
instance?.showFailureScreen('Your payment could not be completed.');
});
return;
}
}
instance?.showFailureScreen('An error occurred during payment.');
return;
}
// --- Process payment handle ---
processPayment(result).then((response) => {
if (response?.partialAuth?.processedAsPartialAuth) {
// Partial payment — ask customer to pay the remainder
instance?.showPartialAuthScreen({
merchantRefNum: generateUniqueRefNum(),
partialAuth: {
amount: response.partialAuth.approvedAmount,
groupId: response.partialAuth.groupId
}
});
} else {
// Fully paid
instance.showSuccessScreen();
}
});
},
function (stage, expired) {
// Handle close callback
},
function (instance, amount, paymentMethod) {
// Handle risk callback
}
);
Integration checklist
-
After calling your Payments API, check response.partialAuth.processedAsPartialAuth.
-
Call instance.showPartialAuthScreen() with a new merchantRefNum, the approved amount, and the groupId from the Payments API response.
-
Handle error code 9152 and use instance.getPartialAuths() to check if partial payments need to be reversed.
-
Always roll back any captured partial authorizations on your backend before showing the failure screen.
-
Call instance.showSuccessScreen() only when the full amount has been collected.