openapi: 3.0.3
info:
  title: PayByLink API
  description: >-
    This is an API reference for the PayByLink service. The PayByLink API
    enables you to programmatically generate secure payment links for your
    customers with comprehensive configuration options for payment methods,
    customer data collection, and post-payment behaviours.
  version: 1.0.0
servers:
  - url: https://api-services.pxp.io/api/v1
    description: Production environment
  - url: https://api-services.test.pxp.io/api/v1
    description: Sandbox environment
paths:
  /paybylink:
    post:
      summary: Create a payment link
      description: >-
        Generate a secure payment link for customers. Supports both single-use
        and multi-use payment links with comprehensive configuration options for
        payment methods, customer data collection, and post-payment behaviours.
      operationId: create-payment-link
      security:
        - PXP-UST1: []
      parameters:
        - name: X-Request-Id
          in: header
          required: true
          description: UUID v4 request identifier.
          schema:
            type: string
            format: uuid
            example: 550e8400-e29b-41d4-a716-446655440000
        - name: X-Client-Id
          in: header
          required: true
          description: Your merchant client identifier.
          schema:
            type: string
            example: b14d0efd-b57f-470a-932d-c5d8517ff021
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PayByLinkCreateRequest'
      responses:
        '200':
          description: Payment link created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayByLinkCreateResponse'
              examples:
                Payment link creation response:
                  value:
                    linkId: 06da69e0-b668-40b2-ba2f-6c505f08866c
                    url: >-
                      https://paybylink.dev.pxp.io/06da69e0-b668-40b2-ba2f-6c505f08866c
                    status: Active
                    expirationTimestamp: '2025-09-11T04:12:15.3044876Z'
                    site: site-1
                    amounts:
                      transaction: 180
                      currencyCode: USD
                    merchantTransactionId: bbb958c6-37bc-47e3-8dd3-6122d4e361d5
                    merchantShopperId: CUST_001
                    afterPaymentConfiguration:
                      afterPaymentConfigurationType: Redirect
                      redirectUrl: https://localhost:5325/api/v1/paybylink
                      customMessage: custom message
        '400':
          description: Bad request - Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Missing required fields:
                  value:
                    errorCode: INVALID_REQUEST
                    errorReason: One or more validation errors occurred.
                    correlationId: 38f49f03-8e42-46db-9f3d-da3428a039be
                    details:
                      - '''amounts'' - The amounts field is required.'
                      - '''products'' - The products field is required.'
                      - >-
                        'linkConfiguration' - The linkConfiguration field is
                        required.
                Invalid currency code:
                  value:
                    errorCode: INVALID_REQUEST
                    errorReason: One or more validation errors occurred.
                    correlationId: 38f49f03-8e42-46db-9f3d-da3428a039be
                    details:
                      - >-
                        'amounts.currencyCode' - The amounts.currencyCode must
                        be exactly 3 letters.
        '401':
          description: Unauthorised - Invalid or missing authorization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Not authenticated:
                  value:
                    errorCode: NOT_AUTHENTICATED
                    errorReason: Missing authorization data!
                    correlationId: 0ebd78cf-06b7-4266-927e-91b6113ecea1
                    details: []
        '404':
          description: Not found - Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Site not found:
                  value:
                    errorCode: OBJECT_NOT_FOUND
                    errorReason: Site not found for [Site=invalid-site].
                    correlationId: a5478447-da2f-4802-b6e5-277a441cee65
                    details: []
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    PXP-UST1:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        PXP-UST1 authentication with HMAC-SHA256 signature. Format: PXP-UST1
        {tokenId}:{timestamp}:{hmac}
  schemas:
    PayByLinkCreateRequest:
      type: object
      required:
        - merchantTransactionId
        - amounts
        - products
        - linkConfiguration
        - shopper
        - site
        - merchant
        - intent
        - avs
      properties:
        merchantTransactionId:
          type: string
          maxLength: 50
          description: A unique identifier for this transaction.
          example: ORDER-2025-001
        amounts:
          $ref: '#/components/schemas/PaymentAmounts'
        products:
          type: array
          minItems: 1
          description: Array of product information for display on the payment page.
          items:
            $ref: '#/components/schemas/Product'
        linkConfiguration:
          $ref: '#/components/schemas/LinkConfiguration'
        shopper:
          $ref: '#/components/schemas/Shopper'
        site:
          type: string
          description: Your merchant site identifier from your PXP configuration.
          example: site-1
        merchant:
          type: string
          description: Your merchant identifier from your PXP configuration.
          example: merchant-1
        intent:
          type: string
          enum:
            - Purchase
            - Authorisation
            - EstimatedAuthorisation
          description: The transaction intent. [Learn more](how-it-works#intents).
          example: Purchase
        avs:
          $ref: '#/components/schemas/AddressVerificationSystem'
        allowedFundingTypes:
          $ref: '#/components/schemas/AllowedFundingTypes'
        afterPaymentConfiguration:
          $ref: '#/components/schemas/AfterPaymentConfiguration'
      description: >-
        Request payload to create a PayByLink. Contains all necessary
        information to generate a secure payment link.
    PaymentAmounts:
      type: object
      required:
        - transaction
        - currencyCode
      properties:
        transaction:
          type: number
          format: decimal
          minimum: 0.01
          description: The transaction amount.
          example: 29.99
        currencyCode:
          type: string
          minLength: 3
          maxLength: 3
          pattern: ^[A-Z]{3}$
          description: The currency code, in ISO 4217 format.
          example: USD
      description: Details about the payment amount and currency.
    Product:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          maxLength: 100
          description: The product name.
          example: Premium Widget
        description:
          type: string
          maxLength: 500
          description: The product description.
          example: High-quality widget with advanced features
        productImageUrl:
          type: string
          format: uri
          pattern: ^https://
          description: The URL of the product image.
          example: https://example.com/product-image.jpg
      description: Product information for the payment link
    LinkConfiguration:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - SingleUse
            - OpenUse
          description: The type of link to create.
          example: SingleUse
        name:
          type: string
          maxLength: 100
          description: >-
            A human-readable link name. This is solely for display purposes in
            the Unity Portal, for easier identification.
          example: Invoice Payment Link
        expiresInHours:
          type: integer
          minimum: 1
          description: The number of hours until the link expires.
          example: 72
      description: Details about the link behaviour.
    Shopper:
      type: object
      required:
        - countryCode
      properties:
        countryCode:
          type: string
          minLength: 2
          maxLength: 2
          pattern: ^[A-Z]{2}$
          description: ISO 3166-1 alpha-2 country code
          example: US
        merchantShopperId:
          type: string
          description: Your internal customer ID.
          example: CUST_001
        shopperInputPreferences:
          $ref: '#/components/schemas/ShopperInputPreferences'
      description: Details about the customer.
    ShopperInputPreferences:
      type: object
      properties:
        email:
          type: boolean
          default: false
          description: Whether to collect the customer's email address.
        phoneNumber:
          type: boolean
          default: false
          description: Require customer phone number
        firstName:
          type: boolean
          default: false
          description: Whether to collect the customer's first name.
        lastName:
          type: boolean
          default: false
          description: Whether to collect the customer's last name.
        address:
          type: boolean
          default: false
          description: Whether to collect the customer's address.
        dateOfBirth:
          type: boolean
          default: false
          description: Require customer date of birth
        customerNumber:
          type: boolean
          default: false
          description: Require customer reference number
        productSpecifications:
          type: boolean
          default: false
          description: Require product-specific fields
      description: Details about the shopper input preferences.
    AddressVerificationSystem:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - EnableAvsCustomerProvidedAddress
            - EnableAvsMerchantProvidedAddress
            - SkipAvs
          description: The type of AVS.
          example: SkipAvs
        addressVerification:
          $ref: '#/components/schemas/AddressVerification'
      description: Details about the AVS.
    AddressVerification:
      type: object
      required:
        - countryCode
        - houseNumberOrName
        - postalCode
      properties:
        countryCode:
          type: string
          minLength: 2
          maxLength: 2
          pattern: ^[A-Z]{2}$
          description: ISO 3166-1 alpha-2 country code
          example: US
        houseNumberOrName:
          type: string
          maxLength: 100
          description: House number or building name
          example: 123 Main Street
        postalCode:
          type: string
          maxLength: 10
          description: Postal/ZIP code
          example: '12345'
      description: >-
        Pre-filled address verification data (required when AVS type is
        EnableAvsMerchantProvidedAddress)
    AllowedFundingTypes:
      type: object
      properties:
        cards:
          type: array
          items:
            type: string
            enum:
              - Visa
              - Mastercard
              - AmericanExpress
              - Diners
          description: The list of allowed card types.
          example:
            - Visa
            - Mastercard
        wallets:
          type: array
          items:
            type: string
            enum:
              - PayPal
              - ApplePay
          description: The list of allowed wallets.
          example:
            - PayPal
      description: Details about the allowed funding types.
    AfterPaymentConfiguration:
      type: object
      required:
        - afterPaymentConfigurationType
      properties:
        afterPaymentConfigurationType:
          type: string
          enum:
            - ConfirmationPage
            - Redirect
          description: The type of post-payment experience.
          example: Redirect
        redirectUrl:
          type: string
          format: uri
          pattern: ^https://
          description: >-
            The HTTPS URL to redirect the customer to. This is required if
            afterPaymentConfigurationType is set to Redirect.
          example: https://yourstore.com/payment-success
        customMessage:
          type: string
          maxLength: 500
          description: >-
            The custom message to display on the confirmation page. This only
            applies if afterPaymentConfigurationType is set to ConfirmationPage.
          example: Thank you for your purchase!
      description: Details about the post-payment behaviour.
    PayByLinkCreateResponse:
      type: object
      properties:
        linkId:
          type: string
          format: uuid
          description: >-
            The unique payment link identifier generated by PXP. Use this for
            tracking and management operations.
          example: 06da69e0-b668-40b2-ba2f-6c505f08866c
        url:
          type: string
          format: uri
          description: >-
            The complete payment link URL that you can share with customers.
            This is the link customers will use to make their payment.
          example: https://paybylink.dev.pxp.io/06da69e0-b668-40b2-ba2f-6c505f08866c
        status:
          type: string
          enum:
            - Active
            - Cancelled
            - Completed
            - Expired
            - Error
          description: The current status of the payment link.
          example: Active
        expirationTimestamp:
          type: string
          format: date-time
          description: >-
            The date and time when the link expires, in UTC. After this time,
            the link will no longer accept payments.
          example: '2025-09-11T04:12:15.3044876Z'
        site:
          type: string
          description: >-
            The site identifier used in the request, confirming the merchant
            configuration.
          example: site-1
        amounts:
          $ref: '#/components/schemas/PaymentAmounts'
        merchantTransactionId:
          type: string
          description: >-
            Your transaction identifier from the request, used for
            reconciliation and tracking.
          example: ORDER-2025-001
        merchantShopperId:
          type: string
          description: The customer identifier, if provided in the request.
          example: CUST_001
        afterPaymentConfiguration:
          $ref: '#/components/schemas/AfterPaymentConfiguration'
      description: Response containing the created payment link details
    ErrorResponse:
      type: object
      required:
        - errorCode
        - errorReason
        - correlationId
      properties:
        errorCode:
          type: string
          description: The error code returned for the operation.
          example: INVALID_REQUEST
        errorReason:
          type: string
          description: The error reason returned for the operation.
          example: One or more validation errors occurred.
        correlationId:
          type: string
          format: uuid
          description: The unique reference generated by the PSP to locate the error.
          example: 38f49f03-8e42-46db-9f3d-da3428a039be
        details:
          type: array
          items:
            type: string
          description: Additional error details
          example:
            - '''amounts'' - The amounts field is required.'
            - '''products'' - The products field is required.'
      description: Standard error response structure
