>apis>partner

Partner API

In today's competitive retail landscape, providing a seamless and personalized consumer journey is paramount. Recognizing this, we are pleased to introduce our Partner API, designed specifically for retailers looking to integrate advanced decisioning capabilities into their own systems. This powerful API allows retailers to independently determine the eligibility of their customers, enhancing the overall consumer experience and driving higher satisfaction and conversion rates.

If you would like to use the Partner API, please get in touch with us here.

Server-side
REST
JSON

Concepts

Introduction

What the Partner API does, how authentication works and how to get started.

Overview

Our Partner API is a robust and flexible solution that empowers retailers to embed our sophisticated decisioning endpoints directly into their consumer journey. By leveraging this API, retailers can perform real-time eligibility checks on their customers, enabling faster and more accurate decision-making processes. Whether it's for credit approvals, membership qualifications, or special offers, our API ensures that your customers receive timely and relevant responses tailored to their individual profiles.

Key Features and Benefits

Real-time Decisioning: Our API delivers instantaneous responses, allowing retailers to provide immediate feedback to their customers. This speed is critical in maintaining engagement and reducing drop-off rates during key decision points in the consumer journey.

Seamless Integration: Designed with ease of use in mind, our API can be smoothly integrated into your existing systems. Whether you are using a bespoke platform or a widely-adopted e-commerce solution, our comprehensive documentation and support resources make the integration process straightforward and hassle-free.

Enhanced Customer Experience: By incorporating our decisioning endpoints, retailers can offer a more personalized and efficient service. Customers benefit from quick eligibility checks, reducing the friction and uncertainty often associated with these processes.

Data Security and Compliance: We understand the importance of data security and compliance. Our API adheres to the highest standards of data protection, ensuring that all customer information is handled with the utmost care and in accordance with relevant regulations.

Authentication

To use our Partner API, retailers will be given four credentials during the onboarding process: a Client ID, a Client Secret, a Partner ID and a Partner Retailer ID. These credentials ensure that only authorized entities can access the decisioning endpoints, maintaining the integrity and security of the system.

Partner ID and Partner Retailer ID: These identify you as a partner and the retailer you are integrating. They stay the same across every request and must be sent in the body of every request to the endpoints below (apart from the token request), as partnerId (a number) and partnerRetailerId (a string).

Client ID and Client Secret: These are used to request an authorization token. The Client ID also helps track and manage the usage of the API, providing insights into how the decisioning services are being utilized. Keep your Client Secret private.

Authorization Token: This token is a unique identifier that verifies the identity of the requester. It is mandatory for each API call, ensuring that only authenticated and authorized requests are processed. It is obtained via a request using your unique Client ID and Client Secret.

Getting Started

We have designed the onboarding process to be as smooth as possible. Below is a step-by-step guide to getting started with our Partner API:

Sign Up

Contact our sales team to express your interest in using the Partner API. They will guide you through the initial sign-up process and provide you with your credentials: a Client ID, a Client Secret, a Partner ID and a Partner Retailer ID.

Partner Logo

Contact our sales team to have your logo displayed on our SDK. The logo should be submitted in PNG, JPG, or SVG format and have maximum dimensions of 175 pixels in width and 50 pixels in height.

Documentation and SDKs

Access our comprehensive API documentation and Software Development Kits (SDKs) from our developer portal. These resources include detailed information on API endpoints, request/response formats, and sample code to help you get started quickly.

Integration and Testing

Use the provided documentation to integrate the API into your system. Our support team is available to assist with any technical queries you might have during this phase. We also offer a sandbox environment where you can test your integration before going live.

Instructions for testing your integration, including how to force each decision, are in the sandbox testing guide.

Go Live

Once you have successfully tested the integration, you can move to the live environment.

Reference

Environments

Base URLs for the sandbox and production environments.

🧪 Sandbox Environment

This environment should be used during the integration phase. The "Try It Out" feature below will execute requests against the sandbox environment. This environment is a safe space to test your integration without affecting real production data. The base URL for the sandbox environment is shown opposite.

The decision you get in the sandbox depends on the customer’s last name. See Forcing a decision in the sandbox testing guide.

bash

https://partner-sandbox.snapfinance.co.uk

⚠️ Production Environment

Once your integration has been tested and is ready for production, you should update your API requests to point to the production environment. All API requests will interact with live data. The base URL for the production environment is shown opposite.

bash

https://partner.snapfinance.co.uk

Reference

API Endpoints

Every endpoint with its parameters and responses. Try any request from this page.

Each endpoint serves a specific purpose and requires different parameters to be passed in the request. Once you have obtained the token, it will be automatically prepopulated on the headers of every new test request.

Get a token

Attempts to get a token which can be used in the other APIs. The request body must include the clientId and clientSecret for the retailer. This endpoint is used when a broker/retailer needs to get a token. The response includes the newly created bearer token from Auth0.

The token will be valid for 24 hours so please cache it so that you don't call for a token more than once a day.

Body parametersExpand all

clientId: stringRequired

clientSecret: stringRequired

Create a Snap application and get a decision

Sends data to Snap for a customer to get finance offers. This endpoint is used to create an application in Snap, the payload includes the customer's name, address, and other relevant information to get a decision.

Header parametersExpand all

Authorization: stringRequired

Body parametersExpand all

partnerId: integerRequired

partnerRetailerId: stringRequired

partnerAppId: integerRequired

invoiceId: stringRequired

applicationType: string (enum)Required

applicationSource: string (enum)Optional

title: string (enum)Required

firstName: stringRequired

lastName: stringRequired

birthdate: stringRequired

email: stringRequired

mobilePhone: stringRequired

homePhone: stringOptional

maritalStatus: string (enum)Required

marketingPreference: objectOptional

currentAddress: objectRequired

previousAddress: objectOptional

employmentStatus: string (enum)Required

employmentIndustry: integer (enum)Optional

employerName: stringOptional

jobTitle: stringOptional

yearsWithEmployer: integer (enum)Optional

netMonthlyIncome: numberOptional

grossMonthlyIncome: numberOptional

incomeFrequency: string (enum)Required

benefitsType: objectOptional

numberOfDependants: integer (enum)Optional

monthlyExpenditureTotal: numberOptional

monthlyExpenditureBreakdown: objectOptional

creditCommitments: numberOptional

monthlyRentMortgage: numberOptional

rentReason: string (enum)Optional

bankDetails: objectRequired

loanDetails: objectRequired

deliveryDate: stringRequired

submissionDate: stringRequired

basket: array of objectsRequired

clientIp: stringRequired

clientAgent: stringRequired

successUrl: stringRequired

declineUrl: stringRequired

cancelUrl: stringRequired

webhookUrl: stringOptional

redirectUrl: booleanRequired

Cancel Request

Attempts to cancel Application. The request body must include the partnerId, partnerAppId, partnerRetailerId, and reason for cancel. This endpoint is used when a broker/retailer needs to cancel application. The response includes the message from Snap App.

Header parametersExpand all

Authorization: stringRequired

Body parametersExpand all

applicationId: numberOptional

partnerId: numberRequired

partnerAppId: numberRequired

partnerRetailerId: stringRequired

reason: stringRequired

Change the delivery date of an application's order

This endpoint is used when you would like to change the delivery date of an application's order

Header parametersExpand all

Authorization: stringRequired

Body parametersExpand all

partnerId: numberRequired

partnerRetailerId: stringRequired

partnerAppId: numberRequired

deliveryDate: stringRequired

Fulfillment Request

Attempts to notify about application has been delivered. The request body must include the partnerId, partnerAppId, partnerRetailerId. This endpoint is used when a broker/retailer needs to notify about application delivery. The response includes the message from Snap App.

Header parametersExpand all

Authorization: stringRequired

Body parametersExpand all

partnerId: numberRequired

partnerAppId: numberRequired

partnerRetailerId: stringRequired

Refund Request

Attempts to refund an application. The request body must include the partnerId, partnerAppId, and partnerRetailerId. This endpoint is used when a broker/retailer needs to request a refund for an application. The response includes the message from Snap App.

Header parametersExpand all

Authorization: stringRequired

Body parametersExpand all

partnerId: numberRequired

partnerAppId: numberRequired

partnerRetailerId: stringRequired

amount: numberRequired

reason: string (enum)Required

Amend a Snap application

Sends data to Snap to create an amendment for an application, the payload includes the loan details, the new invoice, and other relevant information to get a decision.

Header parametersExpand all

Authorization: stringRequired

Body parametersExpand all

partnerId: integerRequired

partnerRetailerId: stringRequired

partnerAppId: integerRequired

invoiceId: stringRequired

loanDetails: objectRequired

basket: array of objectsRequired

Get the status of the application

This endpoint is used when you would like get the status of application

Header parametersExpand all

Authorization: stringRequired

Body parametersExpand all

partnerId: numberRequired

partnerRetailerId: stringRequired

partnerAppId: numberRequired

Reference

Webhooks

Get a message on your server whenever an application changes status.

How it works

Every time an application changes status, Snap Finance sends an HTTPS POST request with a JSON body to the webhookUrl you passed when you created that application. You don’t need to poll for updates.

Webhooks are only sent for applications created with a webhookUrl. Applications created without one don’t send any.

1. Set up your endpoint

Create a public HTTPS URL on your system that accepts POST requests with a JSON body. Send it as webhookUrl in the body of the create application request (/v1/partner/applications).

2. Verify and read

Check the signature on each message, then read status to see what changed and data for the details.

3. Reply with 2xx

Return a 2xx response quickly. Do any slow work after you reply.

Receiving webhooks

The body of each request is a single JSON object describing one status change for one application. Each message is sent to the webhookUrl you included for that application.

Each request carries these headers:

Header	Use
`Content-Type`	Always `application/json`.
`snap-timestamp`	The timestamp used to sign the message. It is part of the signing string.
`snap-signature`	The signature of the message, as a hex string. Use it to confirm the message came from Snap Finance.

Verify the signature

Always verify the signature before you act on a message. To check a message:

1. Take the snap-timestamp header and the raw request body.

2. Build the signing string: the timestamp, then a colon, then the raw body, for example 1700000000:{"applicationId":…}.

3. Calculate an HMAC with SHA-256 over the signing string, using your signing secret as the key, and write the result as a hex string.

4. Compare your result with the snap-signature header. If they don’t match, reject the message.

Use the raw body exactly as you received it, not a re-serialised copy. Changing the spacing or key order changes the signature. Compare the two values in constant time where your language allows it.

javascript

// Node.js
import crypto from 'node:crypto';

// rawBody is the unmodified request body as a string
function isValidSignature(secret, headers, rawBody) {
  const timestamp = headers['snap-timestamp'];
  const received = headers['snap-signature'];
  if (!timestamp || !received) return false;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}:${rawBody}`)
    .digest('hex');

  const a = Buffer.from(received);
  const b = Buffer.from(expected);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Handling messages well

Reply fast. Return a 2xx response as soon as you have stored the message. Anything else may be treated as a failed delivery.

Expect repeats. A message can be delivered more than once. Make your handler safe to run twice, using applicationId, status and timestamp to spot a message you have already processed.

Updates can repeat a status. After an amendment, the current status can be sent again with new figures. Treat the latest timestamp for a status as the current information.

Use status. It tells you what the message is about. previousStatusText tells you where the application was before.

Don’t rely on order. If messages for the same application arrive out of order, use timestamp to find the latest.

Expect missing keys. Keys that do not apply to a status may not be present. Check that a key exists before you read it.

Ignore keys you don’t know. We may add new keys over time. Your code should not fail when it sees one.

Statuses

The status field is one of these values.

Status	What it means
`APPROVED`	The customer has been approved.
`APPROVED_WITH_CONDITIONS`	The customer has been approved, subject to the checks listed in `verificationRequired`.
`DENIED`	The application has been declined.
`PENDING_DOCS`	Snap Finance is waiting for documents from the customer.
`PENDING_DEL`	The agreement is in place and is waiting for delivery.
`COMPLETE`	Delivery has been confirmed and the application is complete.
`WITHDRAWN`	The application has been withdrawn.
`FUNDED`	The agreement has been funded.
`ERROR`	An error has occurred on the application.

Payloads by status

Choose a status to see an example payload. Values are illustrative. The same example application is used throughout, so figures may differ between statuses.

json

approved.json

{
  "applicationId": 1234567,
  "snapAppId": "2608040647UK",
  "status": "APPROVED",
  "previousStatus": 2,
  "previousStatusText": "PENDING",
  "timestamp": "2026-10-27T16:08:29+00:00",
  "continueLink": "https://express.snapfinance.co.uk/?mid=4607&source=SDK&applicationId=1234567",
  "data": {
    "invoiceNumber": "INV-100245",
    "approvedAt": "2026-10-27T16:08:27+00:00",
    "expiryDate": "2026-11-26T16:08:27+00:00",
    "maxAmount": 1500,
    "maxTerm": 24,
    "offers": [
      {
        "termMonths": 12,
        "apr": 29.9,
        "interestRate": 0.162,
        "approvedAmount": 1500,
        "loanAmount": 1000,
        "repaymentAmount": 96.84,
        "paymentFrequency": "MONTHLY",
        "totalRepayable": 1162.08,
        "totalInterestRepayable": 162.08,
        "deposit": 0,
        "totalCashPrice": 1000
      },
      {
        "termMonths": 24,
        "apr": 29.9,
        "interestRate": 0.319,
        "approvedAmount": 1500,
        "loanAmount": 1000,
        "repaymentAmount": 54.97,
        "paymentFrequency": "MONTHLY",
        "totalRepayable": 1319.28,
        "totalInterestRepayable": 319.28,
        "deposit": 0,
        "totalCashPrice": 1000
      }
    ]
  }
}

Top-level fields

Types use JSON terms. “string (date-time)” means a string such as 2026-10-27T16:08:29+00:00. Amounts are in pounds.

Field	Type	Description	Sent on
`applicationId`	number	Snap Finance’s numeric ID for the application.	All
`snapAppId`	string	The application reference, for example `2608040647UK`.	All
`status`	string	The new status. One of `APPROVED`, `APPROVED_WITH_CONDITIONS`, `DENIED`, `PENDING_DOCS`, `PENDING_DEL`, `COMPLETE`, `WITHDRAWN`, `FUNDED`, `ERROR`.	All
`previousStatus`	number	The code of the last status before this change. Use `previousStatusText` to read it.	All
`previousStatusText`	string	The last status before this change, for example `PENDING` or `PENDING_DOCS`.	All
`timestamp`	string (date-time)	When the change happened, with a UTC offset, for example `2026-10-27T16:08:29+00:00`.	All
`continueLink`	string	A link to Snap Finance’s application page for the customer.	`APPROVED`, `APPROVED_WITH_CONDITIONS`, `PENDING_DOCS`
`data`	object	The status-specific fields below.	All

Fields in data

Each key holds a value on the statuses shown. On other statuses it may not be present.

Field	Type	Description	Has a value on
`invoiceNumber`	string	The invoice number for the application.	All
`approvedAt`	string (date-time)	When the application was approved.	`APPROVED`, `APPROVED_WITH_CONDITIONS`
`expiryDate`	string (date-time)	When the approval expires.	`APPROVED`
`maxAmount`	number	The maximum amount the customer is approved for, in pounds.	`APPROVED`, `PENDING_DEL`
`maxTerm`	number	The maximum term in months.	`APPROVED`
`offers`	array of offers	The offers available to the customer. See Offer fields.	`APPROVED`
`verificationRequired`	array of strings	The checks the customer still needs to complete, for example `["INCOME_PORTAL"]`.	`APPROVED_WITH_CONDITIONS`
`verificationExpiry`	string (date-time)	When the verification step expires.	`APPROVED_WITH_CONDITIONS`
`declinedAt`	string (date-time)	When the application was declined.	`DENIED`
`declineReason`	string	The decline reason code, for example `ELIGIBLE_CHECK`.	`DENIED`
`documentsExpiry`	string (date-time)	When the customer’s documents are due by.	`PENDING_DOCS`
`fulfilmentExpiry`	string (date-time)	The date by which the order needs to be fulfilled.	`PENDING_DEL`
`approvedAmount` … `totalCashPrice`	as in Offer fields	The agreed figures for the application: `approvedAmount`, `loanAmount`, `totalCashPrice`, `deposit`, `termMonths`, `repaymentAmount`, `paymentFrequency`, `interestRate`, `apr`, `totalRepayable` and `totalInterestRepayable`. They use the same types and meanings as the offer fields, but sit directly in `data`.	`PENDING_DEL`, `COMPLETE`
`subsidyPercentage`	number	The subsidy percentage, for example `0.08`.	`PENDING_DEL`, `COMPLETE`
`subsidyFee`	number	The subsidy fee in pounds.	`PENDING_DEL`, `COMPLETE`
`brokerCommission`	number	The broker commission rate, for example `0.02`.	`PENDING_DEL`, `COMPLETE`
`brokerCommissionAmount`	number	The broker commission in pounds.	`PENDING_DEL`, `COMPLETE`
`completedAt`	string (date-time)	When the application was completed.	`COMPLETE`
`withdrawnBy`	string	Who withdrew the application.	`WITHDRAWN`
`withdrawnAt`	string (date-time)	When the application was withdrawn.	`WITHDRAWN`
`withdrawReason`	string	The reason for the withdrawal, for example `Retailer Request`.	`WITHDRAWN`
`fundedAmount`	number	The amount funded, in pounds.	`FUNDED`
`fundingDate`	string (date-time)	The date of funding.	`FUNDED`
`fundingReference`	string	The funding reference.	`FUNDED`
`errorCode`	string	The error code.	`ERROR`
`errorMessage`	string	A description of the error.	`ERROR`
`occurredAt`	string (date-time)	When the error occurred.	`ERROR`

Offer fields

Each item in offers has these fields.

Field	Type	Description
`termMonths`	number	Term of the agreement in months.
`apr`	number	Annual percentage rate, for example `29.9`.
`interestRate`	number	Interest rate, for example `0.162`.
`approvedAmount`	number	Approved amount in pounds.
`loanAmount`	number	Loan amount in pounds.
`repaymentAmount`	number	Amount of each repayment in pounds.
`paymentFrequency`	string	How often repayments are made, for example `MONTHLY`.
`totalRepayable`	number	Total amount repayable in pounds.
`totalInterestRepayable`	number	Total interest repayable in pounds.
`deposit`	number	Deposit in pounds.
`totalCashPrice`	number	Total cash price in pounds.

Tools

Postman Collection

Test every endpoint from Postman instead of the browser.

Download a collection with every endpoint above. It is generated from the same API specification as this page, so it is always up to date.

Download Postman collection

Step 01 Import the collection

Download the collection using the button above. In Postman, select Import and drop in the downloaded file. The collection includes every endpoint listed above, with example request bodies.

Step 02 Set the collection variables

Open the collection, go to the Variables tab and fill in the credentials provided during onboarding: clientId, clientSecret, partnerId, partnerRetailerId.

clientId, clientSecret are only used to get a token, while partnerId, partnerRetailerId stay the same across requests and are filled into the body of every other request in the collection.

baseUrl defaults to https://partner-sandbox.snapfinance.co.uk. Change it to https://partner.snapfinance.co.uk to use the Production environment.

Step 03 Get a token

Send the Get a token request. The response is saved to token automatically and sent with every other request in the collection.

Introduction

Overview

Key Features and Benefits

Authentication

Getting Started

Sign Up

Partner Logo

Documentation and SDKs

Integration and Testing

Go Live

Environments

🧪 Sandbox Environment

⚠️ Production Environment

API Endpoints

Get a token

Body parametersExpand all

POST/v1/token

Response example

Create a Snap application and get a decision

Header parametersExpand all

Body parametersExpand all

POST/v1/partner/applications

Response example

Cancel Request

Header parametersExpand all

Body parametersExpand all

POST/v1/partner/cancel

Response example

Change the delivery date of an application's order

Header parametersExpand all

Body parametersExpand all

PUT/v1/partner/delivery-date

Response example

Fulfillment Request

Header parametersExpand all

Body parametersExpand all

POST/v1/partner/fulfillment

Response example

Refund Request

Header parametersExpand all

Body parametersExpand all

POST/v1/partner/refund

Response example

Amend a Snap application

Header parametersExpand all

Body parametersExpand all

POST/v1/partner/amendment

Response example

Get the status of the application

Header parametersExpand all

Body parametersExpand all

POST/v1/partner/status

Response example

Webhooks

How it works

1. Set up your endpoint

2. Verify and read

3. Reply with 2xx

Receiving webhooks

Verify the signature

Handling messages well

Statuses

Payloads by status

Top-level fields

Fields in data

Offer fields

Postman Collection

Step 01 Import the collection

Step 02 Set the collection variables

Step 03 Get a token