top of page
Developers
API guide for developers working with Synapi
Synapi POS API – Client Guide
Contents
1. API Behaviours
2. Merchant Requests
2.1. Create Merchant
2.2. Update Merchant
3. Loan Product Requests
3.1. Get Loan Product Options
4. Loan Application Requests
4.1. Step 1 – Start Application
4.2. Step 2 – Hard Credit Check
4.3. Step 3 – Card Submitted
4.4. Step 4 – Loan Explanation Accepted
4.5. Step 5 – Esign
4.6. At Clinic – Payout Funds
5. Example Error Responses
6. Debit Card Capture
7. Loan Application Request Workflow
1. API Behaviours
The Synapi POS API follows REST principles in which the client creates and updates resources.
There are 3 kinds of resource:
-
Loan_products – details of loan products that are available for a given loan amount.
-
Merchants – these are the practitioners. Information about how to pay them must be given to the API before loans can be made for their products.
-
Applications – these are the loan applications. The lifecycle of an application includes several steps, therefore several update requests will be made for each application resource.
All requests and responses are in JSON with, generally, a flat structure. The response body will contain a reference to the resource as well as any other information which the client does not already know.
As with any API there are numerous error scenarios caused by mistakes by the client or problems with the server. These kinds of errors (as opposed to the deliberate “application rejected” kind) will result in a 4xx or 5xx HTTP response (as opposed to a 200 OK).
Error responses will contain a body in a common format that describes the nature of the error.
{
"error_code": "SOME_ERROR_CODE",
"error_message": "Some text describing the error in more detail"
}
See Example Error Responses below.
The API client does not necessarily have to react programmatically to an error_code, but they are provided in case they’re useful and to aid development and debugging. A simple approach would be to look at the HTTP response code instead – is it the client’s mistake or the server’s? – and react accordingly.
The error_message should not be shown to the consumer but is there to provide further information to a developer or debugger.
2. Merchant Requests
Synapi needs to know how to transfer funds to merchants (practitioners) in order to allow loans to pay for the products/services they offer.
Faces Consent must use this API to register a merchant with Synapi before loan applications can be made for that merchant’s services. This API will return a reference to the merchant (merchant_ref) which should be remembered by FC so it can be included in subsequent loan application API requests.
Available merchant requests:
-
POST/merchants
-
PATCH/merchants/<merchant_ref>
2.1. Create Merchant
POST/merchants
Use this request to register a merchant (practitioner) with Synapi, supplying the information needed for Synapi to transfer funds to them.
Typical request/response:
POST/merchants
{
"merchant_name": "Sarah’s Smiles",
"bank_name": "Lloyds",
"bank_account_number": "01234567",
"bank_sort_code": "123456"
}
200 OK
{
"merchant_ref": "23464a01-f91e-4b20-80ef-229482de09b7"
}
Request Fields POST /merchants
Response Fields POST /merchants
2.2. Update Merchant
PATCH /merchants/<merchant_ref>
Use this request to update the details of a merchant, specifying the fields you want to change.
If changing bank details, the 3 fields bank_name, bank_account_number and bank_sort_code must all be specified.
Typical request/response:
PATCH /merchants/23464a01-f91e-4b20-80ef-229482de09b7
{
“merchant_name” : “David”,
"bank_name": "Nat West",
"bank_account_number": "76543210",
"bank_sort_code": "654321"
}
200 OK
{
"merchant_ref": "23464a01-f91e-4b20-80ef-229482de09b7"
}
3. Loan Product Requests
Consumers will be presented with a range of loan options from which they will choose one before starting the loan application process. The options vary by the number of monthly repayments.
The repayment cost for each option should be shown to the consumer so they understand clearly the nature of the loan they are applying for.
Available loan product requests:
-
GET /loan_products?loan_amount=<loan_amount>
3.1. Get Loan Product Options
GET /loan_products?loan_amount=<loan_amount>
Use this request to find the list of loan products available for the specified loan amount.
The response is an array of loan_product resources.
Typical request/response:
GET /loan_products?loan_amount=123.00
200 OK
[
{
"loan_term_months": 3,
"instalment_amount": 41.30,
"total_amount": 123.90
},
{
"loan_term_months": 6,
"instalment_amount": 20.76,
"total_amount": 124.56
},
{
"loan_term_months": 9,
"instalment_amount": 13.86,
"total_amount": 124.74
},
{
"loan_term_months": 12,
"instalment_amount": 10.43,
"total_amount": 125.16
}
]
Request Parameters GET /loan_products
Response Fields GET /loan_products
Merchant Requests
Create Merchant
Update Merchant
Loan Product Request
API Behaviours
Get Loan Product Options
Loan Application requests
Start Application
4. Loan Application Requests
Synapi has integrated with Lending Stream Prime as the lender. LS requires a certain sequence of steps to apply for a loan so the
POS API provides a request for each of those steps.
From a resource model point of view, the loan application is first created. Then various aspects of it are updated – the word at the
end of the PATCH path specifies the aspect. The responses contain the information needed by the client to perform the next step
in the process.
For a loan application, these requests should be called in this order:
-
POST /applications
-
PATCH /applications/<application_ref>/hard
-
PATCH /applications/<application_ref>/card
-
PATCH /applications/<application_ref>/secci
-
PATCH /applications/<application_ref>/esign
Sometime, after a loan has been approved, when the loan should be paid out, this request should be called (triggered by the
consumer clicking on an email link):
-
PATCH /applications/<application_ref>/payout
The API will enforce the correct order of requests, E.g. it won’t allow /secci before /card. If that is attempted the client will
receive a 409 Conflict HTTP response.
As with the other parts of the API, standard REST behavior can be expected for things like badly formed requests, server errors,
etc. Such 4xx and 5xx responses will contain a body detailing the problem.
Expected and normal “problems” such as “this application is rejected” will be communicated with 200 OK responses containing
some information describing the nature of the problem. All of the loan application requests (apart from the last /payout one)
have 2 forms of 200 OK (i.e. “good”) response – the happy-path response containing the information needed by the client to
proceed, and the sad-path response containing, where appropriate, information about what went wrong.
Every response will include the new status of the loan application. The client should inspect the status to determine if the step
was successful or not. The possible statuses are summarised in the table below and explained more fully in each request’s
detailed section further on in this document.
The consumer can choose to exit the application process at any of the steps and it is useful to record that with Synapi.
To do that, the client should send the next request in the process but specify that the consumer has chosen not to proceed, e.g.
PATCH .../hard {"agree_credit_check": false}
This will change the application’s status, which will be returned in the response, e.g.
"status": "CONSUMER_DECLINED_HARD"
Loan application statuses:
In cases where Synapi has put the loan application into a failed status, i.e. the application has been rejected, the API will include
reject_reason in the response.
Loan rejection reasons (reject_reason)
OUTSTANDING_LOAN - The consumer already has an open loan with the lender. They are not
allowed another one until the first has been settled.
UNDERWRITING_REJECT - The lender has decided to decline the loan application for some
underwriting reason.
KYC_CONFLICT - In the lender’s system, the loan applicant has been identified but appears to
have provided conflicting personal details in this loan application. It’s not possible to proceed.
OTHER - Some other reason has caused the loan application to be refused. Synapi has no plans
to return this reject_reason but reserves the right to do so in the future.
4.1. Step 1 – Start Application
POST /applications
The first step in the loan application process is to send this request detailing the merchant and the loan, as well as the identity,
contact and financial information about the consumer.
The lender’s system will perform basic underwriting checks for things such as affordability and fraud.
The loan amount must be a whole number of pounds.
Typical request/responses:
POST /applications
{
"merchant_ref": "23464a01-f91e-4b20-80ef-229482de09b7",
"loan_amount": 400.00,
"loan_term_months": 6,
"title": "MR",
"first_name": "David",
"last_name": "Jones",
"dob_day": 3,
"dob_month": 9,
"dob_year": 1999,
"email": "david.jones@gmail.com",
"mobile_phone": "07890853223",
"post_code": "HE65EX",
"building_info": "Flat 19, Emlyn Gardens",
"street": "Main Street",
"city": "London",
"employment_type": "FULL_TIME",
"monthly_income": 5000,
"monthly_expenses": 800,
"no_of_dependents": 1
}
200 OK
{
"application_ref": "f58b1d11-45e7-45b2-a397-d149da30d22e",
"status": "SOFT_APPROVED"
}
200 OK
{
"application_ref": "f58b1d11-45e7-45b2-a397-d149da30d22e",
"status": "REJECTED_SOFT"
}
Request Fields POST /applications
Response Fields POST /applications
Hard Credit Check
4.2. Step 2 – Hard Credit Check
PATCH /applications/<application_ref>/hard
If the first step was successful, the next is to gain consent from the consumer to perform a credit check, which will leave a trace on their
credit file. Some further bank information is also required in this request.
A successful response will include a card_capture_url which is to be used for the consumer to submit their debit card details securely
with Lending Stream’s PCI-compliant system. This is described in more detail in the next section Step 3 – Card Submitted.
Typical request/responses – credit check agreed:
PATCH /applications/f58b1d11-45e7-45b2-a397-d149da30d22e/hard
{
"agree_credit_check": true,
"bank_account_number": "01234567",
"bank_sort_code": "123456",
"debit_card_type": "VISA_DEBIT"
}
200 OK
{
"application_ref": "f58b1d11-45e7-45b2-a397-d149da30d22e",
"status": "HARD_APPROVED",
"card_capture_url": "https://..."
}
200 OK
{
"application_ref": "f58b1d11-45e7-45b2-a397-d149da30d22e",
"status": "REJECTED_HARD"
}
Typical request/response – credit check declined by the consumer:
PATCH /applications/f58b1d11-45e7-45b2-a397-d149da30d22e/hard
{
"agree_credit_check": false
}
200 OK
{
"application_ref": "f58b1d11-45e7-45b2-a397-d149da30d22e",
"status": "CONSUMER_DECLINED_HARD"
}
Request Fields PATCH /applications/<application_ref>/hard
Response Fields PATCH /applications/<application_ref>/hard
4.3. Step 3 – Card Submitted
PATCH /applications/<application_ref>/card
Before this request is called, the consumer’s debit card details should be gathered. The output of that is the card_ref value to
send in this /card request. The gathering of this data, for compliance reasons, must be performed by a full-stack PCI-certified system – which will be Lending Stream’s card system. In practice, this means that the card entry form must be served up by LS
and submitted to LS without any leakage of sensitive data.
It is anticipated that the client system (FC) will display the card form in an iframe inside a FC web page. The Debit Card capture section of this document describes what FC has to implement for this to work.
A successful PATCH /card response will include URLs to loan explanation and SECCI documents which should be displayed to the consumer, who should be asked to read them and confirm whether or not they accept the loan terms they describe.
Typical request/response – debit card submitted successfully:
PATCH /applications/f58b1d11-45e7-45b2-a397-d149da30d22e/card
{
"card_captured": true,
"card_ref": "897ba9da12cd"[PN1]
}
200 OK
{
"application_ref": "f58b1d11-45e7-45b2-a397-d149da30d22e",
"status": "CARD_SUBMITTED",
"loan_explanation_doc_url": "https://...",
"secci_doc_url": "https://..."
}
Typical request/response – debit card failed:
PATCH /applications/f58b1d11-45e7-45b2-a397-d149da30d22e/card
{
"card_captured": false
}
200 OK
{
"application_ref": "f58b1d11-45e7-45b2-a397-d149da30d22e",
"status": "CARD_SUBMIT_FAILED"
}
Request Fields PATCH /applications/<application_ref>/card
Response Fields PATCH /applications/<application_ref>/card
4.4. Step 4 – Loan Explanation Accepted
PATCH /applications/<application_ref>/secci
This request informs Synapi whether or not, after viewing the loan explanation and SECCI documents, the consumer has chosen
to accept
the loan terms.
A successful PATCH /secci response will include a URL to the esign document which should be displayed to the consumer, who should be asked to read it and enter their signature by typing their name into a text box.
Typical request/response – loan terms accepted:
PATCH /applications/f58b1d11-45e7-45b2-a397-d149da30d22e/secci
{
"agree_precontract": true
}
200 OK
{
"application_ref": "f58b1d11-45e7-45b2-a397-d149da30d22e",
"status": "CONTRACT_AGREED",
"esign_doc_url": "https://..."
}
Typical request/response – loan terms declined by consumer:
PATCH /applications/f58b1d11-45e7-45b2-a397-d149da30d22e/secci
{
"agree_precontract": false
}
200 OK
{
"application_ref": "f58b1d11-45e7-45b2-a397-d149da30d22e",
"status": "CONSUMER_DECLINED_CONTRACT"
}
Request Fields PATCH /applications/<application_ref>/secci
Response Fields PATCH /applications/<application_ref>/secci
4.5. Step 5 – Esign
PATCH /applications/<application_ref>/esign
This request informs Synapi whether or not, after viewing the esign document, the consumer has chosen to sign the loan contract.
If the consumer signed, the response would indicate the loan application now has the LOAN_APPROVED status and the consumer can be shown a page telling them their application has been successful. The client system should email the consumer confirmation of the booking which includes a link (to the client system) which the consumer should click on when it’s time to pay for the product/service they have
ordered.
Typical request/response – signature provided:
PATCH /applications/f58b1d11-45e7-45b2-a397-d149da30d22e/esign
{
"agree_esign": true,
"signature": "D. Jones"
}
200 OK
{
"application_ref": "f58b1d11-45e7-45b2-a397-d149da30d22e",
"status": "LOAN_APPROVED"
}
Typical request/response – esign declined by consumer:
PATCH /applications/f58b1d11-45e7-45b2-a397-d149da30d22e/esign
{
"agree_esign": false
}
200 OK
{
"application_ref": "f58b1d11-45e7-45b2-a397-d149da30d22e",
"status": "CONSUMER_DECLINED_ESIGN"
}
Request Fields PATCH /applications/<application_ref>/esign
Response Fields PATCH /applications/<application_ref>/esign
4.6. At Clinic – Payout Funds
PATCH /applications/<application_ref>/payout
The booking confirmation email sent to the consumer by the client system will have explained that the consumer should click on a linkin the email when it’s time to pay for their order. The email link will be a client system URL (i.e., fc.com) containing the client system’s identifier for the loan. The handler for that request should do 2 things:
-
Look up the application_ref and send a PATCH /payout request to Synapi POS.
-
Upon a successful response ("status": "LOAN_PAYOUT_SENT") from the API, serve up an HTML page
confirming the loan has -
been paid out – this is for the benefit of the consumer and the merchant who is being paid.
When Synapi POS gets this request, it will arrange to formally start the loan (email the consumer and start charging interest) and
arrange to disburse the loan funds to the merchant and the client system, according to the split payment rules.
The paying out of the loan may be done asynchronously so it will not wait for funds transfers to complete before responding, and the LOAN_PAYOUT_SENT status indicates that Synapi will make best efforts to transfer the funds in a timely manner.
Typical request/response:
PATCH /applications/f58b1d11-45e7-45b2-a397-d149da30d22e/payout
{} (empty body)
200 OK
{
"application_ref": "f58b1d11-45e7-45b2-a397-d149da30d22e",
"status": "LOAN_PAYOUT_SENT"
}
Response Fields PATCH /applications/<application_ref>/payout
5. Example Error Responses
Below are some examples of error responses caused by unexpected input or an internal error.
405 Method Not Allowed {
"error_code": "BAD_METHOD",
"error_message": "You cannot PATCH /merchants"
}
404 Not Found {
"error_code": "RESOURCE_NOT_FOUND",
"error_message": "There is no such application resource"
}
400 Bad Request {
"error_code": "MISSING_FIELD",
"error_message": "The first_name field is missing"
}
400 Bad Request {
"error_code": "BAD_FIELD_FORMAT",
"error_message": "The sort_code field has a bad format"
}
409 Conflict {
"error_code": "APPLICATION_WRONG_STATE",
"error_message": "The application is in the wrong state for this request, did you miss a step?"
}
500 Internal Server Error {
"error_code": "DB_ERROR",
"error_message": "An unexpected database error has occurred"
}
6. Debit Card capture
(Note that card_ref is the Synapi POS API name for the data item that is named CIMTranId in Lending Stream’s debit card system:
card_ref == CIMTranId.)
See Loan Application request flow diagram below for a pictorial description of how card capture works.
The POS API’s PATCH /applications/<application_ref>/hard response includes a card_capture_url which should be loaded into an
iframe. Specifically, the client system (FC) should serve up to the consumer an HTML page containing
<iframe src="$card_capture_url">. The iframe will then load the debit card entry form from Lending Stream’s system. After the consumer
has filled in their card details and submitted the form, LS will respond back with a redirect to a client system URL. The browser
makes a request to that URL, which is implemented in the client system and should return a simple page that runs some Javascript to change the URL of the main browser document (the iframe’s parent) so it fetches the next loan application page from the client system. This redirect-then-javascript technique is how the iframe “gets closed”, and also allows a vital item of data to travel from LS’s card system
to browser to FC’s system – the CIMTranId/card_ref.
Here is what the client system needs to implement:
-
After performing PATCH /hard with this API, serve up to the consumer an HTML page that contains
<iframe src="$card_capture_url">. -
Handle the happy-path redirect URL. This is known as CARD_SUCCESS_URL and the Synapi POS system will know
of it. -
Handle the sad-path redirect URL, known as CARD_FAIL_URL.
-
Both handlers should return to the browser an HTML page that points the main browser document to the next loan
application page. The recommendation is to have the page run some Javascript similar to this:
document.parent.src= https://... -
The handler for CARD_SUCCESS_URL should expect a CIMTranId query param, e.g. the redirect will be to
https://fc.com/card_success?CIMTranId=xxx. The handler should include that param in the URL it sets for the
iframe’s parent, e.g. document.parent.src = https://fc.com/step4?CIMTranId=xxx -
The handler for /step4 should send a PATCH /card request to Synapi POS using the CIMTranId value for the
card_ref field. The API response will include the loan explanation and SECCI document URLs so that FC can arrange to show them to the consumer. -
The handler for CARD_FAIL_URL has no query params to deal with but should load a “loan application failed” page into the iframe’s parent and arrange to PATCH /card with "card_captured": false.
7. Loan Application Request Workflow
Card Submitted
Loan Explanation Accepted
Esign
Payout Funds
Error Responses
Debit Card Capture
Loan Application Workflow
bottom of page