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:

Request a quote for a given customer
Refer a potential customer to MarketFinance (the customer need to be redirected to MarketFinance application journey to complete the application)
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.

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:

The Partner calls into Lending API and provides the data points they currently have.
Lending API responds with the quote and the URL to continue the application.
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.
The Borrower fills out remaining fields and submits the application.

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

Partner makes a request to the Lending API CreateApplication endpoint to register a draft application on the API.
Lending API responds with a 201 Created status code to confirm the application has been created.
Lending API provides Accurate or Representative quotes to the Partner via webhook or GetOffersByApplicationId endpoint.
Partner displays a button on their web site to allow the Borrower to accept the quote.
Borrower clicks the button to accept the quote.
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.
Borrower validates pre-populated data, fills out remaining fields and submits the application on the application journey website.
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:

Partner makes a request to the CreateApplication endpoint to create a draft application.
Lending API responds with a 201 Created status code to confirm the application has been created.
Lending API begins risk decisioning process to determine borrower's eligibility.
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:

Retrieve your key that you should have received from the MarketFinance team. This should be stored securely on your server.
Generate a HMAC-SHA256 hash based on the payload you received in the request and your HMAC key.
The generated hash should be base64-encoded.
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.

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.

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:

Buyer has been onboarded by the Marketplace.
Marketplace makes a request to the MarketPay API CreateBuyer endpoint to register them on the API to identify if they can use MarketPay.
MarketPay API begins risk decisioning process to determine if a limit can be provided to the Buyer.
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.

Marketplace uses webhooks or the GetBuyer endpoint to determine whether the Buyer has been Approved and MarketPay payment methods are available to them.
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.
MarketPay API responds with a 200 OK response and provides the pricing scheme available to the Buyer.
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.
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.

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.
Buyer confirms they want to proceed and place the order on the Marketplace.
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.

MarketPay API responds with a 200 OK response.
Marketplace delivers the goods to the Buyer and an invoice has been generated.
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.

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.

Buyer, existing or new, has been onboarded by the MarketPlace and has been offered MarketPay.
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.

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.

Marketplace redirects the customer to the returned URL.
Buyer lands on the Payments Journey page, which includes filling out Company and User details if they were not initially provided in step 2.
Buyer selects their preferred payment method and finally completes their payment journey.
Payments Journey redirects the Buyer back to the Marketplace.
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.

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.

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

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:

Retrieve your key that you should have received from the MarketFinance team. This should be stored securely on your server.
Generate a HMAC-SHA256 hash based on the payload you received in the request and your HMAC key.
The generated hash should be base64-encoded.
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.