Kriya Buyers API
The Buyers API from Kriya — 6 operation(s) for buyers.
OpenAPI Specification
openapi: 3.0.1
info:
title: Kriya Onboarding Buyers API
description: "<a name=\"introduction\"></a>\n# Introduction\nWelcome to Onboarding API, an extension to the existing [KriyaPaymentsApi platform](https://docs.kriya.co/payments) that allows partners to automate onboarding process, and to view results of these checks in a simple way.\n\n>Access to the API is available to all valid users through the same KriyaPaymentsApi credentials.\n\nDevelopers can use this documentation to understand how to automate onboarding process with Kriya.\n\n## Cross-Origin Resource Sharing\n\nThis API features Cross-Origin Resource Sharing (CORS) implemented in compliance with W3C spec. That allows cross-domain communication from the browser. Furthermore, all responses have a wildcard same-origin, making them wholly public and accessible to everyone, including any code on any site.\n\n### [Authorization](https://docs.kriya.co/payments#section/Introduction/Authorization)\n### [Rate Limiting](https://docs.kriya.co/payments#section/Introduction/Rate-Limiting)\n### [Response Status Codes](https://docs.kriya.co/payments#section/Introduction/Response-Status-Codes)\n\n<a name=\"definitions\"></a>\n# Definitions\n\n**Onboarding**: onboarding is a process that must be completed by buyers before they can start using Kriya. Onboarding process generally includes a set of credit checks, fraud checks and other steps. The exact steps in the process depend on the legal entity type (e.g. limited company, sole trader) and the merchant account configuration.\nOnboarding process comprises\n1. Required Company Checks\n2. Additional Onboarding Checks\n\n**Additional Onboarding Checks**: Additional onboarding checks are optional and can be embedded into onboarding process by merchant's request. \nKriya offers following checks to minimise the risks: \n1. Identity Verification and Proof of Address \n2. Sanction Screening\n3. Selfie Check\n\n**Company checks**: Credit decisioning checks performed over the company.\n\n**Identity Verification and Proof of Address Check**: A process that cross-references the personal and address information provided by the individual with the data held by credit bureaus or other public/private registries.\n\n**Sanction Screening**: A process that verify that the subject of screening is not in the lists of sanctioned/high-risk entities and sanctioned/high-risk/politically exposed individuals.\n\n**Selfie Check**: A process of ID(Identification) verification includes the submission of a photo of their ID document and a selfie and their further analysis.\n\n**Onboarding Status**: A buyer characteristic that is considered only when any of the additional checks are required in combination with Risk Decision Status and affect Buyer ability to transact with Kriya. OnboardingStatus is merchant agnostic. Read more [here](#onboarding-status) about possible Onboarding Status values and their meanings. \n\n**Verified buyer**: A buyer with an onboarding status of Approved.\n\n**Unverified buyer**: A buyer with an onboarding status that is not Approved.\n\n**Onboarding API**: Public API that provides a variety of methods for onboarding initiation.\n\n**Onboarding journey**: Is a web application flow that allow user to input information that is required for onboarding process. \n\n<a name=\"integration-scenarios\"></a>\n# Integration Scenarios\nOnboarding Journey is the main integration scenario that should be used by our partners.\nThere's an OnboardingApi but its functionality is limited to Onboarding Journey initiation.\n\nOnboardingJourney can provide the following functionality\n1. Creation of a Limited Company or Government Entity and execution of Company checks for them\n2. Creation of a Sole Trader and execution of Company checks for it\n3. Gather information required for any additional checks and run them \n4. Display outcome of the onboarding\n\nN.B. Onboarding Journey embedded into Payment Journey for above-mentioned scenarios, so no effort is required from partners who already using Payment Journey integration scenario. \n\n<a name=\"onboarding-journey-initiation\"></a>\n## Onboarding Journey Initiation\nOnboarding Journey can be initiated in the following ways: \n- by making a call to Onboarding API [CreateOnboardingJourney](#tag/Onboarding-API/operation/CreateOnboardingJourney) endpoint: it will return a link to the newly created Onboarding Journey.\n- by redirecting a user to `https://api.kriya.co/onboardingJourney/create?merchantIdentifier=&merchantCompanyIdentifier=&onboardingCompletedUrl=&onboardingIneligibleUrl=`\n - merchantIdentifier is a required parameter \n - merchantCompanyIdentifier is autogenerated when not provided\n - onboardingIneligibleUrl defaults to https://kriya.co when not provided\n - onboardingCompletedUrl defaults to https://kriya.co when not provided\n \nThis API request will return a location header in the response to redirect the user to the newly created Onboarding Journey. \n\n## Onboarding Journey Limited Companies Company Check Demonstration\nThe following videos illustrate the comprehensive, end-to-end journey from the buyer's viewpoint.\nBoth of them showcase the sequence starting from a buyer's decision to use Kriya PayLater, leading up to the redirection to Kriya’s Onboarding Journey by the merchant website.\nInternally, the merchant website should use any of the above-mentioned approaches for initiation and redirection to Onboarding Journey. It's important to highlight that a specific buyer (identified by merchantCompanyIdentifier) will consistently be associated with the same onboarding link.\n\n### Additional Checks are not Required by a merchant\n\n\n### Additional Checks are Required by merchant\n\n\nOnce the company checks are completed and the director is chosen there are several ways for the director can proceed with additional checks:\n- in the case when the selected director is the current user within the journey, they can continue with onboarding by clicking `Start` button on `What's next page`.\n- the buyer representative who initiated the onboarding can copy the link by clicking `Copy` button on `What's next page` and pass it via any communication channel to dedicated director.\n- an email will be sent to provided director's email address with an invitation for director to complete onboarding process.\n\n\nN.B. Each Merchant Company Identifier is uniquely linked to a single Kriya Company Identifier. Once this association is set, it becomes permanent. As a result, whenever the Merchant Company Identifier is provided, the corresponding company information will be autofilled based on this established linkage.\n\n<a name=\"sole-trader-onboarding\"></a>\n## Sole Trader Onboarding\nOnboarding Journey for a new Sole Trader includes\n- collection of Sole Trader's details that will be used for automated check\n- collection of the answers to eligibility\n- receiving acknowledgement and confirmation for the Declaration of Sole Trader for Kriya agreement\n- execution of company checks to ensure eligibility for Kriya PayLater\n\nOnboarding can be initiated using of the approaches listed [here](#onboarding-journey-initiation)\n\nThe following video illustrates the comprehensive, end-to-end journey from the viewpoint of a Sole Trader.\nThis visual guide begins at the moment when merchant redirects a new Sole Trader to Onboarding Journey.\n\n\n \n \n<a name=\"payment-journey-integration\"></a>\n## Payment Journey and Onboarding Journey integration\nWhen Payment Journey is run for a new buyer then the Onboarding Journey is initiated. \nIt's worth to mention that there are currently several scenarios that are covered by Onboarding Journey \n\n\n- running eligibility check only for a new Limited Company when no additional checks are required by merchant: there's a seamless transition from the Payment Journey to the Onboarding Journey and back.\n \n \n\nN.B. When additional checks are required by merchant then redirection back to Payment Journey happens only when the user that undergo onboarding checks is a director. In other cases redirection won't happen and user will end up Payment Journey on Onboarding Completion page from where they can return back to merchant site and initiate another Payment Journey.\n\n- onboarding of a new Sole Trader and running company checks when additional Selfie check is required by merchant: the user will be redirected from the Payment Journey to the Onboarding Journey and back (in case when all checks successfully completed)\n\n\n \n\n<a name=\"data-types\"></a>\n# Data Types\n\nThe following section outlines some specific ways in which data should be interpreted or sent in requests to and from the API.\n\n<a name=\"kriyacompanyidentifier\"></a>\n## Kriya Company Identifier (KriyaCompanyIdentifier)\nKriya Company Identifier is the unique identifier of a Limited Company in the Payments API. It is retrieved firstly via the Kriya Payments API `Search` endpoint.\n\n<a name=\"merchantcompanyidentifier\"></a>\n## Merchant Company Identifier (MerchantCompanyIdentifier)\nThe Merchant Company Identifier serves as an internal reference for merchants, uniquely identifying a company within the system. This identifier is assigned during the company onboarding process. It's crucial to note that once established, the mapping between the Merchant Company Identifier and the Kriya Company Identifier becomes immutable, ensuring a consistent and reliable reference point throughout the system's usage.\n\n<a name=\"nationalid\"></a>\n## National Id (NationalId)\nNational identifier of a company: in the UK it is the company registration number.\n\n<a name=\"defined-types\"></a>\n# Defined Types\n\n> Unless specified otherwise, all properties are `Required` when making API calls.\n\n\n<a name=\"person\"></a>\n## Person\nDefines the minimum required fields that represent a person.\n\n| Property | Data Type | Description | Constraints |\n|-------------|-----------|---------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------|\n| FullName | String | Full name of a person | It must be between 1 and 128 characters. Director Full Name must match information from Company House registry. |\n| Email | String | Contact email that will be used for communication purposes | It must be between 1 and 128 characters. Should be a valid email. |\n\n<a name=\"onboarding-status\"></a>\n## Onboarding Status\n\n| Name | Description |\n|--------------|---------------------------------------------------------------------------------------------------------------------|\n| NotStarted | Default for all newly created companies. |\n| InProgress | Status of an eligible company for which additional onboarding checks required by the merchant have been initiated. |\n| Passed | Represents a company for which all additional onboarding checks have been successfully completed. |\n| Failed | Represents a company for which any of the additional onboarding checks have failed. |\n| ManualReview | Represents a company for which any of the additional onboarding checks require manual review. |\n\n\n<a name=\"requester\"></a>\n## Requester\nDefines the minimum required fields that represent a requester\n\n| Property | Data Type | Description | Constraints |\n|-------------|-----------|------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|\n| FullName | String | Full name of a person | It must be between 1 and 128 characters. |\n| Email | String | Contact email that will be used for communication purposes | It must be between 1 and 128 characters. Should be a valid email. |\n| PhoneNumber | String | Contact mobile phone number that will be used in 2FA | It must be between 1 and 16 characters. Should be a valid mobile phone number that can receive SMS. |\n\n<a name=\"onboarding-journey\"></a>\n## Onboarding Journey\n\nAdditional information required for smooth Onboarding Journey web application flows:\n\n| Property | Data Type | Description | Is Required for <br/> Company Check? |\n|---------------|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------|\n| AbandonedUrl | Url | This URL determines the destination to which the director will be redirected if they choose to exit the Onboarding Journey prematurely. | Yes |\n| CompleteUrl | Url | This URL specifies the webpage to which the director will be redirected upon successful completion of the Onboarding Journey, ensuring a seamless transition to the next phase or action. | Yes |\n| IneligibleUrl | Url | This URL is the designated redirection point for directors if the company does not successfully pass the eligibility check during the Onboarding Journey, providing a pathway to additional resources or next steps. | Yes |\n| InReviewUrl | Url | This URL is the specified redirection destination for directors in instances where the company does not pass the automatic eligibility check and subsequently necessitates a manual review during the Onboarding Journey, guiding them toward further instructions or information. | Yes | \n\n<a name=\"webhooks\"></a>\n# Webhooks\nThe Onboarding API introduces extensions to the existing [BuyerRiskDecisionChanged](https://docs.kriya.co/payments#section/Webhooks/) webhook within the Kriya Payments API by incorporating additional field to provide more detailed insights into the onboarding status:\n1. `onboardingStatus`: This field displays the current [Onboarding Status](#onboarding-status) for the buyer.\n\n\n<a name=\"api-environments\"></a>\n# API Environments\n\nThe API currently supports two environments, that is, both **Test** and **Production**. No any further actions is required if you have already requested access to each of these environments for Kriya Payments API.\n\n## Test\n\nThe Test API can be accessed through the base URL [https://api.kriya.dev/onboarding/](https://api.kriya.dev/onboarding/)\n\nThe Test environment has been created to allow partners to test their integrations. Alongside this, the Test API also supports overriding certain internal operations to support testing scenarios during integrations. See [Test Scenarios Simulators](#test-scenarios-simulators) for more details.\n\n> You may, on occasion, find API requests taking over 1 second anywhere up to 15 seconds. This is due to the technology being used in our test environment where cold starts can occur. This will not be the case in the Production environment.\n\n<a name=\"test-scenarios-simulators\"></a>\n### Test Scenario Simulators\n\nDuring your integration with the Kriya Onboarding API, it's pivotal to test various scenarios to ensure your system adeptly handles all possible outcomes. Our test environment is equipped with additional API endpoints, specifically designed to simulate various scenarios, enabling you to thoroughly test your integration. These simulations might not be directly achievable via the production endpoints, providing a comprehensive testing ground to validate your integration's robustness and reliability.\n\n#### Onboarding Status Transitions\nCompany Onboarding Status is taking into consideration by merchant who requires additional checks. Onboarding Status calculation is based on all additional checks outcomes.\nTo facilitate comprehensive testing across these specific statuses, we provide an endpoint within the Test environment, enabling you to update your Onboarding Status. There are no restrictions for the status transitions: any status can be transitioned to any other.\n\nThe endpoint can be called using the following request:\nPUT [https://api.kriya.dev/onboarding/scenario/onboardingStatus](https://api.kriya.dev/onboarding/scenario/onboardingStatus)\n\n```json\n{\n \"merchantCompanyIdentifier\": \"GB02398929\",\n \"onboardingStatus\": \"Passed\"\n}\n```\n\n## Production\n\nThe Production API can be accessed through the base URL [https://api.kriya.co/onboarding/](https://api.kriya.co/onboarding/).\n\n<a name=\"support\"></a>\n# Support\n\nIf you have any questions concerning API or suggestions or are facing any issues, please get in touch with us at <apisupport@kriya.co>.\n\n# API Endpoints\n"
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: https://api.kriya.dev/onboarding/
description: Test Environment
- url: https://api.kriya.co/onboarding/
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:
updateBuyerScenarioRequest:
type: object
properties:
kriyaCompanyIdentifier:
type: string
description: A unique identifier for a company assigned by Kriya.
format: uuid
nullable: true
merchantCompanyIdentifier:
type: string
description: A unique identifier for a company assigned by the Merchant.
nullable: true
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
description: Country of Registration, The ISO-3166 alpha-2 country code. Defaults to 'GB' if not specified.
nullable: true
companyType:
enum:
- LimitedCompany
- SoleTrader
type: string
description: Business type of the company. Defaults to 'LimitedCompany' if not specified.
nullable: true
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
description: The new limit for the buyer to be given.
format: int64
nullable: true
directorDetails:
type: object
properties:
fullName:
type: string
description: First and Last Name of the director.
nullable: true
deprecated: true
firstName:
type: string
description: First name of the director.
nullable: true
lastName:
type: string
description: Last name of the director.
nullable: true
phoneNumber:
type: string
description: Director phone number.
nullable: true
dateOfBirth:
type: string
description: Director date of birth.
format: date-time
nullable: true
residentialAddress:
$ref: '#/components/schemas/address'
description: Company director details.
nullable: true
createBuyerRequest:
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.
nullable: true
countryCode:
type: string
description: Country of Registration, The ISO-3166 alpha-2 country code. Defaults to 'GB' if not specified.
nullable: true
type:
enum:
- LimitedCompany
- SoleTrader
type: string
description: Business type of the company. Defaults to 'LimitedCompany' if not specified.
nullable: true
contactDetails:
$ref: '#/components/schemas/buyerContactDetails'
kriyaCompanyIdentifier:
type: string
description: Unique identifier of the company in Kriya.
format: uuid
nullable: true
merchantCompanyIdentifier:
type: string
description: Unique identifier of the company for the Merchant.
nullable: true
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.
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
description: A unique identifier for a company assigned by Kriya.
format: uuid
nullable: true
merchantCompanyIdentifier:
type: string
description: A unique identifier for a company assigned by the Merchant.
nullable: true
getBuyerResponse:
type: object
properties:
kriyaCompanyIdentifier:
type: string
description: A unique identifier for a company assigned by Kriya.
format: uuid
nullable: true
merchantCompanyIdentifier:
type: string
description: A unique identifier for a company assigned by the Merchant.
nullable: true
name:
type: string
description: The legal name of the company.
registrationNumber:
type: string
companyIdentifier:
type: string
description: Company identifier, i.e. registration number for a Limited Company or the email address or phone number for a Sole Trader.
nullable: true
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
- Approv
# --- truncated at 32 KB (38 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kriya/refs/heads/main/openapi/kriya-buyers-api-openapi.yml