Kriya Buyers API

openapi: 3.2.0
info:
  title: Kriya Payments Buyers API
  description: '# Introduction

    Welcome to Kriya Payments API, the platform that allows partners to offer a Buy Now Pay Later (BNPL) payment scheme to their business customers.'
  contact:
    name: Support
    url: https://kriya.co/
    email: apisupport@kriya.co
  version: ''
  x-logo:
    url: https://cdn.kriya.co/images/Kriya-Putty-Large.svg
    backgroundColor: '#00283C'
    altText: Kriya Logo
servers:
- url: http://localhost:7071/api
- url: https://api.kriya.dev/payments/
  description: Test Environment
- url: https://api.kriya.co/payments/
  description: Production Environment
tags:
- name: Buyers
paths:
  /scenario/buyers/risk-decision:
    put:
      tags:
      - Buyers
      summary: Updates buyer risk decision status for testing
      description: Simulates a buyer's risk decision status for testing purposes in the sandbox environment.
      operationId: BuyerRiskDecisionScenario
      requestBody:
        description: Risk decision to be applied to the buyer
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/updateBuyerScenarioRequest'
      responses:
        '401':
          description: Invalid API Key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problemDetails'
        '400':
          description: The request body could not be understood by the server or contains semantic errors. The response body provides details of the specific reason for the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problemDetails'
        '200':
          description: No description
  /companies/search:
    post:
      tags:
      - Buyers
      summary: Searches for companies
      description: Searches for companies.
      operationId: CompaniesSearch
      requestBody:
        description: Search parameters
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/companySearchRequest'
      responses:
        '401':
          description: Invalid API Key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problemDetails'
        '400':
          description: The request body could not be understood by the server or contains semantic errors. The response body provides details of the specific reason for the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problemDetails'
        '200':
          description: No description
  /buyers:
    post:
      tags:
      - Buyers
      summary: Registers a new buyer company
      description: Registers a new buyer company in the Kriya Payments system. If the buyer already exists, the request will succeed without modifying the existing data. To amend the Bank Account details or the Contact details please refer to the other buyer endpoints.
      operationId: CreateBuyer
      requestBody:
        description: Data of the buyer to be created.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/createBuyerRequest'
      responses:
        '201':
          description: Payload of CreateBuyerResponse
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/createBuyerResponse'
        '401':
          description: Invalid API Key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problemDetails'
        '400':
          description: The request body could not be understood by the server or contains semantic errors. The response body provides details of the specific reason for the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problemDetails'
  /buyers/pricing-scheme/single:
    post:
      tags:
      - Buyers
      summary: Retrieves buyer payment options and fees
      description: Retrieves the available payment options and associated fees for a buyer.
      operationId: FindBuyerPricingScheme
      requestBody:
        description: The Buyer to find the pricing scheme for.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/getSingleBuyerPricingSchemeRequest'
      responses:
        '200':
          description: The pricing schemes for the buyer.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/buyerPricingScheme'
        '401':
          description: Invalid API Key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problemDetails'
        '404':
          description: The resource with this identifier was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problemDetails'
        '500':
          description: Something went wrong, please get in touch with tech team.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problemDetails'
  /buyers/single:
    post:
      tags:
      - Buyers
      summary: Fetches buyer company information
      description: Fetches detailed information about a buyer company using its identifier.
      operationId: GetSingleBuyer
      requestBody:
        description: Data of the company to retrieve
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/getSingleBuyerRequest'
      responses:
        '200':
          description: Get buyer company details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getBuyerResponse'
        '401':
          description: Invalid API Key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problemDetails'
        '404':
          description: The resource with this identifier was not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problemDetails'
        '500':
          description: Something went wrong, please get in touch with tech team.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problemDetails'
  /buyers/contact-details:
    put:
      tags:
      - Buyers
      summary: Modifies buyer's contact information
      description: Updates the contact details of a buyer company.
      operationId: UpdateBuyerContactDetails
      requestBody:
        description: Contact details to be updated
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/updateBuyerContactDetailsRequest'
      responses:
        '401':
          description: Invalid API Key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problemDetails'
        '400':
          description: The request body could not be understood by the server or contains semantic errors. The response body provides details of the specific reason for the error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/problemDetails'
        '201':
          description: No description
components:
  schemas:
    address:
      type: object
      properties:
        addressLine1:
          type:
          - string
          - 'null'
          description: First line of the address.
        addressLine2:
          type:
          - string
          - 'null'
          description: Second line of the address.
        city:
          type:
          - string
          - 'null'
          description: Name of the city.
        region:
          type:
          - string
          - 'null'
          description: Name of the Region.
        postCode:
          type:
          - string
          - 'null'
          description: Postcode.
        country:
          type:
          - string
          - 'null'
          description: Country.
      description: Director residential address.
    updateBuyerContactDetailsRequest:
      type: object
      properties:
        companyIdentifier:
          type: string
          description: The identifier for the company, i.e. registration number for a Limited Company or the email address or phone number for a Sole Trader.
        companyCountryCode:
          type:
          - string
          - 'null'
          description: Country of Registration, The ISO-3166 alpha-2 country code. Defaults to 'GB' if not specified.
        companyType:
          enum:
          - LimitedCompany
          - SoleTrader
          type:
          - string
          - 'null'
          description: Business type of the company. Defaults to 'LimitedCompany' if not specified.
        kriyaCompanyIdentifier:
          type:
          - string
          - 'null'
          description: A unique identifier for a company assigned by Kriya.
          format: uuid
        merchantCompanyIdentifier:
          type:
          - string
          - 'null'
          description: A unique identifier for a company assigned by the Merchant.
        name:
          type:
          - string
          - 'null'
          description: Full name of the primary contact for the buyer.
        email:
          type:
          - string
          - 'null'
          description: Email address of the primary contact for the buyer.
        role:
          type:
          - string
          - 'null'
          description: Role of the primary contact for the buyer.
        phoneNumber:
          type:
          - string
          - 'null'
          description: Phone number of the primary contact for the buyer. This is not limited to UK phone numbers.
    companySearchRequest:
      type: object
      properties:
        name:
          type: string
        nationalId:
          type: string
        address:
          $ref: '#/components/schemas/address'
        website:
          type: string
        email:
          type: string
        kriyaCompanyIdentifier:
          type:
          - string
          - 'null'
          format: uuid
    createBuyerResponse:
      type: object
      properties:
        kriyaCompanyId:
          type: string
          description: The unique Kriya identifier of the created company.
          format: uuid
    getSingleBuyerRequest:
      type: object
      properties:
        companyIdentifier:
          type: string
          description: The identifier for the company, i.e. registration number for a Limited Company or the email address or phone number for a Sole Trader.
        countryCode:
          type: string
          description: Country of Registration, The ISO-3166 alpha-2 country code. Defaults to 'GB' if not specified.
        type:
          enum:
          - LimitedCompany
          - SoleTrader
          type: string
          description: Business type of the company. Defaults to 'LimitedCompany' if not specified.
        kriyaCompanyIdentifier:
          type:
          - string
          - 'null'
          description: A unique identifier for a company assigned by Kriya.
          format: uuid
        merchantCompanyIdentifier:
          type:
          - string
          - 'null'
          description: A unique identifier for a company assigned by the Merchant.
    getSingleBuyerPricingSchemeRequest:
      type: object
      properties:
        companyIdentifier:
          type: string
          description: The identifier for the company, i.e. registration number for a Limited Company or the email address or phone number for a Sole Trader.
        countryCode:
          type: string
          description: Country of Registration, The ISO-3166 alpha-2 country code. Defaults to 'GB' if not specified.
        type:
          enum:
          - LimitedCompany
          - SoleTrader
          type: string
          description: Business type of the company. Defaults to 'LimitedCompany' if not specified.
        kriyaCompanyIdentifier:
          type:
          - string
          - 'null'
          description: A unique identifier for a company assigned by Kriya.
          format: uuid
        merchantCompanyIdentifier:
          type:
          - string
          - 'null'
          description: A unique identifier for a company assigned by the Merchant.
    createBuyerRequest:
      type: object
      properties:
        companyIdentifier:
          type:
          - string
          - 'null'
          description: The identifier for the company, i.e. registration number for a Limited Company or the email address or phone number for a Sole Trader.
        countryCode:
          type:
          - string
          - 'null'
          description: Country of Registration, The ISO-3166 alpha-2 country code. Defaults to 'GB' if not specified.
        type:
          enum:
          - LimitedCompany
          - SoleTrader
          type:
          - string
          - 'null'
          description: Business type of the company. Defaults to 'LimitedCompany' if not specified.
        contactDetails:
          $ref: '#/components/schemas/buyerContactDetails'
        kriyaCompanyIdentifier:
          type:
          - string
          - 'null'
          description: Unique identifier of the company in Kriya.
          format: uuid
        merchantCompanyIdentifier:
          type:
          - string
          - 'null'
          description: Unique identifier of the company for the Merchant.
    directorDetails:
      type:
      - object
      - 'null'
      properties:
        fullName:
          type:
          - string
          - 'null'
          description: First and Last Name of the director.
          deprecated: true
        firstName:
          type:
          - string
          - 'null'
          description: First name of the director.
        lastName:
          type:
          - string
          - 'null'
          description: Last name of the director.
        phoneNumber:
          type:
          - string
          - 'null'
          description: Director phone number.
        dateOfBirth:
          type:
          - string
          - 'null'
          description: Director date of birth.
          format: date-time
        residentialAddress:
          $ref: '#/components/schemas/address'
      description: Company director details.
    getBuyerResponse:
      type: object
      properties:
        kriyaCompanyIdentifier:
          type:
          - string
          - 'null'
          description: A unique identifier for a company assigned by Kriya.
          format: uuid
        merchantCompanyIdentifier:
          type:
          - string
          - 'null'
          description: A unique identifier for a company assigned by the Merchant.
        name:
          type: string
          description: The legal name of the company.
        registrationNumber:
          type: string
        companyIdentifier:
          type:
          - string
          - 'null'
          description: Company identifier, i.e. registration number for a Limited Company or the email address or phone number for a Sole Trader.
        countryCode:
          type: string
        type:
          enum:
          - LimitedCompany
          - SoleTrader
          type: string
          description: The associated business type of the company.
        contactDetails:
          $ref: '#/components/schemas/buyerContactDetails'
        status:
          enum:
          - Unknown
          - Submitted
          - InReview
          - Approved
          - Rejected
          - OnHold
          type: string
          description: The risk decision provided for the buyer.
        totalLimit:
          type: integer
          description: The total limit given to the buyer, if approved.
          format: int64
        availableLimit:
          type: integer
          description: The available limit remaining for the buyer.
          format: int64
        usedLimit:
          type: integer
          description: The total limit currently utilised across all active orders.
          format: int64
        director:
          $ref: '#/components/schemas/directorDetails'
        rejectionReasons:
          type: array
          items:
            type: string
          description: Reasons provided for a Buyers risk decision outcome of 'Rejected'.
    buyerContactDetails:
      type:
      - object
      - 'null'
      properties:
        name:
          type:
          - string
          - 'null'
          description: Full name of the primary contact for the buyer.
        email:
          type:
          - string
          - 'null'
          description: Email address of the primary contact for the buyer.
        phoneNumber:
          type:
          - string
          - 'null'
          description: Phone number of the primary contact for the buyer, including the country calling code.
      description: Primary contact details of the company.
    updateBuyerScenarioRequest:
      type: object
      properties:
        kriyaCompanyIdentifier:
          type:
          - string
          - 'null'
          description: A unique identifier for a company assigned by Kriya.
          format: uuid
        merchantCompanyIdentifier:
          type:
          - string
          - 'null'
          description: A unique identifier for a company assigned by the Merchant.
        companyIdentifier:
          type: string
          description: Company identifier for the buyer, i.e. registration number for a Limited Company or the email address or phone number for a Sole Trader.
        companyCountryCode:
          type:
          - string
          - 'null'
          description: Country of Registration, The ISO-3166 alpha-2 country code. Defaults to 'GB' if not specified.
        companyType:
          enum:
          - LimitedCompany
          - SoleTrader
          type:
          - string
          - 'null'
          description: Business type of the company. Defaults to 'LimitedCompany' if not specified.
        status:
          enum:
          - Unknown
          - Submitted
          - InReview
          - Approved
          - Rejected
          - OnHold
          type: string
          description: The risk decision status for the buyer to be transitioned to.
        limit:
          type:
          - integer
          - 'null'
          description: The new limit for the buyer to be given.
          format: int64
    buyerPricingScheme:
      type: object
      properties:
        identifier:
          type: string
          description: The unique identifier of the payment option
        name:
          type: string
          description: The name of the payment option.
        description:
          type: string
          description: The description of the payment option.
        isEnabled:
          type: boolean
          description: The flag to determine if the buyer can use this payment option.
        feePercentage:
          type: number
          description: The associated fee percentage for the payment option that is payable by the buyer.
          format: double
        isPayNowEnabled:
          type: boolean
          description: The flag to determine if the pay now option is enabled for the payment option.
    problemDetails:
      type: object
      properties:
        title:
          type: string
          description: The high level message returned for an non-success response.
        message:
          type: string
          description: A description of the issue.
        errors:
          type: array
          items:
            type: string
          description: The individual errors that caused the non-success response.
        date:
          type: string
          description: The date and time at which the errors occured.
          format: date-time
        operationId:
          type: string
          description: The unique identifier for the operation where the error was caused. This will be of use and should be provided when requesting further support.