APIs

  • Lending API

    Market Finance Lending API https://marketfinance.com/

    Introduction

    Welcome to Lending API, the platform that allows our partners to connect their customer data to the lending portal. This means they can provide loan quotes and offers direct to their customer, from their website/portal.

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

    This documentation can be used by developers to understand how to implement the BNPL scheme.

    Want to learn more about LendingAPI? Contact us at apisupport@marketfinance.com.

    Definitions

    Buyer: The user requesting a form of business funding.

    Partner: A consumer of the MarketFinance Lending API that intends to pass customer data to MarketFinance for the purpose of identifying lending options for them.

    Application: Details of the customer that are used to generate a Quote and an Offer.

    Quote: An indicative set of pricing data for the funding being requested. Intended to give customers an understanding of the likelihood of funding and pricing if they were to continue with their application.

    Offer: An underwritten offer with the actual pricing data 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. Customer accepts an Offer).

    Integration Scenarios

    The Lending API provides two integration scenarios for our partners, those being a Referral Journey or via Autosubmit flow.

    Referral Journey

    This flow refers to being able to send a request to MarketFinance for a customer to be referred to our dedicated application journey. The API accepts any available application data you can provide to create a Draft application. Whenever asynchronous process finishes a webhook is sent to Partner with MarketFinance RedirectUrl which allows the customer to access and continue their application.

    The following steps demonstrates a typical sequence if actions:

    1. Partner wants to offer MarketFinance Quote via Partner's website for a Buyer.
    2. Partner makes a request to the Lending API 'CreateApplication' endpoint to register them on the API.
    3. LendingAPI responds with a '201 Created' status code to confirm the application has been created.
    4. LendingAPI exposing RedirectUrl via webhook and GetApplication endpoints.
    5. Partner expose a button with RedirectUrl to allow Buyers to Apply.
    6. Buyer clicks the button and get redirected to MarketFinance Unified Application Journey web site.
    7. Buyer verifies or adjust pre-populated data and submits application.
    8. LendingAPI begins risk decisioning process to determine buyers eligibility to applied products.
    9. LendingAPI notifies Partner via Webhook in case Underwritten Offer being offered or any additional actions required from Buyer to advance.

    Autosubmit Flow

    This flow allows to skip MarketFinance Unified Application Journey website and submit applications via Lending API.

    The following steps demonstrates a typical sequence if actions:

    1. Partner wants to offer MarketFinance Quote via Partner's website for a Buyer.
    2. Partner makes a request to the Lending API 'CreateApplication' endpoint to register them on the API.
    3. LendingAPI responds with a '201 Created' status code to confirm the application has been created.
    4. LendingAPI begins risk decisioning process to determine buyers eligibility to applied products.
    5. LendingAPI notifies Partner via Webhook in case Underwritten Offer being offered or any additional actions required from Buyer to advance.

    Security

    Authorization

    Partners may sign up to our developer portal and request a subscription to the Lending API product.

    Once you have been approved to use the API, you will have access to your own API keys and have the control to re-generate them on-demand via the developer portal.

    The API keys 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 our 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.

    Webhooks

    The Lending API uses webhooks to send requests to Partner's application when a specific event occurs across a number of entities.

    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 happend while Lending API was trying to download documents provided by Partner.

    Security

    The Webhooks do not currently include any method for consumers to validate the integrity of the requests being sent. This is currently under development where the requests can be validated using HMAC by additional headers provided in the request.

    API Environments

    The API currently supports two environments, that is both Test and Production. Please note that you must sign up for both the Test and Production environments separately.

    Test

    Developer portal: mistaging.developer.azure-api.net

    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.

    Production

    Developer portal: developer.marketfinance.com

    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.

    If you're interested to learn more about how LendingAPI can help your business you can either request a demo here or contact us at apisupport@marketfinance.com.

  • MarketPay Public

    Introduction

    Welcome to MarketPay 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.

    This documentation can be used by developers to understand how to implement the BNPL scheme.

    Want to learn more about MarketPay? You can either request a demo here or contact us at marketpay@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 MarketPay endpoints may return a number of different HTTP status codes.

    Status Code Description
    200 OK The request was received and successfully processed by MarketPay.
    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. Please contact us at apisupport@marketfinance.com so that we can investigate further.

    Definitions

    Marketplace: The Marketplace is the partner that will integrate with the MarketPay 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 MarketPay API and be given an approved spending limit prior to being able to transact with us.

    Supplier: A Supplier is a business that is providing goods or services to be sold via the Marketplace. The Supplier must be registered and approved on MarketPay 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 the 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 MarketPay can offer a Buyer to transact with. MarketPay continually monitors the spending limits assigned to Buyers and may increase or decrease it.

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

    MarketPay Fee: Orders created may be paid for from a number of 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 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 MarketPay API provides a variety of methods of integration for partners. This includes, a direct API integration and a MarketPay hosted Payments Journey web application.

    To assist in identifying the correct integration, the following table outlines the differences in scenarios:

    Property Direct API Payments Journey
    Effort Estimated effort of between 1-4 weeks to implement. The developer effort is larger as it involves a bespoke integration built by the Marketplace. Estimated effort of around 1 week. Lower development effort as the majority of the integration is handled by the MarketPay 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 MarketPay order that the Marketplace must embed in their own checkouts. MarketPay 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 not currently supported but is on the MarketPay roadmap.
    User experience The Marketplace must define their own UX and UI for their Buyers that aligns with the API flows. Users stay within the domain of the Marketplaces website. User experience is pre-defined by MarketPay and optimised based on regularly reviewed metrics collected from customers that use the journey. Users must be redirected to an external site to continue their checkout journey.
    API Updates Changes to MarketPay 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 capabilities to the API that can help to improve it and provide a better experience for customers.

    Direct API Integration

    A direct API integration is the preferred choice for partners that want to have full control over the customer journey and embed the capabilities of the API directly into their own 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 makes a request to the MarketPay API CreateBuyer endpoint to register them on the API to identify if they can use MarketPay.
    3. MarketPay API begins risk decisioning process to determine if a limit can be provided to the Buyer.
    4. MarketPay API responds with a 201 Created status code to confirm the Buyer has been created.

    Note: Marketplaces must wait until a Buyer has been Approved otherwise they cannot create orders. See Webhooks for more details on how to get notified of this.

    1. Marketplace uses webhooks or the GET Buyer endpoint to determine if MarketPay should be a payment method available to them.
    2. Marketplace may make a request to the MarketPay API GetBuyerPricingScheme endpoint to understand the payment methods available to the Buyer, along with any associated fees that might be exposed on the checkout journey.
    3. MarketPay API responds with a 200 OK response and provides the pricing scheme available to the Buyer.
    4. Buyer uses the Marketplace to purchase services or goods and chooses to pay with MarketPay, presuming the Marketplace has exposed the ability to checkout using MarketPay.
    5. Marketplace makes a request to the MarketPay 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 limit of the Buyer.

    1. MarketPay API responds with a 201 Created to confirm it has been created and also details about the Buyers possible payment methods and limit.
    2. Buyer confirms they want to proceed and place the order on the Marketplace.
    3. Marketplace makes a request to the MarketPay API TransitionOrder endpoint and moves it from the Draft status to Submitted.

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

    1. MarketPay API responds with a 200 OK response.
    2. Marketplace delivers the goods to the Buyer and an invoice has been generated.
    3. Marketplace makes a request to the MarketPay API TransitionOrder endpoint and moves it from Submitted status to ReadyToAdvance.

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

    1. MarketPay API responds with a 200 OK response.

    API Integration Flow

    Payments Journey Integration

    The Payments Journey driven integration utilises a MarketFinance 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 E2E journey from the customers perspective once they have been redirected to the Payments Journey.

    Payments Journey Walkthrough

    Payments journey flow

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

    1. Buyer, existing or new, would like to transact via MarketPay on the Marketplace.
    2. Marketplace makes a request to the MarketPay 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.

    1. MarketPay API responds with a 201 Created status code to confirm it has been created and also a redirect URL.

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

    1. Marketplace redirects the customer to the returned URL.
    2. Buyer lands on the Payments Journey page, which includes filling out Company and User details if they were not initially provided in step 2.
    3. Buyer selects their preferred payment method and finally completes their payment journey.
    4. Payments Journey redirects the Buyer back to the Marketplace.
    5. Buyer places the order on the Marketplace.
    6. Marketplace makes a request to the MarketPay API TransitionOrder endpoint and moves it from Draft to Submitted.

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

    1. MarketPay API responds with a 200 OK response to confirm the order has been submitted.

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

    Payments journey flow

    Initiating a payment journey

    To initiate a payment journey, there are two extra properties that 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 successfully completed the Payments Journey. Upon redirection, you will now have an order that has been created, still in the Draft status, which can be Submitted.

    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 MarketPay API GetOrder endpoint which will include a PaymentJourney.Status property that will be one of:

    • 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 is able to amend the order amount (PUT on the orders endpoint) and redirect the Buyer back to the payments journey, if applicable.
    • Ineligible - MarketPay 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 - MarketPay were unable to transact with the Buyer as their available 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 MarketPay can still transact with the funds available on the Buyers available limit.

    There is one more optional property that can be specified:

    AutoTransitionOnCompletion

    This property defines the status that the order will get after payment journey is completed. By default it is draft, however you are getting the possibility to transition it either to Submitted or ReadyToAdvance statuses.

    Shopify

    MarketPay are currently in the development process for providing integrations with Shopify. If you would like to learn more about this, please contact us at marketpay@marketfinance.com.

    WooCommerce

    MarketPay are currently in the development process for providing integrations with WooCommerce. If you would like to learn more about this, please contact us at marketpay@marketfinance.com.

    Other e-commerce platforms

    If you're interested in using the MarketPay API and the platform you're using isn't listed above, please let us know by contacting us a marketpay@marketfinance.com.

    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.

    MarketPay supports the following EU 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 that is the record of a transaction occuring via MarketPay. There are a number of varying validation rules that 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. Must be between 1 and 150 characters. Must be unique across all orders.
    Status String (Enum) The status of the order. Defaults to Draft if not specified. See Order Status. Optional.
    BuyerCompany Object
    Buyer    		 The Buyer company purchasing the goods or services. A subset of details of the Buyer, see Buyer. Optional for Draft orders.
    SupplierCompany Object
    Supplier    		 The Supplier providing the goods or services to the Buyer. 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 is 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 MarketFinance 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 for Draft orders. 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 partner platform. Optional. Must not be earlier than 4 days from the current date.

    Order Status

    An order can be created in any status as long as constraints have been met. The status and can be transitioned to a number of others, those being:

    Name Description ReadOnly
    Draft The draft order status has no impact on a Buyers available limit. It can either be transitioned to Submitted or Cancelled. A Draft order is the default status for all newly created orders, if no status was specified. No
    Submitted The order would be transitioned to this status, typically, 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 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 MarketPay API to advance funds equivalent to the order amount to the Marketplace and Supplier, where applicable. The same requirements as Submitted are needed but also the DeliveryDate must be supplied. 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. 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. Yes
    Cancelled The order has been cancelled. Any deductions to the Buyers available limit, if transitioning from Submitted have been reverted. No

    The following order transitions can occur via the API:

    Order Transitions

    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 payable by the Buyer. When MarketPay advances funds, fees will be taken from the payable amounts and then remaining funds 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 MarketPay fees, see Monetary Data 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 MarketPay fees, see Monetary Data 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 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 MarketPay fees. Must be greater than zero.
    CurrencyCode String (Enum) The currency the order is to be purchased in. Must be a valid ISO 4217 code. Must be one of USD, GBP, EUR. The code must also match the Buyers country of registration, e.g. USD for 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. Must be between 5 and 150 characters.
    Email String The Email address of the user. Must be a valid Email address. Must be between 1 and 150 characters.
    Role String The role of the user within the company. Must be between 1 and 150 characters. Optional.
    PhoneNumber String The contact phone number of the user. Must be a valid phone number. This is not limited to UK phone numbers. Optional.

    Address

    The address details that are currently used to define the delivery address for the order.

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

    Payment Journey

    The payments journey is only required if you're not using the direct API Integration. See Integration Scenarios for more information.

    | Property | DataType | Description | Constraints | |----------------------------|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------| | PaymentAcceptedRedirectUrl | String | The URI that the Payments Journey will redirect to if the customer completes the journey. | Must be a valid absolute URI. | | PaymentDeclinedRedirectUrl | String | The URI 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. | Must be a valid absolute URI. | | DeclineStatus | String (Enum) | The status describing why an order is declined. See Decline Status for more information. | | | AutoTransitionOnCompletion | String (Enum) | The order status value that the order will get when payment journey is completed. See Order Status for more information. | |

    Decline Status

    The decline status will give user an understanding of why the order was declined.

    Property Description
    Ineligible The buyer is ineligible to place an order, e.g. they are in a Rejected status.
    InsufficientFunds The buyer placed an order for the amount more than the approved limit.

    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 MarketPay platform and have received an approved limit before they can submit orders.

    Property DataType Description Constraints
    Name String The legal name of the company. Must be between 1 and 250 characters.
    RegistrationNumber String The company registration number. 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 Buyer's company. The spending limit currency will be assigned based upon this. GB will be defaulted if not specified. Must be a 2 character ISO 3166-1 alpha-2 code. Optional.
    Type String (Enum) The Buyers company type. This will default to LimitedCompany if not supplied. MarketPay only supports LimitedCompany for now. 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. MarketPay supports accounts within GB, US and a number of 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 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 an order will be contacted. See Contact Details definition. Optional.
    Status String (Enum) The status given to the Buyer company from the MarketPay risk team. This determines whether or not they can transact with us. See Buyer/Supplier Decision Status for further details. Only returned by MarketPay API responses. This will be ignored if included in any requests.
    TotalLimit Long (int64) The spending limit provided to the Buyer by the MarketPay risk team. A Buyers spending limit is always under continuing review and MarketPay may increase or decrease a Buyers spending limit over time. The value provided will be >= 0. Only returned by MarketPay API responses. This will be ignored if included in any requests.
    AvailableLimit Long (int64) The amount remaining of the Buyer's total limit that they have to transact with using MarketPay. Only returned by MarketPay API responses. This will be ignored if included in any requests.

    Minimum details for a Buyer to be created

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

    Full details that can be specified

    {
    "name": "Test Buyer",
    "registrationNumber": "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"
    }
}

    Buyer Pricing Scheme

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

    Property DataType Description Constraints
    Identifier String The unique identifier for the payment option. The identifier is used when specifying the PaymentMethod for an Order., e.g. 'PAY30'.
    Name String The name of the payment option.
    Description String The description of the payment option.
    IsEnabled Boolean A flag that identifies whether or not this payment option 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 MarketPay API and authorised as a seller of goods or services on the platform. Similar to Buyers, a Supplier must also be approved on MarketPay 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, MarketPay 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. Must be between 1 and 250 characters.
    RegistrationNumber String The company registration number. Must be between 1 and 20 characters.
    CountryCode String The code that identifies the country of incorporation of the Supplier's company . GB will be defaulted if not specified. 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. MarketPay supports accounts within GB, US and a number of 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 MarketPay risk team. This determines whether or not the Marketplace can sell goods or services on their behalf using MarketPay. See Buyer/Supplier Decision Status for further details. Only returned by MarketPay API responses. This will be ignored if included in any requests.

    Buyer/Supplier Decision Status

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

    Name Description
    Submitted The Buyer has been registered and no risk decisioning has been started. This Buyer is unlikely to be in this status for long as a newly registered Buyer are passed through an auto-decisioning process and will move immediately to InReview.
    InReview The Buyer is currently being reviewed. This can be due to an automated decisioning or further information being required where manual intervention is needed by the MarketPay risk team. The company may be contacted to provide further details.
    Approved The Buyer has been approved and now has a TotalLimit >= 1.
    Rejected The Buyer has been rejected and will not be able to transact using MarketPay. If the Buyer was previously Approved their spending limit will 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. Must be a valid ISO 4217 code. Required for all bank accounts. Must be one of USD, GBP, EUR. Depending upon which code used the constraints change as described in this table.
    AccountName String The name of the bank account. Used to help verify bank details. Must be between 1 and 50 characters. Required for all bank accounts.
    SortCode String The sort code or routing number (USD). Must be between 1 and 10 characters. Required for both GBP and USD accounts.
    AccountNumber String The account number. Must be between 1 and 10 characters. Required for both GBP and USD accounts.
    Bic String The Swift BIC (Bank identifier code). Must be between 1 and 10 characters. Optional for all bank accounts. Must be a valid ISO 9362 code.
    AccountType String (Enum) The type of USD account. Must be one of Checking or Savings. Required for USD accounts.
    Iban String The International Bank Account Number as per ISO 3616. 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. Must be between 5 and 150 characters. Optional.
    Email String The Email address of the primary contact. Must be a valid Email address. Must be between 1 and 150 characters. Optional.
    Role String The role of the primary contact within the company. Must be between 1 and 150 characters. Optional.
    PhoneNumber String The contact phone number of the primary contact. Must be a valid phone number. This is not limited to UK phone numbers. Optional.

    Monetary data

    The structure of the monetary data, composed by the amount and the currency.

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

    Webhooks

    The MarketPay API uses webhooks to send POST requests to your application when a specific event occurs across a number of entities. This mechanism ensures that your apps are able to stay in sync with MarketPay data or allow you to react to specific 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 MarketPay 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.
    • 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 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 structures for the events types are:

    BuyerRiskDecisionChanged

    {
    "companyRegistrationNumber": "12345678",
    "limit": 15000000,
    "status": "Approved",
    "currentBalance": 14100000
}

    OrderStatusChanged

    {
    "marketplaceOrderId": "ORDER-00001",
    "oldStatus": "Draft",
    "newStatus": "Submitted"
}

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

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

    Configuring Webhooks

    A single URL on your server to receive requests to is required for us to set up your webhook. To set this up, please contact us at apisupport@marketfinance.com 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 MarketPay API signs the payload in the request and includes a base64-encoded HMAC in the request header X-MarketPay-Signature. To verify the webhook was sent from the MarketPay 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-MarketPay-Signature. If the two match, then the webhook has been verified as being sent from the MarketPay 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 = xMarketPaySignature.Equals(Convert.ToBase64String(hashBytes));

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

    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, MarketPay 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, MarketPay will get 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 MarketPay to their own applications on a recurring basis, e.g. recurring data fetching.

    Delayed Requests

    There may be times where webhook requests are made with a delay since the event occured. This may be due to processing times on MarketPay or due to retries made to the server for the webhook URL. To account for this, 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 MarketPay 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-staging.marketfinance.ninja/marketpay/

    The Test environment has been created to allow for 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 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.

    Production

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

    Test Scenarios

    To provide an efficient method of testing in the Test environment, the API exposes endpoints that will allow you to override specific internal operations.

    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 auto-risk decisioning 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/{companyRegistrationNumber}/risk-decision
    • /api/scenario/Suppliers/{companyRegistrationNumber}/risk-decision

    Order Status Transitions

    There are a number of 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 MarketPay. However, to ensure you are able to 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 are able to 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

    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.

    If you're interested to learn more about how MarketPay can help your business you can either request a demo here or contact us at marketpay@marketfinance.com.