openapi: 3.2.0
info:
  title: Teya APIs for external plugins Pay By Link API
  version: 1.0.0
  description: APIs that external plugins can access
  name: Teya
tags:
- description: APIs exposed for pay by link customers
  name: Pay by Link
  x-displayName: PayByLink
paths:
  /v2/payment-links:
    post:
      description: 'API to create a new payment link.


        Access Token Required scope: payment-links/create'
      operationId: createPaymentLinkV2
      parameters:
      - description: 'A unique key to identify the request.

          If the request is repeated with the same key, the same response will be returned.

          If the request is repeated with a different key or without a key, a new session will be created.

          '
        in: header
        name: Idempotency-Key
        required: true
        schema:
          description: 'A unique key to identify the request.

            If the request is repeated with the same key, the same response will be returned.

            If the request is repeated with a different key or without a key, a new session will be created.

            '
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/pbl_CreatePaymentLinkRequestV2'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pbl_CreatePaymentLinkResponse'
          description: New payment link has been created
        '400':
          content:
            application/json:
              example:
                code: BAD_REQUEST
                description: Bad Request
          description: Bad request
        '401':
          content:
            application/json:
              example:
                code: UNAUTHORISED
                description: Unauthorised
          description: Lacks valid authentication credentials for the requested resource
        '403':
          content:
            application/json:
              example:
                code: FORBIDDEN
                description: Forbidden
          description: The server understands the request but refuses to authorise it
        '429':
          content:
            application/json:
              example:
                code: TOO_MANY_REQUESTS
                description: Too Many Requests
          description: Too many requests in a given amount of time
        '500':
          content:
            application/json:
              example:
                code: INTERNAL_SERVER_ERROR
                description: Internal Server Error
          description: Internal Server Error
      security:
      - pbl_oauth_dev: []
      - pbl_oauth_prd: []
      summary: Creates a new payment link
      tags:
      - Pay by Link
  /v1/payment-links/{payment_link_id}:
    get:
      description: 'API to get a payment link by id.


        Access Token Required scope: payment-links/id/get'
      operationId: getPaymentLink
      parameters:
      - description: The payment link id
        in: path
        name: payment_link_id
        required: true
        schema:
          description: A unique identifier for the created payment link
          example: 20eb276c-5b6b-4474-a5a1-49bcd6193148
          format: uuid
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pbl_GetPaymentLinkResponse'
          description: a payment link has been returned
        '400':
          content:
            application/json:
              example:
                code: BAD_REQUEST
                description: Bad Request
          description: Bad request
        '401':
          content:
            application/json:
              example:
                code: UNAUTHORISED
                description: Unauthorised
          description: Lacks valid authentication credentials for the requested resource
        '403':
          content:
            application/json:
              example:
                code: FORBIDDEN
                description: Forbidden
          description: The server understands the request but refuses to authorise it
        '404':
          content: {}
          description: payment link not found
        '429':
          content:
            application/json:
              example:
                code: TOO_MANY_REQUESTS
                description: Too Many Requests
          description: Too many requests in a given amount of time
        '500':
          content:
            application/json:
              example:
                code: INTERNAL_SERVER_ERROR
                description: Internal Server Error
          description: Internal Server Error
      security:
      - pbl_oauth_dev: []
      - pbl_oauth_prd: []
      summary: Gets a payment link by id
      tags:
      - Pay by Link
  /v2/payment-links/{payment_link_id}:
    patch:
      description: 'Updates mutable properties of a payment link.

        Currently supports updating expiration timestamp.


        Access Token Required scope: payment-links/id/update'
      operationId: updatePaymentLink
      parameters:
      - description: The payment link id
        in: path
        name: payment_link_id
        required: true
        schema:
          description: A unique identifier for the created payment link
          example: 20eb276c-5b6b-4474-a5a1-49bcd6193148
          format: uuid
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/pbl_UpdatePaymentLinkRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/pbl_GetPaymentLinkResponse'
          description: Payment link updated successfully
        '400':
          content:
            application/json:
              example:
                code: BAD_REQUEST
                description: Bad Request
          description: Bad request
        '401':
          content:
            application/json:
              example:
                code: UNAUTHORISED
                description: Unauthorised
          description: Lacks valid authentication credentials for the requested resource
        '403':
          content:
            application/json:
              example:
                code: FORBIDDEN
                description: Forbidden
          description: The server understands the request but refuses to authorise it
        '404':
          content: {}
          description: Payment link not found
        '429':
          content:
            application/json:
              example:
                code: TOO_MANY_REQUESTS
                description: Too Many Requests
          description: Too many requests in a given amount of time
        '500':
          content:
            application/json:
              example:
                code: INTERNAL_SERVER_ERROR
                description: Internal Server Error
          description: Internal Server Error
      security:
      - pbl_oauth_dev: []
      - pbl_oauth_prd: []
      summary: Updates an existing payment link
      tags:
      - Pay by Link
components:
  schemas:
    pbl_DeliveryInfo:
      example:
        email: emailaddress@example.com
        phone_number: '+447700900123'
      properties:
        email:
          description: Email address to send the payment link to
          type: string
        phone_number:
          description: 'An international phone number  including the country code, formatted according to the E.164 standard.

            This is the phone number that we will use to share the payment link via SMS'
          type: string
      title: DeliveryInfo
      type: object
    pbl_UpdatePaymentLinkRequest:
      properties:
        expires_at:
          description: 'New expiration timestamp in ISO-8601 format.

            Expiration can be set up to 5 minutes in the past or any time in the future. Expiry in the past effectively cancels the link.

            These links can have their expiration changed if needed in the future again.

            Payment link must be in one of the following states to be updated: VALID, EXPIRED, or MANUALLY_EXPIRED.

            If not provided in the request, the expiration will not be updated.

            If provided as null, the expiration will be cleared.

            '
          example: '2026-07-03T13:37:58.709Z'
          format: date-time
          type: string
      title: UpdatePaymentLinkRequest
      type: object
    pbl_CreatePaymentLinkResponse:
      description: The created payment link information
      example:
        payment_link: https://pbl.teya.com/20eb276c-5b6b-4474-a5a1-49bcd6193148
        payment_link_id: 20eb276c-5b6b-4474-a5a1-49bcd6193148
      properties:
        payment_link:
          description: The created payment link
          format: url
          type: string
        payment_link_id:
          description: A unique identifier for the created payment link
          example: 20eb276c-5b6b-4474-a5a1-49bcd6193148
          format: uuid
          type: string
      required:
      - payment_link_id
      title: Create Payment Link Response
      type: object
    pbl_Amount:
      description: 'The transaction amount in the smallest currency unit according to ISO 4217 format.

        For example:

        - 100 ISK (Icelandic króna): the amount is 100 (since 1 ISK = 1 subunit).

        - 100 EUR (Euro): the amount is 10000 (since 1 EUR = 100 cents).

        - 100 USD (US Dollar): the amount is 10000 (since 1 USD = 100 cents).

        - 100 KWD (Kuwaiti Dinar): the amount is 100000 (since 1 KWD = 1000 fils).

        '
      example:
        currency: GBP
        value: 100
      properties:
        currency:
          description: Currency code (e.g. `USD`, `GBP`, `EUR`) following ISO-4217 format.
          enum:
          - AED
          - AFN
          - ALL
          - AMD
          - ANG
          - AOA
          - ARS
          - AUD
          - AWG
          - AZN
          - BAM
          - BBD
          - BDT
          - BGN
          - BHD
          - BIF
          - BMD
          - BND
          - BOB
          - BOV
          - BRL
          - BSD
          - BTN
          - BWP
          - BYN
          - BYR
          - BZD
          - CAD
          - CDF
          - CHE
          - CHF
          - CHW
          - CLF
          - CLP
          - CNY
          - COP
          - COU
          - CRC
          - CUC
          - CUP
          - CVE
          - CZK
          - DJF
          - DKK
          - DOP
          - DZD
          - EGP
          - ERN
          - ETB
          - EUR
          - FJD
          - FKP
          - GBP
          - GEL
          - GHS
          - GIP
          - GMD
          - GNF
          - GTQ
          - GYD
          - HKD
          - HNL
          - HRK
          - HTG
          - HUF
          - IDR
          - ILS
          - INR
          - IQD
          - IRR
          - ISK
          - JMD
          - JOD
          - JPY
          - KES
          - KGS
          - KHR
          - KMF
          - KPW
          - KRW
          - KWD
          - KYD
          - KZT
          - LAK
          - LBP
          - LKR
          - LRD
          - LSL
          - LYD
          - MAD
          - MDL
          - MGA
          - MKD
          - MMK
          - MNT
          - MOP
          - MRO
          - MRU
          - MUR
          - MVR
          - MWK
          - MXN
          - MXV
          - MYR
          - MZN
          - NAD
          - NGN
          - NIO
          - NOK
          - NPR
          - NZD
          - OMR
          - PAB
          - PEN
          - PGK
          - PHP
          - PKR
          - PLN
          - PYG
          - QAR
          - RON
          - RSD
          - RUB
          - RWF
          - SAR
          - SBD
          - SCR
          - SDG
          - SEK
          - SGD
          - SHP
          - SLE
          - SLL
          - SOS
          - SRD
          - SSP
          - STD
          - STN
          - SVC
          - SYP
          - SZL
          - THB
          - TJS
          - TMT
          - TND
          - TOP
          - TRY
          - TTD
          - TWD
          - TZS
          - UAH
          - UGX
          - USD
          - USN
          - UYI
          - UYU
          - UZS
          - VED
          - VEF
          - VES
          - VND
          - VUV
          - WST
          - XAF
          - XCD
          - XCG
          - XOF
          - XPF
          - YER
          - ZAR
          - ZMW
          - ZWL
          format: enum
          type: string
        value:
          description: The transaction amount in the smallest currency unit according to ISO 4217 format.
          format: int64
          maximum: 9223372036854
          type: integer
      required:
      - currency
      - value
      title: Transaction Amount
      type: object
    pbl_PaymentLinkLineItem:
      description: Basket information to be shown in payment page
      example:
        description: Shipping
        quantity: 1
        unit_price: 100
      properties:
        description:
          description: This a description for a item in the basket
          type: string
        quantity:
          description: The number of items, Must be a positive value
          format: int32
          type: integer
        unit_price:
          description: The price of a single item including VAT, Can be negative for discounts
          format: int32
          type: integer
      required:
      - description
      - quantity
      - unit_price
      title: PaymentLinkLineItem
      type: object
    pbl_GetPaymentLinkResponse:
      description: The requested payment link data
      example:
        amount:
          currency: USD
          value: 100
        billing_address:
          city: London
          country: GB
          street_address_line1: Main Street
          zipcode: SW1A1AA
        cancel_url: https://example.com/cancel
        customer:
          email: emailaddress@example.com
          name: John Doe
          phone_number: '+447911123456'
        customer_success_email: customer@example.com
        expires_at: '2024-07-03T13:37:58.709Z'
        line_items:
        - description: Product 1
          quantity: 1
          unit_price: 100
        merchant_reference: merchant-reference-id
        merchant_success_email: merchant@example.com
        metadata:
          order_id: '12345'
          table_number: '5'
        payment_link_id: 20eb276c-5b6b-4474-a5a1-49bcd6193148
        post_success_payment: REDIRECT
        required_customer_fields:
        - EMAIL
        - PHONE
        status: COMPLETED
        success_url: https://example.com/success
        supported_card_brands:
        - VISA
        - MASTERCARD
        supported_payment_methods:
        - CARD
      properties:
        amount:
          $ref: '#/components/schemas/pbl_Amount'
        billing_address:
          $ref: '#/components/schemas/pbl_AddressDto'
          description: Billing address provided at creation time
        cancel_url:
          description: URL to redirect to when the customer cancels the payment
          type: string
        customer:
          $ref: '#/components/schemas/pbl_Customer'
          description: Customer information provided at creation time
        customer_success_email:
          description: Email address to send customer success notification to
          type: string
        expires_at:
          description: Date when the link will be considered expired in ISO 8601 format
          format: date-time
          type: string
        line_items:
          description: Basket information to be shown in payment page
          items:
            $ref: '#/components/schemas/pbl_PaymentLinkLineItem'
          type: array
        merchant_reference:
          description: An identifier that can be used to reference the transaction on the merchant's side. Overrides 'source_reference_id
          example: '1234567890'
          maxLength: 60
          type: string
        merchant_success_email:
          description: Email address to send merchant success notification to
          type: string
        metadata:
          additionalProperties:
            type: string
          description: Metadata key-value pairs associated with the payment link
          type: object
        payment_link_id:
          description: A unique identifier for the created payment link
          example: 20eb276c-5b6b-4474-a5a1-49bcd6193148
          format: uuid
          type: string
        post_success_payment:
          description: Action to take after a successful payment
          enum:
          - SHOW_SUCCESS_PAGE
          - REDIRECT
          example: SHOW_SUCCESS_PAGE
          title: Post Success Payment Options
          type: string
        required_customer_fields:
          description: Customer fields that must be collected during checkout
          items:
            enum:
            - SHIPPING_ADDRESS
            - PHONE
            - EMAIL
            type: string
          uniqueItems: true
          type: array
        status:
          description: The status of the payment link
          enum:
          - VALID
          - COMPLETED
          - MANUALLY_EXPIRED
          - DISABLED
          - EXPIRED
          type: string
        success_url:
          description: URL to redirect to after a successful payment
          type: string
        supported_card_brands:
          description: Card brands supported for this payment link
          items:
            enum:
            - AMEX
            - MASTERCARD
            - VISA
            type: string
          uniqueItems: true
          type: array
        supported_payment_methods:
          description: Payment methods supported for this payment link
          items:
            enum:
            - CARD
            - TOKEN
            - APPLE_PAY
            type: string
          uniqueItems: true
          type: array
      required:
      - amount
      - payment_link_id
      - status
      title: GetPaymentLinkResponse
      type: object
    pbl_CreatePaymentLinkRequestV2:
      description: 'A request to create a payment link.

        When used with a user token, the field `store_id` is mandatory.

        When used with a terminal token, the field `delivery_info` is mandatory.

        '
      example:
        amount:
          currency: USD
          value: 100
        billing_address:
          city: London
          country: GB
          street_address_line1: Main Street
          zipcode: SW1A1AA
        cancel_url: https://mywebsite.com/checkout/cart
        customer:
          email: emailaddress@example.com
          name: John Doe
          phone_number: '+447911123456'
        customer_success_email: john.doe@example.com
        delivery_info:
          email: emailaddress@example.com
          phone_number: '+447700900123'
        expires_at: '2024-07-03T13:37:58.709Z'
        language: en-GB
        line_items:
        - description: Product 1
          quantity: 1
          unit_price: 100
        merchant_reference: '12345678'
        merchant_success_email: merchant@example.com
        metadata:
          order_id: '12345'
          table_number: '5'
        post_success_payment: REDIRECT
        required_customer_fields:
        - EMAIL
        - PHONE
        store_id: f47ac10b-58cc-4372-a567-0e02b2c3d479
        success_url: https://mywebsite.com/checkout/success
        supported_card_brands:
        - VISA
        - MASTERCARD
        supported_payment_methods:
        - CARD
        - APPLE_PAY
        transaction_type: SALE
        type: SINGLE_USE
      properties:
        amount:
          $ref: '#/components/schemas/pbl_Amount'
        billing_address:
          $ref: '#/components/schemas/pbl_AddressDto'
          description: Billing address of the customer. Ignored for MULTI_USE payment links.
        cancel_url:
          description: URL to redirect the customer once the transaction has finished with error or cancellation (must use HTTPS)
          type: string
        customer:
          $ref: '#/components/schemas/pbl_Customer'
          description: Customer information. Ignored for MULTI_USE payment links.
        customer_success_email:
          description: If present, an email is sent to the customer upon successful payment with the receipt.
          type: string
        delivery_info:
          $ref: '#/components/schemas/pbl_DeliveryInfo'
          description: Information needed to deliver the link to the merchant customer using email and/or SMS.
        expires_at:
          description: 'Date when the link will be considered expired in ISO 8601 format.

            If not provided, the payment link will not have an expiry date.

            '
          format: date-time
          type: string
        language:
          description: "The language that will be used to notify the client. It follows IETF BCP 47 and:\n - If provided, it should match any of the supported languages: en-GB, hu-HU, is-IS, cs-CZ, hr-HR, sk-SK, pt-PT, pt-BR, de-DE, es-ES, fr-FR, it-IT, pl-PL\nIf it's different, the request will be rejected with BAD_REQUEST\n - If not provided, the merchant language will be used"
          example: en-GB
          type: string
        line_items:
          description: Basket information to be shown in payment page
          items:
            $ref: '#/components/schemas/pbl_PaymentLinkLineItem'
          type: array
        merchant_reference:
          description: An identifier that can be used to reference the transaction on the merchant's side. Overrides 'source_reference_id
          example: '1234567890'
          maxLength: 60
          type: string
        merchant_success_email:
          description: If present, an email is sent to the merchant upon successful payment with the receipt.
          type: string
        metadata:
          additionalProperties:
            type: string
          description: Metadata key-value pairs. Maximum 10 keys allowed. Keys must not exceed 40 characters and values must not exceed 500 characters.
          type: object
        post_success_payment:
          description: Defines the behavior after a successful payment. SHOW_SUCCESS_PAGE displays a success page, REDIRECT redirects to the success_url.
          enum:
          - SHOW_SUCCESS_PAGE
          - REDIRECT
          example: SHOW_SUCCESS_PAGE
          format: enum
          title: Post Success Payment Options
          type: string
        required_customer_fields:
          description: Customer fields that must be collected during checkout
          items:
            enum:
            - SHIPPING_ADDRESS
            - PHONE
            - EMAIL
            type: string
          uniqueItems: true
          type: array
        store_id:
          description: The unique identifier of a store
          example: f47ac10b-58cc-4372-a567-0e02b2c3d479
          format: uuid
          title: Store Id
          type: string
        success_url:
          description: URL to redirect the customer once the transaction has successfully finished (must use HTTPS)
          type: string
        supported_card_brands:
          description: Array of supported card brands. If null, defaults to all card brands enabled for the store.
          items:
            enum:
            - AMEX
            - MASTERCARD
            - VISA
            type: string
          uniqueItems: true
          type: array
        supported_payment_methods:
          description: Array of supported payment methods. If null, defaults to all payment methods enabled for the store.
          items:
            enum:
            - CARD
            - TOKEN
            - APPLE_PAY
            type: string
          uniqueItems: true
          type: array
        transaction_type:
          description: 'Indicates the transaction type. Default is SALE.

            Identifies the transaction type. Use SALE for standard payments, PRE_AUTHORISATION to reserve funds for later capture, or ACCOUNT_VERIFICATION to verify and tokenize a card without charging.

            '
          enum:
          - SALE
          - PRE_AUTHORISATION
          - ACCOUNT_VERIFICATION
          example: SALE
          format: enum
          type: string
        type:
          description: Indicates the payment link type. Default is SINGLE_USE.
          enum:
          - SINGLE_USE
          example: SINGLE_USE
          format: enum
          type: string
      required:
      - amount
      title: CreatePaymentLinkRequestV2
      type: object
    pbl_AddressDto:
      description: An address
      example:
        city: London
        country: GB
        state: London
        street_address_line1: Main Street
        street_address_line2: No. 1
        street_address_line3: Building 1
        zipcode: SW1A1AA
      properties:
        city:
          description: City name
          example: London
          maxLength: 100
          type: string
        country:
          description: ISO-3166-1 alpha2 country code
          example: GB
          type: string
        state:
          description: State or province
          example: London
          maxLength: 100
          type: string
        street_address_line1:
          description: Street address line 1
          example: Main Street
          maxLength: 100
          type: string
        street_address_line2:
          description: Street address line 2
          example: No. 1
          maxLength: 100
          type: string
        street_address_line3:
          description: Street address line 3
          example: Building 1
          maxLength: 100
          type: string
        zipcode:
          description: Postal/ZIP code
          example: SW1A1AA
          maxLength: 16
          type: string
      required:
      - country
      title: Address
      type: object
    pbl_Customer:
      example:
        email: emailaddress@example.com
        name: John Doe
        phone_number: '+447911123456'
      properties:
        email:
          description: Customer email address
          type: string
        name:
          description: Customer name, used to prefill the hosted checkout form
          type: string
        phone_number:
          description: 'Customer phone number.

            An international phone number including the country code, formatted according to the E.164 standard.

            '
          type: string
      title: Customer Information
      type: object
  securitySchemes:
    checkout_oauth_dev:
      flows:
        authorizationCode:
          authorizationUrl: https://id.teya.xyz/oauth/v2/oauth-authorize
          scopes: {}
          tokenUrl: https://id.teya.xyz/oauth/v2/oauth-token
        clientCredentials:
          scopes: {}
          tokenUrl: https://id.teya.xyz/oauth/v2/oauth-token
      type: oauth2
    checkout_oauth_prd:
      flows:
        authorizationCode:
          authorizationUrl: https://id.teya.com/oauth/v2/oauth-authorize
          scopes: {}
          tokenUrl: https://id.teya.com/oauth/v2/oauth-token
        clientCredentials:
          scopes: {}
          tokenUrl: https://id.teya.com/oauth/v2/oauth-token
      type: oauth2
    Ecommerce_Transaction_Payments_-_Public_oauth:
      flows:
        authorizationCode:
          authorizationUrl: https://id.teya.com/oauth/v2/oauth-authorize
          scopes: {}
          tokenUrl: https://id.teya.com/oauth/v2/oauth-token
        clientCredentials:
          scopes: {}
          tokenUrl: https://id.teya.com/oauth/v2/oauth-token
      type: oauth2
    pbl_oauth_dev:
      flows:
        authorizationCode:
          authorizationUrl: https://id.teya.xyz/oauth/v2/oauth-authorize
          scopes: {}
          tokenUrl: https://id.teya.xyz/oauth/v2/oauth-token
        clientCredentials:
          scopes: {}
          tokenUrl: https://id.teya.xyz/oauth/v2/oauth-token
      type: oauth2
    pbl_oauth_prd:
      flows:
        authorizationCode:
          authorizationUrl: https://id.teya.com/oauth/v2/oauth-authorize
          scopes: {}
          tokenUrl: https://id.teya.com/oauth/v2/oauth-token
        clientCredentials:
          scopes: {}
          tokenUrl: https://id.teya.com/oauth/v2/oauth-token
      type: oauth2
    Teya_Digital_Receipts_Service_oauth_prd:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://id.teya.com/oauth/v2/oauth-authorize
          tokenUrl: https://id.teya.com/oauth/v2/oauth-token
          scopes: {}
    Payments_Refunds_Wrapper_API_oauth_prd:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://id.teya.com/oauth/v2/oauth-token
          scopes:
            terminal: ''
        authorizationCode:
          authorizationUrl: https://id.teya.com/oauth/v2/oauth-authorize
          tokenUrl: https://id.teya.com/oauth/v2/oauth-token
          scopes: {}