Tabeo - API

Tabeo offers a synchronous API for third-party integrations. For fulfilment purposes, offers may be polled at certain intervals to observe status changes. These endpoints may be used to integrate Tabeo with a variety of shop and cart systems.

Release Notes

Fulfillment's reference is now required for some merchants (please confirm with your account manager).

Offer creation

Endpoint to create a new Pay Over Time (finance) or Pay Now (card payments) offer.

POST endpoint

https://demo.api.tabeo.co.uk/v1/merchant/integration-offers

Parameters

consumerFirstName: StringRequired
consumerLastName: StringRequired
consumerEmail: StringRequired
consumerPhoneNumber: StringOptional
title: StringRequired
Title for offer to be shown on the Tabeo interface, e.g.. 'Invisible Retainers’
currency: StringRequired
This should match your account’s currency, e.g. ‘gbp’ for a UK account, or ‘eur’ for a Netherlands account.
price: IntegerRequired
This is the net price, net of any discounts, inclusive of any taxes, in pence
type: Enum: pay_over_time, pay_nowDefault: pay_over_timeOptional
initialPaymentPlanOptions: Array of numbersRequiredNew
Required only for type = 'pay_over_time'. An array of the tenors to be presented to the customer; e.g. [3,6,12] or [6].
externalMetadata: { [key: string]: string; }Optional
A json object of up to ten metadata fields that you can use to store information for your own needs, such as GUID, invoiceID, internalIDs, etc
skipInitialPaymentOptionsEmail: BooleanDefault: falseOptional
If true, Tabeo will not send it's usual initial email to the consumer showing the offer and related loan options. This may be desired if a client will trigger their own email or website notification for the customer.
individual: {"name": string, "type": string}Default: nullOptionalNew
Available only for type = 'pay_over_time'. Used for storing additional names. For “type” field, currently only type “clinician” is supported. E.g. {"name": "john doe", "type": "clinician"}
fulfillment: {"startedAt": date}Default: nullOptionalNew
Available only for type = 'pay_over_time'. Used to indicate time of service fulfilment/delivery. Past, present or future dates are supported. Reference required for some merchants (please confirm with your account manager). E.g. {"startedAt": "2020-02-25T14:23:47Z", "reference":"REFERENCE_001"}

The endpoint will respond with an offer object json. This will contain all pertinent information relating to the offer.

Example Request: Pay over time

curl -X POST   https://demo.api.tabeo.co.uk/v1/merchant/integration-offers \
  -H 'Authorization: Bearer [AUTHORIZATION TOKEN]’ \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
        "consumerFirstName": "Foo",
        "consumerLastName": "Bar",
        "price": 120000,
        "consumerPhoneNumber": "07511223131",
        "consumerEmail": "[email protected]",
        "title": "Bridge",
        "currency": "gbp",
        "initialPaymentPlanOptions": [12,24],
        "externalMetadata": {"guid":33983,"id":"TyaJHGA-1736"},
        "individual": {"name": "Dr. Foo Bar", "type": "clinician"},
        "fulfillment": {"startedAt": "2020-02-25T14:23:47Z", "reference": "REFERENCE_001"}
}

Example Response: Pay over time

{
   "data":{
      "offer":{
         "bankAccountAttempts":0,
         "bankAccountID":null,
         "bankAccountLastMissingMandateReminderSentAt":null,
         "bankAccountRemovedAt":null,
         "buyerCode":null,
         "consumerEmail":"[email protected]",
         "consumerFirstName":"Foo",
         "consumerGender":null,
         "consumerID":null,
         "consumerLastName":"Bar",
         "consumerMiddleName":null,
         "consumerPhoneNumber":"07511223131",
         "countryCode":"gb",
         "createdAt":"2021-04-29T12:07:09.033542385Z",
         "currency":"gbp",
         "expiresAt":"2021-05-06T12:07:09.026043746Z",
         "feeAmount":null,
         "hardCheckStatus":null,
         "id":10012,
         "individualID":null,
         "lastStateTransitionedAt":"2021-04-29T12:07:09.02606363Z",
         "legacyOfferID":null,
         "loanAgreementID":null,
         "loanID":null,
         "merchantID":24,
         "merchantLateRefundFeeAmountToDate":null,
         "merchantNetProceedsTransfers":[
            
         ],
         "merchantPayoutAt":null,
         "merchantProceedsTransferredAt":null,
         "metadata":{
            "autoConfirmation":false,
            "externalMetadata":{
               "guid":33983,
               "id":"TyaJHGA-1736"
            },
            "overviewShortLink":"https://demo.m.tabeo.co.uk/r/WguHd",
            "patientName":"Foo Bar",
            "publicShortLink":"https://demo.m.tabeo.co.uk/r/UWEWd",
            "riskProfiles":[
               {
                  "order":0,
                  "name":"default",
                  "lenderCode":null,
                  "loanOptions":[
                     {
                        "numberOfMonths":6,
                        "interestRate":0,
                        "rebateDays":0,
                        "isRegulated":false,
                        "isAvailableForInitialPaymentPlan":false
                     },
                     {
                        "numberOfMonths":10,
                        "interestRate":0,
                        "rebateDays":0,
                        "isRegulated":false,
                        "isAvailableForInitialPaymentPlan":false
                     },
                     {
                        "numberOfMonths":12,
                        "interestRate":0,
                        "rebateDays":0,
                        "isRegulated":false,
                        "isAvailableForInitialPaymentPlan":true
                     },
                     {
                        "numberOfMonths":24,
                        "interestRate":0,
                        "rebateDays":0,
                        "isRegulated":false,
                        "isAvailableForInitialPaymentPlan":true
                     }
                  ],
                  "fundingType":"default"
               }
            ]
         },
         "numberOfPaymentDayChanges":0,
         "paymentAuthorization":null,
         "paymentGateway":"",
         "paymentSourceAttempts":0,
         "paymentSourceID":null,
         "payoutGateway":"stripe_connect",
         "price":120000,
         "publicAccessToken":"BSwJknFCJBormUIxbNbiioeqoMtHidBQkzjoyskcpTHphoxdlJvribiEIggESpCo",
         "reference":null,
         "referralID":null,
         "revisedPrice":null,
         "revisedRequiredMerchantFeeAmount":null,
         "revisedValueAtRisk":null,
         "status":"new",
         "title":"Bridge",
         "totalMerchantRefundAmountToDate":null,
         "type":"pay_over_time",
         "updatedAt":"2021-04-29T12:07:09.038352658Z",
         "uuid":"32cea5de-beb2-55ae-ad18-151fa2059709",
         "valueAtRisk":null
      }
   },
   "status":"success",
   "type":"response_ready"
}

Example Request: Pay now

curl -X POST   https://demo.api.tabeo.co.uk/v1/merchant/integration-offers \
  -H 'Authorization: Bearer [AUTHORIZATION TOKEN]’ \
  -H 'Content-Type: application/json' \
  -H 'cache-control: no-cache' \
  -d '{
        "consumerFirstName": "Foo",
        "consumerLastName": "Bar",
        "price": 120000,
        "consumerPhoneNumber": "07511223131",
        "consumerEmail": "[email protected]",
        "title": "Bridge",
        "currency": "gbp",
        "externalMetadata": {"guid":33983,"id":"TyaJHGA-1736"},
        "type": "pay_now"
}

Example Response: Pay now

{
   "data":{
      "offer":{
         "bankAccountAttempts":0,
         "bankAccountID":null,
         "bankAccountLastMissingMandateReminderSentAt":null,
         "bankAccountRemovedAt":null,
         "buyerCode":null,
         "consumerEmail":"[email protected]",
         "consumerFirstName":"Foo",
         "consumerGender":null,
         "consumerID":null,
         "consumerLastName":"Bar",
         "consumerMiddleName":null,
         "consumerPhoneNumber":"07511223131",
         "countryCode":"gb",
         "createdAt":"2021-04-29T12:22:35.186240533Z",
         "currency":"gbp",
         "expiresAt":"2021-05-06T12:22:35.178949336Z",
         "feeAmount":null,
         "hardCheckStatus":null,
         "id":10017,
         "individualID":null,
         "lastStateTransitionedAt":"2021-04-29T12:22:35.17896482Z",
         "legacyOfferID":null,
         "loanAgreementID":null,
         "loanID":null,
         "merchantID":24,
         "merchantLateRefundFeeAmountToDate":null,
         "merchantNetProceedsTransfers":[
            
         ],
         "merchantPayoutAt":null,
         "merchantProceedsTransferredAt":null,
         "metadata":{
            "autoConfirmation":false,
            "externalMetadata":{
               "guid":33983,
               "id":"TyaJHGA-1736"
            },
            "overviewShortLink":"https://demo.m.tabeo.co.uk/r/yzpvj",
            "patientName":"Foo Bar",
            "publicShortLink":"https://demo.m.tabeo.co.uk/r/iZtGC"
         },
         "numberOfPaymentDayChanges":0,
         "paymentAuthorization":null,
         "paymentGateway":"",
         "paymentSourceAttempts":0,
         "paymentSourceID":null,
         "payoutGateway":"stripe_connect",
         "price":120000,
         "publicAccessToken":"DzEzHsINbMtCPfQxdsJAXjcKqpjXsDkqVOCJZYbiYShthiYRwaxaRsCsKHEuSZSu",
         "reference":null,
         "referralID":null,
         "revisedPrice":null,
         "revisedRequiredMerchantFeeAmount":null,
         "revisedValueAtRisk":null,
         "status":"new",
         "title":"Bridge",
         "totalMerchantRefundAmountToDate":null,
         "type":"pay_now",
         "updatedAt":"2021-04-29T12:22:35.189771916Z",
         "uuid":"7575cb49-e10c-55ae-8ade-dac53694ce69",
         "valueAtRisk":null
      }
   },
   "status":"success",
   "type":"response_ready"
}

Retrieving an existing offer

GET endpoint

https://demo.api.tabeo.co.uk/v1/merchant/offers/:offerid

Example Request

curl -X GET \
https://demo.api.tabeo.co.uk/v1/merchant/offers/:offerid \
-H 'Authorization: Bearer [AUTHORIZATION TOKEN]' \
-H 'Content-Type: application/json' \
-H 'cache-control: no-cache'

In most cases, you will want to get subresources for an offer.

Subresources include: metdata, individual (e.g. clinician's name) and simplified statuses on the offer's current state.

For example, to check whether an offer has been paid successfully, the sub resource simplifiedStatus should be used.

A more thorough call that retrieves an offer object with its simplifiedStatus and metaData sub resources would be:

curl -X GET \
https://demo.api.tabeo.co.uk/v1/merchant/offers/:offerid?subResource=simplifiedStatus&subResource=metaData \
-H 'Authorization: Bearer [AUTHORIZATION TOKEN]' \
-H 'Content-Type: application/json' \
-H 'cache-control: no-cache'

For descriptions of simplifiedStatus, please see Offer object simplifiedStatus states below.

Retrieving a collection of offers with simplifiedStatus and paging constraints

A GET endpoint

https://demo.api.tabeo.co.uk/v1/merchant/offers

Example Requests

To retrieve up to 6 offers with any of the following statuses: applying, loan_offer_made, funds_on_way].

curl -X GET \
'https://demo.api.tabeo.co.uk/v1/merchant/offers?order=updatedAt:desc&condition=simplifiedStatus:[applying,loan_offer_made,funds_on_way]&limit=6&offset=0' \
-H 'Authorization: Bearer [AUTHORIZATION TOKEN]'

Without any status constraints and up to 100 offers ordered by updatedAt field:

curl -X GET \
'https://demo.api.tabeo.co.uk/v1/merchant/offers?order=updatedAt:desc&limit=100&offset=0' \
-H 'Authorization: Bearer [AUTHORIZATION TOKEN]'

If you want to limit it to say only ones with simplifiedStatus: 'settled', then you'd do something like this:

curl -X GET \
'https://demo.api.tabeo.co.uk/v1/merchant/offers?condition=simplifiedStatus:[settled]&order=updatedAt:desc&limit=100&offset=0' \
-H 'Authorization: Bearer [AUTHORIZATION TOKEN]'

Getting referred offers

Some offers may be transferred to another applicant in the case of the initial applicant failing checks. Such offers are identifiable with simplifiedStatus: 'transferred'.

A GET endpoint

https://api.tabeo.co.uk/v1/merchant/offers/:offerid?subResource=transferredOffer

Example Requests

When getting the offer, a transferredOffer sub resource may be applied on the old offer to get a sub resource with the new offer:

curl -X GET \
'https://api.tabeo.co.uk/v1/merchant/offers/28599?subResource=transferredOffer' \
-H 'Authorization: Bearer [AUTHORIZATION TOKEN]'

This will get transferredOffer id of 28756

You can then GET the new offer with id 28756 and monitor its status .

If required, legacyOffer sub resource id may be used on the new offer to get a sub resource with the old/legacy offer:

curl -X GET \
'https://api.tabeo.co.uk/v1/merchant/offers/28756?subResource=legacyOffer' \
-H 'Authorization: Bearer [AUTHORIZATION TOKEN]'

This will get a legacyOffer id of 28599.

Offer object simplifiedStatus states

The following is the currently specified list of possible simplifiedStatus states for the offer object.

sent: offer sent to consumer
opened: offer opened by consumer
applying: consumer is undergoing offer application
loan_offer_made: the final decision and offer for the customer is presented
payment_error: verifying consumer's payment source failed (e.g. debit card, direct debit, etc)
pending_release: consumer accepted our loan agreement and awaiting first payment for pay over time, or full payment for pay now
release_error: payment failed
contact_support: error condition on offer
loan_started: first payment for pay over time made and the loan is now active
fulfillment_required: offer requires fulfillment (see below: Fufillment creation and update)
funds_on_way: merchant proceeds funds from offer are on way
settled: merchant funds are now fully paid out
transferred: consumer opted to transfer offer
canceled: offer canceled
failed: offer expired or did not pass risk and ID checks

Create fulfillment

For some merchants (please confirm with your account manager), a fulfillment is required before merchant proceeds from an offer are transferred for pay out to your bank account. Once a fulfillment is created using this endpoint, Tabeo will automatically schedule the transfer for the date specified for fulfillment.

POST endpoint

https://demo.api.tabeo.co.uk/v1/merchant/offers/:offerid/integration-fulfillment

Parameters

startedAt: DateRequired
The fulfillment date. If the date is in the past, then merchant offer proceeds are scheduled for immediate transfer for pay out to your bank account.
reference: String
Your reference, such as tracking number or invoice ID. Required for some merchants (please confirm with your account manager)

Example Request: Create fulfillment

curl -X POST https://demo.api.tabeo.co.uk/v1/merchant/offers/:offerid/integration-fulfillment \
          -H 'Authorization: Bearer [AUTHORIZATION TOKEN]’ \
          -H 'Content-Type: application/json' \
          -H 'cache-control: no-cache' \
          -d '{
            "startedAt": "2021-05-25T14:23:47Z",
            "reference": "INV2101"
            }

Example Response: Create fulfillment

{
   "data":{
      "fulfillment":{
         "createdAt":"2021-04-30T09:05:55.814665Z",
         "deletedAt":null,
         "id":10001,
         "reference":"INV2101",
         "startedAt":"2020-02-25T14:23:47Z",
         "updatedAt":"2021-04-30T09:05:55.814665Z",
         "uuid":"03b47184-f0e8-5432-a6ee-fcfb42db7023"
      }
   },
   "status":"success",
   "type":"response_ready"
}

Fulfillment update

Endpoint to update the fulfillment date of an offer. This is only applicable if your merchant account requires it.

PUT endpoint

https://demo.api.tabeo.co.uk/v1/merchant/offers/:offerid/integration-fulfillment

Parameters

startedAt: DateRequired
The fulfillment date. If the date is in the past, then merchant offer proceeds are scheduled for immediate transfer for pay out to your bank account.
reference: String
Your reference, such as tracking number or invoice ID. Required for some merchants (please confirm with your account manager)

Example Request: Update fulfillment

curl -X PUT https://demo.api.tabeo.co.uk/v1/merchant/offers/:offerid/integration-fulfillment \
          -H 'Authorization: Bearer [AUTHORIZATION TOKEN]’ \
          -H 'Content-Type: application/json' \
          -H 'cache-control: no-cache' \
          -d '{
            "startedAt": "2021-05-25T14:23:47Z",
            "reference": "D2102"
            }

Example Response: Update fulfillment

{
   "data":{
    "data":{
       "fulfillment":{
          "createdAt":"2021-04-30T13:37:17.829289Z",
          "deletedAt":null,
          "id":10001,
          "reference":"D2102",
          "startedAt":"2022-02-25T14:23:47Z",
          "updatedAt":"2021-04-30T13:37:27.132545Z",
          "uuid":"38750b11-ef52-57fb-b69e-d45d7d2f3048"
       }
    },
    "status":"success",
    "type":"response_ready"
 }

LatestAPI documentation (v1.3)

Release Notes

Offer creation

Parameters

Example Request: Pay over time

Example Response: Pay over time

Example Request: Pay now

Example Response: Pay now

Retrieving an existing offer

Example Request

Retrieving a collection of offers with simplifiedStatus and paging constraints

Example Requests

Getting referred offers

Example Requests

Offer object simplifiedStatus states

Create fulfillment

Parameters

Example Request: Create fulfillment

Example Response: Create fulfillment

Fulfillment update

Parameters

Example Request: Update fulfillment

Example Response: Update fulfillment