{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/api/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["partial"]},"type":"markdown"},"seo":{"title":"Getting Started","meta":[{"name":"robots","content":"noindex, nofollow"},{"name":"pingdom","content":"sh3MDv8mJpWhCWSTdGtN"}]},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"getting-started","__idx":0},"children":["Getting Started"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Shift4 API is REST-based, providing a complete payment processing platform for developers. It has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All API requests are made to the following base URL:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"https://api.shift4.com\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Key characteristics of the API:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["All requests ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["must"]}," use HTTPS. Any HTTP requests will be rejected."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Request bodies use ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["form-encoded parameters"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["All responses are returned as ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["JSON"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The API operates in two modes: ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["test"]}," and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["live"]},", each with separate API keys. Test mode transactions are completely isolated from production."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"authentication","__idx":1},"children":["Authentication"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Authentication Required"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All API requests must be authenticated using your ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["API secret key"]}," via HTTP Basic Auth. Use your secret key as the username and leave the password empty. Never share your secret key or expose it in client-side code."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can find your API keys in the ",{"$$mdtype":"Tag","name":"SiteLink","attributes":{"href":"/dashboard"},"children":["Shift4 Dashboard"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Shift4 API uses ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["HTTP Basic Authentication"]},". To authenticate, provide your API secret key as the username and leave the password field empty."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Test keys"]}," start with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sk_test_"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Live keys"]}," start with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sk_live_"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example request:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl https://api.shift4.com/charges -u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa:\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The key above belongs to a shared demo account, so the examples throughout these"," ","docs are runnable as written. Substitute your own key to work against your data."," ","The demo account predates the current prefixes, so its keys read ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pr_test_"]}," and"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pu_test_"]}," where yours will read ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sk_test_"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pk_test_"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Note the trailing colon (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":[":"]},") after the key -- this tells cURL to send an empty password."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Important security considerations:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Never"]}," expose your secret key in client-side code, public repositories, or anywhere accessible to end users."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["For client-side integrations with Shift4.js, use your ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["public keys"]}," instead (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pk_test_"]}," for test mode, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pk_live_"]}," for live mode)."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"errors","__idx":2},"children":["Errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Shift4 API uses standard HTTP status codes to indicate the outcome of a request:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Status Code"},"children":["Status Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Success"]}," -- The request completed successfully."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Bad Request"]}," -- The request was malformed or missing required parameters."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Unauthorized"]}," -- No valid API key was provided."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["402"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Card Error"]}," -- The card was declined or failed verification."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["404"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Not Found"]}," -- The requested resource does not exist."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Rate Limit"]}," -- Too many requests in a given time period."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["500"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Server Error"]}," -- An internal error occurred on Shift4's servers."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Error object structure:"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When an error occurs, the response body contains an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]}," object with the following fields:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"error\": {\n    \"type\": \"card_error\",\n    \"code\": \"invalid_number\",\n    \"message\": \"The card number is not a valid credit card number.\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Error types:"]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invalid_request"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The request was malformed or missing required parameters."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["card_error"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The card was declined or failed verification."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["gateway_error"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An internal error occurred on Shift4's servers."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Card error codes:"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"error-types","__idx":3},"children":["Error Types"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invalid_request"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The request was malformed or missing required parameters."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["card_error"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The card was declined or failed verification."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["gateway_error"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An internal error occurred on Shift4's servers."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"card-error-codes","__idx":4},"children":["Card Error Codes"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Code"},"children":["Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invalid_number"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The card number is not a valid credit card number."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invalid_expiry_month"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The card's expiration month is invalid."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invalid_expiry_year"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The card's expiration year is invalid."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["invalid_cvc"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The card's CVC number is invalid."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["incorrect_cvc"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The card's CVC is incorrect."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["incorrect_zip"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The card's ZIP code failed validation."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["card_declined"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The card was declined."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expired_card"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The card has expired."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["insufficient_funds"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The card has insufficient funds to complete the purchase."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lost_or_stolen"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The card has been reported as lost or stolen."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["suspected_fraud"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The charge was flagged as potentially fraudulent."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["processing_error"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["An error occurred while processing the card."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["blacklisted"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The card number, fingerprint, or email is on a blacklist."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expired_token"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The token has already been used or has expired."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["limit_exceeded"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The charge amount exceeds the maximum allowed."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["authentication_required"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The charge requires 3D Secure authentication."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["do_not_honor"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The issuing bank has declined the transaction."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["do_not_try_again"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The issuing bank has declined and requests no further attempts."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"idempotency","__idx":5},"children":["Idempotency"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Shift4 API supports ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["idempotent requests"]},", allowing you to safely retry requests without the risk of performing the same operation twice. This is especially important for payment operations."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To make an idempotent request, include the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Idempotency-Key"]}," header with a unique value (UUIDs are recommended):"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl https://api.shift4.com/charges \\\n  -u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \\\n  -H \"Idempotency-Key: unique_key_123\" \\\n  -d \"amount=1000\" \\\n  -d \"currency=USD\" \\\n  -d \"card=tok_example\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Key details:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Idempotency keys are valid for ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["24 hours"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If a duplicate request is detected, the server responds with the original response and includes an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Idempotent-Replayed: true"]}," header."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Only ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}," requests support idempotency keys. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE"]}," requests are inherently idempotent."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"metadata","__idx":6},"children":["Metadata"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Most Shift4 objects support a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["metadata"]}," parameter, allowing you to attach custom key-value pairs to resources."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Up to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["20"]}," key-value pairs per object."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Keys can be up to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["40"]}," characters long."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Values can be up to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["500"]}," characters long."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Useful for storing reference IDs from your own system (e.g., order IDs, user IDs)."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl https://api.shift4.com/charges \\\n  -u pr_test_tXHm9qV9qV9bjIRHcQr9PLPa: \\\n  -d \"amount=1000\" \\\n  -d \"currency=USD\" \\\n  -d \"card=tok_example\" \\\n  -d \"metadata[order_id]=12345\" \\\n  -d \"metadata[customer_email]=user@example.com\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Metadata is not used by Shift4 for any processing -- it is purely for your own record-keeping."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"pagination","__idx":7},"children":["Pagination"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All list endpoints return paginated results using cursor-based pagination."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Query parameters:"]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Parameter"},"children":["Parameter"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["limit"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Number of results per page (1--100, default 10)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["startingAfterId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Return results starting after the object with this ID."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["endingBeforeId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Return results ending before the object with this ID."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["created[gte]"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Filter results created at or after this timestamp."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["created[lte]"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Filter results created at or before this timestamp."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Example response:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"list\": [\n    { \"id\": \"char_7Hd8sK2mNpQ4rLbVx0TfYcWs\", \"amount\": 1000, \"currency\": \"USD\" },\n    { \"id\": \"char_9x2Kd8bViQ0rLmNpQ4TsHfYc\", \"amount\": 2500, \"currency\": \"USD\" }\n  ],\n  \"hasMore\": true\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["hasMore"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},", pass the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," of the last item in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["list"]}," array as the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["startingAfterId"]}," parameter to retrieve the next page."]}]},"headings":[{"value":"Getting Started","id":"getting-started","depth":1},{"value":"Authentication","id":"authentication","depth":2},{"value":"Errors","id":"errors","depth":2},{"value":"Error Types","id":"error-types","depth":3},{"value":"Card Error Codes","id":"card-error-codes","depth":3},{"value":"Idempotency","id":"idempotency","depth":2},{"value":"Metadata","id":"metadata","depth":2},{"value":"Pagination","id":"pagination","depth":2}],"frontmatter":{"title":"Getting Started","seo":{"title":"Getting Started"}},"lastModified":"2026-09-11T07:43:43.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/api","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}