High level B2B financing flow
\nStep-By-Step
\nStep 1 - Creating the company and user
\nIntegrator needs to create a company and user entites applying for KoverlyPay credit line.
\nTo create a Company, use:
\ncurl --location 'https://sand2.koverly.com/platform/v1/company' \\\n--header 'Authorization: Bearer YOUR_JWT_TOKEN' \\\n--data '{\n \"name\": \"My Importer\",\n \"legalName\": \"Import Wines Inc.\",\n \"address\": {\n \"address1\": \"100 main street\",\n \"address2\": \"\",\n \"Town\": \"Boston\",\n \"countrySubDivision\" : \"MA\",\n \"country\": \"US\",\n \"postalCode\": \"02215\"\n },\n \"legalTaxType\": \"EIN\",\n \"legalTaxNumber\": \"12-2323244443\"\n}\n\nThis will return example response as a Company object.
\n{\n \"success\": true,\n \"statusCode\": 0,\n \"company\": {\n \"companyId\": \"60e63207-0974-46a1-89f4-8a4098053102\",\n \"name\": \"My Importer\",\n \"legalName\": \"Import Wines Inc.\",\n \"address\": {\n \"address1\": \"100 main street\",\n \"address2\": \"\",\n \"address3\": null,\n \"town\": null,\n \"postalCode\": \"02215\",\n \"countrySubDivision\": \"MA\",\n \"country\": \"US\",\n \"formatted\": \"100 main street, MA, US 02215\"\n },\n \"legalTaxType\": \"EIN\",\n \"legalTaxNumber\": \"12-2323244443\",\n \"defaultCurrency\": \"USD\"\n }\n}\n\nThe companyId is the unique identifier of your client that you will be retaining for future references and API calls.
\nTo create a User:
\ncurl --location 'https://sand2.koverly.com/platform/v1/company/60e63207-0974-46a1-89f4-8a4098053102/user' \\\n--data '{\n \"first_name\": \"Jhon\",\n \"last_name\" : \"Smith\",\n \"email\": \"j.smith@gmail.com\",\n \"role\" : \"ADMIN\",\n \"active\": true\n}\n'\n\nIn response, you will get a user object with userId.
\nStep 2.1 - Credit Application via Koverly Platform
\nIn this step, we will initialize the user with Koverly platform and allow the user to complete a credit application within Koverly.
\nTo do this, we will call the API to get a sign-up-link:
\ncurl --location --request GET 'https://sand2.koverly.com/platform//platform/v1/company/60e63207-0974-46a1-89f4-8a4098053102/user/33455gff4334-0974-46a1-89f4-8a409804r4r4/sign-up-url\n\nThis will return a single-use URL that can be used to initiate signup to the company that was just created.
\n{\n \"success\": true,\n \"statusCode\": 0,\n \"url\": \"http:localhost:12341/invite/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpbnZpdGUiOnRydWUsImludml0ZXJFbWFpbCI6InBsYXRmb3JtQGtvdmVybHkuY29tIiwiaW52aXRlck5hbWUiOiJVbmtub3duIiwiaW52aXRlckxpbmsiOiJodHRwczovL2Rldi5rb3Zlcmx5LmNvbS9kYXNoYm9hcmQvZThjYTdmOGQtZmZmYS00MTVkLWEwYTAtOWNlZDY1ZTA0MWRhL3NldHRpbmdzL21hbmFnZV91c2VycyIsImludml0ZWRFbWFpbCI6InRlc3QtMTIzNEBrb3Zlcmx5LmNvbSIsImlkIjoiZTFjMTQ2NjMtZmI1YS00ZjRiLTllMGItZmQ0MWEwMjAzYzJlIiwiY29tcGFueUlkIjoiZThjYTdmOGQtZmZmYS00MTVkLWEwYTAtOWNlZDY1ZTA0MWRhIiwiZW1haWxUb2tlbiI6IlJhWW5xN0dRazdZbERWNVAwSkpnIiwiaWF0IjoxNjg1MTAzODc1LCJleHAiOjE2ODUxOTAyNzV9.hVe4IlMKRRsxmTrh0psU1ROsldrZfx0QIW1R21Jtkzg\"\n}\n\nUser will then go through credit application and credit line approval in the Koverly platform.
\nStep 2.2 - Credit Application via Koverly Widget
\nThis allows the user to go through the credit application and credit line approval in an embedded widget on your site.
\nTo do this, we first call the widget application to prepare endpoint with user id
\ncurl --location -g 'https://sand2.koverly.com/platform/v1/company/{companyId}/credit/application/widget/prepare \\\n--data '{\n \"userId\": \"{userid}\"\n}'\n\n{\n \"success\": true,\n \"statusCode\": 0,\n \"token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ3aWRnZXQiOnRydWUsImNvbXBhbnlJZCI6IjkwOTgyOGRmLTRhNDQtNDc5Yy1iNzliLTdiNGJiZWYwNDhjNiIsImNvbnRhY3RJZCI6IjQyY2Q3MGUxLTYwNmMtNDI0ZC05M2VkLTI5MjhjMWU0MWY0YSIsImlkIjoiY2U4ZjE5YTYtZjcwZi00MzgwLTg0ZDMtNDY4NDk2ZTFlNTQ0IiwiYmlsbHMiOlt7ImJpbGxJZCI6IjFmZGVkODU4LTBhMzgtNGZjYi04MjNiLTA3NTE3ZjI5OTAxZSJ9LHsiYmlsbElkIjoiOTk1YTNmMWMtMzliMS00N2MyLWI0MDgtMDQyNGY3NGZjYzQxIn1dLCJpYXQiOjE2OTExNjAyNDAsImV4cCI6MTY5MTE2MDU0MH0.N1kgouJWBAuv2JdX2onq9d4i1rXm3R1nLKL4z5zGsp4\"\n}\n\nThe following token can subsequently be used to bring up the UI widget that will take the user through initialization steps.
\nThe token is then passed to the KoverlyApi in Javascript to initialize the embedded widget.
\n<html>\n.....\n<script id=\"{widget-id}\" src=\"https://sand2.koverly.com/embedded.js\"></script>\n...\nkoverlyAPI.on('KOVERLY_EMBEDDED_CREDIT_APP_CLOSE', (data) => {console.log('KOVERLY_EMBEDDED_CHECKOUT_CLOSE', data)});\nkoverlyAPI.initCheckout({ sso_token: \"tokken from call above\" });\n\nStep 2.3 - Credit Application via Koverly API
\nThis option enables you to create a completely white labled solution for credit application and credit line approval via API. It can be also be used to pre-fill elements of the application.
\nIn order to do this, you will need to call the the application creation API.
\nStep 3 - Credit approval
\nKoverly aims to provide credit approvals in near-real-time. However, since this still takes a few seconds we provide two ways to obtain notification of a completed credit descision.
\n- \n
- WebHook will be fired upon completion of the credit descision. \n
- A status call can be activated on demand to poll the status of the decision. \n
In both cases, the data returned will be the same.
\n{\n \"success\": true,\n \"statusCode\": 0,\n \"status\": {\n \"status\": \"active|inactive|declined|pending\",\n \"limit\": 22222,\n \"balance\": 0.0\n }\n}\n\nStep 4 - Credit checkout
\nIn order to complete checkout using Koverly API or through the Koverly credit checkout widget, the \"Vendor\" company getting paid needs to be created and associated as a \"Vendor\" to an existing company. Following this, one or more bills to be used in the checkout process must also be created.
\nThe process for the creation of the \"Vendor\" company is the same as any other Company as described in Step 1.
\nStep 4 - Vendor Association
\nOnce the vendor company is created we need to associate it to your clients company with the call below.
\ncurl --location --request PUT 'https://sand2.koverly.com/platform/v1/company/45bb5f5b-b0fb-4821-b732-92882bed35fe/vendor/e1bc0e29-0cf7-4589-b123-eeb185aa753d' \\\n--data ''\n\nwhich will return
\n{\n \"success\": true,\n \"statusCode\": 0,\n \"vendor\": {\n \"contactOwnerId\": \"fda61c9a-3be4-480b-b30a-2f355d593843\",\n \"companyId\": \"380aee60-696b-4eea-b435-d9c9f23f4bc7\",\n \"name\": \"Partest2 company 7897897898755\",\n \"legalName\": null,\n \"address\": {\n \"address1\": \"Somehwere 12334\",\n \"address2\": null,\n \"address3\": null,\n \"town\": null,\n \"postalCode\": null,\n \"countrySubDivision\": null,\n \"country\": null,\n \"formatted\": \"Somehwere 12334\"\n },\n \"defaultCurrency\": \"USD\"\n }\n}\n\nOnce a vendor is created, one or more bills can be created using the Bill API to prepare for payment.
\nTo add a bill:
\ncurl --location -g 'https://sand2.koverly.com/platform/v1/company/45bb5f5b-b0fb-4821-b732-92882bed35fe/vendor/{{vendorId we created in prev step}}/bill' \\\n--data '{\n \"invoiceNumber\": \"123456343\",\n \"dueDate\": \"2021-12-22T05:00:00.000Z\",\n \"amount\": 12,\n \"balance\": 12,\n \"createdTime\": \"\"\n \"note\": \"Some note\",\n \"memo\": \"Some memo\",\n \"currency\": \"USD\"\n}'\n\nIn response to this call, we will return created invoice object with the id that can be referenced for future calls.
\n{\n \"success\": true,\n \"statusCode\": 0,\n \"bill\": {\n \"billId\": \"8eca3ea4-3827-4133-bd1a-7588734cc3f1\",\n \"status\": null,\n \"invoiceNumber\": \"123456343\",\n \"account\": \"1234567897897898755\",\n \"createdTime\": \"2021-12-22T05:00:00.000Z\",\n \"dueDate\": \"2021-12-22T05:00:00.000Z\",\n \"payerId\": \"7f0c72f3-f2b6-4d95-8e2b-7505a62d8c5f\",\n \"payerName\": \"Partest2 company 7897897898755\",\n \"payeeId\": \"686e39f4-acee-45ec-9b22-f17613b5f308\",\n \"payeeName\": \"Partest1 company 7897897898755\",\n \"amount\": 12,\n \"balance\": 12,\n \"isPaid\": false,\n \"note\": \"Some note\",\n \"memo\": \"Some memo\",\n \"invoiceState\": \"Open\",\n \"paymentIds\": [],\n \"payeeCanEdit\": true,\n \"payerCanEdit\": false,\n \"paidTime\": null,\n \"currency\": \"GBP\"\n }\n}\n\nStep 4.1 - Credit checkout with Koverly API
\ncurl --X POST --location -g 'https://sand2.koverly.com/platform/v1/company/{companyId}/vendor/{vendorId}/credit/loan/reservation \\\n--data '{\n \"bills\": [\n {\n \"billId\": \"74d03b21-0394-4140-bf37-42dad7e7fcf0\"\n }\n ],\n \"collectingMethodId\": \"788625669942507186122198476200016\",\n \"fundingMethodId\": \"453347897897898755\",\n \"creditOfferId\": \"25431698\"\n}'\n\nIt is optional to provide CollectingMethodId and fundingMethodId . If not provided, this will be defaulted to Customer's primary payment information and the Vendor's primary funding information stored in your application.
In return, a sucessful loan reservation will be generated, locking in an amount for the Customer's credit amount until the reservation is canceled or allocated.
\n","_postman_id":"234ce5d1-2633-4957-946d-bc2f1a30fc64","auth":{"type":"noauth","isInherited":true,"source":{"_postman_id":"4a4d9fc7-1922-418c-aad6-dd8a8ad68bff","id":"4a4d9fc7-1922-418c-aad6-dd8a8ad68bff","name":"B2B Financing","type":"folder"}}}],"id":"4a4d9fc7-1922-418c-aad6-dd8a8ad68bff","description":"Koverly’s B2B Financing solution allows you to provide flexible payment options within your existing checkout flow with credit that is underwritten and managed by Koverly.
\nBusinesses using Koverly’s B2B Financing solution will receive payment within 24 hours of checkout. Koverly assumes all credit risk - underwriting clients, conducting approvals and managing payment collections.
\nDepending on your integration needs, Koverly’s B2B Financing solution can be fully embedded into your proprietary checkout, or implemented with lighter integrations.
\nMultiple integration options allow you to offer the best user experience for your platform:
\nAPI References
\nThe following Koverly APIs are necessary to implement our B2B Financing solution:
\n- \n
- Company \n
- User \n
- Vendor \n
- Bill \n
- Embedded Finance \n
Overview
\nHigh level integrations steps.
\nStep-By-Step
\nThe first step to integration is onboarding a new client to the payment platform. This a combination of API calls to create a Company object that is populated with initial information; create a User object; and finally to initiate an invitation to the User to join the newly created company.
Once the user has being invited and goes through login setup process to get access to Koverly platform, the following will appear in your account:
\nOnce you select to activate the account, you will be guided through the activation process, which includes passing the KYC/Complaince stage to gain access to the fully activated account.
\nThe flow continues until the \"approval pending\" screen
\nOnce the User and Company have been created and completed onboarding, the API(s) can be used to:
- \n
- SSO into the account via secure link without additional log-in \n
- Create
Vendorsand `Customers` on behalf of the on-boardedCompanies\n - Add
InvoiceandBillto the platform \n - Get
Paymentinformation via status call or viaWebHook\n
Example
\nSequence Diagram for this example
\nCreate Company
\ncurl --location 'https://sand2.koverly.com/platform/v1/company' \\\n--header 'Authorization: Bearer YOUR_JWT_TOKEN' \\\n--data '{\n \"name\": \"My Importer\",\n \"legalName\": \"Import Wines Inc.\",\n \"address\": {\n \"address1\": \"100 main street\",\n \"address2\": \"\",\n \"Town\": \"Boston\",\n \"countrySubDivision\" : \"MA\",\n \"country\": \"US\",\n \"postalCode\": \"02215\"\n },\n \"legalTaxType\": \"EIN\",\n \"legalTaxNumber\": \"12-2323244443\"\n}\n\nWill return example response as a Company object.
\n{\n \"success\": true,\n \"statusCode\": 0,\n \"company\": {\n \"companyId\": \"60e63207-0974-46a1-89f4-8a4098053102\",\n \"name\": \"My Importer\",\n \"legalName\": \"Import Wines Inc.\",\n \"address\": {\n \"address1\": \"100 main street\",\n \"address2\": \"\",\n \"address3\": null,\n \"town\": null,\n \"postalCode\": \"02215\",\n \"countrySubDivision\": \"MA\",\n \"country\": \"US\",\n \"formatted\": \"100 main street, MA, US 02215\"\n },\n \"legalTaxType\": \"EIN\",\n \"legalTaxNumber\": \"12-2323244443\",\n \"defaultCurrency\": \"USD\"\n }\n}\n\nThe companyId is the unique identifier of your client that you will be retaining for future references and API calls.
\nCreate User
\ncurl --location 'https://sand2.koverly.com/platform/v1/company/60e63207-0974-46a1-89f4-8a4098053102/user' \\\n--data '{\n \"first_name\": \"Jhon\",\n \"last_name\" : \"Smith\",\n \"email\": \"j.smith@gmail.com\",\n \"role\" : \"ADMIN\",\n \"active\": true\n}\n'\n\nIn response, you will get a user object with userId.
\nOnce the user is created, you can get a sign-on-url using the following code:
\ncurl --location --request GET 'https://sand2.koverly.com/platform//platform/v1/company/60e63207-0974-46a1-89f4-8a4098053102/user/33455gff4334-0974-46a1-89f4-8a409804r4r4/sign-up-url\n\nThis will return a 1-time use URL that can be used to initiate a signup to the company that was just created.
\n{\n \"success\": true,\n \"statusCode\": 0,\n \"url\": \"http:localhost:12341/invite/eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpbnZpdGUiOnRydWUsImludml0ZXJFbWFpbCI6InBsYXRmb3JtQGtvdmVybHkuY29tIiwiaW52aXRlck5hbWUiOiJVbmtub3duIiwiaW52aXRlckxpbmsiOiJodHRwczovL2Rldi5rb3Zlcmx5LmNvbS9kYXNoYm9hcmQvZThjYTdmOGQtZmZmYS00MTVkLWEwYTAtOWNlZDY1ZTA0MWRhL3NldHRpbmdzL21hbmFnZV91c2VycyIsImludml0ZWRFbWFpbCI6InRlc3QtMTIzNEBrb3Zlcmx5LmNvbSIsImlkIjoiZTFjMTQ2NjMtZmI1YS00ZjRiLTllMGItZmQ0MWEwMjAzYzJlIiwiY29tcGFueUlkIjoiZThjYTdmOGQtZmZmYS00MTVkLWEwYTAtOWNlZDY1ZTA0MWRhIiwiZW1haWxUb2tlbiI6IlJhWW5xN0dRazdZbERWNVAwSkpnIiwiaWF0IjoxNjg1MTAzODc1LCJleHAiOjE2ODUxOTAyNzV9.hVe4IlMKRRsxmTrh0psU1ROsldrZfx0QIW1R21Jtkzg\"\n}\n\nOnce signed up, the activation process described above will take place. When this process has been completed, a fully activated account will be accessible to invited users.
\nCreating Customers
\nKoverly's AR platform provides tools for effecient collection of Customers.
The Customer companies can be created manually within the platform itself, or via API.
To create a Customer, first create a new Company object as described above for this Customer. Once the company object has been created and a new companyId for this customer has been generated, this call can be made:
curl --location -g --request PUT 'https://sand2.koverly.com/platform/v1/company/60e63207-0974-46a1-89f4-8a4098053102/customer/{customerId}'\n\n** The {customerId} is an id of the company created in the first step.
\nAfter this call, a new customer will show up in the Koverly AR section for customers.
\nCustomer Users
\nIn the situation when you need to SSO to one of our embedded UI solutions you will need to create a user record under the customer in order to pass the secure identity from your login system. In this case you might need to be able to create a User object under the customer object.
\ncurl --location 'https://sand2.koverly.com/platform/v1/company/0420c8d0-aeb8-455b-b50d-552d739893c6/customer/f0202277-1ff1-4702-bf5d-2d6bd1df580b/user' \\\n--data-raw '{\n \"firstName\": \"Mike\",\n \"lastName\" : \"MMM\",\n \"email\": \"mike+111@koverly.com\",\n \"role\": \"ADMIN\",\n \"isActive\": true\n}\n'\n\nCreating Invoice
\nAfter a customer has been created and setup has been completed, invoices can be added to thier record so that the AR process can be presented.
\nTo add an invoice we call:
\ncurl --location -g 'https://sand2.koverly.com/platform/v1/company/45bb5f5b-b0fb-4821-b732-92882bed35fe/customer/{{customerId we created in prev step}}/invoice' \\\n--data '{\n \"invoiceNumber\": \"123456343\",\n \"dueDate\": \"2021-12-22T05:00:00.000Z\",\n \"amount\": 12,\n \"balance\": 12,\n \"createdTime\": \"\"\n \"note\": \"Some note\",\n \"memo\": \"Some memo\",\n \"currency\": \"USD\"\n}'\n\nIn response to this call, we will return created invoice object with the id that can be referenced for future calls.
\n{\n \"success\": true,\n \"statusCode\": 0,\n \"invoice\": {\n \"invoiceId\": \"8eca3ea4-3827-4133-bd1a-7588734cc3f1\",\n \"status\": null,\n \"invoiceNumber\": \"123456343\",\n \"account\": \"1234567897897898755\",\n \"createdTime\": \"2021-12-22T05:00:00.000Z\",\n \"dueDate\": \"2021-12-22T05:00:00.000Z\",\n \"payerId\": \"7f0c72f3-f2b6-4d95-8e2b-7505a62d8c5f\",\n \"payerName\": \"Partest2 company 7897897898755\",\n \"payeeId\": \"686e39f4-acee-45ec-9b22-f17613b5f308\",\n \"payeeName\": \"Partest1 company 7897897898755\",\n \"amount\": 12,\n \"balance\": 12,\n \"isPaid\": false,\n \"note\": \"Some note\",\n \"memo\": \"Some memo\",\n \"invoiceState\": \"Open\",\n \"paymentIds\": [],\n \"payeeCanEdit\": true,\n \"payerCanEdit\": false,\n \"paidTime\": null,\n \"currency\": \"GBP\"\n }\n}\n\nCreating Vendors
\nVendors are created in the same way as customers. Company for vendor object is created as described above. Secondly, we need to call
curl --location --request PUT 'https://sand2.koverly.com/platform/v1/company/45bb5f5b-b0fb-4821-b732-92882bed35fe/vendor/e1bc0e29-0cf7-4589-b123-eeb185aa753d' \\\n--data ''\n\nwhich will return
\n{\n \"success\": true,\n \"statusCode\": 0,\n \"vendor\": {\n \"contactOwnerId\": \"fda61c9a-3be4-480b-b30a-2f355d593843\",\n \"companyId\": \"380aee60-696b-4eea-b435-d9c9f23f4bc7\",\n \"name\": \"Partest2 company 7897897898755\",\n \"legalName\": null,\n \"address\": {\n \"address1\": \"Somehwere 12334\",\n \"address2\": null,\n \"address3\": null,\n \"town\": null,\n \"postalCode\": null,\n \"countrySubDivision\": null,\n \"country\": null,\n \"formatted\": \"Somehwere 12334\"\n },\n \"defaultCurrency\": \"USD\"\n }\n}\n\nCheckout Widget
\nIn order to create checkout widget, we first need to create all required supporting objects.
\nStep 1 - Obtain company ID
\nPartners
\nIf the company that presents the widget is a partner and is presenting it on the customer portal on behalf of the customer (such is the case with software platforms), the first step is to create (or if already created select) a companyId to be used with the partner API requests.
Themselves
\nIf the company implements functionality for themselves the companyId in all requests is its own ID. You can find companyId in the API credentials section.
\nStep 2 - Create customers and users
\nCalling individual micro-services
\nStep 2.1
\nCreate a customer company that will be paying with presented checkout. In order to do this, we create a new company.
\ncurl --location 'https://sand2.koverly.com/platform/v1/company' \\\n--header 'Authorization: Bearer YOUR_JWT_TOKEN' \\\n--data '{\n \"name\": \"My Customer\",\n \"legalName\": \"Import Wines Inc.\",\n \"address\": {\n \"address1\": \"100 main street\",\n \"address2\": \"\",\n \"Town\": \"Boston\",\n \"countrySubDivision\" : \"MA\",\n \"country\": \"US\",\n \"postalCode\": \"02215\"\n },\n \"legalTaxType\": \"EIN\",\n \"legalTaxNumber\": \"12-2323244443\"\n}\n\nThis will create a Customer company instance.
\nSubsequently, we need to associate this company as a customer to the payee company that we selected in step 1
\n curl --location -g --request PUT 'https://sand2.koverly.com/platform/v1/company/{companyId}/customer/{customerId}'\n\nCompanyId is the Id of the company of the API caller found in API credential section.
CustomerId is id of the customer company that we created in previous call.
Step 2.2
\nIf the customer company created does not have this specific user (a user that was authenticated in the context of this flow), we need to create this user.
\ncurl --location 'https://sand2.koverly.com/platform/v1/company/{companyId}/customer/{customerId}/user' \\\n--data '{\n \"first_name\": \"Jhon\",\n \"last_name\" : \"Smith\",\n \"email\": \"j.smith@gmail.com\",\n \"role\" : \"ADMIN\"\n}\n'\n\nThe id of the user returned with this call should be retained for future payment calls at user level in the hosting application.
\nCalling a single combined endpoint
\ncurl --location -g 'https://sand2.koverly.com/platform/v1/company/{companyId}/payment/widget/prepare' \\\n--data '{\n \"customer\": {\n \"name\": \"Wine Importer 2\",\n \"legalName\": \"Import Intl Wines Inc.\",\n \"address\": {\n \"address1\": \"100 main street\",\n \"address2\": \"\",\n \"postalCode\": \"02215\",\n \"countrySubDivision\": \"MA\",\n \"country\": \"US\",\n \"formatted\": \"100 main street, MA, US 02215\"\n },\n \"legalTaxType\": \"EIN\",\n \"legalTaxNumber\": \"12-2323244441\",\n \"defaultCurrency\": \"USD\"\n },\n \"user\": {\n \"firstName\": \"m1\",\n \"lastName\": \"m22\",\n \"email\": \"mike+11@koverly.com\",\n \"role\": \"ADMIN\",\n \"isActive\": true\n }\n}'\n\nStep 3 - Add invoices
\nThe next step is to select or add all required invoices. You can add all outstanding invoices right away, or only the once you want paid now. The only requirement is that once invoices are created their ids are retained in the system somewhere, so that the same invoice does not get created multiple times.
\ncurl --location -g 'https://sand2.koverly.com/platform/v1/company/{companyId}/customer/{{customerId we created in prev step}}/invoice' \\\n--data '{\n \"invoiceNumber\": \"123456343\",\n \"dueDate\": \"2021-12-22T05:00:00.000Z\",\n \"amount\": 12,\n \"balance\": 12,\n \"note\": \"Some note\",\n \"memo\": \"Some memo\",\n \"currency\": \"USD\"\n}'\n\nStep 4 - Payment widget endpoint
\nIn this step, we will call the /../payment/widget endpoint with all of the data gathered above to get a secure token, required for widget initialization.
https://sand2.koverly.com/platform/v1/company/39389d44-e063-4967-b8ba-403cfd333f1f/customer/330c41dc-3dd7-46c6-9ae0-185511b15609/payment/widget
\ncurl --location -g 'https://sand2.koverly.com/platform/v1/company/{companyId}/customer/330c41dc-3dd7-46c6-9ae0-185511b15609/payment/widget \\\n--data '{\n \"invoices\": [\n {\n \"invoiceId\": \"f0437cc6-be8d-4a4d-bcd4-a3c9fe7503d5\"\n }\n ],\n \"userId\": \"{userid}\"\n}'\n\n{\n \"success\": true,\n \"statusCode\": 0,\n \"token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ3aWRnZXQiOnRydWUsImNvbXBhbnlJZCI6IjkwOTgyOGRmLTRhNDQtNDc5Yy1iNzliLTdiNGJiZWYwNDhjNiIsImNvbnRhY3RJZCI6IjQyY2Q3MGUxLTYwNmMtNDI0ZC05M2VkLTI5MjhjMWU0MWY0YSIsImlkIjoiY2U4ZjE5YTYtZjcwZi00MzgwLTg0ZDMtNDY4NDk2ZTFlNTQ0IiwiYmlsbHMiOlt7ImJpbGxJZCI6IjFmZGVkODU4LTBhMzgtNGZjYi04MjNiLTA3NTE3ZjI5OTAxZSJ9LHsiYmlsbElkIjoiOTk1YTNmMWMtMzliMS00N2MyLWI0MDgtMDQyNGY3NGZjYzQxIn1dLCJpYXQiOjE2OTExNjAyNDAsImV4cCI6MTY5MTE2MDU0MH0.N1kgouJWBAuv2JdX2onq9d4i1rXm3R1nLKL4z5zGsp4\"\n}\n\nStep 5 - Initialize embedded widget
\nThe token is passed into the KoverlyApi in Javascript to initialize the embedded widget
\n<html>\n.....\n<script id=\"{widget-id}\" src=\"https://sand2.koverly.com/embedded.js\"></script>\n...\nkoverlyAPI.on('KOVERLY_EMBEDDED_CHECKOUT_CLOSE', (data) => {console.log('KOVERLY_EMBEDDED_CHECKOUT_CLOSE', data)});\nkoverlyAPI.on('KOVERLY_EMBEDDED_CHECKOUT_SCHEDULE', (data) => {console.log('KOVERLY_EMBEDDED_CHECKOUT_SCHEDULE', data)});\nkoverlyAPI.initCheckout({ sso_token: \"tokken from call above\" });\n\nThe checkout widget allows for an embedded checkout experience powered by Koverly's technology.
\nIn order to put together a functional checkout widget, the following is required:
\n- \n
Web-based application with an ability to embed custom JavaScript code
\n \nAuthenticated user, whose identity can be passed, securely, to the widget
\n \nAccess to the Koverly API and API credentials to complete required calls for object creation
\n \n
Javascript Example
\n<html>\n.....\n<script id=\"{widget-id}\" src=\"https://sand2.koverly.com/embedded.js\"></script>\n...\nkoverlyAPI.on('KOVERLY_EMBEDDED_CHECKOUT_CLOSE', (data) => {console.log('KOVERLY_EMBEDDED_CHECKOUT_CLOSE', data)});\nkoverlyAPI.on('KOVERLY_EMBEDDED_CHECKOUT_SCHEDULE', (data) => {console.log('KOVERLY_EMBEDDED_CHECKOUT_SCHEDULE', data)});\nkoverlyAPI.initCheckout({ sso_token: \"SOME_TOKEN_STRING\" });\n....\n\ndata variable will contain to properties error and result
{\n \"error\": null,\n \"result\": {\n \"success\": true,\n \"payment\": {\n \"paymentId\": \"c725490a-9328-4677-8e20-c53f3ccb9348\",\n \"status\": \"paid\",\n \"paymentType\": \"ACH/ACH\"\n }\n }\n}\n\nKoverly’s B2B checkout solution allows customers to pay via ACH/bank transfer or credit card. Payments can be made in USD or foreign currency with real-time FX conversion rates built into checkout flow.
\nBusinesses in the United States may also apply for KoverlyPay financing for the option to spread payments over time.
\nThere are multiple integration options at every level:
\nAPI References
\nThe following Koverly APIs are necessary to implement our B2B Checkout solution:
\n- \n
- Company \n
- Vendors \n
- Customer \n
- Invoice \n
- Bill \n
- Method \n
- Users \n
- Payments \n
- Webhooks \n
These Koverly APIs are optional for B2B Checkout implementation:
\n- \n
- FX \n
- Embedded Finance \n
Create new company API endpoint is used to create all types of companies within Koverly business network.
\nThe endpoint accepts JSON payload with company specification and returns an initialized company object.
\nIt can be used to create:
\n- \n
- Companies \n
- Vendors \n
- Customers \n
- Partners (Coming soon) \n
Request
\nResponse
\n","auth":{"type":"jwt","jwt":{"payload":"\n\n","auth":{"type":"jwt","jwt":{"payload":"Company can be updated with this PUT request by including an id into the request.
\n
Returns company information based on company id
\n","auth":{"type":"jwt","jwt":{"payload":"Remove company. Not all companies can be removed. If a company already has associated information it can not be safely removed.
\nIf you want to remove vendor/customer from the company list use provided APIs at the relashionship level.
\n","auth":{"type":"jwt","jwt":{"payload":"Company object is used to create an operating business entity in Koverly system. Same company can play a number of roles in the monetary exchange supported by the platform. It could be the payer, payee, service provider or a partner.
\nThe address object within the Company object su structured as follows.
\n","_postman_id":"5685a695-e92d-4f44-8361-7cb6aebb0a1a","auth":{"type":"jwt","jwt":{"payload":"Get a vendor company object.
\n","auth":{"type":"jwt","jwt":{"payload":"This method adds a vendor to a company.
\n","auth":{"type":"jwt","jwt":{"payload":"Get all vendors from a specific company
\n","auth":{"type":"jwt","jwt":{"payload":"Filter vendors of said company
\n","type":"text/plain"},"key":"filter","value":null}],"variable":[]}},"response":[],"_postman_id":"3e502019-4b1f-4532-905d-920165e749af"},{"name":"/platform/{api.version}/company/{companyId}/vendor/{vendorId}","id":"b794fb28-781e-434a-afcc-6c5cfa49e7ba","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"DELETE","header":[],"url":"https://sand2.koverly.com/platform/v1/company/39389d44-e063-4967-b8ba-403cfd333f1f/vendor/add","description":"Remove a vendor from a company. This is not always safe and is allowed only if vendor does not have active transactions.
\n","auth":{"type":"jwt","jwt":{"payload":"Vendors are companies that are setup to get remittances and fund transfers.
\nTo setup a vendor use Company API to create a company and then add this company as a vendor to another. Companies can be vendors and customers in the same time.
\n","_postman_id":"27e7893f-c891-461e-aa65-f34db0af1609","auth":{"type":"jwt","jwt":{"payload":"Get a customer company object.
\n","auth":{"type":"jwt","jwt":{"payload":"Get a customer company object.
\n","auth":{"type":"jwt","jwt":{"payload":"Get a customer company object.
\n","auth":{"type":"jwt","jwt":{"payload":"Get a customer company object.
\n","auth":{"type":"jwt","jwt":{"payload":"When using payment widget or other embedded functions and need to create user to pass identity information from your context a user under specific customer of the company can be created.
\n","_postman_id":"b6c6cb5f-2dc2-4feb-bf1b-4144fcffd705","auth":{"type":"jwt","jwt":{"payload":"Get a vendor company object.
\n","auth":{"type":"jwt","jwt":{"payload":"Add a customer to a company record.
\n","auth":{"type":"jwt","jwt":{"payload":"Publish statment dashboard for payment.
\n","auth":{"type":"jwt","jwt":{"payload":"Add a customer to a company record.
\n","auth":{"type":"jwt","jwt":{"payload":"Get all vendors from a specific company
\n","auth":{"type":"jwt","jwt":{"payload":"Filter customer query
\n","type":"text/plain"},"key":"filter","value":null}],"variable":[]}},"response":[],"_postman_id":"473a5722-8332-4a9e-8aa7-0fc52f698330"},{"name":"/platform/{api.version}/company/{companyId}/customer/{customerId}","id":"cb068afa-c44b-4421-949f-dca9454dbb33","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"DELETE","header":[],"url":"https://sand2.koverly.com/platform/v1/company/39389d44-e063-4967-b8ba-403cfd333f1f/customer/{customerId}","description":"Remove a customer from a company. This is not always safe and is allowed only if vendor does not have active transactions.
\n","auth":{"type":"jwt","jwt":{"payload":"Customers are companies that are setup to get statements and invoices
\nTo setup a customer use Company API to create a company and then add this company as a customer to another.
\nCompanies can be vendors and customers in the same time.
\n","_postman_id":"de72556b-15c6-4b21-b8f3-84e3dd8535c9","auth":{"type":"jwt","jwt":{"payload":"Get a vendor company object.
\nResponse Example
\n{\n \"success\": true,\n \"statusCode\": 0,\n \"invoice\": {\n \"invoiceId\": \"51e7492a-332a-481c-9eea-6c4ff4a8b1c0\",\n \"invoiceNumber\": \"123456343\",\n \"createdTime\": \"2021-12-22T05:00:00.000Z\",\n \"dueDate\": \"2021-12-22T05:00:00.000Z\",\n \"payerId\": \"316534da-43ea-4ccf-98d2-7f9e6a4d868f\",\n \"payerName\": \"Partest2 company 7897897898755\",\n \"payeeId\": \"b4506a89-5914-4b4e-8027-4efe212bfb10\",\n \"payeeName\": \"Partest1 company 7897897898755\",\n \"amount\": 12,\n \"balance\": 12,\n \"isPaid\": false,\n \"note\": \"Some note\",\n \"memo\": \"Some memo\",\n \"invoiceState\": \"Open\",\n \"paidTime\": null,\n \"currency\": \"GBP\"\n }\n}\n\nCreate new invoice.
\nResponse Example
\n{\n \"success\": true,\n \"statusCode\": 0,\n \"invoice\": {\n \"invoiceId\": \"51e7492a-332a-481c-9eea-6c4ff4a8b1c0\",\n \"invoiceNumber\": \"123456343\",\n \"createdTime\": \"2021-12-22T05:00:00.000Z\",\n \"dueDate\": \"2021-12-22T05:00:00.000Z\",\n \"payerId\": \"316534da-43ea-4ccf-98d2-7f9e6a4d868f\",\n \"payerName\": \"Partest2 company 7897897898755\",\n \"payeeId\": \"b4506a89-5914-4b4e-8027-4efe212bfb10\",\n \"payeeName\": \"Partest1 company 7897897898755\",\n \"amount\": 12,\n \"balance\": 12,\n \"isPaid\": false,\n \"note\": \"Some note\",\n \"memo\": \"Some memo\",\n \"invoiceState\": \"Open\",\n \"paidTime\": null,\n \"currency\": \"GBP\"\n }\n}\n\nAdd a company to be a customer for another company.
\n","auth":{"type":"jwt","jwt":{"payload":"Filter to query
\n","type":"text/plain"},"key":"filter","value":null}],"variable":[]}},"response":[],"_postman_id":"9616e85a-6423-411f-b60f-fcaef44b3b47"},{"name":"/platform/{api.version}/company/{companyId}/invoice/search","id":"31191ac3-6c1e-4937-98c3-327785ffff83","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[],"body":{"mode":"raw","raw":"{\n \"amount\": 1000.00,\n \"currency\": \"EUR\",\n \"dueDate\": \"10/10/2023\",\n \"createdTime\": \"10/10/2023\",\n \"state\": \"Open\"\n}\n","options":{"raw":{"language":"json"}}},"url":"https://sand2.koverly.com/platform/v1/company/39389d44-e063-4967-b8ba-403cfd333f1f/invoice/search","description":"Add a company to be a customer for another company.
\n","auth":{"type":"jwt","jwt":{"payload":"Filter to query
\n","type":"text/plain"},"key":"filter","value":null}],"variable":[]}},"response":[],"_postman_id":"31191ac3-6c1e-4937-98c3-327785ffff83"},{"name":"/platform/{api.version}/company/{companyId}/customer/{customerId}/invoice/{invoiceId}","id":"6b41fc5d-ac9e-489d-88e9-c05842714e03","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"PATCH","header":[],"body":{"mode":"raw","raw":"{\n \"amount\": 1000.00,\n \"currency\": \"EUR\",\n \"dueDate\": \"10/10/2023\",\n \"createdTime\": \"10/10/2023\",\n \"state\": \"Open\"\n}\n","options":{"raw":{"language":"json"}}},"url":"https://sand2.koverly.com/platform/v1/company/39389d44-e063-4967-b8ba-403cfd333f1f/customer/330c41dc-3dd7-46c6-9ae0-185511b15609/invoice/{{invoiceId}}","description":"Add a company to be a customer for another company.
\n","auth":{"type":"jwt","jwt":{"payload":"Remove a customer from a company. This is not always safe and is allowed only if vendor does not have active transactions.
\n","auth":{"type":"jwt","jwt":{"payload":"Invoice
\nInvoice is request for payment presented between the company and its customer. The following fields are part of invoice object
\n","_postman_id":"cd96b30b-e1a7-4b87-88b6-6cd305d06a9b","auth":{"type":"jwt","jwt":{"payload":"Get a vendor company object.
\nResponse Example
\n{\n \"success\": true,\n \"statusCode\": 0,\n \"invoice\": {\n \"invoiceId\": \"51e7492a-332a-481c-9eea-6c4ff4a8b1c0\",\n \"invoiceNumber\": \"123456343\",\n \"createdTime\": \"2021-12-22T05:00:00.000Z\",\n \"dueDate\": \"2021-12-22T05:00:00.000Z\",\n \"payerId\": \"316534da-43ea-4ccf-98d2-7f9e6a4d868f\",\n \"payerName\": \"Partest2 company 7897897898755\",\n \"payeeId\": \"b4506a89-5914-4b4e-8027-4efe212bfb10\",\n \"payeeName\": \"Partest1 company 7897897898755\",\n \"amount\": 12,\n \"balance\": 12,\n \"isPaid\": false,\n \"note\": \"Some note\",\n \"memo\": \"Some memo\",\n \"invoiceState\": \"Open\",\n \"paidTime\": null,\n \"currency\": \"GBP\"\n }\n}\nAdd a company to be a customer for another company.
\n","auth":{"type":"jwt","jwt":{"payload":"Add a company to be a customer for another company.
\n","auth":{"type":"jwt","jwt":{"payload":"Get all vendors from a specific company
\n","auth":{"type":"jwt","jwt":{"payload":"Filter expression
\n","type":"text/plain"},"key":"filter","value":null}],"variable":[]}},"response":[],"_postman_id":"810e3edf-4308-4881-aba5-c11a5da21325"},{"name":"/platform/{api.version}/company/{companyId}/bill/search","id":"8ff99b28-59c2-4853-86b0-e61c7415a867","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"body":{"mode":"raw","raw":"{\n \"name\": \"Company name\",\n \"legal_name\": \"Company legal name\",\n \"address\": {\n \"address1\": \"address lini 1\",\n \"address2\": \"address lini 2\",\n \"Town\": \"The town company is located at\",\n \"ctrySubDivision\" : \"In US its State\",\n \"country\": \"2-character ISO Country code\",\n \"postalCode\": \"Postal Code\"\n },\n \"legal_id\": \"EIN or equivalent\",\n \"signup_link\" : \".... this link can be used to sugnup uninitialized company...\"\n}\n","options":{"raw":{"language":"json"}}},"url":"https://sand2.koverly.com/platform/v1/company/39389d44-e063-4967-b8ba-403cfd333f1f/bill/search?filter","description":"Get all vendors from a specific company
\n","auth":{"type":"jwt","jwt":{"payload":"