# Checkout Request

A Checkout Request defines either a single charge or an automatically recurring subscription, and is used to initialize Shift4 Checkout.

Checkout Requests are deprecated and will be removed in a future release. All new integrations should use [Checkout Sessions](/docs/api/shift4-gateway/checkout/createcheckoutsession) instead.

Creating a Checkout Request can be done offline, without the need to communicate with Shift4 servers. There is no endpoint to call — you build a JSON object and sign it with your secret key.

If you already have a customer object that represents your customer, you can include its identifier in the Checkout Request so that the created charge or subscription is automatically assigned to that customer. If the identifier of an existing customer is not provided, a new customer object is created automatically.

Checkout Request is a gated feature. If it is not enabled for your account, signed Checkout Requests are rejected. Contact [devsupport@shift4.com](mailto:devsupport@shift4.com) to find out more.

## Attributes

Exactly one of `charge`, `subscription`, or `customCharge` is required.

### charge

`object`, optional -- either `charge`, `subscription`, or `customCharge` is required.

Defines the charge that will be created by Checkout.

| Attribute | Type | Description |
|  --- | --- | --- |
| `amount` | integer, required | Charge amount in minor units of a given currency. |
| `currency` | string, required | Charge currency represented as a three-letter ISO currency code. |
| `capture` | boolean, optional | Whether this charge should be immediately captured. Default: `true`. |
| `vendorReference` | string, optional | Additional transaction identifier used throughout Shift4's systems. |
| `metadata` | object, optional | Set of key-value pairs attached to the charge. |


For more information about the meaning of these attributes, see the [charge create request](/docs/api/shift4-gateway/charges/createcharge).

### subscription

`object`, optional -- either `charge`, `subscription`, or `customCharge` is required.

Defines the subscription that will be created by Checkout.

| Attribute | Type | Description |
|  --- | --- | --- |
| `planId` | string, required | Identifier of a plan that will be assigned to this subscription. |
| `captureCharges` | boolean, optional | Whether charges created by this subscription will be immediately captured. Default: `true`. |
| `metadata` | object, optional | Set of key-value pairs attached to the subscription. |


For more information about the meaning of these attributes, see the [subscription create request](/docs/api/shift4-gateway/subscriptions/createsubscription).

### customCharge

`object`, optional -- either `charge`, `subscription`, or `customCharge` is required.

Defines a charge with a custom amount that will be selected by the customer in Checkout. Either `amountOptions` or `customAmount` is required.

| Attribute | Type | Description |
|  --- | --- | --- |
| `amountOptions` | list of integers | List of predefined amounts, in minor units of a given currency, that the customer can choose from. |
| `customAmount` | object | Object with `min` and `max` attributes defining a valid range for the custom amount provided by the customer. |
| `currency` | string, required | Charge currency represented as a three-letter ISO currency code. |
| `capture` | boolean, optional | Whether this charge should be immediately captured. Default: `true`. |
| `metadata` | object, optional | Set of key-value pairs attached to the charge. |


Providing `amountOptions` causes Checkout to show buttons with predefined amounts from which the customer can choose. Providing `customAmount` causes Checkout to show an input field where the customer can type any amount within the specified range. Providing both at the same time causes Checkout to show both options.

### Other attributes

| Attribute | Type | Description |
|  --- | --- | --- |
| `customerId` | string, optional | Identifier of an existing customer that will be used to create the charge or subscription. |
| `termsAndConditionsUrl` | string, optional | URL to your terms and conditions page. If provided, an additional page is shown in Checkout before the payment page, where the customer must accept your terms. If the Checkout Request creates a subscription, information about the recurring payment is also shown on that page. |
| `customFieldsTitle` | string, optional | Header for the custom field section in the Checkout form. |
| `customFields` | list of objects, optional | List of custom fields with unique keys. Maximum 3 fields. |
| `locale` | string, optional | Language of the form, provided as two letters compliant with the IETF standard. If missing, browser settings are applied. |
| `threeDSecure` | object, optional | 3D Secure options. |


#### customFields

Each entry contains the following fields:

| Attribute | Type | Description |
|  --- | --- | --- |
| `key` | string | A unique identifier of the field. |
| `label` | string | A unique label of the field in the Checkout form. |
| `optional` | boolean | Defines whether the field is required. Default: `false`. |


#### threeDSecure

| Attribute | Type | Description |
|  --- | --- | --- |
| `enable` | boolean | Whether 3D Secure verification should be attempted. Default: `false`. |
| `requireEnrolledCard` | boolean | The charge will fail if the card does not support 3D Secure (is not enrolled for 3D Secure verification). Default: `false`. |
| `requireSuccessfulLiabilityShiftForEnrolledCard` | boolean | The charge will fail when the card supports 3D Secure verification, but that verification was not successful -- for example, the customer cancelled the verification or provided invalid information in the 3D Secure popup. Default: `true`. |


## Signing a Checkout Request

A Checkout Request signature is created using HMAC with SHA256, using the Checkout Request JSON and your secret key. A signed Checkout Request is created by concatenating the signature, a pipe character (`|`), and the Checkout Request JSON, and then encoding the result with BASE64.

The complete formula:

```
$signed_checkout_request = base64( hmac_sha256( $checkout_request, $private_key ) + "|" + $checkout_request )
```

Always sign Checkout Requests on your server. Your secret key must never be exposed in client-side code.

### Example

Bash
```bash
export checkout_request='{"charge":{"amount":499,"currency":"USD"}}'
export signature=`echo -n "$checkout_request" | openssl dgst -sha256 -hmac 'pr_test_tXHm9qV9qV9bjIRHcQr9PLPa' | sed 's/^.* //'`
echo -n "$signature|$checkout_request" | base64
```

PHP
```php
$checkoutRequest = json_encode([
    'charge' => [
        'amount'   => 499,
        'currency' => 'USD',
    ],
]);

$signature = hash_hmac('sha256', $checkoutRequest, 'pr_test_tXHm9qV9qV9bjIRHcQr9PLPa');
$signedCheckoutRequest = base64_encode($signature . '|' . $checkoutRequest);
```

Node.js
```javascript
const crypto = require('crypto');

const checkoutRequest = JSON.stringify({
  charge: { amount: 499, currency: 'USD' },
});

const signature = crypto
  .createHmac('sha256', 'pr_test_tXHm9qV9qV9bjIRHcQr9PLPa')
  .update(checkoutRequest)
  .digest('hex');

const signedCheckoutRequest = Buffer
  .from(`${signature}|${checkoutRequest}`)
  .toString('base64');
```

Python
```python
import base64
import hashlib
import hmac
import json

checkout_request = json.dumps({
    'charge': {'amount': 499, 'currency': 'USD'},
})

signature = hmac.new(
    b'pr_test_tXHm9qV9qV9bjIRHcQr9PLPa',
    checkout_request.encode('utf-8'),
    hashlib.sha256,
).hexdigest()

signed_checkout_request = base64.b64encode(
    f'{signature}|{checkout_request}'.encode('utf-8')
).decode('utf-8')
```

This produces a signed Checkout Request such as:

```
ODViMmQ1NWEwYmNkZmMxZTI5ZTAwOGYzZDdlODhhYmRkNGQzOGUyMjE4NjU4NjA2MjkzYjk1ZDA2ZWNkMzk4Y3x7ImNoYXJnZSI6eyJhbW91bnQiOjQ5OSwiY3VycmVuY3kiOiJVU0QifX0=
```

## Examples

### With a charge

```json
{
  "charge": {
    "amount": 499,
    "currency": "USD"
  },
  "customerId": "cust_AoR0wvgntQWRUYMdZNLYMz5R",
  "customFields": [
    {
      "key": "your_text_here",
      "label": "Your Text Here",
      "optional": false
    },
    {
      "key": "your_signature",
      "label": "Your Signature",
      "optional": true
    }
  ]
}
```

### With a subscription

```json
{
  "subscription": {
    "planId": "plan_bLu3vzO8yhAFhbxFEadm6HUV"
  },
  "customerId": "cust_AoR0wvgntQWRUYMdZNLYMz5R"
}
```

### With a custom charge

```json
{
  "customCharge": {
    "amountOptions": [100, 200, 500, 1000, 2000],
    "customAmount": {
      "min": 100,
      "max": 5000
    },
    "currency": "USD"
  },
  "customerId": "cust_AoR0wvgntQWRUYMdZNLYMz5R"
}
```

## Next steps

- [**Checkout Sessions**](/docs/api/shift4-gateway/checkout/createcheckoutsession) -- the recommended integration model.
- [**Charges**](/docs/api/shift4-gateway/charges/createcharge) -- understand the charge object created behind the scenes.