# Shift4 Gateway API

The Shift4 API is organized around REST. Our API has predictable resource-oriented URLs,
accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard
HTTP response codes, authentication, and verbs.

## Base URL

All API requests should be made to:

```
https://api.shift4.com
```

## Authentication

The Shift4 API uses HTTP Basic Authentication. Provide your API secret key as the
username and leave the password empty.

```bash
curl https://api.shift4.com/charges -u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:
```


Version: 1.0.0

## Servers

Production API
```
https://api.shift4.com
```

## Security

### BasicAuth

[object Object],[object Object],[object Object],[object Object],[object Object],[object Object]

Type: http
Scheme: basic

## Download OpenAPI description

 - [Shift4 Gateway API](https://matterhorn-api.redocly.app/_bundle/docs/api/shift4-gateway.yaml)

## Charges

 - [POST /charges](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/charges/createcharge.md): Creates a new charge. To charge a credit card, you create a charge object. If your API key is in test mode, the supplied payment source (e.g., card token) won't actually be charged, although everythin
 - [GET /charges](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/charges/listcharges.md): Returns a list of charges you've previously created. The charges are returned in sorted order, with the most recent charges appearing first.
 - [GET /charges/{chargeId}](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/charges/getcharge.md): Retrieves the details of a charge that has previously been created.
 - [POST /charges/{chargeId}](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/charges/updatecharge.md): Updates the specified charge by setting the values of the parameters passed. Any parameters not provided are left unchanged. To resolve a pending payment-method charge in test mode, address the charge
 - [POST /charges/{chargeId}/capture](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/charges/capturecharge.md): Captures a previously uncaptured charge. This is the second step of a two-step payment flow (authorize then capture). Charges must be captured within 5 days of authorization.
 - [POST /charges/{chargeId}/incremental-authorization](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/charges/incrementalauthorization.md): Increments the amount of a pre-authorized charge. To be able to increment an authorization, the charge must be created with `captured=false` and `options.authorizationType=pre`.
## Refunds

 - [POST /refunds](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/refunds/createrefund.md): Refund an existing charge, which will result in funds being returned to the previously charged credit or debit card. Partial refunds are only possible for a captured charge. Partial refunds can be re
 - [GET /refunds](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/refunds/listrefunds.md): List refund objects for a given charge. Results are sorted by creation date, with the most recent objects first.
 - [GET /refunds/{refundId}](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/refunds/getrefund.md): Retrieves an existing refund object.
 - [POST /refunds/{refundId}](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/refunds/updaterefund.md): Updates an existing refund object. Any parameters not provided are left unchanged.
## Customers

 - [POST /customers](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/customers/createcustomer.md): Creates a new customer object. You can attach a card to the customer so it can be reused for [recurring charges](/docs/api/shift4-gateway/charges/createcharge).
 - [GET /customers](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/customers/listcustomers.md): Returns a list of customers. The customers are returned in sorted order, with the most recently created appearing first.
 - [GET /customers/{customerId}](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/customers/getcustomer.md): Retrieves the details of an existing customer.
 - [POST /customers/{customerId}](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/customers/updatecustomer.md): Updates the specified customer by setting the values of the parameters passed. Any parameters not provided are left unchanged.
 - [DELETE /customers/{customerId}](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/customers/deletecustomer.md): Deletes an existing customer object.
## Cards

 - [POST /customers/{customerId}/cards](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/cards/createcard.md): Adds a new card to an existing customer. There are three ways to create a new card object: use a card token (for example obtained from Components), use a charge identifier (saves the card that was us
 - [GET /customers/{customerId}/cards](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/cards/listcards.md): Returns a list of cards belonging to a customer. The cards are returned in sorted order, with the most recently created appearing first.
 - [GET /customers/{customerId}/cards/{cardId}](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/cards/getcard.md): Retrieves the details of a card that belongs to a customer.
 - [POST /customers/{customerId}/cards/{cardId}](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/cards/updatecard.md): Updates the specified card. Any parameters not provided are left unchanged.
 - [DELETE /customers/{customerId}/cards/{cardId}](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/cards/deletecard.md): Deletes an existing card object. If you delete the card that is the current default card, the most recently added card is used as the new default card. If you delete the last card, the default card is
## Payment Methods

 - [POST /payment-methods](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/payment-methods/createpaymentmethod.md): Creates a new payment method for alternative payment types.
 - [GET /payment-methods](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/payment-methods/listpaymentmethods.md)
 - [GET /payment-methods/{paymentMethodId}](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/payment-methods/getpaymentmethod.md)
 - [DELETE /payment-methods/{paymentMethodId}](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/payment-methods/deletepaymentmethod.md)
## Subscriptions

 - [POST /subscriptions](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/subscriptions/createsubscription.md): Creates a new subscription object. The subscription is billed to the customer's current default card.
 - [GET /subscriptions](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/subscriptions/listsubscriptions.md): Lists subscription objects. Results are sorted by creation date, with the most recent objects first.
 - [GET /subscriptions/{subscriptionId}](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/subscriptions/getsubscription.md): Retrieves an existing subscription object.
 - [POST /subscriptions/{subscriptionId}](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/subscriptions/updatesubscription.md): Updates an existing subscription object. Any parameters not provided are left unchanged.
 - [DELETE /subscriptions/{subscriptionId}](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/subscriptions/cancelsubscription.md): Cancels an existing subscription.
 - [GET /subscriptions/{subscriptionId}/charges](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/subscriptions/listsubscriptioncharges.md): Lists the charge attempts made by a subscription, including automatic renewals (rebills) and failed attempts. Results are sorted with the most recent records first. Note that unlike other list endpoin
## Plans

 - [POST /plans](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/plans/createplan.md): Creates a new plan object.
 - [GET /plans](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/plans/listplans.md): Lists plan objects. Results are sorted by creation date, with the most recent objects first.
 - [GET /plans/{planId}](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/plans/getplan.md): Retrieves an existing plan object.
 - [POST /plans/{planId}](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/plans/updateplan.md): Updates an existing plan object. Any parameters not provided are left unchanged. Changing the amount or currency of a plan will only affect future rebills of all subscriptions that are using this pla
 - [DELETE /plans/{planId}](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/plans/deleteplan.md): Deletes an existing plan object. Note that when you delete a plan, the existing subscriptions will continue to be charged until they are canceled.
## Events

 - [GET /events](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/events/listevents.md): List event objects. Results are sorted by creation date, with the most recent objects first.
 - [GET /events/{eventId}](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/events/getevent.md): Retrieves an existing event object.
## Tokens

 - [POST /tokens](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/tokens/createtoken.md): Creates a new token object. This method can be called with either your API public key or your API secret key.
 - [GET /tokens/{tokenId}](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/tokens/gettoken.md): Retrieves an existing token object.
 - [POST /3d-secure](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/tokens/initializethreedsecure.md): Initializes a new 3D Secure authentication process. Generally (apart from a few specialized use cases) it is not recommended to initialize 3D Secure from the API. You should use our Components or Chec
## Blacklist

 - [POST /blacklist](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/blacklist/createblacklistrule.md): Creates a new blacklist rule object.
 - [GET /blacklist](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/blacklist/listblacklistrules.md): Lists blacklist rule objects. Results are sorted by creation date, with the most recent objects first.
 - [GET /blacklist/{blacklistRuleId}](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/blacklist/getblacklistrule.md): Retrieves an existing blacklist rule object.
 - [DELETE /blacklist/{blacklistRuleId}](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/blacklist/deleteblacklistrule.md): Deletes an existing blacklist rule object.
## Credits

 - [POST /credits](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/credits/createcredit.md): Creates a new credit object. A credit represents funds transferred to a card. Either `customerId` or `card` must be provided. If you are in test mode, then the provided card won't receive any funds, a
 - [GET /credits](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/credits/listcredits.md): List credit objects. Results are sorted by creation date, with the most recent objects first. This feature is available for selected business models only. Please contact devsupport@shift4.com to find
 - [GET /credits/{creditId}](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/credits/getcredit.md): Retrieves an existing credit object. This feature is available for selected business models only. Please contact devsupport@shift4.com to find out more.
 - [POST /credits/{creditId}](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/credits/updatecredit.md): Updates an existing credit object. Any parameters not provided are left unchanged. This feature is available for selected business models only. Please contact devsupport@shift4.com to find out more.
## Disputes

 - [GET /disputes](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/disputes/listdisputes.md): Lists dispute objects. Results are sorted by creation date, with the most recent objects first.
 - [GET /disputes/{disputeId}](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/disputes/getdispute.md): Retrieves an existing dispute object.
 - [POST /disputes/{disputeId}](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/disputes/updatedispute.md): Updates an existing dispute object. Any parameters not provided are left unchanged.
 - [POST /disputes/{disputeId}/close](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/disputes/closedispute.md): Closing the dispute indicates that you do not want to submit any further evidence and acknowledge it as lost.
## File Uploads

 - [POST /files](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/file-uploads/createfileupload.md): Creates a new file upload object. A successful request returns a file upload object that represents the uploaded file.
 - [GET /files](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/file-uploads/listfileuploads.md): Lists file upload objects. Results are sorted by creation date, with the most recent objects first.
 - [GET /files/{fileUploadId}](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/file-uploads/getfileupload.md): Retrieves an existing file upload object.
## Fraud Warnings

 - [GET /fraud-warnings](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/fraud-warnings/listfraudwarnings.md): Lists fraud warning objects. Results are sorted by creation date, with the most recent objects first.
 - [GET /fraud-warnings/{fraudWarningId}](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/fraud-warnings/getfraudwarning.md): Retrieves an existing fraud warning object.
## Payouts

 - [GET /payouts](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/payouts/listpayouts.md): Lists payout objects. Results are sorted by payout date, with the most recent objects first.
 - [POST /payouts](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/payouts/createtestpayout.md): Creates a test payout based on test mode charges, refunds, chargebacks and credits. This endpoint takes no parameters and is only available when using a test API key.
 - [GET /payouts/{payoutId}](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/payouts/getpayout.md): Retrieves an existing payout object.
 - [GET /payout-transactions](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/payouts/listpayouttransactions.md): Lists payout transaction objects. Results are sorted by creation date, with the most recent objects first. Either the `payout` or the `source` parameter must be provided.
## Checkout

 - [POST /checkout-sessions](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/checkout/createcheckoutsession.md): Creates a new checkout session. Sessions must be created using a secret API key. Pass the returned `clientSecret` to the `checkout.js` script to render the payment form, or use the returned `url` for
 - [GET /checkout-sessions](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/checkout/listcheckoutsessions.md): Lists checkout session objects. Results are sorted by creation date, with the most recent objects first.
 - [GET /checkout-sessions/{checkoutSessionId}](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/checkout/getcheckoutsession.md): Retrieves an existing checkout session object.
## Payment Links

 - [POST /payment-links](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/payment-links/createpaymentlink.md): Creates a new payment link. Every new payment link is active by default. An optional failed-payment limit can be set only at creation.
 - [GET /payment-links](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/payment-links/listpaymentlinks.md): Lists payment link objects. Results are sorted by creation date, with the most recent objects first.
 - [GET /payment-links/{paymentLinkId}](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/payment-links/getpaymentlink.md): Retrieves an existing payment link object.
 - [POST /payment-links/{paymentLinkId}](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/payment-links/updatepaymentlink.md): Updates an existing payment link. Attributes not provided in the request are left unchanged.
 - [POST /payment-links/{paymentLinkId}/deactivate](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/payment-links/deactivatepaymentlink.md): Deactivates an existing payment link. Every new payment link is active by default. Payment links with a limited number of charges are deactivated automatically the moment the limit is reached.
 - [POST /payment-links/{paymentLinkId}/reactivate](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/payment-links/reactivatepaymentlink.md): Reactivates a deactivated payment link. A payment link cannot be reactivated once its limit of successful charges or failed payment attempts has been reached.
 - [GET /payment-links/{paymentLinkId}/charges](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/payment-links/listpaymentlinkcharges.md): Lists the charges made through a given payment link. Results are sorted by creation date, with the most recent objects first. To read the custom field values a customer submitted for a given payment,
## Testing

 - [POST /charges/{clientChargeId}](https://matterhorn-api.redocly.app/docs/api/shift4-gateway/testing/resolvechargestatus.md): Resolves the status of a pending charge programmatically. This is useful when the payment process is asynchronous and you need to settle its status without performing the real payment flow — for examp