{"componentChunkName":"component---src-templates-redoc-operation-js","path":"/payment-methods/tag/Data-definitions/schema/BillingDetails/","result":{"data":{"contentItem":{"type":"redoc-operation","link":"/payment-methods/tag/Data-definitions/schema/BillingDetails/","data":{"redocStoreStr":"{\"menu\":{\"activeItemIdx\":-1},\"definition\":{\"data\":{\"openapi\":\"3.0.1\",\"info\":{\"title\":\"Payment methods API\",\"description\":\"Use the payment methods API to create, get, and detach payment\\nmethods. Payment methods represent a customer's payment instruments. For\\nexample, a payment method can be saved payment card information that a\\ncustomer uses for a purchase.  You may use payment methods with\\npayment intents or save payment methods using the customers API for future\\npayments.\\n\",\"version\":\"1.0.2\",\"contact\":{\"name\":\"Toast developer support\"}},\"servers\":[{\"url\":\"https://payments.toasttab.com\"}],\"paths\":{\"/v1/payment-methods\":{\"post\":{\"summary\":\"Create a payment method\",\"description\":\"Creates a payment method.\\n\",\"operationId\":\"createPaymentMethod\",\"parameters\":[{\"name\":\"Toast-Session-Secret\",\"in\":\"header\",\"schema\":{\"type\":\"string\",\"format\":\"string\"},\"required\":true,\"description\":\"A unique and randomized identifier for the payment or setup intent.\"},{\"name\":\"Toast-Idempotency-Key\",\"in\":\"header\",\"schema\":{\"type\":\"string\",\"format\":\"UUID\"},\"required\":true,\"description\":\"An integration generated universally unique identifier (UUID) that is used to recognize retries of the same request.\"}],\"requestBody\":{\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/PaymentMethodRequest\"}}}},\"responses\":{\"200\":{\"description\":\"Succesful operation. Payment method created.\",\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/PaymentMethodResponse\"}}}},\"400\":{\"description\":\"Invalid request, card data, or session.\",\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/ErrorMessage\"}}}},\"403\":{\"description\":\"Your Toast API client does not have permission to create the payment method.\",\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/ErrorMessage\"}}}},\"409\":{\"description\":\"Payment method not found or hasn't been scoped to payment or setup intent.\",\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/ErrorMessage\"}}}},\"500\":{\"description\":\"Internal server error.\",\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/ErrorMessage\"}}}}},\"security\":[{\"OAuth2\":[\"simplified-payments-integration:write\"]},{\"OAuth2\":[\"simplified-payments-integration.server:write\"]}]}},\"/v1/payment-methods/{id}/detach\":{\"post\":{\"summary\":\"Detach a payment method\",\"description\":\"Deletes a stored payment method from a customer record. Detaching a payment method is permanent and the payment method cannot be reattached to the customer record.\\n\",\"operationId\":\"detachPaymentMethod\",\"parameters\":[{\"name\":\"Toast-Restaurant-External-ID\",\"in\":\"header\",\"schema\":{\"type\":\"string\",\"format\":\"string\"},\"required\":true,\"description\":\"The identifier of the location.\"},{\"name\":\"id\",\"in\":\"path\",\"required\":true,\"description\":\"The unique identifier of the payment method.\",\"schema\":{\"type\":\"string\",\"format\":\"UUID\"}}],\"requestBody\":{\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/DetachPaymentMethodRequest\"}}}},\"responses\":{\"200\":{\"description\":\"Request processed. The payment method was either deleted (no active mandates associated) or retained with the `usage` value set to `OFF_SESSION` (active mandates associated).\",\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/DetachPaymentMethodResponse\"}}}},\"400\":{\"description\":\"Invalid request or payment method access validation failed.\",\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/ErrorMessage\"}}}},\"403\":{\"description\":\"Your Toast API client does not have permission to detach the saved payment method.\",\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/ErrorMessage\"}}}},\"404\":{\"description\":\"The specified saved payment method was not found.\",\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/ErrorMessage\"}}}},\"500\":{\"description\":\"Internal server error.\",\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/ErrorMessage\"}}}}},\"security\":[{\"OAuth2\":[\"simplified-payments-integration.server:write\"]}]}},\"/v1/payment-methods/{paymentMethodId}/mandates\":{\"get\":{\"summary\":\"Get mandates for a payment method\",\"description\":\"Returns mandates associated with a payment method. Optionally filter by active status.\",\"operationId\":\"getMandatesForPaymentMethod\",\"parameters\":[{\"name\":\"paymentMethodId\",\"in\":\"path\",\"required\":true,\"description\":\"The identifier of the payment method.\",\"schema\":{\"type\":\"string\",\"format\":\"uuid\"}},{\"name\":\"active\",\"in\":\"query\",\"required\":false,\"description\":\"Filter mandates by active status. When true, returns only ACTIVE mandates. When false, returns only INACTIVE mandates. When omitted, returns all mandates regardless of status.\",\"schema\":{\"type\":\"boolean\"}}],\"responses\":{\"200\":{\"description\":\"Successful operation. Returns information about mandates for the specific payment method.\",\"content\":{\"application/json\":{\"schema\":{\"type\":\"array\",\"items\":{\"$ref\":\"#/components/schemas/Mandate\"}}}}},\"400\":{\"description\":\"Invalid payment method ID format.\",\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/ErrorMessage\"}}}},\"403\":{\"description\":\"Unauthorized access.\",\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/ErrorMessage\"}}}},\"404\":{\"description\":\"Payment method not found.\",\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/ErrorMessage\"}}}}},\"security\":[{\"OAuth2\":[\"simplified-payments-integration:read\"]}]}},\"/v1/mandates/{mandateId}\":{\"get\":{\"summary\":\"Get mandate by ID\",\"description\":\"Retrieves a specific mandate by its ID.\",\"operationId\":\"getMandateById\",\"parameters\":[{\"name\":\"mandateId\",\"in\":\"path\",\"required\":true,\"description\":\"The unique identifier of the mandate.\",\"schema\":{\"type\":\"string\",\"format\":\"uuid\"}}],\"responses\":{\"200\":{\"description\":\"Successful operation. Returns the mandate.\",\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/Mandate\"}}}},\"400\":{\"description\":\"Invalid mandate ID format.\",\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/ErrorMessage\"}}}},\"403\":{\"description\":\"Unauthorized access.\",\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/ErrorMessage\"}}}},\"404\":{\"description\":\"Mandate not found.\",\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/ErrorMessage\"}}}}},\"security\":[{\"OAuth2\":[\"simplified-payments-integration:read\"]}]},\"delete\":{\"summary\":\"Revoke a mandate\",\"description\":\"Revokes an existing mandate by setting its status to `INACTIVE`.\",\"operationId\":\"revokeMandate\",\"parameters\":[{\"name\":\"mandateId\",\"in\":\"path\",\"required\":true,\"description\":\"The unique identifier of the mandate.\",\"schema\":{\"type\":\"string\",\"format\":\"uuid\"}}],\"responses\":{\"204\":{\"description\":\"Successful operation. Mandate revoked.\"},\"400\":{\"description\":\"Invalid mandate ID format.\",\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/ErrorMessage\"}}}},\"403\":{\"description\":\"Unauthorized access.\",\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/ErrorMessage\"}}}},\"404\":{\"description\":\"Mandate not found.\",\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/ErrorMessage\"}}}}},\"security\":[{\"OAuth2\":[\"simplified-payments-integration:write\"]}]}}},\"components\":{\"schemas\":{\"Card\":{\"type\":\"object\",\"description\":\"Card creation attributes.\",\"properties\":{\"number\":{\"type\":\"string\",\"description\":\"The payment card number.\"},\"cvv\":{\"type\":\"string\",\"description\":\"The three- or four-digit card verification value (CVV) of the payment card.\"},\"expiry\":{\"type\":\"object\",\"description\":\"The expiration month and year of the payment card.\",\"properties\":{\"month\":{\"type\":\"string\",\"description\":\"The expiration month of the payment card.\"},\"year\":{\"type\":\"string\",\"description\":\"The expiration year of the payment card.\"}}}}},\"CardResponse\":{\"type\":\"object\",\"properties\":{\"firstSix\":{\"type\":\"string\",\"description\":\"The first six digits of the payment card.\"},\"lastFour\":{\"type\":\"string\",\"description\":\"The last four digits of the payment card.\"},\"expiry\":{\"type\":\"object\",\"description\":\"The expiration month and year of the payment card.\",\"properties\":{\"month\":{\"type\":\"string\",\"description\":\"The expiration month of the payment card.\"},\"year\":{\"type\":\"string\",\"description\":\"The expiration year of the payment card.\"}}},\"brand\":{\"type\":\"string\",\"description\":\"The payment card brand. For example, AMEX™, Discover™, Mastercard™, or Visa™.\",\"enum\":[\"VISA\",\"MASTERCARD\",\"AMEX\",\"DISCOVER\",\"JCB\",\"DINERS\",\"CITI\",\"MAESTRO\",\"LASER\",\"SOLO\",\"INTERAC\",\"EFTPOS\",\"UNKNOWN\"]},\"fingerprint\":{\"type\":\"string\",\"format\":\"uuid\",\"description\":\"A unique identifier for the card.\"},\"funding\":{\"type\":\"string\",\"description\":\"The funding type of the card.\",\"enum\":[\"DEBIT\",\"CREDIT\",\"PREPAID\",\"UNKNOWN\"]}},\"description\":\"Details about a payment card.\"},\"PaymentMethodRequest\":{\"type\":\"object\",\"properties\":{\"type\":{\"type\":\"string\",\"description\":\"The type of payment method.\\n* `CARD` - Payment card, including Apple Pay and Google Pay digital wallets.\\n  Use `card.wallet.type` to indicate the wallet type.\\n* `CARD_PRESENT` - This is reserved for future use.\\n* `GIFT_CARD` - This is reserved for future use.\\n* `GIFT_CARD_PRESENT` - This is reserved for future use.\\n* `US_BANK_ACCOUNT` - Reserved for future use. US bank account payment method for ACH transactions.\\n  Provide account details via the `usBankAccount` field.\\n\",\"enum\":[\"CARD\",\"CARD_PRESENT\",\"GIFT_CARD\",\"GIFT_CARD_PRESENT\",\"US_BANK_ACCOUNT\"]},\"card\":{\"$ref\":\"#/components/schemas/Card\"},\"billingDetails\":{\"type\":\"object\",\"properties\":{\"postalCode\":{\"type\":\"string\",\"description\":\"The postal or ZIP code.\"}}},\"usage\":{\"type\":\"string\",\"nullable\":true,\"description\":\"Field used to determine if the logged-in customer will save the payment method for future usage. The value is `ON_SESSION` for cards saved during checkout. The value is `NULL` if the card will not be saved for future usage.\\n* `ON_SESSION` - Saves the payment method for future customer-initiated transactions.\\n* `OFF_SESSION` - Saves the payment method for future merchant-initiated transactions.\\n* `ON_AND_OFF_SESSION` - Saves the payment method for future customer or merchant-initiated transactions.\\n\",\"enum\":[\"ON_SESSION\",\"OFF_SESSION\",\"ON_AND_OFF_SESSION\"]}},\"description\":\"Request to create a payment method.\"},\"PaymentMethodResponse\":{\"type\":\"object\",\"properties\":{\"id\":{\"type\":\"string\",\"description\":\"The identifier of the payment method.\"},\"type\":{\"type\":\"string\",\"description\":\"The type of payment method.\",\"enum\":[\"CARD\",\"CARD_PRESENT\",\"GIFT_CARD\",\"GIFT_CARD_PRESENT\",\"US_BANK_ACCOUNT\"]},\"billingDetails\":{\"$ref\":\"#/components/schemas/BillingDetails\"},\"usage\":{\"type\":\"string\",\"nullable\":true,\"description\":\"Indicates whether the payment method is saved for future use.\\n* `ON_SESSION` - Saved for future customer-initiated transactions.\\n* `OFF_SESSION` - Saved for future merchant-initiated transactions.\\n* `ON_AND_OFF_SESSION` - Saved for both customer-initiated and merchant-initiated transactions.\\n\",\"enum\":[\"ON_SESSION\",\"OFF_SESSION\",\"ON_AND_OFF_SESSION\"]},\"card\":{\"$ref\":\"#/components/schemas/CardResponse\"}},\"description\":\"Response to create a payment method.\"},\"ErrorMessage\":{\"type\":\"object\",\"description\":\"An object that contains information about one or more errors that the Toast platform encountered when processing your API request. For more information, see [API responses and errors in the _Toast Developer Guide_](https://doc.toasttab.com/doc/devguide/apiResponsesAndErrors.html).\",\"properties\":{\"status\":{\"type\":\"integer\",\"description\":\"The HTTP status code of the response.\",\"format\":\"int32\"},\"code\":{\"type\":\"integer\",\"description\":\"A numeric identifier for the error condition.\",\"format\":\"int32\"},\"message\":{\"type\":\"string\",\"description\":\"A description of the error condition.\"},\"messageKey\":{\"type\":\"string\",\"description\":\"Reserved for future use.\"},\"fieldName\":{\"type\":\"string\",\"description\":\"Reserved for future use.\"},\"link\":{\"type\":\"string\",\"description\":\"Reserved for future use.\"},\"requestId\":{\"type\":\"string\",\"description\":\"The unique identifier of the HTTP request that your client sent to the Toast API.\"},\"developerMessage\":{\"type\":\"string\",\"description\":\"Additional detail about the error condition, if it is available.\"},\"errors\":{\"type\":\"array\",\"description\":\"A JSON array of `ErrorMessage` objects.\",\"items\":{\"$ref\":\"#/components/schemas/ErrorMessage\"}},\"canRetry\":{\"type\":\"boolean\",\"description\":\"Indicates whether you can retry the operation that caused the error.\"}}},\"DetachPaymentMethodRequest\":{\"type\":\"object\",\"properties\":{\"customerId\":{\"type\":\"string\",\"description\":\"The unique identifier for the customer record that identifies the customer in the\\nToast platform. The identifier is used to retrieve the payment cards\\nsaved to a customer’s profile.\\n\"}},\"description\":\"Request to detach a payment method from a customer record.\"},\"DetachPaymentMethodResponse\":{\"type\":\"object\",\"description\":\"Response to detach a payment method from a customer record.\",\"properties\":{\"id\":{\"type\":\"string\",\"description\":\"The identifier of the payment method.\"},\"type\":{\"type\":\"string\",\"description\":\"The type of payment method.\"},\"card\":{\"description\":\"Card details. Present when `type` is `CARD`.\",\"allOf\":[{\"$ref\":\"#/components/schemas/CardResponse\"}]}}},\"Mandate\":{\"type\":\"object\",\"properties\":{\"id\":{\"type\":\"string\",\"format\":\"uuid\",\"description\":\"The identifier of the mandate.\"},\"customerId\":{\"type\":\"string\",\"format\":\"uuid\",\"description\":\"The unique identifier for the customer record that identifies the customer in the Toast platform.\"},\"paymentMethodId\":{\"type\":\"string\",\"format\":\"uuid\",\"description\":\"The identifier of the payment method.\"},\"originalTransactionId\":{\"type\":\"string\",\"format\":\"uuid\",\"description\":\"The identifier of the original transaction that established the customer consent to authorize the payment card to be used for merchant-initiated transactions.\"},\"standingInstructionType\":{\"$ref\":\"#/components/schemas/StandingInstructionType\"},\"status\":{\"$ref\":\"#/components/schemas/MandateStatus\"},\"createdAt\":{\"type\":\"string\",\"format\":\"date-time\",\"description\":\"The date and time the mandate was created and the customer consented to authorize the payment card to be used for merchant-initiated transactions in ISO 8601 format.\"},\"externalReferenceId\":{\"type\":\"string\",\"description\":\"The optional reference identifier for the consent agreement language.\"}}},\"StandingInstructionType\":{\"type\":\"string\",\"enum\":[\"INSTALLMENT\",\"RECURRING\",\"UNSCHEDULED\"],\"description\":\"The instruction type used by the merchant and sent to the payment processor.\"},\"MandateStatus\":{\"type\":\"string\",\"enum\":[\"ACTIVE\",\"INACTIVE\"],\"description\":\"The status of the mandate. An `ACTIVE` mandate authorizes the payment card to be used for merchant-initiated transactions. An `INACTIVE` mandate indicates that the customer has revoked their consent to authorize the payment card to be used for merchant-initiated transactions.\"},\"BillingDetails\":{\"type\":\"object\",\"description\":\"Billing details associated with a payment method.\",\"properties\":{\"postalCode\":{\"type\":\"string\",\"description\":\"The postal or ZIP code.\"},\"country\":{\"type\":\"string\",\"description\":\"The country code.\"},\"name\":{\"type\":\"string\",\"description\":\"The billing name.\"},\"phone\":{\"type\":\"string\",\"description\":\"The billing phone number.\"},\"city\":{\"type\":\"string\",\"description\":\"The billing city.\"},\"state\":{\"type\":\"string\",\"description\":\"The billing state or province.\"},\"email\":{\"type\":\"string\",\"description\":\"The billing email address.\"},\"address\":{\"type\":\"object\",\"description\":\"The billing street address.\",\"properties\":{\"addressLine1\":{\"type\":\"string\",\"description\":\"The first line of the street address.\"},\"addressLine2\":{\"type\":\"string\",\"description\":\"The second line of the street address.\"}}}}}},\"securitySchemes\":{\"OAuth2\":{\"type\":\"oauth2\",\"flows\":{\"clientCredentials\":{\"tokenUrl\":\"/authentication/v1/authentication/customer/oauth/token\",\"scopes\":{\"simplified-payments-integration:write\":\"payment method write access\",\"simplified-payments-integration.server:write\":\"payment method write access\",\"simplified-payments-integration.server:read\":\"payment method read access\",\"payment-data-tokenizer.payment-method:read\":\"payment method read access\",\"payment-data-tokenizer.payment-methods.tokens:read\":\"read tokens inside a payment method\",\"payment-data-tokenizer.payment-method.pii:read\":\"read PII data (e.g., cardHolderName, billingDetails) in payment method responses\"}}}}}}}},\"options\":{\"hideTryItPanel\":true,\"pagination\":\"item\",\"generateCodeSamples\":{\"languages\":[{\"lang\":\"curl\"},{\"lang\":\"Java\"},{\"lang\":\"Python\"},{\"lang\":\"Node.js\"},{\"lang\":\"C#\"}]},\"showConsole\":false,\"hideHostname\":true,\"hideDownloadButton\":true,\"sortPropsAlphabetically\":true,\"schemaDefinitionsTagName\":\"Data definitions\",\"disableSearch\":true,\"ctrlFHijack\":false,\"disableSidebar\":true,\"theme\":{\"overrides\":{\"DownloadButton\":{\"custom\":\"\"},\"NextSectionButton\":{\"custom\":\"\"}},\"codeBlock\":{\"tokens\":{}},\"schema\":{\"constraints\":{},\"examples\":{}},\"rightPanel\":{\"textColor\":\"#eeeeee\"},\"typography\":{\"heading1\":{},\"heading2\":{},\"heading3\":{},\"rightPanelHeading\":{}}}}}","redocHasSecurityDefinitions":false,"redocInfoPageLink":"/payment-methods/overview/","redocItemId":"tag/Data-definitions/schema/BillingDetails","redocHasInfoPage":false,"settings":{"generateCodeSamples":{"languages":[{"lang":"curl"},{"lang":"Java"},{"lang":"Python"},{"lang":"Node.js"},{"lang":"C#"}]},"showConsole":false,"hideHostname":true,"hideDownloadButton":true,"sortPropsAlphabetically":true,"schemaDefinitionsTagName":"Data definitions","hideTryItPanel":true},"requestLogin":false,"lastModified":"2024-08-01T13:41:19.000Z"},"seo":{"title":"BillingDetails"}}},"pageContext":{"id":"e431fe31-53f2-5d45-8704-126c975b5a5btag/Data-definitions/schema/BillingDetails/__redocly content/payment-methods/tag/Data-definitions/schema/BillingDetails/","seo":{"title":"BillingDetails","description":"<SchemaDefinition showWriteOnly={true} schemaRef=\"#/components/schemas/BillingDetails\" />","image":"","keywords":null,"jsonLd":null,"lang":null},"pageId":"payment-methods.reference.page.yaml#tag/Data-definitions/schema/BillingDetails/","pageBaseUrl":"/payment-methods","type":"redoc-operation","toc":{"enable":true,"maxDepth":4,"headings":null},"data":{},"catalogInfo":null,"link":"/payment-methods/tag/Data-definitions/schema/BillingDetails/","sidebarName":"api-reference","isLanding":false,"showPrevButton":null,"showNextButton":null,"apiVersions":[{"definitionId":"paymentMethods","id":"paymentMethods","title":"paymentMethods","isDefault":true,"apiId":null}],"apiVersionId":null,"isDefaultApiVersion":true}},"staticQueryHashes":["1123603147","1180902673","1302185487","1344209882","1398840060","1520077861","1975142765","2667623876","2950305614","3743992808","561138138"]}