Toast Merchants API

openapi: 3.2.0
info:
  title: Credit Cards Merchants API
  description: "A simple, single request, synchronous API to authorize credit card \ntransactions associated with an orders API order.\n"
  version: 1.0.0
  contact:
    name: Toast developer support
servers:
- url: https://toast-api-server/ccpartner/v1
tags:
- name: Merchants
paths:
  /merchants/{merchantUuid}/payments/{paymentUuid}:
    put:
      operationId: merchantsMerchantUuidPaymentsPaymentUuidPut
      summary: Authorize a credit card
      description: 'Authorize a credit card payment. Funds will be held until the

        payment is voided or captured.


        You must submit an orders API request to apply the payment to a

        check within five minutes of authorization, otherwise the

        payment is automatically voided.


        Payment must be captured within seven days of authorization,

        otherwise the payment is automatically voided. Capture

        occurs the evening after the order is fulfilled by the

        restaurant.

        '
      parameters:
      - name: merchantUuid
        in: path
        description: 'The Toast GUID of the merchant (restaurant) that will

          receive the payment. This is the same value as the

          Toast-Restaurant-External-ID.

          '
        required: true
        schema:
          type: string
      - name: paymentUuid
        in: path
        description: 'The unique identifier (UID) of this authorization,

          generated by the restaurant organization or integration

          partner.

          '
        required: true
        schema:
          type: string
      - name: Toast-Restaurant-External-ID
        in: header
        description: 'The GUID of the restaurant used as the context of the request.

          '
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentAuthorization'
        description: The authorization request, including encrypted credit card information and payment details.
        required: true
      responses:
        '200':
          description: The authorization request was processed. See the response for details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentStatus'
        '400':
          description: The request was not valid. A required field may be missing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToastError'
        '404':
          description: The merchant (restaurant) does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToastError'
        '409':
          description: 'An authorization request was already made for this payment

            UUID. Verify that you are generating unique payment UUIDs

            for each request.  This can also occur if the same request

            is resubmitted, but the state has since been changed by

            another system (for example, voided on the POS).

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToastError'
        '422':
          description: 'The request failed validation. The structure is not

            correct. A message with more information is returned if

            using the certification environment.

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToastError'
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToastError'
      security:
      - oauth2:
        - credit_cards.authorization:write
      tags:
      - Merchants
components:
  schemas:
    ToastError:
      description: Contains error details.
      type: object
      properties:
        description:
          type: string
          description: A human-readable description of the problem.
        detail:
          type: string
          description: Error details, such as an exception and stack trace.
      required:
      - description
    PartnerServiceInfo:
      required:
      - instanceId
      description: 'Information about the client that made the payment request. This

        information can be used for troubleshooting problems.

        '
      type: object
      properties:
        instanceId:
          type: string
          description: 'An identifier for the client that made the authorization

            request. For example, this might be a partner service

            instance ID that is visible in log messages.

            '
        additionalInfo:
          type: string
          description: 'Additional information about the service. For example, this

            might be a JSON structure containing the IP address and

            service version.

            '
    BillingAddress:
      description: 'An international billing address including name and phone number.

        A `BillingAddress` object for a `PaymentRequestMetadata` `billingAddress`

        value must exactly match address information you provide in encrypted

        credit card data.

        '
      type: object
      required:
      - postalCode
      - country
      properties:
        name:
          type: string
          description: 'The name attached to the billing address. This is not necessarily

            the same as the name on the card.

            '
        phone:
          type: string
          description: 'The phone number associated with the account in [E.164 format](https://www.itu.int/rec/T-REC-E.164).

            '
        address1:
          type: string
          description: Line 1 of the address
        address2:
          type: string
          description: Line 2 of the address
        city:
          type: string
          description: City of the address
        region:
          type: string
          description: Region or state of the address
        postalCode:
          type: string
          description: 'Postal or ZIP code. If using a code with an extra four digits,

            for example a US ZIP+4 code, do not separate the extra digits.

            For example, `123451234`.

            '
        country:
          type: string
          description: Country code using the ISO 3166-1 alpha-3 standard
    PaymentAuthorization:
      description: A request to authorize a credit card payment.
      type: object
      required:
      - cardNumberOrigin
      - willSaveCard
      - encryptedCardData
      - amount
      - tipAmount
      - requestMetadata
      - keyId
      properties:
        cardNumberOrigin:
          type: string
          enum:
          - END_USER
          - PARTNER_VAULT
          description: "The way that the credit card was provided for the payment\nrequest. The value is `END_USER` if the cardholder entered\nthe card number (PAN) as part of a web order. The value is\n`PARTNER_VAULT` if the PAN was retrieved from a vault\ncontrolled by the integration partner.\n\nThis value is used with `willSaveCard` to report information \nabout stored credit card numbers to credit card provider \nnetworks. If your organization is using stored credit card \ninformation for a credit card authorization, this value must \nbe `PARTNER_VAULT`. The default value is `END_USER`.\n"
        willSaveCard:
          type: boolean
          description: "Indicates whether your organization will save the restaurant \nguests' credit card information for future use.\n\nToast reports information about stored credit card information \nto some credit card providers. This \"card on file\" or \"stored \ncredentials\" reporting is required by some credit card provider \nnetworks. These networks may impose fees for non-compliance \nwith \"card on file\" reporting requirements.\n\nNote that integration partners are responsible for any and \nall fees incurred, and must comply with all applicable law \nand rules relevant to, \"card on file\" consent, storage, use \nand reporting requirements in accordance with card brand \nregulations and the integration partner agreement.\n"
        encryptedCardData:
          type: object
          description: 'A base64-encoded version of the encrypted card data payload.

            For information about encrypting and encoding credit card

            information, see the <cite>Toast API Developer''s

            Guide</cite>.

            '
        amount:
          type: number
          format: double
          description: 'The check price that should be charged to the credit card,

            not including the tip. For example, the value `10.00`

            represents ten USD and zero cents. The `amount` must not be

            negative. The total of the `amount` value and the `tipAmount`

            value must be greater than zero.

            '
        keyId:
          type: string
          description: "The identifier of the encryption key and algorithm used \nto encrypt the credit card data. Toast integration support \nprovides this identifier along with the encryption key \nitself. If you received an encryption key before June 2018,\nyou may omit this field. For all API users, supplying a\nkeyId value prevents downtime during key rotations.\n"
        tipAmount:
          type: number
          format: double
          description: 'The tip that should be charged to the credit card. For

            example, the value `1.00` represents one USD and zero cents.

            The tip amount must not be negative. The total of the `amount`

            value and the `tipAmount` value must be greater than zero.

            '
        requestMetadata:
          $ref: '#/components/schemas/PaymentRequestMetadata'
    AuthorizationMetadata:
      description: 'Additional details about a payment, typically displayed on a receipt

        and logged by the partner.

        '
      type: object
      required:
      - localTransactionDate
      - cardBrand
      - authorizationCode
      - last4
      properties:
        localTransactionDate:
          type: string
          format: date-time
          description: 'A copy of the `localTransactionDate` provided by the partner, in ISO 8601 format.

            '
        cardBrand:
          type: string
          description: The brand of the credit card. For example, AMEX, Discover, Visa, or Mastercard.
        authorizationCode:
          type: string
          description: 'A code generated by card processing networks upon accepting an

            authorization request.

            '
        last4:
          type: string
          description: 'The final four digits of the credit card number.

            '
    PaymentRequestMetadata:
      description: Metadata about the request being made.
      type: object
      required:
      - partnerServiceInfo
      - localTransactionDate
      - originIPAddr
      - cardFirst6
      - cardLast4
      - billingAddress
      - guestIdentifier
      properties:
        partnerServiceInfo:
          $ref: '#/components/schemas/PartnerServiceInfo'
        localTransactionDate:
          type: string
          format: date-time
          description: "The date and time, in ISO 8601 format, when the guest presents their credit card. \n"
        originIPAddr:
          type: string
          description: The public ipv4 or ipv6 address of the cardholder making the payment. The origin IP address is essential for detecting and preventing fraud attempts in credit card authorization requests. To prevent disruption to your transaction workflow, ensure the correct origin IP address is used.
        cardFirst6:
          type: string
          description: 'The first six digits of the credit card number. The first six

            digits are the bank identification number (BIN) for the card.

            Must exactly match that provided in the encrypted card data.

            '
        cardLast4:
          type: string
          description: 'The last four digits of the credit card number. Must exactly

            match that provided in the encrypted card data.

            '
        billingAddress:
          $ref: '#/components/schemas/BillingAddress'
        deliveryAddress:
          $ref: '#/components/schemas/DeliveryAddress'
        userAgent:
          type: string
          description: 'For payments taken through a browser, the browser''s user agent string.

            '
        guestIdentifier:
          type: string
          description: 'An identifier for the guest making the payment such as

            an email address or phone number. Must consist of the following characters:

            `a-z, A-Z, 0-9, =, ., -, _, +, @, :, &, ^, %, !, $`

            '
        guestEmail:
          type: string
          description: 'The email address of the guest placing the payment.

            '
        appName:
          type: string
          description: 'A company-specific name for the mobile app (if any) the payment is made through.

            For instance, use ''MyCompany Android App'' instead of ''Android App''

            '
        appVersion:
          type: string
          description: 'The version of the mobile app (if any) the payment is made through.

            You can use any string to represent the app version. There are no

            format or content requirements.

            '
    PaymentStatus:
      description: Status of a payment.
      type: object
      required:
      - paymentState
      properties:
        paymentState:
          type: string
          enum:
          - AUTHORIZED
          - ACKNOWLEDGED
          - DENIED
          description: 'The state of the payment. Toast may add values to this field.

            Make sure that your implementation can handle additional

            values.

            '
        authorizationMetadata:
          $ref: '#/components/schemas/AuthorizationMetadata'
        amount:
          description: The amount of this payment, not including tip.
          type: object
        tipAmount:
          description: The tip amount of this payment.
          type: object
        denialReason:
          description: The reason a payment was denied. This must be displayed to the consumer.
          type: string
        error:
          type: string
          description: If the payment is in an error state, this will contain the error.
    DeliveryAddress:
      description: 'A generic international delivery address including name and phone number.

        '
      type: object
      required:
      - address1
      - city
      - region
      - postalCode
      - country
      properties:
        name:
          type: string
          description: 'The name associated with the address.

            '
        phone:
          type: string
          description: 'The phone number associated with the account in [E.164 format](https://www.itu.int/rec/T-REC-E.164).

            '
        address1:
          type: string
          description: Line 1 of the address
        address2:
          type: string
          description: Line 2 of the address
        city:
          type: string
          description: City of the address
        region:
          type: string
          description: Region or state of the address
        postalCode:
          type: string
          description: 'Postal or ZIP code. If using a code with an extra four digits,

            for example a US ZIP+4 code, do not separate the extra digits.

            For example, `123451234`.

            '
        country:
          type: string
          description: Country code using the ISO 3166-1 alpha-3 standard
  securitySchemes:
    oauth2:
      description: "Access to Toast APIs, specific endpoints, \nand specific API endpoint operations is \ncontrolled by the scopes that are associated \nwith your API account. \nA full reference for Toast API scopes and \ntheir capabilities can be found in the\n[_Toast Developer Guide_](https://doc.toasttab.com/doc/devguide/apiScopes.html).\n"
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://toast-api-server/authentication/v1/authentication/login
          scopes:
            credit_cards.authorization:write: 'Allows authorization of payments through the credit cards API.

              '