# Authorize a payment

A payment authorization is the process of requesting the card scheme to verify the payment details. If authorization is successful, funds are reserved so that you can capture the payment at a later date.

You can perform the following types of authorization:

| Authorization type | Description |
| --- | --- |
| Final | The authorization amount will not change before the payment is captured. |
| Estimated | The authorization amount is an estimate. It may change through future incremental authorizations before it is captured. |
| Incremental | This always follows an estimated authorization and does one of the following:<br><br>- Increases the authorization amount – For Visa globally, and American Express in the United States (US)<br>- Extends the authorization validity period and authorization amount – For Mastercard cards globally<br>- Extends the authorization validity period – For Mada cards only |
| Partial | This captures part of the authorization amount if the cardholder has insufficient funds to cover the full amount. |

---

## Request a final authorization

By default, all payment requests processed by Checkout.com are treated as final authorizations.

To explicitly request a final authorization, provide `"authorization_type": "Final"` in your [payment request](https://api-reference.checkout.com/tag/Payments/#operation/requestAPaymentOrPayout).

You can also specify whether you want to automatically capture the full amount using the `capture` field.

For partial captures, you must [capture the payment manually](https://www.checkout.com/docs/payments/manage-payments/capture-a-payment.md#Manually_capture_a_payment).

> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Production**

`POST` `https://{prefix}.api.checkout.com/payments`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payments`

### Request example

```json
{
  "source": {
    "type": "card",
    "number": "4242424242424242",
    "expiry_month": 12,
    "expiry_year": 2025
  },
  "amount": 100,
  "currency": "USD",
  "reference": "ORD-752-814",
  "authorization_type": "Final",
  "processing_channel_id": "pc_q4dbxom5jbgudnjzjpz7j2z6uq",
  "capture": false
}
```

### Response example

```json
{
  "id": "pay_tqgk5c6k2nnexagtcuom5ktlua",
  "action_id": "act_tqgk5c6k2nnexagtcuom5ktlua",
  "amount": 100,
  "currency": "USD",
  "approved": true,
  "status": "Authorized",
  "auth_code": "503198",
  "expires_on": "2024-04-05T10:11:12Z",
  "eci": "05",
  "scheme_id": "511129554406717",
  "response_code": "10000",
  "response_summary": "Approved",
  "balances": {
    "total_authorized": 100,
    "total_voided": 0,
    "available_to_void": 100,
    "total_captured": 0,
    "available_to_capture": 100,
    "total_refunded": 0,
    "available_to_refund": 0
  },
  "risk": {
    "flagged": false
  },
  "source": {
    "id": "src_il5ncjpijceulefzbhkm2c3di4",
    "type": "card",
    "expiry_month": 12,
    "expiry_year": 2025,
    "scheme": "Visa",
    "last4": "4242",
    "fingerprint": "71580B426F1D190D29087FF265D8F48DF1AD34EDE41C27CBFF9D23C1A14D1776",
    "bin": "424242",
    "card_type": "CREDIT",
    "card_category": "CONSUMER",
    "issuer": "Test Bank",
    "issuer_country": "US",
    "product_id": "A",
    "product_type": "Visa Traditional",
    "avs_check": "S",
    "cvv_check": "Y"
  },
  "customer": {
    "id": "cus_sozpnpktte5uzooigxau35uloq"
  },
  "processed_on": "2024-03-16T22:11:24Z",
  "reference": "ORD-752-814",
  "processing": {
    "acquirer_transaction_id": "8367314942",
    "retrieval_reference_number": "162588399162"
  },
  "_links": {
    "self": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_tqgk5c6k2nnexagtcuom5ktlua"
    },
    "actions": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_tqgk5c6k2nnexagtcuom5ktlua/actions"
    },
    "authorize": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_tqgk5c6k2nnexagtcuom5ktlua/authorizations"
    },
    "capture": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_tqgk5c6k2nnexagtcuom5ktlua/captures"
    },
    "void": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_tqgk5c6k2nnexagtcuom5ktlua/voids"
    }
  }
}
```

The [`balances` object](https://api-reference.checkout.com/tag/Payments/#operation/getPaymentDetails) returned in the response provides an overview of the payment’s balances, as well as the amounts that are available for subsequent payment actions.

---

## Request an estimated authorization

If you do not know the final amount for a transaction when you request a payment, you can request an estimated authorization.

For example, a car rental agency estimates an authorization amount that includes the rental fee, taxes, and mileage rates. However, when the vehicle is returned, the agency needs to increase the authorization amount due to additional fees.

- Visa and Mastercard (globally), and American Express (in the US) support estimated authorizations for all [merchant category codes (MCCs)](https://www.checkout.com/docs/developer-resources/codes/merchant-category-codes.md).
- Mada cards support estimated authorizations for the following MCCs:
  - 3300 - 3499 – Car Rental
  - 3500 - 3999 – Hotels
  - 4121 – Taxicabs and Limousines
  - 4215 – Courier Services - Air or Ground, Freight forwarders
  - 4411 – Steamship and Cruise Lines
  - 4789 – Transportation Services
  - 5411 – Grocery Stores, Supermarkets
  - 5812 – Eating places and Restaurants
  - 5814 – Fast Food Restaurants
  - 7011 – Lodging - Hotels - Not Listed Elsewhere
  - 7394 – Equipment, Tool, Furniture, and Appliance Rental
  - 7512 – Car Rental Companies - Not Listed Elsewhere
  - 7519 – Motor Home and Recreational Vehicle Rentals
  - 7523 – Automobile Parking Lots and Garages
  - 7999 – Recreation Services

> **Information**
>
> Mastercard refers to estimated authorizations as 'preauthorizations'.

> **Information**
>
> Automatic payment capture is automatically disabled for estimated authorizations.

To perform an estimated authorization, provide `"authorization_type": "Estimated"` in your payment request.

> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Production**

`POST` `https://{prefix}.api.checkout.com/payments`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payments`

### Request example

```json
{
  "source": {
    "type": "card",
    "number": "4242424242424242",
    "expiry_month": 12,
    "expiry_year": 2025
  },
  "amount": 100,
  "currency": "USD",
  "reference": "ORD-752-814",
  "authorization_type": "Estimated",
  "processing_channel_id": "pc_q4dbxom5jbgudnjzjpz7j2z6uq",
  "capture": false
}
```

### Response example

```json
{
  "id": "pay_tqgk5c6k2nnexagtcuom5ktlua",
  "action_id": "act_tqgk5c6k2nnexagtcuom5ktlua",
  "amount": 100,
  "currency": "USD",
  "approved": true,
  "status": "Authorized",
  "auth_code": "503198",
  "expires_on": "2024-04-05T10:11:12Z",
  "eci": "05",
  "scheme_id": "511129554406717",
  "response_code": "10000",
  "response_summary": "Approved",
  "balances": {
    "total_authorized": 100,
    "total_voided": 0,
    "available_to_void": 100,
    "total_captured": 0,
    "available_to_capture": 100,
    "total_refunded": 0,
    "available_to_refund": 0
  },
  "risk": {
    "flagged": false
  },
  "source": {
    "id": "src_il5ncjpijceulefzbhkm2c3di4",
    "type": "card",
    "expiry_month": 12,
    "expiry_year": 2025,
    "scheme": "Visa",
    "last4": "4242",
    "fingerprint": "71580B426F1D190D29087FF265D8F48DF1AD34EDE41C27CBFF9D23C1A14D1776",
    "bin": "424242",
    "card_type": "CREDIT",
    "card_category": "CONSUMER",
    "issuer": "Test Bank",
    "issuer_country": "US",
    "product_id": "A",
    "product_type": "Visa Traditional",
    "avs_check": "S",
    "cvv_check": "Y"
  },
  "customer": {
    "id": "cus_sozpnpktte5uzooigxau35uloq"
  },
  "processed_on": "2024-03-16T22:11:24Z",
  "reference": "ORD-752-814",
  "processing": {
    "acquirer_transaction_id": "8367314942",
    "retrieval_reference_number": "162588399162"
  },
  "_links": {
    "self": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_tqgk5c6k2nnexagtcuom5ktlua"
    },
    "actions": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_tqgk5c6k2nnexagtcuom5ktlua/actions"
    },
    "authorize": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_tqgk5c6k2nnexagtcuom5ktlua/authorizations"
    },
    "capture": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_tqgk5c6k2nnexagtcuom5ktlua/captures"
    },
    "void": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_tqgk5c6k2nnexagtcuom5ktlua/voids"
    }
  }
}
```

The [`balances` object](https://api-reference.checkout.com/tag/Payments/#operation/getPaymentDetails) returned in the response provides an overview of the payment’s balances, as well as the amounts that are available for subsequent payment actions.

If you need to increase the authorization amount before you [capture the payment](https://www.checkout.com/docs/payments/manage-payments/capture-a-payment.md), you can perform an [incremental authorization](https://www.checkout.com/docs/payments/manage-payments/authorize-a-payment/adjust-an-estimated-authorization.md).

After performing an estimated authorization, you have a set number of days to capture the payment before it expires. The [authorization validity period](#Authorization_validity_period) varies per card scheme.

---

## Request a partial authorization

With a standard authorization request, the issuer declines the transaction with a `20051` [response code](https://www.checkout.com/docs/developer-resources/codes/api-response-codes.md) if the cardholder has insufficient funds in their account to cover the full amount.

If you enable partial authorization for a Visa, Mastercard, or American Express (US only) payment, the issuer can return an authorization response for part of the full amount instead.

For example, if the full authorization amount is 100 GBP and the cardholder has 80 GBP in their account, with an approved partial authorization you can do the following:

- Capture the available 80 GBP.
- Void the transaction, if you or the cardholder choose not to process the partial amount.
- Prompt the cardholder to use a different payment method and process the remaining 20 GBP in a new payment request.

To request a partial authorization, set the `partial_authorization.enabled` field in your request to `true`.

> **Note**
>
> We recommend that you do not automatically capture partially authorized payments. This reduces the likelihood of customers disputing unwanted transactions.

> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Production**

`POST` `https://{prefix}.api.checkout.com/payments`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payments`

### Request example

```json
{
  "amount": 10000,
  "currency": "GBP",
  "source": {
    "type": "card",
    "expiry_month": "12",
    "expiry_year": "2027",
    "cvv": "153",
    "number": "4757337282365488"
  },
  "partial_authorization": {
    "enabled": true
  },
  "capture": false
}
```

If the `response_code` field in the response returns `10000`, you can [capture](https://www.checkout.com/docs/payments/manage-payments/capture-a-payment.md) the full amount.

If the response code is `10010`, inform the customer about the partial authorization and take one of the following actions, based on their response:

- If they accept the partial authorization request, you can capture the partial amount.
- If they do not accept, [void the payment](https://www.checkout.com/docs/payments/manage-payments/void-a-payment.md) and ask the customer to use an alternative payment method, or retry the payment later.

### Response example

```json
{
  "id": "pay_p2l6rr42k2qupd7576qpjin2py",
  "action_id": "act_dx4mex77fktu5c2an77zpjqgke",
  "amount": 5000,
  "amount_requested": 10000,
  "currency": "GBP",
  "approved": true,
  "status": "Authorized",
  "auth_code": "PWVHML",
  "response_code": "10010",
  "response_summary": "Partial Value Approved",
  "balances": {
    "total_authorized": 5000,
    "total_voided": 0,
    "available_to_void": 5000,
    "total_captured": 0,
    "available_to_capture": 5000,
    "total_refunded": 0,
    "available_to_refund": 0
  },
  "risk": {
    "flagged": false,
    "score": 0.0
  },
  "source": {
    "id": "src_voxmd5a6j7uupkow55r4ewmd3m",
    "type": "card",
    "billing_address": {
      "address_line1": "123 High St.",
      "address_line2": "Flat 456",
      "city": "London",
      "zip": "SW1A 1AA",
      "country": "GB"
    },
    "phone": {
      "number": "79460000",
      "country_code": "44"
    },
    "expiry_month": 12,
    "expiry_year": 2027,
    "scheme": "Visa",
    "last4": "5488",
    "fingerprint": "DDA617DF9E84C145B932DD09D4DDCB3A32C80C34E6CDBFFEEF2D2423FECC4ABF",
    "bin": "416549",
    "card_type": "DEBIT",
    "card_category": "CONSUMER",
    "issuer": "Test Bank",
    "issuer_country": "GB",
    "product_id": "I",
    "product_type": "Visa Infinite",
    "avs_check": "N",
    "cvv_check": "Y",
    "payment_account_reference": "V0010013822353374818836592526"
  },
  "customer": {
    "id": "cus_qeqdzlrxgmeexhrijsmdccm7oi"
  },
  "processed_on": "2024-01-18T13:27:37.7726822Z",
  "scheme_id": "484018484577883",
  "processing": {
    "acquirer_transaction_id": "531620484018484577883",
    "retrieval_reference_number": "401832531620",
    "merchant_category_code": "0742",
    "scheme_merchant_id": "516529",
    "scheme": "VISA",
    "partner_response_code": "10",
    "acquirer_name": "Checkout Visa",
    "acquirer_country_code": "GB",
    "aft": false
  },
  "expires_on": "2024-02-17T13:27:37.7726822Z",
  "_links": {
    "self": {
      "href": "https://{prefix}.api.checkout.com/payments/pay_p2l6rr42k2qupd7576qpjin2py"
    },
    "actions": {
      "href": "https://{prefix}.api.checkout.com/payments/pay_p2l6rr42k2qupd7576qpjin2py/actions"
    },
    "capture": {
      "href": "https://{prefix}.api.checkout.com/payments/pay_p2l6rr42k2qupd7576qpjin2py/captures"
    },
    "void": {
      "href": "https://{prefix}.api.checkout.com/payments/pay_p2l6rr42k2qupd7576qpjin2py/voids"
    }
  }
}
```

### Simulate a partial authorization

To simulate an approval for a partial authorization in your sandbox environment, request a payment using one of the following test cards as the payment `source`.

> **Note**
>
> To enable partial authorizations in your sandbox environment, contact your account manager or [request support](https://dashboard.checkout.com/support/new?topic=case_account_management_and_access&issue=issue_account_changes).

| Scheme | Card number |
| --- | --- |
| American Express (US only) | `345678901234456` |
| Mastercard | `5518207720770101` |
| Visa | `4757337282365488` |

Set the requested `amount` to one of the following values:
  - `10000`
  - `1000`

The response returns the following fields and values:

- `response_code` set to `10010`
- `response_summary` set to  `Partial Value Approved`
-  The partial approved amount:
    - `"amount": "5000"`, if you requested `"amount": "10000"`
    - `"amount": "700"`, if you requested `"amount": "1000"`
    - `"amount": "840"`, if you requested `"amount": "1000"` with American Express

---

## Authorization validity period

Card schemes set their own rules around how much time an authorization is valid for. You can successfully capture a payment after an authorization has expired, but this increases the risk of:

- A failed capture
- Increased interchange fees
- Card scheme transaction fees
- A chargeback

The card schemes apply the following authorization validity periods:

**Final authorization**

| Card scheme | Validity period |
| --- | --- |
| Mastercard | Seven days |
| Visa | - Five days for all merchant-initiated transactions (MITs)<br><br>- 10 days<br><br>- 30 days for Visa domestic transactions in Japan |
| American Express | Seven days |
| Cartes Bancaires | Seven days |
| Diners Club International | Seven days |
| Discover | 10 days |

**Estimated authorization**

| Card scheme | Validity period |
| --- | --- |
| American Express | Seven days for all [merchant category codes (MCCs)](https://www.checkout.com/docs/developer-resources/codes/merchant-category-codes.md), except the following:<br><br>- `7512 CAR RENTALS` – Valid for the duration of the rental<br>- `7011 LODGING` – Valid for the duration of the stay<br>- `4411 STEAMSHIP AND CRUISE LINES` – Valid for the duration of the cruise |
| Mastercard | 30 days<br><br>You can extend this period by performing an [incremental authorization](https://www.checkout.com/docs/payments/manage-payments/authorize-a-payment/adjust-an-estimated-authorization.md), which resets the 30-day expiry period. |
| Visa | - 10 days<br><br>- 30 days for the following MCCs:<br><br>- `3351`-`3500`, `7512 CAR RENTALS`<br>- `3501`-`3999`, `7011 LODGING`<br>- `4411 STEAMSHIP AND CRUISE LINES`<br>- `7513 TRUCK RENTALS`<br>- `7519 MOTOR HOME AND RECREATIONAL VEHICLE RENTALS`<br><br>- 30 days for Visa domestic transactions in Japan |
| Mada | - 14 days for all eligible MCCs. |

## Related topics

- [Adjust an estimated authorization](https://www.checkout.com/docs/payments/manage-payments/authorize-a-payment/adjust-an-estimated-authorization.md): Adjust the authorization amount for a previously authorized payment, or extend its validity period.
- [American Express Enhanced Authorization](https://www.checkout.com/docs/payments/manage-payments/authorize-a-payment/american-express-enhanced-authorization.md): Learn how to use the American Express Enhanced Authorization solution.
- [Discover Enhanced Decisioning](https://www.checkout.com/docs/payments/manage-payments/authorize-a-payment/discover-enhanced-decisioning.md): Learn how to use the Discover Enhanced Decisioning solution.