APIs

  • 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:

    Referral Journey

    Application journey on the MarketFinance-hosted web-site:

    Referral Journey Walkthrough

    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:

    Full Application Journey

    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 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. 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 contact apisupport@marketfinance.com.

    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 spending 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 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 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 limited to displaying the Marketplace log but further enhancements are on the 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 API capabilities to ensure the customer has a high quality experience.

    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 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.

    1. Marketplace uses webhooks or the GetBuyer endpoint to determine whether the Buyer has been Approved and MarketPay payment methods are available to them.
    2. Marketplace may make a request to the MarketPay API GetBuyerPricingScheme endpoint to understand which payment methods are available to the Buyer, along with any associated fees they may incur.
    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 spending limit of the Buyer.

    1. MarketPay API responds with a 201 Created to confirm the order has been created and also returns 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 spending 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 advance 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 end-to-end journey from the customers perspective once they have been redirected to the MarketPay hosted Payments Journey.

    Payments Journey Walkthrough

    Payments journey flow

    The following flow shows a typical scenario for the Payments Journey. A Buyer has chosen to pay using MarketPay 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 MarketPay.
    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 returns 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.

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

    1. Marketplace makes a request to the MarketPay 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.

    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

    AutoTransitionOnCompletion

    This property defines the status that the order will transition to after payment journey is completed but prior to 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 automatically transition an order to Submitted or ReadyToAdvance instead.

    Initiating a payment journey

    To initiate a payment journey, there are two 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, 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 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 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 MarketPay can still transact with the funds available on the Buyers available spending limit.

    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 GB, 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 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)
    Order Status
    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. 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. Must not be earlier than 4 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": {
      	"companyRegistrationNumber": "00123456",
      	"companyName": "Buyer Company",
      	"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": {
        "companyRegistrationNumber": "00123456",
        "companyName": "Buyer Company",
      	"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": {
        "companyRegistrationNumber": "00123456",
        "companyName": "Buyer Company",
        "type": "LimitedCompany",
        "countryOfRegistration": "GB"
      },
      "supplierCompany": {
          "companyRegistrationNumber": "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.marketfinance.com",
        "paymentDeclinedRedirectUrl": "https://declined.marketfinance.com",
        "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 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 spending 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 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 MarketPay API to advance funds equivalent to the order amount, minus fees, to 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 Buyers available spending limit 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. 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. 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 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 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. | 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. | Must be a valid absolute URI. | | DeclineStatus | String (Enum) | The status describing 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 payment journey is completed. See Order Status for more information. | |

    Decline Status

    The decline status 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 MarketPay were unable to transact with the Buyer as they have not been or are no longer in an Approved status.
    InsufficientFunds MarketPay 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 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 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 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.

    Minimum details for a Supplier to be created

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

    Full details that can be specified

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

    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 but no risk decision has been made. Automatic risk decisioning 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 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 spending limit > 0.
    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 expressed 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, e.g. due to our automated risk decisioning.
    • 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.

    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

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

    OrderStatusChanged

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

    The following example shows what a full 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 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 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 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 MarketPay 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 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

    Production

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

    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.

    API Endpoints