APIs

• FinCrime Service

  Introduction

  FinCrime Service allows RDC to notify Kriya about alerts for monitored entities.

  Authorization

  Once you have been approved to use the API, you will have access to your own API keys that must be sent using the header X-MarketFinance-ApiKey with every request.

  All incoming data and outgoing responses will be provided using JSON.

  All requests must be sent over HTTPS.

  Rate Limiting

  To manage the volume of requests on the API, limits are placed on the number of requests that can be made. This approach ensures we can continue to have a reliable API for partners to consume.

  The requests are measured over a specified period of time per API key. The current limitations are that no more than 2000 requests can be made to the API every 5 minutes across all endpoints. If the limit is breached, the API will begin to respond with 429 Too Many Requests until the time interval has refreshed.

  If limits are consistently breached on the API, we may temporarily disable your access to the API and inform you of this.

• Kriya Payments API

  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.

  Access to the API is restricted to select partners, and those with access will have received the relevant credentials.

  Developers can use this documentation to understand how to implement the BNPL scheme.

  Want to learn more about Kriya Payments? You can either request a demo here or contact us at payments@kriya.co.

  Cross-Origin Resource Sharing

  This API features Cross-Origin Resource Sharing (CORS) implemented in compliance with W3C spec. And 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.

  Authorization

  Once approved to use the API, you will have access to your API keys that you must send using the header X-Kriya-ApiKey with every request.

  Requests and responses must use JSON.

  All API requests must be sent over HTTPS.

  Rate Limiting

  The API limits the number of requests that can be made. This approach ensures we can continue to have a reliable API for partners to consume.

  Requests are measured over a specified period per API key. The current limitations are that no more than 2000 requests can be made to the API every 5 minutes across all endpoints. If the limit is breached, the API will begin to respond with 429 Too Many Requests until the time interval has been refreshed.

  If limits are consistently breached on the API, we may temporarily disable your access to the API and inform you of this.

  Response Status Codes

  API requests made to Kriya Payments endpoints may return several different HTTP status codes.

  Status Code	Description
  200 OK	The request was received and successfully processed by Kriya Payments.
  201 Created	The request was received and successfully processed, and a new resource was created.
  400 Bad Request	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.
  401 Unauthorized	The X-Kriya-ApiKey header was not present or is invalid.
  404 Not Found	The requested resource could not be found.
  429 Too Many Requests	The application has exceeded the rate limit. See Rate Limiting.
  500 Internal Server Error	An unexpected internal error has occurred. Please get in touch with us at apisupport@kriya.co so that we can investigate further.
  503 Service Unavailable	The server is currently unavailable and cannot accept requests. We will inform Marketplaces of any planned downtime or outages. If you have not received any communication and you have received this response code, please get in touch with us at apisupport@kriya.co.

  Definitions

  Marketplace: The Marketplace is the partner that will integrate with the Kriya Payments API. This is typically an online platform that provides goods or services to Buyers, either directly or via Suppliers.

  Buyer: A Buyer is a business that is purchasing goods or services from the Marketplace. A Buyer must be registered on Kriya Payments API and be given an approved spending limit before being able to transact with us.

  Supplier: A Supplier is a business that provides goods or services to be sold via the Marketplace. The Supplier must be registered and approved on Kriya Payments API before the Marketplace sells goods or services on their behalf. A Supplier may also be a Buyer on either the same or other Marketplaces.

  Order: An order is an agreement between the Buyer, Supplier, and the Marketplace of buying goods and services. The value of the order may be the sum of one or many goods or services. An individual order can be purchased via the BNPL options provided to Buyers.

  Spending Limit: The spending limit is the total amount that Kriya Payments can offer a Buyer to transact with. Kriya Payments continually monitors the spending limits assigned to Buyers and may increase or decrease them.

  Available Spending Limit: The available spending limit is the amount that the Buyer can use to transact using Kriya Payments. Whenever an order progresses beyond the Draft status, the total amount of the order is deducted from the available spending limit. All orders made must fall within the available spending limit for the Buyer.

  Kriya Payments Fee: Orders created may be paid for from several payment methods, e.g. "Pay in 30 days". Each payment method may include a fee that is payable by the Buyer that is based on a percentage of the order amount. When the Buyers available spending limit is reduced, it is exclusive of fees. For example, a Buyer may want to pay for a £1,000 order using a payment method that has a 1.00% fee. The total amount payable by the Buyer would be £1,010, and their available spending limit is reduced by £1,000.

  Payment Method: A payment method is a specific term under which an order is to be paid. For example, "Pay in 30 days" or "Pay in 3 instalments". Each Marketplace and Buyer can have different methods provided to them at the checkout stage. Fees associated with payment methods can be set globally or overridden for specific Buyers.

  Integration Scenarios

  The Kriya Payments API provides a variety of methods of integration for partners. This includes direct API integration and a Kriya Payments-hosted Payments Journey web application.

  The following table outlines the differences in scenarios:

  Property	Direct API	Payments Journey
  Effort	The estimated effort of between 1-4 weeks to implement. The developer effort is more significant as it involves a bespoke integration built by the Marketplace.	The estimated effort of around one week to implement. Lower development effort as the majority of the integration is handled by the Kriya Payments Payments Journey with only minimal API integration required by the Marketplace.
  Checkout data collection	Additional fields, if not currently exposed, may be required to create a Kriya Payments order that the Marketplace must embed in their checkouts.	Kriya Payments collects Company and User details on your behalf. Returning Buyers also have their previous data pre-populated to increase the speed of the checkout process.
  Branding	The integration will be built by the Marketplace, and any branding can be fully controlled.	Co-branding is limited to displaying the Marketplace logo, but further enhancements are on the roadmap.
  User experience	The Marketplace must define its UX and UI for its Buyers that align with the API flows. Users stay within the domain of the Marketplaces website.	User experience is pre-defined by Kriya Payments and optimised based on regularly reviewed metrics collected from customers that use the Payment Journey. Users must be redirected to an external site to continue their checkout journey.
  API Updates	Changes to Kriya Payments API, including any new capabilities, will have to be developed by the Marketplace.	Payments Journey will constantly be kept up to date with the latest API capabilities to ensure the customer has a high-quality experience.

  Direct API Integration

  Direct API integration is the preferred choice for partners that want to have complete control over the customer journey and embed the capabilities of the API directly into their solutions.

  Direct API flow

  The following flow demonstrates a typical sequence for a new Buyer transacting using the API:

  1. Buyer has been onboarded by the Marketplace.
  2. Marketplace requests to the Kriya Payments API CreateBuyer endpoint to register them on the API to identify if they can use Kriya Payments.
  3. Kriya Payments API begins the risk decision process to determine if a limit can be provided to the Buyer.
  4. Kriya Payments API responds with a 201 Created status code to confirm the Buyer has been created.

  Note: Marketplaces may create Draft orders whilst awaiting a risk decision. However, no orders can be Submitted until the Buyer has been Approved. See Webhooks for more details on how to get notified of this.

  5. Marketplace uses webhooks or the GetBuyer endpoint to determine whether the Buyer has been Approved and Kriya payment methods are available to them.
  6. Marketplace may call the Kriya Payments API GetBuyerPricingScheme endpoint to understand which payment methods are available to the Buyer, along with any associated fees they may incur.
  7. Kriya Payments API responds with a 200 OK response and provides the pricing scheme available to the Buyer.
  8. Buyer uses the Marketplace to purchase services or goods and chooses to pay with Kriya Payments, presuming the Marketplace has exposed the ability to checkout using Kriya Payments.
  9. Marketplace calls the Kriya Payments API CreateOrder endpoint, which will create a new order in the default Draft status.

  A Draft order is non-committal and can be cancelled at any time. It does not impact the available spending limit of the Buyer.

  10. Kriya Payments API responds with a 201 Created to confirm the order has been created and also returns details about the Buyer's possible payment methods and limit.
  11. Buyer confirms they want to proceed and place the order on the Marketplace.
  12. Marketplace calls the Kriya Payments API TransitionOrder endpoint and moves it from the Draft status to Submitted.

  By transitioning the order to a Submitted status, the Buyers available spending limit is reduced based on the total amount of the order.

  13. Kriya Payments API responds with a 200 OK response.
  14. Marketplace delivers the goods to the Buyer, and an invoice has been generated.
  15. Marketplace requests to the Kriya Payments API TransitionOrder endpoint and moves it from Submitted status to ReadyToAdvance.

  This is the trigger from the Marketplace to inform Kriya Payments to advance funds to the Marketplace and Supplier if applicable. No further changes can be made to the order at this point.

  16. Kriya Payments API responds with a 200 OK response.

  

  Payments Journey Integration

  The Payments Journey-driven integration utilises a Kriya Payments-hosted web application that handles the checkout journey for customers. This is the preferred approach for partners that are looking for a lower-effort solution.

  Payments Journey Demonstration

  The following file shows a walk-through of an end-to-end journey from the customer's perspective once they have been redirected to the Kriya Payments hosted Payments Journey.

  

  Payments Journey flow

  The following flow shows a typical scenario for the Payments Journey. A Buyer has chosen to pay using Kriya Payments on the Marketplace, and they will complete their checkout process via the Payments Journey before being redirected back to the Marketplace.

  1. Buyer, existing or new, has been onboarded by the MarketPlace and has been offered Kriya Payments.
  2. Marketplace calls the Kriya Payments API CreateOrder endpoint, which will create a new order in the default Draft status.

  To initiate a payment journey additional fields are required. See, Initiating a payment journey below.

  3. Kriya Payments API responds with a 201 Created status code to confirm it has been created and also returns a redirect URL, which is valid for 14 days.

  The redirect URL is used to redirect the customer to the Kriya Payments-hosted Payments Journey.

  4. Marketplace redirects the customer to the returned URL.
  5. Buyer lands on the Payments Journey page, which includes filling out Company and User details if they were not initially provided in step 2.
  6. Buyer selects their preferred payment method and finally completes their payment journey.
  7. Payments Journey redirects the Buyer back to the Marketplace.
  8. Buyer places the order on the Marketplace.

  If your checkout process does not require the Buyer to confirm the placement of the order, you can use our AutoTransitionOnCompletion field, which automatically performs step 9 for you. See below for further details.

  9. Marketplace calls the Kriya Payments API TransitionOrder endpoint and moves it from Draft to Submitted.

  By transitioning the order to the Submitted status, the Buyer's available spending limit is reduced based on the total amount of the order.

  10. Kriya Payments API responds with a 200 OK response to confirm that the order has been submitted.

  At this point, the same steps from 11 onwards in the API flow are now followed.

  

  AutoTransitionOnCompletion

  This property defines the status that the order will transition to after the payment journey is completed but before redirecting them back to the Marketplace. By default, any payment journey completion will leave an order in its Draft status. However, this property allows you to transition an order to Submitted or ReadyToAdvance instead automatically.

  Initiating a Payment Journey

  Two properties must be specified to ensure you receive a redirect URL to the Payments Journey:

  PaymentAcceptedRedirectUrl

  This refers to the URL that we will redirect the Buyer to once they have completed the Payments Journey. Upon redirection, you will now have an order that has been created, still in the Draft status, unless the AutoTransitionOnCompletion property has been set.

  PaymentDeclinedRedirectUrl

  This refers to the URL that we will redirect the Buyer to if, at any point in the journey, they either do not wish to proceed or cannot proceed. Upon redirection, you will still have an order that has been created, still in the Draft status, which can be set to Cancelled if applicable. You will be able to retrieve the details about why the Payments Journey has been declined by retrieving the order details via the Kriya Payments API GetOrder endpoint, which will include a PaymentJourney.Status property that will be either:

  • UserInitiated - The user decided to return to the Marketplace and no longer proceed with the order at this time. e.g. They may wish to add additional items to their basket or choose an alternative payment method. The Marketplace can amend the order amount (PUT on the orders endpoint) and redirect the Buyer back to the payments journey, if applicable.
  • Ineligible - Kriya Payments were unable to transact with the Buyer as they have not been or are no longer approved. The Marketplace is expected to provide the Buyer with an alternative payment method.
  • InsufficientFunds - Kriya Payments were unable to transact with the Buyer as their available spending limit is less than the amount of the current order. The Marketplace is expected to either provide the Buyer with an alternative payment method or provide partial payment so that Kriya can still transact with the funds available on the Buyer's available spending limit.

  Shopify

  Kriya is currently in the development process of providing integrations with Shopify. If you would like to learn more about this, please get in touch us at payments@kriya.co.

  WooCommerce

  Kriya Payments is now readily available for WooCommerce merchant stores. To receive the plugin, please get in touch with us at apisupport@kriya.co.

  Configuring the plugin

  1. Log into WordPress Admin Dashboard.
  2. Select the Plugins > Add New option in the left column menu.
  3. Select Upload Plugin.
  4. Select Drop files or click here to install and select the .zip file provided to you.

  To update the plugin, you can follow the above steps with a new version of the .zip file. You do not need to repeat the steps below as they are still stored.

  At this point, the plugin has now been installed. To configure the plugin for your store, you should:

  1. In Wordpress Admin Dashboard, select WooCommerce > Settings option in the left column menu.
  2. Select the Payments tab.
  3. Select the All payment methods option at the top of the screen.
  4. Select the Manage button on the Kriya Payments payment method.
  5. Input your Test and Production (Live) API keys into the appropriate fields.

  You can use the Test mode to send any orders to our test environment, prior to sending live orders.

  6. Press Save changes

  

  The plugin will now be active and the Kriya payment method is now available on the store checkout.

  Other e-commerce platforms

  If you're interested in using the Kriya Payments API and the platform you're using isn't listed above, please let us know by contacting us a payments@kriya.co.

  Data Types

  The following section outlines some specific ways in which data should be interpreted or sent in requests to and from the API.

  Currency

  All currencies shall be both requested and returned using their ISO 4217 codes.

  Monetary Amounts

  Any monetary amounts requested and returned via the API shall be represented as their lowest denomination. For example:

  • £123.90 is represented as 12390
  • $50.00 is represented as 5000

  Countries

  Wherever a country of registration is required, it must be done so using the ISO 3166-1 alpha-2 code.

  Kriya Payments supports GB, the US and the following European countries that we can service:

  • Austria (AT)
  • Belgium (BE)
  • Bulgaria (BG)
  • Croatia (HR)
  • Cyprus (CY)
  • Czech Republic (CZ)
  • Denmark (DK)
  • Estonia (EE)
  • Finland (FI)
  • France (FR)
  • Germany (DE)
  • Greece (GR)
  • Hungary (HU)
  • Ireland (IE)
  • Italy (IT)
  • Latvia (LV)
  • Lithuania (LT)
  • Luxembourg (LU)
  • Malta (MT)
  • Netherlands (NL)
  • Poland (PL)
  • Portugal (PT)
  • Romania (RO)
  • Slovakia (SK)
  • Slovenia (SI)
  • Spain (ES)
  • Sweden (SE)

  Defined Types

  Unless specified otherwise, all properties are Required when making API calls.

  Order

  The order is the record of a transaction occurring via Kriya Payments. Several varying validation rules come into play depending on the status of the order. Please see Order Status for further information.

  Property	DataType	Description	Constraints
  MarketplaceOrderId	String	The unique order identifier from the Marketplace.	It must be between 1 and 150 characters. It must be unique across all orders.
  Status	String (Enum) Order Status	The status of the order. Defaults to Draft if not specified.	See Order Status. Optional.
  BuyerCompany	Object Buyer	The Buyer company that is purchasing the goods or services. For a subset of details of the Buyer, see Buyer.	Optional for Draft orders.
  SupplierCompany	Object Supplier	The Supplier that provides the goods or services to the Buyer. For a subset of details of the Supplier, see Supplier.	Required for Marketplaces that do not fulfil orders themselves. Optional for all other Marketplaces.
  User	Object User	The user on the Marketplace that is placing the order on behalf of the Buyer company. See User.	Optional for Draft orders.
  Payment	Object Payment	Details of the payment to be made. This includes the order amount and which payment method is being used.	See Payment for more details.
  DeliveryAddresses	Object Array Address	The address or addresses the goods or services are being supplied to. See Address.	Optional for Draft orders.
  PaymentJourney	Object Payment Journey	The details surrounding the Kriya hosted payments journey, see Payment Journey.	Not required if you are following a Direct Api Integration approach. See Integration Scenarios.
  DeliveryDate	DateTime	The delivery date for the goods or services to the Buyer.	Optional. It must not be earlier than the date the order was created.
  InvoiceReference	String	The InvoiceReference number from the Marketplace associated with one or many orders. This can be used to group a set of orders with a single Invoice.	Optional.
  OrderPlacedDate	DateTime	The date the order was placed on the Marketplace.	Optional. It must not be earlier than four days from the current date.

  The following examples show the differing minimum requirements for an Order across multiple statuses:

  Draft

  {
    "marketPlaceOrderId": "0001",
    "payment": {
      "supplier": {
        "amount": 10000
      }
    }
  }
  

  Submitted

  {
      "marketPlaceOrderId": "0001",
      "status": "Submitted",
      "buyerCompany":
      {
          "companyIdentifier": "00123456",
          "companyName": "Buyer Company",
          "countryOfRegistration": "GB",
          "type": "LimitedCompany"
      },
      "payment":
      {
          "supplier":
          {
              "amount": 1
          },
          "paymentMethod": "PAY30"
      },
      "deliveryAddresses":
      [
          {
              "addressLine1": "56 Manor Road",
              "addressLine2": "School Lane",
              "city": null,
              "region": "Bath",
              "postCode": "BA20 8XT"
          }
      ],
      "user":
      {
          "email": "arty.fischel@user.com",
          "fullName": "Arty Fischel"
      }
  }
  

  ReadyToAdvance

  {
      "marketPlaceOrderId": "0001",
      "status": "ReadyToAdvance",
      "buyerCompany":
      {
          "companyIdentifier": "00123456",
          "companyName": "Buyer Company",
          "countryOfRegistration": "GB",
          "type": "LimitedCompany"
      },
      "payment":
      {
          "supplier":
          {
              "amount": 1
          },
          "paymentMethod": "PAY30"
      },
      "deliveryAddresses":
      [
          {
              "addressLine1": "56 Manor Road",
              "addressLine2": "School Lane",
              "city": null,
              "region": "Bath",
              "postCode": "BA20 8XT"
          }
      ],
      "user":
      {
          "email": "arty.fischel@user.com",
          "fullName": "Arty Fischel"
      }
  }
  

  Order with all properties populated

  {
      "marketPlaceOrderId": "0001",
      "status": "Draft",
      "buyerCompany":
      {
          "companyIdentifier": "00123456",
          "companyName": "Buyer Company",
          "countryOfRegistration": "GB",
          "type": "LimitedCompany"
      },
      "supplierCompany":
      {
          "companyIdentifier": "98765432",
          "companyName": "Supplier Company",
          "countryOfRegistration": "GB"
      },
      "payment":
      {
          "supplier":
          {
              "amount": 25000,
              "currency": "GBP"
          },
          "marketplace":
          {
              "amount": 10000,
              "currency": "GBP"
          },
          "paymentMethod": "PAY30"
      },
      "deliveryAddresses":
      [
          {
              "addressLine1": "56 Manor Road",
              "addressLine2": "School Lane",
              "city": null,
              "region": "Bath",
              "postCode": "BA20 8XT"
          }
      ],
      "paymentJourney":
      {
          "paymentAcceptedRedirectUrl": "https://accepted.kriya.co",
          "paymentDeclinedRedirectUrl": "https://declined.kriya.co",
          "autoTransitionOnCompletion": "Submitted"
      },
      "user":
      {
          "email": "arty.fischel@user.com",
          "fullName": "Arty Fischel",
          "role": "Director",
          "phoneNumber": "07777777777"
      },
      "deliveryDate": "2022-07-09",
      "invoiceReference": "INV-001",
      "orderPlacedDate": "2022-07-04"
  }
  

  Order Status

  An order can be created in any modifiable status as long as constraints have been met. The status can be transitioned to several others, those being:

  Name	Description	ReadOnly
  Draft	The draft order status has no impact on a Buyer's available spending limit. It can either be transitioned to Submitted or Cancelled. The Draft status will be the default for all newly created orders if no status has been specified.	No
  Submitted	The order would be transitioned to this status when a customer has chosen to place the order via the Marketplace. Upon transitioning to this status, the orders DeliveryAddresses, Payment, User, BuyerCompany and SupplierCompany, if applicable, must be supplied. The Buyers available spending limit must be >= to the total order amount, and if so, the Buyers available spending limit is reduced to reflect this. The order can still be transitioned to Cancelled at this point.	No
  ReadyToAdvance	Transitioning to this status will inform Kriya Payments API to advance funds equivalent to the order amount, minus fees, to both the Marketplace and Supplier, where applicable. The same requirements as Submitted are needed. At this point, the order cannot be transitioned to Cancelled, and no further updates can be made to the order.	No
  Advanced	The funds associated with the order have now been transferred to the relevant parties involved.	Yes
  Repaid	The Buyer has fully repaid the total amount of the order, including any fees. The Buyers available spending limit is increased by the order amount.	Yes
  Overdue	The Buyer has not fully paid the total amount of the order, including any fees, within the payment period (e.g. 30 days in the case of "Pay in 30 days").	Yes
  Closed	The order has been fully completed and is now closed. The Buyers available spending limit is increased by the order amount.	Yes
  Cancelled	The order has been cancelled. Any deductions to the Buyer's available spending limit have been reverted.	No

  The following order transitions can occur via the API:

  

  Payment

  The payment details of the order, including the amounts payable to the Supplier and Marketplace, where applicable. For example, an order may be split so that £980 goes to the Supplier and the remaining £20 is payable to the Marketplace, which equates to £1,000 owed by the Buyer. When Kriya advances funds, fees will be taken from the payable amounts, and then the remaining funds will be paid to the Marketplace and Supplier as specified. It is the responsibility of the Marketplace to define how the order amount should be separated.

  Property	DataType	Description	Constraints
  Supplier	Object Monetary Data	The total amount of the order payable to the Supplier, excluding any Kriya fees.	It must be greater than zero when Supplier details are included in the order.
  Marketplace	Object Monetary Data	The total amount of the order payable to the Marketplace, excluding any Kriya fees.	It must be greater than zero when included. Optional only when Supplier details are included in the order.
  PaymentMethod	String	The payment method chosen for the order. e.g. Pay in 30 days.	Optional for Draft or Cancelled orders. Retrieve the available payment methods for the Buyer via the Buyer Pricing Scheme endpoint.

  Payment Data

  The details of the order amount that is payable to either the Marketplace or Supplier.

  Property	DataType	Description	Constraints
  Amount	Long (int64)	The total amount of the order, excluding any Kriya fees.	It must be greater than zero.
  CurrencyCode	String (Enum)	The currency the order is to be purchased in.	It must be a valid ISO 4217 code. It must be one of USD, GBP or EUR. The code must also match the Buyers country of registration, e.g. USD for the US.
  PaymentMethod	String	The payment method chosen for the order. e.g. Pay in 30 days.	Optional for Draft or Cancelled orders.

  User

  The user that is making the order on behalf of the Buyer company. If no primary contact details have been specified for the Buyer, the details provided here will be used to contact the Buyer if any issues arise with the order.

  Property	DataType	Description	Constraints
  Name	String	The full name of the user.	It must be between 5 and 150 characters.
  Email	String	The Email address of the user.	It must be a valid Email address. It must be between 1 and 150 characters.
  Role	String	The role of the user within the company.	It must be between 1 and 150 characters. Optional.
  PhoneNumber	String	The contact phone number of the user.	It must be a valid phone number. This is not limited to UK phone numbers. Optional.

  Address

  The address details are used to define the delivery address for the order and the residential address of the individual responsible for a SoleTrader business.

  Property	DataType	Description	Constraints
  AddressLine1	String	First line of the address.	It must be between 1 and 250 characters.
  AddressLine2	String	Second line of the address.	It must be between 1 and 250 characters. Optional.
  City	String	Name of the city.	It must be between 1 and 189 characters. Optional.
  Region	String	Name of the region.	It must be between 1 and 90 characters. Optional.
  PostCode	String	A valid postal code.	It must be a valid postal code.
  Country	String	A valid country	Optional.

  Payment Journey

  The payments journey is only required if you're using the Payments Journey Integration. See Integration Scenarios for more information.

  | Property | DataType | Description | Constraints | |----------------------------|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------| | PaymentAcceptedRedirectUrl | String | The URL that the Payments Journey will redirect to if the customer completes the journey. | It must be a valid absolute URI. | | PaymentDeclinedRedirectUrl | String | The URL that the payments journey will redirect to if the customer does not complete the journey. This can occur when the Buyer has decided to return to the Marketplace, they are ineligible or have insufficient funds to complete the order. | It must be a valid absolute URI. | | DeclineStatus | String (Enum) | The status describes why a Buyer was redirected to the PaymentDeclinedRedirectUrl. See Decline Status for more information. | | | AutoTransitionOnCompletion | String (Enum) | The order status that the order will transition to when the payment journey is completed. See Order Status for more information. | |

  Decline Status

  The DeclineStatus informs you why the user was redirected back to the PaymentDeclinedRedirectUrl.

  Property	Description
  UserInitiated	The user decided to return to the Marketplace and no longer proceed with the order at this time. e.g. They may wish to add additional items to their basket or choose an alternative payment method.
  Ineligible	Kriya Payments were unable to transact with the Buyer as they have not been or are no longer in the Approved status.
  InsufficientFunds	Kriya Payments were unable to transact with the Buyer as their available spending limit is less than the amount of the current order.

  Buyer

  The Buyer is a business on the Marketplace that is purchasing the goods or services from a Supplier or the Marketplace directly. A Buyer must be registered on the Kriya Payments platform and have received an approved limit before they can submit orders.

  Property	DataType	Description	Constraints
  Name	String	The legal name of the company.	It must be between 1 and 250 characters.
  CompanyIdentifier	String	The identifier for the company, i.e. registration number for a LimitedCompany or Email address for a SoleTrader.	LimitedCompany: It must be between 1 and 20 characters. GB based companies must provide a valid 8-character registration number that can be found on Companies House. SoleTrader: It must be a valid Email address.
  CountryCode	String	The code that identifies the country of incorporation of the Buyer's company. The spending limit currency will be assigned based on this. GB will be defaulted to if not specified.	It must be a 2-character ISO 3166-1 alpha-2 code. Optional.
  Type	String (Enum)	The Buyer's company type. This will default to LimitedCompany if not supplied. The SoleTrader type does not yet support any automated risk decisions and therefore, manual intervention is always required.	One of LimitedCompany, SoleTrader. Optional.
  BankAccount	Object Bank Account	The bank account details of the company. This is required for Buyers that want to make their payments via Direct Debit. Kriya Payments supports accounts within GB, the US and several European countries. The bank account details provided must match the associated currency from the CountryCode of the company. For example, a US company must provide a valid US bank account.	See the Bank Account definition. Optional unless the Buyer is paying by Direct Debit.
  ContactDetails	Object Contact Details	The primary contact details for the Buyer company. Any correspondence, in particular, relating to overdue orders will also be sent to the details provided here. Otherwise, only the individual user that created the order will be contacted.	See the Contact Details definition. Optional.
  Director	Object Director	The details of the individual in control of the SoleTrader business. This is used for Kriya Payments risk decisions.	See the Director's definition. Only required for SoleTrader Buyer Type.
  Status	String (Enum)	The status given to the Buyer company from the Kriya Payments risk team. This determines whether or not they can transact with us. See Buyer/Supplier Decision Status for further details.	Only returned by Kriya Payments API responses. This will be ignored if included in any requests.
  TotalLimit	Long (int64)	The spending limit provided to the Buyer by the Kriya Payments risk team. A Buyers spending limit is always under continuing review, and Kriya Payments may increase or decrease a Buyers spending limit over time.	The value provided will be >= 0. Only returned by Kriya Payments API responses. This will be ignored if included in any requests.
  AvailableLimit	Long (int64)	The amount that remains of the Buyer's total limit that they have to transact with using Kriya Payments.	Only returned by Kriya Payments API responses. This will be ignored if included in any requests.

  Minimum details for a Buyer to be created
  Note: This will create a LimitedBuyer for GB as defaults are applied for optional fields.

  {
      "name": "Test Buyer",
      "companyIdentifier": "12345678"
  }
  

  Full details that can be specified
  LimitedCompany

  {
      "name": "Test Buyer",
      "companyIdentifier": "12345678",
      "countryCode": "GB",
      "type": "LimitedCompany",
      "bankAccount": {
          "currencyCode": "GBP",
          "accountName": "Bank of England",
          "sortCode": "100000",
          "accountNumber": "31510604"
      },
      "contactDetails": {
          "name": "Arty Fischel",
          "email": "arty.fischel@user.com",
          "role": "Director",
          "phoneNumber": "+447825998724"
      }
  }
  

  SoleTrader

  {
      "name": "Test Buyer",
      "companyIdentifier": "test@user.com",
      "countryCode": "GB",
      "type": "SoleTrader",
      "bankAccount":
      {
          "currencyCode": "GBP",
          "accountName": "Bank of England",
          "sortCode": "100000",
          "accountNumber": "31510604"
      },
      "director":
      {
          "fullName": "Amelia Bennett",
          "phoneNumber": "07798622788",
          "dateOfBirth": "1975-09-01",
          "residentialAddress": {
              "addressLine1": "80 Church Lane",
              "addressLine2": "Mill Road",
              "city": "Birmingham",
              "region": "West Midlands",
              "postCode": "B2 4JD",
              "country": "United Kingdom"
          }
      }
  }
  

  Buyer Pricing Scheme

  The pricing scheme for a Buyer refers to the possible payment methods available to them, including the fee percentage payable by the Buyer for each method. Pricing schemes are only returned by the API and cannot be modified.

  Property	DataType	Description	Constraints
  Identifier	String	The unique identifier for the payment method. The identifier is used when specifying the PaymentMethod for an Order., e.g. 'PAY30'.
  Name	String	The name of the payment method.
  Description	String	The description of the payment method.
  IsEnabled	Boolean	A flag that identifies whether or not this payment method can be used by the Buyer.
  FeePercentage	Decimal	The fee percentage payable by the Buyer that is added onto the total amount of their order.	Returned as a decimal value between 0 and 100. e.g. 1.5 would be a 1.5% Buyer fee.

  Supplier

  If a Marketplace is not the single Supplier of goods or services or they do not fulfil orders directly at all, then the Supplier must be specified. The Supplier is a company that has been registered on Kriya Payments API and authorised as a seller of goods or services on the platform. Similar to Buyers, a Supplier must also be approved on Kriya Payments API before goods or services can be sold on their behalf on the Marketplace.

  When an order is placed on behalf of a Supplier via the Marketplace, Kriya Payments will need to ensure funds are paid to the Supplier. Due to this, Bank Account details are required for all Suppliers.

  Property	DataType	Description	Constraints
  Name	String	The legal name of the company.	It must be between 1 and 250 characters.
  CompanyIdentifier	String	The identifier for the company.	It must be between 1 and 20 characters. GB based companies must provide a valid 8-character registration number that can be found on Companies House.
  CountryCode	String	The code that identifies the country of incorporation of the Supplier's company. GB will be defaulted to if not specified.	It must be a 2-character ISO 3166-1 alpha-2 code. Optional.
  BankAccount	Object Bank Account	The bank account details of the company for any funds to be paid into. Kriya Payments supports accounts within GB, the US and several European countries. The bank account details provided must match the associated currency from the CountryCode of the company. For example, a US company must provide a valid US bank account.	Required. See Bank Account definition.
  Status	String (Enum)	The status given to the Supplier company from the Kriya Payments risk team. This determines whether or not the Marketplace can sell goods or services on the Supplier's behalf using Kriya Payments. See Buyer/Supplier Decision Status for further details.	Only returned by Kriya Payments API responses. This will be ignored if included in any requests.

  Minimum details for a Supplier to be created

  {
      "name": "Test Supplier",
      "companyIdentifier": "98765432",
      "countryCode": "GB",
      "bankAccount":
      {
          "currencyCode": "GBP",
          "accountName": "Bank of England",
          "sortCode": "100000",
          "accountNumber": "31510604"
      }
  }
  

  Full details that can be specified

  {
      "name": "Test Supplier",
      "companyIdentifier": "98765432",
      "countryCode": "GB",
      "bankAccount": {
          "currencyCode": "GBP",
          "accountName": "Bank of England",
          "sortCode": "100000",
          "accountNumber": "31510604"
      }
  }
  

  Buyer/Supplier Decision Status

  Kriya Payments reviews Buyers regularly and may increase or decrease an approved Buyer's spending limit. In addition to this, Kriya Payments may also reject or require further review of Buyers, which will prevent them from placing other orders. The following statuses can be found for a Buyer:

  Name	Description
  Submitted	The Buyer has been registered, but no risk decision has been made. The automatic risk decision has been triggered to generate a decision.
  InReview	The Buyer is currently being reviewed. Further information is needed before a decision can be made, and manual intervention is required by the Kriya Payments risk team. The company may be contacted to provide further details.
  Approved	The Buyer has been approved and now has a spending limit > 0.
  Rejected	The Buyer has been rejected and will not be able to transact using Kriya Payments. If the Buyer was previously Approved, their spending limit would now be 0.

  Bank Account

  Bank Account details are required for all Suppliers. Bank Accounts are only required for Buyers that intend on paying via Direct Debit.

  Property	DataType	Description	Constraints
  CurrencyCode	String (Enum)	The currency the bank account is held in.	It must be a valid ISO 4217 code. Required for all bank accounts. It must be one of USD, GBP or EUR. Depending upon which code is used, the constraints change as described in this table.
  AccountName	String	The name of the bank account. Used to help verify bank details.	It must be between 1 and 50 characters. Required for all bank accounts.
  SortCode	String	The sort code or routing number (USD).	It must be between 1 and 10 characters. Required for both GBP and USD accounts.
  AccountNumber	String	The account number.	It must be between 1 and 10 characters. Required for both GBP and USD accounts.
  Bic	String	The Swift BIC (Bank identifier code).	It must be between 1 and 10 characters. Optional for all bank accounts. It must be a valid ISO 9362 code.
  AccountType	String (Enum)	The type of USD account.	It must be one of Checking or Savings. Required for USD accounts.
  Iban	String	The International Bank Account Number as per ISO 3616.	It must be between 1 and 34 characters. Required for EUR bank accounts.

  The following examples show the requirements for the bank account structure for different countries:

  GB:

  {
      "currencyCode": "GBP",
      "accountName": "Bank of England",
      "sortCode": "100000",
      "accountNumber": "31510604"
  }
  

  US:

  {
      "currencyCode": "USD",
      "accountName": "Bank of America",
      "sortCode": "220737409",
      "accountNumber": "58474125",
      "accountType": "Checking"
  }
  

  European countries:

  {
      "currencyCode": "EUR",
      "accountName": "Bayerische Landesbank",
      "iban": "DE89370400440532013000"
  }
  

  Contact Details

  The primary contact details are used for the Buyer company. Any correspondence, in particular, relating to overdue orders will be sent to the details provided here. Otherwise, the individual user that created the order will be contacted.

  Property	DataType	Description	Constraints
  Name	String	The full name of the primary contact.	It must be between 5 and 150 characters. Optional.
  Email	String	The Email address of the primary contact.	It must be a valid Email address. It must be between 1 and 150 characters. Optional.
  Role	String	The role of the primary contact within the company.	It must be between 1 and 150 characters. Optional.
  PhoneNumber	String	The contact phone number of the primary contact.	It must be a valid phone number. This is not limited to UK phone numbers. Optional.

  Director

  The details of the individual responsible for the SoleTrader business. This data is required for any SoleTrader Buyer for Kriya Payments risk decisions.

  Property	DataType	Description	Constraints
  FullName	String	The full name of the individual responsible for the SoleTrader business.	It must be between 5 and 150 characters. Optional.
  DateOfBirth	Date	The Date of Birth of the individual responsible for the SoleTrader business.	It must be at least 18 years old.
  PhoneNumber	String	The contact phone number of the individual responsible for the SoleTrader business.	It must be a valid phone number. This is not limited to UK phone numbers. Optional.
  ResidentialAddress	Object Address	The residential address of the individual responsible for the SoleTrader business.	| |

  Monetary data

  The structure of the monetary data is composed of the amount and the currency.

  Property	DataType	Description	Constraints
  Amount	Long (int64)	The amount expressed in the currency below.	It must be greater than zero.
  CurrencyCode	String (Enum)	The currency related to the amount above.	It must be a valid ISO 4217 code. It must be one of USD, GBP or EUR. The code must also match the Buyers country of registration, e.g. USD for the US.

  Webhooks

  The Kriya Payments API uses webhooks to send POST requests to your application when a specific event occurs across several entities. This mechanism ensures that your apps can stay in sync with Kriya Payments data or allow you to react to particular events. Webhooks also provide a better alternative than polling specific endpoints for changes.

  All supported event types will be sent to the same Webhook URL provided. The following event types are supported via webhooks:

  • BuyerRiskDecisionChanged - The Kriya Payments risk decision has changed for a Buyer. Either an already Approved Buyer has had their spending limit increased/decreased, or a Buyer status has transitioned to a different Order Status, e.g. due to our automated risk decisions.
  • BuyerAvailableLimitChanged - An event has occurred that has altered the available spending limit for the Buyer. Examples of this may be an order transitioning to a new status, such as Submitted, ReadyToAdvance or Repaid, etc. The value of an order has changed, the buyer belongs to multiple Marketplaces and has transacted elsewhere or our risk team have altered the status/limit of the Buyer directly.
  • OrderStatusChanged - An order has transitioned to a different status. This is particularly useful for tracking operational activities beyond the checkout process. For example, an order moves from Advanced to Repaid when a successful payment has been made by a Buyer. See Order Status to see all transitions. The message will also contain the available spending limit of the Buyer.
  • SupplierRiskDecisionChanged - The Kriya Payments risk decision has changed for a Supplier. It occurs when the status of a Supplier is transitioned to another Order Status by the Kriya Payments Risk team. There are no automated decisions for Suppliers yet.

  The payload you will receive from the webhook will be sent using the following structure:

  Property	DataType	Description
  Type	String	The defined Type of the event that triggered the webhook to be sent.
  Timestamp	DateTime	The date and time that the event occurred.
  Message	Object	The object that relates specifically to the Type of event being sent.

  The possible Message object structures for the events types are:

  BuyerRiskDecisionChanged

  {
      "companyIdentifier": "12345678",
      "countryCode": "GB",
      "companyType": "limitedcompany",
      "limit": 15000000,
      "status": "Approved",
      "currentBalance": 14100000
  }
  

  BuyerAvailableLimitChanged

  {
      "companyIdentifier": "12345678",
      "countryCode": "GB",
      "companyType": "limitedcompany",
      "currentBalance": 14100000,
      "currencyCode": "GBP"
  }
  

  OrderStatusChanged

  {
      "marketplaceOrderId": "0001",
      "oldStatus": "Draft",
      "newStatus": "Submitted",
      "buyerCurrentBalance": 1500000
  }
  

  SupplierRiskDecisionChanged

  {
      "companyIdentifier": "12345678",
      "countryCode": "GB",
      "status": "Approved"
  }
  

  The following example shows what a complete webhook request may look like:

  {
      "type": "OrderStatusChanged",
      "message": {
          "marketplaceOrderId": "0001",
          "oldStatus": "Draft",
          "newStatus": "Submitted",
          "buyerCurrentBalance": 1500000
      },
      "timestamp": "2022-03-28T15:09:21.5369596+00:00"
  }
  

  Configuring Webhooks

  A single URL on your server to receive requests is required for us to set up your webhook. To set this up, please get in touch with us at apisupport@kriya.co, and we can configure this for you in both your test and production environments.

  Verifying Webhooks

  When your server receives requests from webhooks, the authenticity and integrity of the request should be verified. You will be able to perform this verification by generating a hash-based message authentication code (HMAC) based on the payload in the webhook request and a secret key specific to you.

  The Kriya Payments API signs the payload in the request and includes a base64-encoded HMAC in the request header X-Kriya-Signature. To verify the webhook was sent from the Kriya Payments API and the integrity of the payload, you should:

  1. Retrieve the key that you should have received from the Kriya team. This should be stored securely on your server.
  2. Generate an HMAC-SHA256 hash based on the payload you received in the request and your HMAC key.
  3. The generated hash should be base64-encoded.
  4. Compare this generated value with the value from X-Kriya-Signature. If the two values match, then the webhook has been verified as being sent from the Kriya Payments API.

  Code sample (C#, .NET):

  using System.Security.Cryptography;
  using System.Text;
  ...
  using var hmacSha256 = new HMACSHA256(Encoding.UTF8.GetBytes(hmacKey));
  var hashBytes = hmacSha256.ComputeHash(Encoding.UTF8.GetBytes(payload));
  var isVerified = xKriyaPaymentsSignature.Equals(Convert.ToBase64String(hashBytes));
  

  If you haven't received your HMAC key yet? Please get in touch with us at apisupport@kriya.co.

  Limitations and Best Practices

  Acknowledgement and Retries

  Any requests made to the URL specified must return an acknowledgement by providing a 2XX response. If no acknowledgement is made, Kriya Payments will retry your URL up to 3 times with an exponential backoff of 2 seconds for each retry (i.e. 2s, 4s, 8s) until retries are exhausted. If retries have been exhausted, Kriya Payments will contact you and provide further details and decide if/when webhooks should be replayed.

  Reconciliation

  As mentioned above, webhook delivery is not always guaranteed. It is therefore suggested that the Marketplace implements relevant mechanisms to synchronise any data they require from Kriya Payments to their applications regularly, e.g. recurring data fetching.

  Delayed Requests

  There may be times when webhook requests are made with a delay since the event occurred. This may be due to processing times on Kriya Payments or due to retries made to the server for the webhook URL. It is suggested that the Timestamp received on every request is reviewed to determine if you perceive the data to be 'stale' and instead, either the webhook event is ignored if a more recent one has been provided or the Kriya Payments API called directly to re-retrieve the latest data.

  API Environments

  The API currently supports two environments, that is, both Test and Production. Please note that you must request access to these environments separately and receive API keys for both.

  Test

  The Test API can be accessed through the base URL https://api.kriya.dev/payments/

  The 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 for more details.

  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.

  Test Scenario Simulators

  When integrating with the Kriya Payments API, there may be certain situations that you want to be able to test and ensure your integration handles successfully, for example, when an order is Repaid. In our test environment, we have provided a set of API endpoints that can be used to simulate these scenarios that you would not typically be able to do directly via the production endpoints.

  Buyer/Supplier Decisioning

  This is valuable in instances where you need to test specific scenarios against Buyers/Suppliers with a certain status or spending limit. Without calling this endpoint, any newly registered Buyers/Suppliers on the Test environment may resolve to one of the possible Buyer/Supplier Decision Statuses due to our automated risk decisions and is, therefore, non-deterministic.

  To override this, you can use the Test environment-specific endpoints to transition a Buyer/Supplier to a specific status or set a spending limit for a Buyer:

  • /api/scenario/Buyers/risk-decision
  • /api/scenario/Suppliers/risk-decision

  Order Status Transitions

  There are several Order Statuses that an order can be transitioned to. However, a number of them are not possible to be set by the API as they are only transitioned to the statuses internally within Kriya Payments. However, to ensure you can test orders in these specific statuses, we have provided an endpoint on the Test environment that allows you to transition your order to a valid Order Status.

  Please note that whilst you can transition to these internal statuses, the transition must still be valid. For example, you cannot move a ReadyToAdvance order directly to Repaid without transitioning to Advanced first.

  • /api/scenario/orders/{MarketplaceOrderId}/transition

  Production

  The Production API can be accessed through the base URL https://api.kriya.co/payments/.

  Support

  If you have any questions concerning API or suggestions or are facing any issues, please get in touch with us at apisupport@kriya.co.

  If you're interested to learn more about how Kriya Payments can help your business, you can either request a demo here or contact us at payments@kriya.co.

  API Endpoints

• Lending API

  Introduction

  Lending API allows MarketFinance partners to interact with MarketFinance lending products via API. Lending API covers the following main use cases:

  1. Request a quote for a given customer
  2. Refer a potential customer to MarketFinance (the customer need to be redirected to MarketFinance application journey to complete the application)
  3. Submit a full application for MarketFinance (the customer doesn't need to be redirected to the MarketFinance application journey)

  Access to the API is restricted to selected partners and those with access will have received the relevant credentials.

  If you want to learn more about LendingAPI, please contact us at apisupport@marketfinance.com.

  Cross-Origin Resource Sharing

  This API features Cross-Origin Resource Sharing (CORS) implemented in compliance with W3C spec. And that allows cross-domain communication from the browser. All responses have a wildcard same-origin which makes them completely public and accessible to everyone, including any code on any site.

  Authorization

  Once you have been approved to use the API, you will have access to your own API keys that must be sent using the header X-MarketFinance-ApiKey with every request.

  All incoming data and outgoing responses will be provided using JSON.

  All requests must be sent over HTTPS.

  Rate Limiting

  To manage the volume of requests on the API, limits are placed on the number of requests that can be made. This approach ensures we can continue to have a reliable API for partners to consume.

  The requests are measured over a specified period of time per API key. The current limitations are that no more than 2000 requests can be made to the API every 5 minutes across all endpoints. If the limit is breached, the API will begin to respond with 429 Too Many Requests until the time interval has refreshed.

  If limits are consistently breached on the API, we may temporarily disable your access to the API and inform you of this.

  Response Status Codes

  API requests made to Lending Api endpoints may return a number of different HTTP status codes.

  Status Code	Description
  200 OK	The request was received and successfully processed by LendingApi.
  201 Created	The request was received, successfully processed and a new resource was created.
  400 Bad Request	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.
  401 Unauthorized	The X-MarketFinance-ApiKey header was not present or is invalid.
  404 Not Found	The requested resource could not be found.
  429 Too Many Requests	The application has exceeded the rate limit. See Rate Limiting.
  500 Internal Server Error	An unexpected internal error has occurred. Please contact us at apisupport@marketfinance.com so that we can investigate further.
  503 Service Unavailable	The server is currently unavailable and cannot accept requests. We will inform Partner of any planned downtime or outages. If you have not received any communication and you have received this response code, please contact apisupport@marketfinance.com.

  Definitions

  Borrower: A legal entity requesting funding.

  Partner: A consumer of the MarketFinance Lending API that intends to offer MarketFinance products to Borrowers.

  Application: A set of data points used to generate a Quote or an Offer. Contains information about the Borrower and their funding needs.

  Quote: Indicative funding terms for a given Borrower. Intended to inform the Borrower of the likelihood of receiving funding and indicative pricing if they are to continue with their application. There are two types of quotes - Representative Quote and Accurate Quote.

  Representative Quote: A static (hardcoded) quote that is being returned regardless of the inputs provided. It doesn’t reflect the riskiness or eligibility of a given Borrower.

  Accurate Quote: A quote stating the actual price (and other product parameters) the Borrower would likely get if they decide to apply.

  Offer: An underwritten offer with the final pricing for the funding being requested.

  Webhook: The way in which the Lending API exposes events to the Partner when either Quotes and Offers are created or their state changes (e.g. Borrower accepts an Offer).

  Integration Scenarios

  The Lending API provides two integration scenarios, those being the Referral Journey and then Full Application Journey.

  Referral Journey

  This integration scenario is used if the Partner wants to refer a potential Borrower to MarketFinance and the Partner doesn't have enough data to submit a full application.

  The main steps are:

  1. The Partner calls into Lending API and provides the data points they currently have.
  2. Lending API responds with the quote and the URL to continue the application.
  3. The Partner presents the quote to the Borrower, if the Borrower is willing to proceed, the Partner redirects the Borrower to the URL received from the API.
  4. The Borrower fills out remaining fields and submits the application.

  On a lower level the same steps will look like the following:

  1. Partner makes a request to the Lending API CreateApplication endpoint to register a draft application on the API.
  2. Lending API responds with a 201 Created status code to confirm the application has been created.
  3. Lending API provides Accurate or Representative quotes to the Partner via webhook or GetOffersByApplicationId endpoint.
  4. Partner displays a button on their web site to allow the Borrower to accept the quote.
  5. Borrower clicks the button to accept the quote.
  6. Partner calls AcceptOffer endpoint of Lending API and redirects the Borrower to the MarketFinance-hosted application journey web site via RedirectUrl link provided in (3). See the animated gif with the full journey below.
  7. Borrower validates pre-populated data, fills out remaining fields and submits the application on the application journey website.
  8. Lending API notifies the Partner via the Webhook in case the Offer is generated for the Borrower or if additional actions are required from the Borrower to proceed.

  Referral Journey sequence diagram:

  

  Application journey on the MarketFinance-hosted web-site:

  

  Full Application Journey

  This integration scenario is used if the Partner wants to refer a potential Borrower to MarketFinance but doesn't want the Borrower to be redirected to any 3rd party web-sites.

  Typical sequence of actions:

  1. Partner makes a request to the CreateApplication endpoint to create a draft application.
  2. Lending API responds with a 201 Created status code to confirm the application has been created.
  3. Lending API begins risk decisioning process to determine borrower's eligibility.
  4. Lending API notifies the Partner via the Webhook in case the Offer is generated for the Borrower or if additional actions are required from the Borrower to proceed.

  Full Application Journey sequence diagram:

  

  Defined Types

  Unless specified otherwise, all properties are Required when making API calls.

  Application

  A set of data points used to generate a Quote or an Offer. Contains information about the Borrower and their funding needs.

  Property	DataType	Description	Constraints
  ExternalIdentifier	String	The unique application identifier from the Partner.	Must be between 1 and 256 characters. Must be unique across all applications created by Partner.
  IsAutoSubmit	Boolean	false to proceed with Referral Journey, true to proceed with Full Application Journey.	Optional, false by default.
  ReasonForFunding	String (Enum) Reason for Funding	The reason for funding.	Optional. See Reason for Funding for more details.
  ReasonForFundingOtherDetails	String	Additional details in case Other was provided as a value for ReasonForFunding.	Required in case Other was provided as a value for ReasonForFunding.
  ApplicationStatus	String (Enum) Application Status	The status of the application. This field doesn't need to be provided when calling CreateApplication endpoint.	See Application Status.
  Company	Object Company	The Borrower company details.
  Applicant	Object Applicant	Details of the person submitting an application.	Applicant's details may differ from Director's details.
  Director	Object Director	Borrower's company director details. Application is submitted on behalf of this director.	In case an Applicant and Director is the same person the same details should be provided into both fields.
  FundingRequests	Object Array Funding Request	An array of Funding Requests. See Funding Request for more details.	At least one funding request has to be provided.
  Documents	Object Array Document	An array of Documents. See Document for more details.	Optional.

  Examples:

  Application with required fields only

  {
    "externalIdentifier" : "Borrower 123",
    "company": {
      "registrationNumber" : "00000002",
      "name": "Company 123"
    },
    "applicant": {
      "email": "john.doe@corp.com",
      "firstName": "John",
      "lastName": "Doe",
      "phoneNumber": "0123456711"
    },
    "director": {
      "email": "director@mail.com",
      "firstName": "Jane",
      "lastName": "Doe",
      "dateOfBirth": "2000-01-01",
      "postCode": "PO2 7NE",
      "country": "UK",
      "addressLine1": "Address Line 1",
      "city": "Portsmouth",
      "addressDurationMonths": 15
    },
    "fundingRequests": [
      {
          "fundingType": "TermLoan",
          "amount": 150000,
          "tenorType": "Year"
      }
    ]
  }
  

  Application with all fields populated

  {
    "externalIdentifier" : "Borrower 123",
    "isAutoSubmit": false,
    "reasonForFunding": "Other",
    "reasonForFundingOtherDetails": "Test",  
    "company": {
      "registrationNumber" : "00000002",
      "name": "Company 123"
    },
    "applicant": {
      "email": "john.doe@corp.com",
      "firstName": "John",
      "lastName": "Doe",
      "phoneNumber": "0123456711"
    },
    "director": {
      "email": "director@mail.com",
      "firstName": "Jane",
      "lastName": "Doe",
      "dateOfBirth": "2000-01-01",
      "postCode": "PO2 7NE",
      "country": "UK",
      "addressLine1": "Address Line 1",
      "addressLine2": "Address Line 2",
      "city": "Portsmouth",
      "region": "Region",
      "addressDurationMonths": 15
    },
    "fundingRequests": [{
      "fundingType": "TermLoan",
      "amount": 150000,
      "tenorType": "Year"
    }],
    "documents": [{
      "documentType": "BankStatement",
      "url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
      "fileName": "BankStatement.pdf"
    },
    {
      "documentType": "StatutoryAccount",
      "url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
      "fileName": "StatutoryAccount.pdf"
    },
    {
      "documentType": "SupportingDocument",
      "url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
      "fileName": "SupportingDocument.pdf"
    }]
  }
  

  Reason For Funding

  Defines how the Borrower is planning to use the proceeds from a lending product requested (e.g. loan).

  Name	Description
  WorkingCapital	Funding planned to be used for the Borrower's company working capital.
  Investment	Funding planned to be used to support the Borrower's company investments.
  RefinancingCbilsOrBblFacility	Funding planned to be used for refinancing Cbils or Bbl facility.
  RefinancingMarketFinanceDebt	Funding planned to be used to refinance Market Finance debt.
  RefinancingAnyOtherDebt	Funding planned to be used to refinance any other debt.
  Other	Other reason than those specified above. Additional details are required if this value is selected.
  RefinancingRLSFacility	Funding planned to be used to refinance RLS facility.

  Application Status

  Defines the current state of the application. It is set by the Lending Api based on the application processing phase.

  Name	Description
  ProcessingDraft	All new applications created via Lending Api have ProcessingDraft status by default. It can either be transitioned to Draft or Blocked.
  Draft	Lending API completed the initial processing of data provided (e.g. downloading documents).
  ProcessingSubmit	Borrower completed the application journey and submitted the application.
  Submitted	Lending API completes the initial processing of provided data after the application submission.
  Blocked	There is a problem with the application and it's not possible to process it, e.g. there is another active application for the same Borrower. This state is a terminal state.
  RiskRejected	MarketFinance is unable to satisfy the funding request from the Borrower due to the MarketFinance risk policy.
  MoreInformationRequired	Additional details are required from the Borrower to proceed with the application (e.g. incomplete documents were provided). The Borrower will be contacted by MarketFinance representative.

  Company

  Borrower's company information.

  Property	DataType	Description	Constraints
  Name	String	Legal name of the company.	Must be between 1 and 256 characters.
  RegistrationNumber	String	UK Company Registration Number.	Must be valid UK Company registration number.

  Applicant

  Contact information for the person submitting the application.

  Property	DataType	Description	Constraints
  FirstName	String	Applicant's first name.	Must be between 1 and 256 characters.
  LastName	String	Applicant's last name.	Must be between 1 and 256 characters.
  Email	String	Applicant's email address.	Must be valid email address.
  PhoneNumber	String	Applicant's contact phone number.	Applicant's UK phone number starting either from +44 or from 0.

  Director

  The details for the director of the Borrower company. The application is submitted on behalf of this director.

  Property	DataType	Description	Constraints
  FirstName	String	Director's first name.	Must be between 1 and 256 characters.
  LastName	String	Director's last name.	Must be between 1 and 256 characters.
  Email	String	Director's email address.	Must be valid email address.
  DateOfBirth	DateTime	Director's date of birth.	Director must be at least 18 years old.
  AddressLine1	String	First line of the address.	Must be between 1 and 256 characters.
  AddressLine2	String	Second line of the address.	Must be between 1 and 256 characters. Optional.
  Country	String	Name of the country.	Must be between 1 and 256 characters.
  City	String	Name of the city.	Must be between 1 and 256 characters.
  Region	String	Name of the region.	Must be between 1 and 256 characters. Optional.
  PostCode	String	A valid postal code.	Must be a valid UK postal code.
  AddressDurationMonths	Long (int32)	How long has the director lived at their current address (in months).	Must be greater than 0.

  Funding Request

  Details about the funding product requested.

  Property	DataType	Description	Constraints
  FundingType	String (Enum) Funding Type	Requested product type.
  Amount	Decimal	Requested amount in GBP.	Must be greater than 0.
  TenorType	String (Enum) Tenor Type	Required product duration.

  Funding Type

  The type of the product the applicant is appying for.

  Name	Description
  TermLoan	MarketFinance Business Loan product.

  Tenor Type

  Product duration.

  Name	Description
  HalfYear	6 months product duration.
  Year	12 months product duration.
  TwoYears	24 months product duration.
  ThreeYears	36 months product duration.
  FourYears	48 months product duration.
  FiveYears	60 months product duration.
  SixYears	72 months product duration.

  Document

  Document containing the information required for risk assessment.

  Property	DataType	Description	Constraints
  Url	String (Uri)	The document uri for downloading.	Must be a valid url address of 2048 characters max.
  FileName	String	Document's file name.	Must be a valid filename of 256 characters max.
  DocumentType	String (Enum) Document Type	The type of the document.

  Document Type

  The type of the document.

  Name	Description
  BankStatement	Official bank statement.
  StatutoryAccount	Statutory accounts document.
  SupportingDocument	Any other documents.

  Offer

  An underwritten offer with the final pricing for the funding being requested.

  Property	DataType	Description	Constraints
  Id	String (uuid)	The unique identifier of the offer.
  ExpiryAt	DateTime	Offer's expiry date after which the offer will no longer be valid.	Optional.
  Status	String (Enum) Offer Status	The status of the offer.	See Offer Status for more details.
  Details	String	Details of the offer (additional information), e.g. "Representative Rate".
  OfferType	String (Enum) Offer Type	The type of the offer.	See Offer Type for more details.
  FundingType	String (Enum) Funding Type	The product being offered.	See Funding Type for more details.
  AnnualPercentageRate	Decimal	APR - the yearly interest generated by a sum that's charged to borrowers.	Must be greater than 0.
  InterestRate	Decimal	The nominal annual interest rate of the product being offered.	Optional. Must be greater than or equal to 0.
  Amount	Decimal	The amount offered to borrower (e.g. the loan principal amount).	Optional.
  Duration	String (Enum) Tenor Type	The tenor of the product being offered.
  StatusChangedAt	DateTime	The last offer's status change date.
  RepaymentFrequency	String (Enum) Repayment Frequency	Installment frequency - how frequently the borrower have to make repayments.	Optional.
  TotalAmountPayable	Decimal	The total amount payable by the Borrower (e.g. principal + accrued interest + arrangement fee for the loan).	Optional. Must be greater than or equal to 0.
  ArrangementFee	Object Arrangement Fee	An administration charge for arranging the requested lending product.	Optional.

  Offer Status

  The current status of the Offer.

  Name	Description
  Offered	All new offers created via Lending Api have Offered status by default.
  Expired	Expiration date of the offer has passed, the offer is no longer valid. This state is a terminal state.
  CustomerAccepted	Borrower has accepted the offer. This state is assign when Partner calls AcceptOffer endpoint.
  Advanced	Funds were advanced to the Borrower. This state is a terminal state.
  Archived	The offer is no longer valid. E.g. the Borrower has accepted the Quote, but decided not to take the product later in the process.

  Offer Type

  Lending Api support multiple types of offers, those being:

  Name	Description
  Representative	A static (hardcoded) quote that is being returned regardless of the inputs provided. It doesn’t reflect the riskiness or eligibility of a given Borrower.
  Accurate	A quote stating the actual price (and other product parameters) the Borrower would likely get if they decide to apply.
  Underwritten	An underwritten offer with the final product parameters and the pricing for the funding being requested.

  Repayment Frequency

  Installment frequency - how frequently the borrower have to make repayments.

  Name	Description
  Monthly	Repayments have to be made each month.

  Arrangement Fee

  An administration charge for arranging the requested lending product.

  Property	DataType	Description	Constraints
  Amount	Decimal	The amount to be charged in GBP.	Must be greater than or equal to 0.
  IncludeInPrincipal	Boolean	Defines whether the arrangement fee is added to the principal true or will be deducted from the advanced amount false. This is specific to the product and cannot be modified.

  Webhooks

  The Lending API uses webhooks to send POST requests to Partner's application when a specific event occurs. Webhooks is a better alternative than polling specific endpoints for changes.

  The following events are supported via webhooks:

  • ApplicationStatusChanged - An application has transitioned to a different status.
  • OfferStatusChanged - An offer has transitioned to a different status.
  • DocumentDownloadFailure - An error happen while Lending API was trying to download the documents provided by Partner.

  ApplicationStatusChanged

  {
      "applicationIdentifier": "7ec9ada6-d63b-492c-85b2-24cf05db82d9",
      "status": "Draft",
      "updatedAt": "2022-09-06T07:09:10.8096713+00:00",
      "createdAt": "2022-09-06T07:09:07.6731881+00:00",
      "redirectUrl": "https://apply-staging.marketfinance.ninja/application/7ec9ada6-d63b-492c-85b2-24cf05db82d9/continue?key=VQDsPYCs4uqpVnrGtO9oDJAF7E4OvFHCuSfRoqAy1piltGRmeymY8jR6khk5/W0t8TqlZ/ks6F6m4hOvatHOFt0RAI1RRD3036JMLtEgKvBtHxVTuxLRpoWCfTBBjCi7ZTR7dltsMXWqxQXIDOiYoF85eIYkNBFo9eIfI1ZHeenTh8JDnMocJnerNq9HeNzVmmkQgPUlFKC/tVyxMY6r04M0/niR25YT3CIbSJvyhjsfPcHmAfqsG3VBeoHMcOxB44h4LdTj9Yg3LwiPFXf+p2M5iw+NQuCASgyj3fMlojILNIWkS8EjeOUMIqCHRS5zM3Vsx/S+OWvSqEd/0j63Kw=="
  }
  

  OfferStatusChanged

  {
      "expiryAt": "2022-09-13T07:11:35.5646208+00:00",
      "status": "Offered",
      "details": "Standard display name - Standard description",
      "fundingType": "TermLoan",
      "offerType": "Accurate",
      "annualPercentageRate": 0.077800,
      "interestRate": 0.074900,
      "id": "d0b4c944-1d5e-4f7c-af13-7ed74893ee32",
      "amount": 1320000.0000,
      "duration": "Year",
      "statusChangedAt": "2022-09-06T07:11:37.2226245+00:00",
      "repaymentFrequency": "Monthly",
      "totalAmountPayable": 1398657.6200,
      "arrangementFee": {
        "amount": 1200000.0000,
        "includeInPrincipal": true
      }
    }
  

  DocumentDownloadFailure

  {
      "applicationIdentifier": "0a6638f7-3c8a-4187-8d3d-695f53442448",
      "url": "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy1.pdf",
      "fileName": "BankStatement.pdf",
      "documentType": "BankStatement",
      "errorMessage": "Unable to download file at url https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy1.pdf"
  }
  

  Configuring Webhooks

  In order to configure Webhooks, please contact us at apisupport@marketfinance.com and provide with a list of target urls (URLs that will be invoked by the Lending API) for each webhook type for both test and production environments.

  Verifying Webhooks

  When your server receives requests from webhooks, the authenticity and integrity of the request should be verified. You will be able to perform this verification by generating a hash-based message authentication code (HMAC) based on the payload in the webhook request and a secret key specific to you.

  The Lending API signs the payload in the request and includes a base64-encoded HMAC in the request header X-LendingApi-Signature. To verify the webhook was sent from the LendingApi API and the integrity of the payload, you should:

  1. Retrieve your key that you should have received from the MarketFinance team. This should be stored securely on your server.
  2. Generate a HMAC-SHA256 hash based on the payload you received in the request and your HMAC key.
  3. The generated hash should be base64-encoded.
  4. Compare this generated value with the value from X-LendingApi-Signature. If the two match, then the webhook has been verified as being sent from the LendingApi API.

  Code sample (C#, .NET):

  using System.Security.Cryptography;
  using System.Text;
  ...
  using var hmacSha256 = new HMACSHA256(Encoding.UTF8.GetBytes(hmacKey));
  var hashBytes = hmacSha256.ComputeHash(Encoding.UTF8.GetBytes(payload));
  var isVerified = xLendingApiSignature.Equals(Convert.ToBase64String(hashBytes));
  

  Haven't received your HMAC key yet? Please contact us at apisupport@marketfinance.com.

  Acknowledgement and Retries

  Any requests made to the URL specified must return an acknowledgement by providing a 2XX response. If no acknowledgement is made, LendingApi will retry your URL up to 3 times with an exponential back off of 2 seconds for each retry (i.e. 2s, 4s, 8s) until retries are exhausted. If retries have been exhausted, LendingApi will contact you and provide further details and decide if/when webhooks should be replayed.

  Reconciliation

  As mentioned above, webhook delivery is not always guaranteed. It is therefore suggested that the Partner implements relevant mechanisms to synchronise any data they require from LendingApi to their own applications on a recurring basis, e.g. recurring data fetching.

  API Environments

  The API currently supports two environments: Test and Production. Please note that you must request access to these environments separately and receive API keys for both.

  Test

  The Test API can be accessed through the base URL https://api-staging.marketfinance.ninja/lending/

  The Test environment has been created to allow for partners to test their integrations.

  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.

  Production

  The Production API can be accessed through the base URL https://api.marketfinance.com/lending/.

  Support

  If you have any questions in relation to the API, suggestions or are facing any issues, please get in touch with us at apisupport@marketfinance.com.

  API Endpoints

• MarketPay Public

  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.

  Access to the API is restricted to select partners, and those with access will have received the relevant credentials.

  Developers can use this documentation to understand how to implement the BNPL scheme.

  Want to learn more about Kriya Payments? You can either request a demo here or contact us at payments@kriya.co.

  Cross-Origin Resource Sharing

  This API features Cross-Origin Resource Sharing (CORS) implemented in compliance with W3C spec. And 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.

  Authorization

  Once approved to use the API, you will have access to your API keys that you must send using the header X-Kriya-ApiKey with every request.

  Requests and responses must use JSON.

  All API requests must be sent over HTTPS.

  Rate Limiting

  The API limits the number of requests that can be made. This approach ensures we can continue to have a reliable API for partners to consume.

  Requests are measured over a specified period per API key. The current limitations are that no more than 2000 requests can be made to the API every 5 minutes across all endpoints. If the limit is breached, the API will begin to respond with 429 Too Many Requests until the time interval has been refreshed.

  If limits are consistently breached on the API, we may temporarily disable your access to the API and inform you of this.

  Response Status Codes

  API requests made to Kriya Payments endpoints may return several different HTTP status codes.

  Status Code	Description
  200 OK	The request was received and successfully processed by Kriya Payments.
  201 Created	The request was received and successfully processed, and a new resource was created.
  400 Bad Request	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.
  401 Unauthorized	The X-Kriya-ApiKey header was not present or is invalid.
  404 Not Found	The requested resource could not be found.
  429 Too Many Requests	The application has exceeded the rate limit. See Rate Limiting.
  500 Internal Server Error	An unexpected internal error has occurred. Please get in touch with us at apisupport@kriya.co so that we can investigate further.
  503 Service Unavailable	The server is currently unavailable and cannot accept requests. We will inform Marketplaces of any planned downtime or outages. If you have not received any communication and you have received this response code, please get in touch with us at apisupport@kriya.co.

  Definitions

  Marketplace: The Marketplace is the partner that will integrate with the Kriya Payments API. This is typically an online platform that provides goods or services to Buyers, either directly or via Suppliers.

  Buyer: A Buyer is a business that is purchasing goods or services from the Marketplace. A Buyer must be registered on Kriya Payments API and be given an approved spending limit before being able to transact with us.

  Supplier: A Supplier is a business that provides goods or services to be sold via the Marketplace. The Supplier must be registered and approved on Kriya Payments API before the Marketplace sells goods or services on their behalf. A Supplier may also be a Buyer on either the same or other Marketplaces.

  Order: An order is an agreement between the Buyer, Supplier, and the Marketplace of buying goods and services. The value of the order may be the sum of one or many goods or services. An individual order can be purchased via the BNPL options provided to Buyers.

  Spending Limit: The spending limit is the total amount that Kriya Payments can offer a Buyer to transact with. Kriya Payments continually monitors the spending limits assigned to Buyers and may increase or decrease them.

  Available Spending Limit: The available spending limit is the amount that the Buyer can use to transact using Kriya Payments. Whenever an order progresses beyond the Draft status, the total amount of the order is deducted from the available spending limit. All orders made must fall within the available spending limit for the Buyer.

  Kriya Payments Fee: Orders created may be paid for from several payment methods, e.g. "Pay in 30 days". Each payment method may include a fee that is payable by the Buyer that is based on a percentage of the order amount. When the Buyers available spending limit is reduced, it is exclusive of fees. For example, a Buyer may want to pay for a £1,000 order using a payment method that has a 1.00% fee. The total amount payable by the Buyer would be £1,010, and their available spending limit is reduced by £1,000.

  Payment Method: A payment method is a specific term under which an order is to be paid. For example, "Pay in 30 days" or "Pay in 3 instalments". Each Marketplace and Buyer can have different methods provided to them at the checkout stage. Fees associated with payment methods can be set globally or overridden for specific Buyers.

  Integration Scenarios

  The Kriya Payments API provides a variety of methods of integration for partners. This includes direct API integration and a Kriya Payments-hosted Payments Journey web application.

  The following table outlines the differences in scenarios:

  Property	Direct API	Payments Journey
  Effort	The estimated effort of between 1-4 weeks to implement. The developer effort is more significant as it involves a bespoke integration built by the Marketplace.	The estimated effort of around one week to implement. Lower development effort as the majority of the integration is handled by the Kriya Payments Payments Journey with only minimal API integration required by the Marketplace.
  Checkout data collection	Additional fields, if not currently exposed, may be required to create a Kriya Payments order that the Marketplace must embed in their checkouts.	Kriya Payments collects Company and User details on your behalf. Returning Buyers also have their previous data pre-populated to increase the speed of the checkout process.
  Branding	The integration will be built by the Marketplace, and any branding can be fully controlled.	Co-branding is limited to displaying the Marketplace logo, but further enhancements are on the roadmap.
  User experience	The Marketplace must define its UX and UI for its Buyers that align with the API flows. Users stay within the domain of the Marketplaces website.	User experience is pre-defined by Kriya Payments and optimised based on regularly reviewed metrics collected from customers that use the Payment Journey. Users must be redirected to an external site to continue their checkout journey.
  API Updates	Changes to Kriya Payments API, including any new capabilities, will have to be developed by the Marketplace.	Payments Journey will constantly be kept up to date with the latest API capabilities to ensure the customer has a high-quality experience.

  Direct API Integration

  Direct API integration is the preferred choice for partners that want to have complete control over the customer journey and embed the capabilities of the API directly into their solutions.

  Direct API flow

  The following flow demonstrates a typical sequence for a new Buyer transacting using the API:

  1. Buyer has been onboarded by the Marketplace.
  2. Marketplace requests to the Kriya Payments API CreateBuyer endpoint to register them on the API to identify if they can use Kriya Payments.
  3. Kriya Payments API begins the risk decision process to determine if a limit can be provided to the Buyer.
  4. Kriya Payments API responds with a 201 Created status code to confirm the Buyer has been created.

  Note: Marketplaces may create Draft orders whilst awaiting a risk decision. However, no orders can be Submitted until the Buyer has been Approved. See Webhooks for more details on how to get notified of this.

  5. Marketplace uses webhooks or the GetBuyer endpoint to determine whether the Buyer has been Approved and Kriya payment methods are available to them.
  6. Marketplace may call the Kriya Payments API GetBuyerPricingScheme endpoint to understand which payment methods are available to the Buyer, along with any associated fees they may incur.
  7. Kriya Payments API responds with a 200 OK response and provides the pricing scheme available to the Buyer.
  8. Buyer uses the Marketplace to purchase services or goods and chooses to pay with Kriya Payments, presuming the Marketplace has exposed the ability to checkout using Kriya Payments.
  9. Marketplace calls the Kriya Payments API CreateOrder endpoint, which will create a new order in the default Draft status.

  A Draft order is non-committal and can be cancelled at any time. It does not impact the available spending limit of the Buyer.

  10. Kriya Payments API responds with a 201 Created to confirm the order has been created and also returns details about the Buyer's possible payment methods and limit.
  11. Buyer confirms they want to proceed and place the order on the Marketplace.
  12. Marketplace calls the Kriya Payments API TransitionOrder endpoint and moves it from the Draft status to Submitted.

  By transitioning the order to a Submitted status, the Buyers available spending limit is reduced based on the total amount of the order.

  13. Kriya Payments API responds with a 200 OK response.
  14. Marketplace delivers the goods to the Buyer, and an invoice has been generated.
  15. Marketplace requests to the Kriya Payments API TransitionOrder endpoint and moves it from Submitted status to ReadyToAdvance.

  This is the trigger from the Marketplace to inform Kriya Payments to advance funds to the Marketplace and Supplier if applicable. No further changes can be made to the order at this point.

  16. Kriya Payments API responds with a 200 OK response.

  

  Payments Journey Integration

  The Payments Journey-driven integration utilises a Kriya Payments-hosted web application that handles the checkout journey for customers. This is the preferred approach for partners that are looking for a lower-effort solution.

  Payments Journey Demonstration

  The following file shows a walk-through of an end-to-end journey from the customer's perspective once they have been redirected to the Kriya Payments hosted Payments Journey.

  

  Payments Journey flow

  The following flow shows a typical scenario for the Payments Journey. A Buyer has chosen to pay using Kriya Payments on the Marketplace, and they will complete their checkout process via the Payments Journey before being redirected back to the Marketplace.

  1. Buyer, existing or new, has been onboarded by the MarketPlace and has been offered Kriya Payments.
  2. Marketplace calls the Kriya Payments API CreateOrder endpoint, which will create a new order in the default Draft status.

  To initiate a payment journey additional fields are required. See, Initiating a payment journey below.

  3. Kriya Payments API responds with a 201 Created status code to confirm it has been created and also returns a redirect URL, which is valid for 14 days.

  The redirect URL is used to redirect the customer to the Kriya Payments-hosted Payments Journey.

  4. Marketplace redirects the customer to the returned URL.
  5. Buyer lands on the Payments Journey page, which includes filling out Company and User details if they were not initially provided in step 2.
  6. Buyer selects their preferred payment method and finally completes their payment journey.
  7. Payments Journey redirects the Buyer back to the Marketplace.
  8. Buyer places the order on the Marketplace.

  If your checkout process does not require the Buyer to confirm the placement of the order, you can use our AutoTransitionOnCompletion field, which automatically performs step 9 for you. See below for further details.

  9. Marketplace calls the Kriya Payments API TransitionOrder endpoint and moves it from Draft to Submitted.

  By transitioning the order to the Submitted status, the Buyer's available spending limit is reduced based on the total amount of the order.

  10. Kriya Payments API responds with a 200 OK response to confirm that the order has been submitted.

  At this point, the same steps from 11 onwards in the API flow are now followed.

  

  AutoTransitionOnCompletion

  This property defines the status that the order will transition to after the payment journey is completed but before redirecting them back to the Marketplace. By default, any payment journey completion will leave an order in its Draft status. However, this property allows you to transition an order to Submitted or ReadyToAdvance instead automatically.

  Initiating a Payment Journey

  Two properties must be specified to ensure you receive a redirect URL to the Payments Journey:

  PaymentAcceptedRedirectUrl

  This refers to the URL that we will redirect the Buyer to once they have completed the Payments Journey. Upon redirection, you will now have an order that has been created, still in the Draft status, unless the AutoTransitionOnCompletion property has been set.

  PaymentDeclinedRedirectUrl

  This refers to the URL that we will redirect the Buyer to if, at any point in the journey, they either do not wish to proceed or cannot proceed. Upon redirection, you will still have an order that has been created, still in the Draft status, which can be set to Cancelled if applicable. You will be able to retrieve the details about why the Payments Journey has been declined by retrieving the order details via the Kriya Payments API GetOrder endpoint, which will include a PaymentJourney.Status property that will be either:

  • UserInitiated - The user decided to return to the Marketplace and no longer proceed with the order at this time. e.g. They may wish to add additional items to their basket or choose an alternative payment method. The Marketplace can amend the order amount (PUT on the orders endpoint) and redirect the Buyer back to the payments journey, if applicable.
  • Ineligible - Kriya Payments were unable to transact with the Buyer as they have not been or are no longer approved. The Marketplace is expected to provide the Buyer with an alternative payment method.
  • InsufficientFunds - Kriya Payments were unable to transact with the Buyer as their available spending limit is less than the amount of the current order. The Marketplace is expected to either provide the Buyer with an alternative payment method or provide partial payment so that Kriya can still transact with the funds available on the Buyer's available spending limit.

  Shopify

  Kriya is currently in the development process of providing integrations with Shopify. If you would like to learn more about this, please get in touch us at payments@kriya.co.

  WooCommerce

  Kriya Payments is now readily available for WooCommerce merchant stores. To receive the plugin, please get in touch with us at apisupport@kriya.co.

  Configuring the plugin

  1. Log into WordPress Admin Dashboard.
  2. Select the Plugins > Add New option in the left column menu.
  3. Select Upload Plugin.
  4. Select Drop files or click here to install and select the .zip file provided to you.

  To update the plugin, you can follow the above steps with a new version of the .zip file. You do not need to repeat the steps below as they are still stored.

  At this point, the plugin has now been installed. To configure the plugin for your store, you should:

  1. In Wordpress Admin Dashboard, select WooCommerce > Settings option in the left column menu.
  2. Select the Payments tab.
  3. Select the All payment methods option at the top of the screen.
  4. Select the Manage button on the Kriya Payments payment method.
  5. Input your Test and Production (Live) API keys into the appropriate fields.

  You can use the Test mode to send any orders to our test environment, prior to sending live orders.

  6. Press Save changes

  

  The plugin will now be active and the Kriya payment method is now available on the store checkout.

  Other e-commerce platforms

  If you're interested in using the Kriya Payments API and the platform you're using isn't listed above, please let us know by contacting us a payments@kriya.co.

  Data Types

  The following section outlines some specific ways in which data should be interpreted or sent in requests to and from the API.

  Currency

  All currencies shall be both requested and returned using their ISO 4217 codes.

  Monetary Amounts

  Any monetary amounts requested and returned via the API shall be represented as their lowest denomination. For example:

  • £123.90 is represented as 12390
  • $50.00 is represented as 5000

  Countries

  Wherever a country of registration is required, it must be done so using the ISO 3166-1 alpha-2 code.

  Kriya Payments supports GB, the US and the following European countries that we can service:

  • Austria (AT)
  • Belgium (BE)
  • Bulgaria (BG)
  • Croatia (HR)
  • Cyprus (CY)
  • Czech Republic (CZ)
  • Denmark (DK)
  • Estonia (EE)
  • Finland (FI)
  • France (FR)
  • Germany (DE)
  • Greece (GR)
  • Hungary (HU)
  • Ireland (IE)
  • Italy (IT)
  • Latvia (LV)
  • Lithuania (LT)
  • Luxembourg (LU)
  • Malta (MT)
  • Netherlands (NL)
  • Poland (PL)
  • Portugal (PT)
  • Romania (RO)
  • Slovakia (SK)
  • Slovenia (SI)
  • Spain (ES)
  • Sweden (SE)

  Defined Types

  Unless specified otherwise, all properties are Required when making API calls.

  Order

  The order is the record of a transaction occurring via Kriya Payments. Several varying validation rules come into play depending on the status of the order. Please see Order Status for further information.

  Property	DataType	Description	Constraints
  MarketplaceOrderId	String	The unique order identifier from the Marketplace.	It must be between 1 and 150 characters. It must be unique across all orders.
  Status	String (Enum) Order Status	The status of the order. Defaults to Draft if not specified.	See Order Status. Optional.
  BuyerCompany	Object Buyer	The Buyer company that is purchasing the goods or services. For a subset of details of the Buyer, see Buyer.	Optional for Draft orders.
  SupplierCompany	Object Supplier	The Supplier that provides the goods or services to the Buyer. For a subset of details of the Supplier, see Supplier.	Required for Marketplaces that do not fulfil orders themselves. Optional for all other Marketplaces.
  User	Object User	The user on the Marketplace that is placing the order on behalf of the Buyer company. See User.	Optional for Draft orders.
  Payment	Object Payment	Details of the payment to be made. This includes the order amount and which payment method is being used.	See Payment for more details.
  DeliveryAddresses	Object Array Address	The address or addresses the goods or services are being supplied to. See Address.	Optional for Draft orders.
  PaymentJourney	Object Payment Journey	The details surrounding the Kriya hosted payments journey, see Payment Journey.	Not required if you are following a Direct Api Integration approach. See Integration Scenarios.
  DeliveryDate	DateTime	The delivery date for the goods or services to the Buyer.	Optional. It must not be earlier than the date the order was created.
  InvoiceReference	String	The InvoiceReference number from the Marketplace associated with one or many orders. This can be used to group a set of orders with a single Invoice.	Optional.
  OrderPlacedDate	DateTime	The date the order was placed on the Marketplace.	Optional. It must not be earlier than four days from the current date.

  The following examples show the differing minimum requirements for an Order across multiple statuses:

  Draft

  {
    "marketPlaceOrderId": "0001",
    "payment": {
      "supplier": {
        "amount": 10000
      }
    }
  }
  

  Submitted

  {
      "marketPlaceOrderId": "0001",
      "status": "Submitted",
      "buyerCompany":
      {
          "companyIdentifier": "00123456",
          "companyName": "Buyer Company",
          "countryOfRegistration": "GB",
          "type": "LimitedCompany"
      },
      "payment":
      {
          "supplier":
          {
              "amount": 1
          },
          "paymentMethod": "PAY30"
      },
      "deliveryAddresses":
      [
          {
              "addressLine1": "56 Manor Road",
              "addressLine2": "School Lane",
              "city": null,
              "region": "Bath",
              "postCode": "BA20 8XT"
          }
      ],
      "user":
      {
          "email": "arty.fischel@user.com",
          "fullName": "Arty Fischel"
      }
  }
  

  ReadyToAdvance

  {
      "marketPlaceOrderId": "0001",
      "status": "ReadyToAdvance",
      "buyerCompany":
      {
          "companyIdentifier": "00123456",
          "companyName": "Buyer Company",
          "countryOfRegistration": "GB",
          "type": "LimitedCompany"
      },
      "payment":
      {
          "supplier":
          {
              "amount": 1
          },
          "paymentMethod": "PAY30"
      },
      "deliveryAddresses":
      [
          {
              "addressLine1": "56 Manor Road",
              "addressLine2": "School Lane",
              "city": null,
              "region": "Bath",
              "postCode": "BA20 8XT"
          }
      ],
      "user":
      {
          "email": "arty.fischel@user.com",
          "fullName": "Arty Fischel"
      }
  }
  

  Order with all properties populated

  {
      "marketPlaceOrderId": "0001",
      "status": "Draft",
      "buyerCompany":
      {
          "companyIdentifier": "00123456",
          "companyName": "Buyer Company",
          "countryOfRegistration": "GB",
          "type": "LimitedCompany"
      },
      "supplierCompany":
      {
          "companyIdentifier": "98765432",
          "companyName": "Supplier Company",
          "countryOfRegistration": "GB"
      },
      "payment":
      {
          "supplier":
          {
              "amount": 25000,
              "currency": "GBP"
          },
          "marketplace":
          {
              "amount": 10000,
              "currency": "GBP"
          },
          "paymentMethod": "PAY30"
      },
      "deliveryAddresses":
      [
          {
              "addressLine1": "56 Manor Road",
              "addressLine2": "School Lane",
              "city": null,
              "region": "Bath",
              "postCode": "BA20 8XT"
          }
      ],
      "paymentJourney":
      {
          "paymentAcceptedRedirectUrl": "https://accepted.kriya.co",
          "paymentDeclinedRedirectUrl": "https://declined.kriya.co",
          "autoTransitionOnCompletion": "Submitted"
      },
      "user":
      {
          "email": "arty.fischel@user.com",
          "fullName": "Arty Fischel",
          "role": "Director",
          "phoneNumber": "07777777777"
      },
      "deliveryDate": "2022-07-09",
      "invoiceReference": "INV-001",
      "orderPlacedDate": "2022-07-04"
  }
  

  Order Status

  An order can be created in any modifiable status as long as constraints have been met. The status can be transitioned to several others, those being:

  Name	Description	ReadOnly
  Draft	The draft order status has no impact on a Buyer's available spending limit. It can either be transitioned to Submitted or Cancelled. The Draft status will be the default for all newly created orders if no status has been specified.	No
  Submitted	The order would be transitioned to this status when a customer has chosen to place the order via the Marketplace. Upon transitioning to this status, the orders DeliveryAddresses, Payment, User, BuyerCompany and SupplierCompany, if applicable, must be supplied. The Buyers available spending limit must be >= to the total order amount, and if so, the Buyers available spending limit is reduced to reflect this. The order can still be transitioned to Cancelled at this point.	No
  ReadyToAdvance	Transitioning to this status will inform Kriya Payments API to advance funds equivalent to the order amount, minus fees, to both the Marketplace and Supplier, where applicable. The same requirements as Submitted are needed. At this point, the order cannot be transitioned to Cancelled, and no further updates can be made to the order.	No
  Advanced	The funds associated with the order have now been transferred to the relevant parties involved.	Yes
  Repaid	The Buyer has fully repaid the total amount of the order, including any fees. The Buyers available spending limit is increased by the order amount.	Yes
  Overdue	The Buyer has not fully paid the total amount of the order, including any fees, within the payment period (e.g. 30 days in the case of "Pay in 30 days").	Yes
  Closed	The order has been fully completed and is now closed. The Buyers available spending limit is increased by the order amount.	Yes
  Cancelled	The order has been cancelled. Any deductions to the Buyer's available spending limit have been reverted.	No

  The following order transitions can occur via the API:

  

  Payment

  The payment details of the order, including the amounts payable to the Supplier and Marketplace, where applicable. For example, an order may be split so that £980 goes to the Supplier and the remaining £20 is payable to the Marketplace, which equates to £1,000 owed by the Buyer. When Kriya advances funds, fees will be taken from the payable amounts, and then the remaining funds will be paid to the Marketplace and Supplier as specified. It is the responsibility of the Marketplace to define how the order amount should be separated.

  Property	DataType	Description	Constraints
  Supplier	Object Monetary Data	The total amount of the order payable to the Supplier, excluding any Kriya fees.	It must be greater than zero when Supplier details are included in the order.
  Marketplace	Object Monetary Data	The total amount of the order payable to the Marketplace, excluding any Kriya fees.	It must be greater than zero when included. Optional only when Supplier details are included in the order.
  PaymentMethod	String	The payment method chosen for the order. e.g. Pay in 30 days.	Optional for Draft or Cancelled orders. Retrieve the available payment methods for the Buyer via the Buyer Pricing Scheme endpoint.

  Payment Data

  The details of the order amount that is payable to either the Marketplace or Supplier.

  Property	DataType	Description	Constraints
  Amount	Long (int64)	The total amount of the order, excluding any Kriya fees.	It must be greater than zero.
  CurrencyCode	String (Enum)	The currency the order is to be purchased in.	It must be a valid ISO 4217 code. It must be one of USD, GBP or EUR. The code must also match the Buyers country of registration, e.g. USD for the US.
  PaymentMethod	String	The payment method chosen for the order. e.g. Pay in 30 days.	Optional for Draft or Cancelled orders.

  User

  The user that is making the order on behalf of the Buyer company. If no primary contact details have been specified for the Buyer, the details provided here will be used to contact the Buyer if any issues arise with the order.

  Property	DataType	Description	Constraints
  Name	String	The full name of the user.	It must be between 5 and 150 characters.
  Email	String	The Email address of the user.	It must be a valid Email address. It must be between 1 and 150 characters.
  Role	String	The role of the user within the company.	It must be between 1 and 150 characters. Optional.
  PhoneNumber	String	The contact phone number of the user.	It must be a valid phone number. This is not limited to UK phone numbers. Optional.

  Address

  The address details are used to define the delivery address for the order and the residential address of the individual responsible for a SoleTrader business.

  Property	DataType	Description	Constraints
  AddressLine1	String	First line of the address.	It must be between 1 and 250 characters.
  AddressLine2	String	Second line of the address.	It must be between 1 and 250 characters. Optional.
  City	String	Name of the city.	It must be between 1 and 189 characters. Optional.
  Region	String	Name of the region.	It must be between 1 and 90 characters. Optional.
  PostCode	String	A valid postal code.	It must be a valid postal code.
  Country	String	A valid country	Optional.

  Payment Journey

  The payments journey is only required if you're using the Payments Journey Integration. See Integration Scenarios for more information.

  | Property | DataType | Description | Constraints | |----------------------------|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------| | PaymentAcceptedRedirectUrl | String | The URL that the Payments Journey will redirect to if the customer completes the journey. | It must be a valid absolute URI. | | PaymentDeclinedRedirectUrl | String | The URL that the payments journey will redirect to if the customer does not complete the journey. This can occur when the Buyer has decided to return to the Marketplace, they are ineligible or have insufficient funds to complete the order. | It must be a valid absolute URI. | | DeclineStatus | String (Enum) | The status describes why a Buyer was redirected to the PaymentDeclinedRedirectUrl. See Decline Status for more information. | | | AutoTransitionOnCompletion | String (Enum) | The order status that the order will transition to when the payment journey is completed. See Order Status for more information. | |

  Decline Status

  The DeclineStatus informs you why the user was redirected back to the PaymentDeclinedRedirectUrl.

  Property	Description
  UserInitiated	The user decided to return to the Marketplace and no longer proceed with the order at this time. e.g. They may wish to add additional items to their basket or choose an alternative payment method.
  Ineligible	Kriya Payments were unable to transact with the Buyer as they have not been or are no longer in the Approved status.
  InsufficientFunds	Kriya Payments were unable to transact with the Buyer as their available spending limit is less than the amount of the current order.

  Buyer

  The Buyer is a business on the Marketplace that is purchasing the goods or services from a Supplier or the Marketplace directly. A Buyer must be registered on the Kriya Payments platform and have received an approved limit before they can submit orders.

  Property	DataType	Description	Constraints
  Name	String	The legal name of the company.	It must be between 1 and 250 characters.
  CompanyIdentifier	String	The identifier for the company, i.e. registration number for a LimitedCompany or Email address for a SoleTrader.	LimitedCompany: It must be between 1 and 20 characters. GB based companies must provide a valid 8-character registration number that can be found on Companies House. SoleTrader: It must be a valid Email address.
  CountryCode	String	The code that identifies the country of incorporation of the Buyer's company. The spending limit currency will be assigned based on this. GB will be defaulted to if not specified.	It must be a 2-character ISO 3166-1 alpha-2 code. Optional.
  Type	String (Enum)	The Buyer's company type. This will default to LimitedCompany if not supplied. The SoleTrader type does not yet support any automated risk decisions and therefore, manual intervention is always required.	One of LimitedCompany, SoleTrader. Optional.
  BankAccount	Object Bank Account	The bank account details of the company. This is required for Buyers that want to make their payments via Direct Debit. Kriya Payments supports accounts within GB, the US and several European countries. The bank account details provided must match the associated currency from the CountryCode of the company. For example, a US company must provide a valid US bank account.	See the Bank Account definition. Optional unless the Buyer is paying by Direct Debit.
  ContactDetails	Object Contact Details	The primary contact details for the Buyer company. Any correspondence, in particular, relating to overdue orders will also be sent to the details provided here. Otherwise, only the individual user that created the order will be contacted.	See the Contact Details definition. Optional.
  Director	Object Director	The details of the individual in control of the SoleTrader business. This is used for Kriya Payments risk decisions.	See the Director's definition. Only required for SoleTrader Buyer Type.
  Status	String (Enum)	The status given to the Buyer company from the Kriya Payments risk team. This determines whether or not they can transact with us. See Buyer/Supplier Decision Status for further details.	Only returned by Kriya Payments API responses. This will be ignored if included in any requests.
  TotalLimit	Long (int64)	The spending limit provided to the Buyer by the Kriya Payments risk team. A Buyers spending limit is always under continuing review, and Kriya Payments may increase or decrease a Buyers spending limit over time.	The value provided will be >= 0. Only returned by Kriya Payments API responses. This will be ignored if included in any requests.
  AvailableLimit	Long (int64)	The amount that remains of the Buyer's total limit that they have to transact with using Kriya Payments.	Only returned by Kriya Payments API responses. This will be ignored if included in any requests.

  Minimum details for a Buyer to be created
  Note: This will create a LimitedBuyer for GB as defaults are applied for optional fields.

  {
      "name": "Test Buyer",
      "companyIdentifier": "12345678"
  }
  

  Full details that can be specified
  LimitedCompany

  {
      "name": "Test Buyer",
      "companyIdentifier": "12345678",
      "countryCode": "GB",
      "type": "LimitedCompany",
      "bankAccount": {
          "currencyCode": "GBP",
          "accountName": "Bank of England",
          "sortCode": "100000",
          "accountNumber": "31510604"
      },
      "contactDetails": {
          "name": "Arty Fischel",
          "email": "arty.fischel@user.com",
          "role": "Director",
          "phoneNumber": "+447825998724"
      }
  }
  

  SoleTrader

  {
      "name": "Test Buyer",
      "companyIdentifier": "test@user.com",
      "countryCode": "GB",
      "type": "SoleTrader",
      "bankAccount":
      {
          "currencyCode": "GBP",
          "accountName": "Bank of England",
          "sortCode": "100000",
          "accountNumber": "31510604"
      },
      "director":
      {
          "fullName": "Amelia Bennett",
          "phoneNumber": "07798622788",
          "dateOfBirth": "1975-09-01",
          "residentialAddress": {
              "addressLine1": "80 Church Lane",
              "addressLine2": "Mill Road",
              "city": "Birmingham",
              "region": "West Midlands",
              "postCode": "B2 4JD",
              "country": "United Kingdom"
          }
      }
  }
  

  Buyer Pricing Scheme

  The pricing scheme for a Buyer refers to the possible payment methods available to them, including the fee percentage payable by the Buyer for each method. Pricing schemes are only returned by the API and cannot be modified.

  Property	DataType	Description	Constraints
  Identifier	String	The unique identifier for the payment method. The identifier is used when specifying the PaymentMethod for an Order., e.g. 'PAY30'.
  Name	String	The name of the payment method.
  Description	String	The description of the payment method.
  IsEnabled	Boolean	A flag that identifies whether or not this payment method can be used by the Buyer.
  FeePercentage	Decimal	The fee percentage payable by the Buyer that is added onto the total amount of their order.	Returned as a decimal value between 0 and 100. e.g. 1.5 would be a 1.5% Buyer fee.

  Supplier

  If a Marketplace is not the single Supplier of goods or services or they do not fulfil orders directly at all, then the Supplier must be specified. The Supplier is a company that has been registered on Kriya Payments API and authorised as a seller of goods or services on the platform. Similar to Buyers, a Supplier must also be approved on Kriya Payments API before goods or services can be sold on their behalf on the Marketplace.

  When an order is placed on behalf of a Supplier via the Marketplace, Kriya Payments will need to ensure funds are paid to the Supplier. Due to this, Bank Account details are required for all Suppliers.

  Property	DataType	Description	Constraints
  Name	String	The legal name of the company.	It must be between 1 and 250 characters.
  CompanyIdentifier	String	The identifier for the company.	It must be between 1 and 20 characters. GB based companies must provide a valid 8-character registration number that can be found on Companies House.
  CountryCode	String	The code that identifies the country of incorporation of the Supplier's company. GB will be defaulted to if not specified.	It must be a 2-character ISO 3166-1 alpha-2 code. Optional.
  BankAccount	Object Bank Account	The bank account details of the company for any funds to be paid into. Kriya Payments supports accounts within GB, the US and several European countries. The bank account details provided must match the associated currency from the CountryCode of the company. For example, a US company must provide a valid US bank account.	Required. See Bank Account definition.
  Status	String (Enum)	The status given to the Supplier company from the Kriya Payments risk team. This determines whether or not the Marketplace can sell goods or services on the Supplier's behalf using Kriya Payments. See Buyer/Supplier Decision Status for further details.	Only returned by Kriya Payments API responses. This will be ignored if included in any requests.

  Minimum details for a Supplier to be created

  {
      "name": "Test Supplier",
      "companyIdentifier": "98765432",
      "countryCode": "GB",
      "bankAccount":
      {
          "currencyCode": "GBP",
          "accountName": "Bank of England",
          "sortCode": "100000",
          "accountNumber": "31510604"
      }
  }
  

  Full details that can be specified

  {
      "name": "Test Supplier",
      "companyIdentifier": "98765432",
      "countryCode": "GB",
      "bankAccount": {
          "currencyCode": "GBP",
          "accountName": "Bank of England",
          "sortCode": "100000",
          "accountNumber": "31510604"
      }
  }
  

  Buyer/Supplier Decision Status

  Kriya Payments reviews Buyers regularly and may increase or decrease an approved Buyer's spending limit. In addition to this, Kriya Payments may also reject or require further review of Buyers, which will prevent them from placing other orders. The following statuses can be found for a Buyer:

  Name	Description
  Submitted	The Buyer has been registered, but no risk decision has been made. The automatic risk decision has been triggered to generate a decision.
  InReview	The Buyer is currently being reviewed. Further information is needed before a decision can be made, and manual intervention is required by the Kriya Payments risk team. The company may be contacted to provide further details.
  Approved	The Buyer has been approved and now has a spending limit > 0.
  Rejected	The Buyer has been rejected and will not be able to transact using Kriya Payments. If the Buyer was previously Approved, their spending limit would now be 0.

  Bank Account

  Bank Account details are required for all Suppliers. Bank Accounts are only required for Buyers that intend on paying via Direct Debit.

  Property	DataType	Description	Constraints
  CurrencyCode	String (Enum)	The currency the bank account is held in.	It must be a valid ISO 4217 code. Required for all bank accounts. It must be one of USD, GBP or EUR. Depending upon which code is used, the constraints change as described in this table.
  AccountName	String	The name of the bank account. Used to help verify bank details.	It must be between 1 and 50 characters. Required for all bank accounts.
  SortCode	String	The sort code or routing number (USD).	It must be between 1 and 10 characters. Required for both GBP and USD accounts.
  AccountNumber	String	The account number.	It must be between 1 and 10 characters. Required for both GBP and USD accounts.
  Bic	String	The Swift BIC (Bank identifier code).	It must be between 1 and 10 characters. Optional for all bank accounts. It must be a valid ISO 9362 code.
  AccountType	String (Enum)	The type of USD account.	It must be one of Checking or Savings. Required for USD accounts.
  Iban	String	The International Bank Account Number as per ISO 3616.	It must be between 1 and 34 characters. Required for EUR bank accounts.

  The following examples show the requirements for the bank account structure for different countries:

  GB:

  {
      "currencyCode": "GBP",
      "accountName": "Bank of England",
      "sortCode": "100000",
      "accountNumber": "31510604"
  }
  

  US:

  {
      "currencyCode": "USD",
      "accountName": "Bank of America",
      "sortCode": "220737409",
      "accountNumber": "58474125",
      "accountType": "Checking"
  }
  

  European countries:

  {
      "currencyCode": "EUR",
      "accountName": "Bayerische Landesbank",
      "iban": "DE89370400440532013000"
  }
  

  Contact Details

  The primary contact details are used for the Buyer company. Any correspondence, in particular, relating to overdue orders will be sent to the details provided here. Otherwise, the individual user that created the order will be contacted.

  Property	DataType	Description	Constraints
  Name	String	The full name of the primary contact.	It must be between 5 and 150 characters. Optional.
  Email	String	The Email address of the primary contact.	It must be a valid Email address. It must be between 1 and 150 characters. Optional.
  Role	String	The role of the primary contact within the company.	It must be between 1 and 150 characters. Optional.
  PhoneNumber	String	The contact phone number of the primary contact.	It must be a valid phone number. This is not limited to UK phone numbers. Optional.

  Director

  The details of the individual responsible for the SoleTrader business. This data is required for any SoleTrader Buyer for Kriya Payments risk decisions.

  Property	DataType	Description	Constraints
  FullName	String	The full name of the individual responsible for the SoleTrader business.	It must be between 5 and 150 characters. Optional.
  DateOfBirth	Date	The Date of Birth of the individual responsible for the SoleTrader business.	It must be at least 18 years old.
  PhoneNumber	String	The contact phone number of the individual responsible for the SoleTrader business.	It must be a valid phone number. This is not limited to UK phone numbers. Optional.
  ResidentialAddress	Object Address	The residential address of the individual responsible for the SoleTrader business.	| |

  Monetary data

  The structure of the monetary data is composed of the amount and the currency.

  Property	DataType	Description	Constraints
  Amount	Long (int64)	The amount expressed in the currency below.	It must be greater than zero.
  CurrencyCode	String (Enum)	The currency related to the amount above.	It must be a valid ISO 4217 code. It must be one of USD, GBP or EUR. The code must also match the Buyers country of registration, e.g. USD for the US.

  Webhooks

  The Kriya Payments API uses webhooks to send POST requests to your application when a specific event occurs across several entities. This mechanism ensures that your apps can stay in sync with Kriya Payments data or allow you to react to particular events. Webhooks also provide a better alternative than polling specific endpoints for changes.

  All supported event types will be sent to the same Webhook URL provided. The following event types are supported via webhooks:

  • BuyerRiskDecisionChanged - The Kriya Payments risk decision has changed for a Buyer. Either an already Approved Buyer has had their spending limit increased/decreased, or a Buyer status has transitioned to a different Order Status, e.g. due to our automated risk decisions.
  • BuyerAvailableLimitChanged - An event has occurred that has altered the available spending limit for the Buyer. Examples of this may be an order transitioning to a new status, such as Submitted, ReadyToAdvance or Repaid, etc. The value of an order has changed, the buyer belongs to multiple Marketplaces and has transacted elsewhere or our risk team have altered the status/limit of the Buyer directly.
  • OrderStatusChanged - An order has transitioned to a different status. This is particularly useful for tracking operational activities beyond the checkout process. For example, an order moves from Advanced to Repaid when a successful payment has been made by a Buyer. See Order Status to see all transitions. The message will also contain the available spending limit of the Buyer.
  • SupplierRiskDecisionChanged - The Kriya Payments risk decision has changed for a Supplier. It occurs when the status of a Supplier is transitioned to another Order Status by the Kriya Payments Risk team. There are no automated decisions for Suppliers yet.

  The payload you will receive from the webhook will be sent using the following structure:

  Property	DataType	Description
  Type	String	The defined Type of the event that triggered the webhook to be sent.
  Timestamp	DateTime	The date and time that the event occurred.
  Message	Object	The object that relates specifically to the Type of event being sent.

  The possible Message object structures for the events types are:

  BuyerRiskDecisionChanged

  {
      "companyIdentifier": "12345678",
      "countryCode": "GB",
      "companyType": "limitedcompany",
      "limit": 15000000,
      "status": "Approved",
      "currentBalance": 14100000
  }
  

  BuyerAvailableLimitChanged

  {
      "companyIdentifier": "12345678",
      "countryCode": "GB",
      "companyType": "limitedcompany",
      "currentBalance": 14100000,
      "currencyCode": "GBP"
  }
  

  OrderStatusChanged

  {
      "marketplaceOrderId": "0001",
      "oldStatus": "Draft",
      "newStatus": "Submitted",
      "buyerCurrentBalance": 1500000
  }
  

  SupplierRiskDecisionChanged

  {
      "companyIdentifier": "12345678",
      "countryCode": "GB",
      "status": "Approved"
  }
  

  The following example shows what a complete webhook request may look like:

  {
      "type": "OrderStatusChanged",
      "message": {
          "marketplaceOrderId": "0001",
          "oldStatus": "Draft",
          "newStatus": "Submitted",
          "buyerCurrentBalance": 1500000
      },
      "timestamp": "2022-03-28T15:09:21.5369596+00:00"
  }
  

  Configuring Webhooks

  A single URL on your server to receive requests is required for us to set up your webhook. To set this up, please get in touch with us at apisupport@kriya.co, and we can configure this for you in both your test and production environments.

  Verifying Webhooks

  When your server receives requests from webhooks, the authenticity and integrity of the request should be verified. You will be able to perform this verification by generating a hash-based message authentication code (HMAC) based on the payload in the webhook request and a secret key specific to you.

  The Kriya Payments API signs the payload in the request and includes a base64-encoded HMAC in the request header X-Kriya-Signature. To verify the webhook was sent from the Kriya Payments API and the integrity of the payload, you should:

  1. Retrieve the key that you should have received from the Kriya team. This should be stored securely on your server.
  2. Generate an HMAC-SHA256 hash based on the payload you received in the request and your HMAC key.
  3. The generated hash should be base64-encoded.
  4. Compare this generated value with the value from X-Kriya-Signature. If the two values match, then the webhook has been verified as being sent from the Kriya Payments API.

  Code sample (C#, .NET):

  using System.Security.Cryptography;
  using System.Text;
  ...
  using var hmacSha256 = new HMACSHA256(Encoding.UTF8.GetBytes(hmacKey));
  var hashBytes = hmacSha256.ComputeHash(Encoding.UTF8.GetBytes(payload));
  var isVerified = xKriyaPaymentsSignature.Equals(Convert.ToBase64String(hashBytes));
  

  If you haven't received your HMAC key yet? Please get in touch with us at apisupport@kriya.co.

  Limitations and Best Practices

  Acknowledgement and Retries

  Any requests made to the URL specified must return an acknowledgement by providing a 2XX response. If no acknowledgement is made, Kriya Payments will retry your URL up to 3 times with an exponential backoff of 2 seconds for each retry (i.e. 2s, 4s, 8s) until retries are exhausted. If retries have been exhausted, Kriya Payments will contact you and provide further details and decide if/when webhooks should be replayed.

  Reconciliation

  As mentioned above, webhook delivery is not always guaranteed. It is therefore suggested that the Marketplace implements relevant mechanisms to synchronise any data they require from Kriya Payments to their applications regularly, e.g. recurring data fetching.

  Delayed Requests

  There may be times when webhook requests are made with a delay since the event occurred. This may be due to processing times on Kriya Payments or due to retries made to the server for the webhook URL. It is suggested that the Timestamp received on every request is reviewed to determine if you perceive the data to be 'stale' and instead, either the webhook event is ignored if a more recent one has been provided or the Kriya Payments API called directly to re-retrieve the latest data.

  API Environments

  The API currently supports two environments, that is, both Test and Production. Please note that you must request access to these environments separately and receive API keys for both.

  Test

  The Test API can be accessed through the base URL https://api.kriya.dev/payments/

  The 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 for more details.

  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.

  Test Scenario Simulators

  When integrating with the Kriya Payments API, there may be certain situations that you want to be able to test and ensure your integration handles successfully, for example, when an order is Repaid. In our test environment, we have provided a set of API endpoints that can be used to simulate these scenarios that you would not typically be able to do directly via the production endpoints.

  Buyer/Supplier Decisioning

  This is valuable in instances where you need to test specific scenarios against Buyers/Suppliers with a certain status or spending limit. Without calling this endpoint, any newly registered Buyers/Suppliers on the Test environment may resolve to one of the possible Buyer/Supplier Decision Statuses due to our automated risk decisions and is, therefore, non-deterministic.

  To override this, you can use the Test environment-specific endpoints to transition a Buyer/Supplier to a specific status or set a spending limit for a Buyer:

  • /api/scenario/Buyers/risk-decision
  • /api/scenario/Suppliers/risk-decision

  Order Status Transitions

  There are several Order Statuses that an order can be transitioned to. However, a number of them are not possible to be set by the API as they are only transitioned to the statuses internally within Kriya Payments. However, to ensure you can test orders in these specific statuses, we have provided an endpoint on the Test environment that allows you to transition your order to a valid Order Status.

  Please note that whilst you can transition to these internal statuses, the transition must still be valid. For example, you cannot move a ReadyToAdvance order directly to Repaid without transitioning to Advanced first.

  • /api/scenario/orders/{MarketplaceOrderId}/transition

  Production

  The Production API can be accessed through the base URL https://api.kriya.co/payments/.

  Support

  If you have any questions concerning API or suggestions or are facing any issues, please get in touch with us at apisupport@kriya.co.

  If you're interested to learn more about how Kriya Payments can help your business, you can either request a demo here or contact us at payments@kriya.co.

  API Endpoints