Get Started with Terms.Tech

Introduction

Our Buy Now, Pay Later payment solution for B2B marketplaces and ecommerce merchants offers a flexible, secure and convenient way for the buyers to pay for the purchases,  while providing sellers with a faster access to cash. It has been developed using a modular approach and offers payment terms of  up to 90 days, recurring payments and more.

In addition to funding your BNPL transactions, at Terms.Tech, we manage all payment and credit risks associated with transactions and also monitor and protect your customers against fraud risk. 

Our REST APIs use HTTP response codes for API errors andexpect incoming data to be valid JSON objects with requests containing the header Content-Type: application/json. 

All REST API responses, including errors, are in JSON.

All documentation needed to implement our solution on your platform is available here.

Account Management

Marketplace Account

Once you have entered into a contract with us, we will create your account in our merchant portal. You will receive a login ID and password to access your account. 

You will use the portal to view your: 

  1. Your performance
  2. Current and past transactions
  3. Your customer account details
  4. Invoices

Customers Account

A successfully created account is required for all your customers (buyers and sellers) entering into a BNPL transaction. To complete the registration and use our ‘Pay with Terms’ BNPL service, EU law requires that all your new and existing customers successfully pass the Know Your Business (KYB) and AML verification process.

To find out more about the legally mandated KYB review, please go to https://docs.digiteal.eu/technical/index.html#company_pre_registration

Order Management

To be able to pay for an order using our deferred payment method the following three (3) requirements must be met:  

  1. The buyer has successfully registered their business (see Customers Account)
  2. If the seller has not yet registered their business, they have 48 hours after order creation to start the  registration and accept the terms and conditions. If the registration process does not start within 48 hours, it will be cancelled unless stated otherwise in the BNPL contract between the buyer and the marketplace.
  3. The buyer has sufficient credit to cover the order amount.

Credit Limit

Credit Limit Calculation

To evaluate a buyer’s financial viability and assign appropriate credit limit, we [TERMS] utilise a proprietary, custom built algorithm. The algorithm incorporates data from:

  •  3rd party providers
  •  customers’ onboarding 
  •  your marketplace 

Credit Limit Assignment

Credit Limits are assigned based on customer history and diverse data sources. Our systems regularly recalculates the limits using newly available information. The most accurate limits are generated when we regularly receive update information from your on your customer’s payment history.

Displaying Credit Limit

When we generate your customer account, we assign a credit limit that is visible to you  by calling the designated webhook.

So, when should you use GET /companies/{countryISO}-{nationalID}/credit-limit and show your customers their credit limit?

  • on your checkout page: display the option to pay with BNPL if the Credit Limit = > Order Amount;
  • on the customer’s account information or settings page;
  • on marketing banners to show the credit available to your customers after they have securely logged in;
  • in marketing emails;

Order Lifecycle

Order States

StatusDescription
ApprovedThe order was successfully approved and TERMS can extend the financing for this transaction.
DeclinedThe order was declined as the buyer failed eligibility check. No financing can be extended for this transaction.
Review PendingThe order documents (invoice and proof of delivery) are awaiting manual review by a TERMS officer.
CancelledThe order was cancelled (by the buyer or TERMS)
Under InvestigationUploaded order documents (invoice & proof of delivery) are incomplete or incorrect. The merchant or seller is requested to validate them.
Paid outPSP has been instructed to transfer the cash advance and the marketplace fee.
Payment OverdueBuyer has not paid on time the outstanding amount or buyer requested a refund after the SEPA DD execution.
SettledBuyer has successfully paid back the outstanding amount.
CompletedTransaction has been closed (final status)

Error Reason Codes

Buyer’s Order Error Reason Codes

Error Reason CodeDescription
104Seller is not active
105Buyer is not active
120Order amount is higher than the maximum transaction amount for the current marketplace
121Order amount is higher than the current marketplace available funds
137The list of seller order is empty or the buyer and seller have the same UBO (Universal Beneficiary Owner)
140Buyer cannot be found
140Seller or one of the sellers cannot be found
151Buyer has overdue orders
152A seller or sellers are not onboarded successfully and onboarding is mandatory.
194Reference length is more than 250 characters
201Authorisation failed
214Total amount of any order is less or equal to zero (0)
218One of the sellers is the same as buyer
219Buyer has insufficient credit coverage
222Marketplace cannot be found
223Invalid parameter: TERMS product type is invalid

Seller’s Order Error Reason Codes

Error Reason CodeDescription
131Order not found
135New order amount is higher than initial order amount
137Order amount or marketplace fees amount is the same as the old one (if different from 0)
201Authorisation failed
214Marketplace fee amount should be greater or equal to zero (0).
214Seller amount must be greater or equal
201Authorization failed

Order Handling

Create Order

Marketplaces often support transactions based on ‘one-to-many’ relationships, which means one (1) buyer can buy from several sellers.

Use the /buyer-orders API to submit the contents of the transaction, split per seller. We require one unique buyer’s order reference, usually generated by your systems and known to the buyer,  seller’s order reference  for each seller and the total order amount, including any taxes, processing and shipping fees.

The service will return a redirect URL to our Buyer Product Agreement that buyers must sign for each Terms.Tech transaction to benefit from paying with payment terms.

Run Eligibility Check

We run an automatic eligibility check on each buyer’s order received from your marketplace. The result of the credit verification will determine if we accept your buyer and offer them the payment terms or not.

Upload Order Documents

You and your sellers are paid upon shipment, that is, after we received and validated order documents (invoice and proof of delivery).

Use  POST /seller-orders/{sellerOrderReference}-{DocumentType}-{DocumentName}/document to submit the  delivery proof and seller’s final invoice to Terms.Tech.

Update Order

Order can be updated if not all items are available for delivery using PUT /seller-orders/{sellerOrderReference}

Cancel Order

Refunds

Marketplace must notify Terms.Tech about any order or individual items from an order being returned by the customer after the shipment.

Terms.Tech supports both full and partial refunds. Please note that the total amount of all refunds cannot exceed captured amounts.

Full Refund

In case of full refund, the seller is requested to pay back the captured amount.

Partial refund

In case of partial refund,  the seller is requested to pay back the amount corresponding to the amount for the returned line items.

Integration via API

Authentication API

OAUTH2 API Swagger Documentation

[ Base URL: /CredendoOAUTH2Provider/rest/OAuth ]
https://credendo-dev.outsystemsenterprise.com/CredendoOAUTH2Provider/rest/OAuth/swagger.json

Web service to obtain a token based on client credentials.

Basic Authentication is required for all requests.

GET

ATTRIBUTES

client_id

string

REQUIRED

The ClientID as received from the PCI API administrator.

client_secret

string

REQUIRED

The Client Secret key associated to the ClientID – as received from the PCI API administrator.

MODELS

GetTokenResponse{

Response sent by the GetToken service.

access_token

string

default: The token value itself. Needs to be passed in an authentication header of type “Bearer Token” to PCI API web services.

expires_in

integer ($int32)

default: The token validity in seconds

token_type

string

default: The type of token (always “Bearer”)

error

string

default: Short error text.

error_description

string

default: Detailed description of the error.

}

POST

/GetToken

json

{
  "access_token": "string",
  "expires_in": 0,
  "token_type": "string",
  "error": "string",
  "error_description": "string"
}

RESPONSE

{
  "access_token": "string",
  "expires_in": 0,
  "token_type": "string",
  "error": "string",
  "error_description": "string"
}

Customers API

Customers API Swagger Documentation

[ Base URL: /terms42api/rest/customers ]
https://credendo-dev.outsystemsenterprise.com/terms42api/rest/customers/swagger.json

GET

Use this service to get the credit score and available Terms.Tech limit of any company (even not registrerd with Terms.Tech). Uses CreditSafe to identify the company and Credendo processing to get the Terms.Tech limit. This service can be used by marketplaces to promote Terms.Tech to users in case the current transaction would qualify for TERMS (TotalAmount < Limit). This service needs the email address of the company – used to provide the onboarding wizard deep link in case the company is not onboarded. The onboarding link can be used by the marketplace to create a button for their customers to start onboarding with TERMS and have pre-filled info in the onboarding wizard.

Return codes:

HTTP 200:

OK.

HTTP 400:

197 - if the countryISO is invalid;
223 - if the NationalID or CountryISO is empty

HTTP 401:

201 - If the authorization fails

HTTP 404:

140 - if the company was not found;

ATTRIBUTES

countryISO

string

REQUIRED

nationalID

string

REQUIRED

POST

json

/companies/{countryISO}-{nationalID}/credit-limit

{
  "CompanyResponse": {
    "Name": "string",
    "VAT": "string",
    "NationalId": "string",
    "Address": {
      "simpleValue": "string",
      "street": "string",
      "city": "string",
      "postCode": "string",
      "houseNo": "string",
      "postalCode": "string",
      "country": "string",
      "houseNumber": "string"
    },
    "Status": "string",
    "SafeNo": "string",
    "TradingNames": [
      "string"
    ],
    "OfficeType": "string",
    "ConnectId": "string"
  },
  "LimitData": {
    "Rating": "string",
    "FinalLimitAmount": 0.1,
    "AvailableLimitAmount": 0.1
  },
  "isActive": false,
  "OnboardingStatus": "string",
  "canHaveTerms": false,
  "HTTPStatus": {
    "HTTPCode": 1234567891234567,
    "developerMessage": "string",
    "userMessage": "string",
    "errorCode": "string",
    "moreInfo": "string"
  }
}
PUT

Sets the email address to be used when communicating with this company.

ATTRIBUTES

countryISO

string

REQUIRED

nationalID

string

REQUIRED

email

string

REQUIRED

POST

json

/companies/{countryISO}-{nationalID}/email

string
PUT

Sets the preferred communication language for the current company. The company must already exist in the database. If the preferred language is not set the system defaults to the language set on the marketplace.

ATTRIBUTES

countryISO

string

REQUIRED

nationalID

string

REQUIRED

LanguageISO2

string

REQUIRED

POST

json

/companies/{countryISO}-{nationalID}/language

string
GET

Returns the URL for the Terms.Tech onboarding wizard pre-filled with the respective company data. The company must exist in our database (created by a call to the API /CreditLimit). The email of the company must be set previously by calling the setEmail API

ATTRIBUTES

countryISO

string

REQUIRED

nationalID

string

REQUIRED

POST

json

/companies/{countryISO}-{nationalID}/onboarding-url

{
  "OnboardingURL": "string",
  "HTTPStatus": {
    "HTTPCode": 1234567891234567,
    "developerMessage": "string",
    "userMessage": "string",
    "errorCode": "string",
    "moreInfo": "string"
  }
}
GET

Returns a list of matching Businesses based on the search key (valid search keys are: ‘Name’, ‘VAT’ or ‘NationalID’).
Search criteria value does not have to be an exact match for Name.
If search is performed with NationalID or VAT and no match is found in Terms.Tech database, CreditSafe will be contacted to provide company details (these can be used to pre-fill screens for example). In this case the GUID will not be filled in indicating that the company does not yet exists in the internal database and needs to be created by calling the API CreditLimit.
Returns the status of the onboarding, if “Successful” means the company has finished the onboarding process with the PSP. See service CreditLimit for the list of possible onbarding statuses.

Return codes:

HTTP 200:

OK.

HTTP 400:

197 - if the CountryISO is not 2 charachters in length;
198 - if the CountryISO is unknown;
195 - if the SearchKey = &#39;Name&#39; and the SearchValue is not at least 3 characters in length;
196 - if the SearchKey is anything other than &#39;Name&#39;, &#39;NationalID&#39; or &#39;VAT&#39;;

HTTP 401:
201 - If the authorization fails (because the OAuth2 token is missing or invalid).

HTTP 404:
140 - If there are no results matching the search criteria.

HTTP 500:
if an unexpected server error occurs.

ATTRIBUTES

countryISO

string

REQUIRED

Two character country code

searchKey

string

REQUIRED

The type of search; Valid values are: ‘Name’, ‘VAT’ or ‘NationalID’.

searchValue

string

REQUIRED

Part of a Company name or VAT number

MODELS

Address{

simpleValue

string

default:

street

string

default:

city

string

default:

postCode

string

default:

houseNo

string

default:

postalCode

string

default:

country

string

default:

houseNumber

string

default:

}

BusinessEntityAddress{

Street

REQUIRED

string

default:

Number

string

default: In some cases street number is included in the Street field

Zipcode

string

default:

City

REQUIRED

string

default:

AddressType

REQUIRED

string

default: The Type of address can be ‘Headquarters’, ‘Billing’, ‘Shipping’ or ‘Branch’

CountryISO

REQUIRED

string

default:

FullAddressText

string

default:

GUID

REQUIRED

string

default: Unique external identifier, can be used to refer to this Business Entity in input of web services

}

CompanyResponse{

Name

string

default: The name of the Company.

VAT

string

default: The Value Added Tax number.

NationalId

string

default: The National Registration Number for that company

Address

Address{

simpleValue

string

default:

street

string

default:

city

string

default:

postCode

string

default:

houseNo

string

default:

postalCode

string

default:

country

string

default:

houseNumber

string

default:

}

Status

string

default: Indicates if the company is active.

SafeNo

string

default: The CreditSafe external identifier. Indicates if the company has been found by Creditsafe

TradingNames

string

[default: List of other known names for this company. ]

OfficeType

string

default: Indicates if it is a headquarters or a branch

ConnectId

string

default:

}

CompanySearchResponse{

BusinessEntitySearchResultList

REQUIRED

[CompanySearchResult{

The result for a search on a Business entity

Name

REQUIRED

string

default:

Description

string

default:

CompanyType

REQUIRED

string

default:

CountryISO

REQUIRED

string

default:

VAT

string

default:

NationalID

REQUIRED

string

default:

BusinessEntity
AddressList

string

default:The list of all known addresses

[BusinessEntityAddress{

Address of a Business Entity (Company) as returned by PCI services.

Street

REQUIRED

string

default:

Number

string

default: In some cases street number is included in the Street field

Zipcode

string

default:

City

REQUIRED

string

default:

AddressType

REQUIRED

string

default: The Type of address can be ‘Headquarters’, ‘Billing’, ‘Shipping’ or ‘Branch’

CountryISO

REQUIRED

string

default:

FullAddressText

string

default:

GUID

REQUIRED

string

default: Unique external identifier, can be used to refer to this Business Entity in input of web services

}]

OnboardingStatus

REQUIRED

string

default: The status of the onboarding. If Onboarding as seller is successfull, then ‘seller” is returned. If Onboarding as buyer is successfull, then ‘buyer” is returned. If the company is onboarded as both buyer and seller then both are returned separated by a space.

}]

HTTPStatus

REST_ERROR_RICH{

HTTPCode

integer ($int64)

example: 1234567891234567

developerMessage

string

default:

userMessage

string

default:

errorCode

string

default:

moreInfo

string

default:

}

}

CompanySearchResult{

The result for a search on a Business entity

Name

REQUIRED

string

default: The name of the Business Entity

Description

string

default: A short description of the Business

CompanyType

REQUIRED

string

default: The Business Entity classification

CountryISO

REQUIRED

string

default: Country ISO

VAT

string

default: The Business Entity VAT number if known

NationalID

string

default: National Identifier

GUID

REQUIRED

string

default: Unique external identifier, can be used to refer to this Business Entity in input of web services

BusinessEntityAddressList

The list of all known addresses

[BusinessEntityAddress{

Address of a Business Entity (Company) as returned by PCI services.

Street

REQUIRED

string

default:

Number

string

default: In some cases street number is included in the Street field

Zipcode

string

default:

City

REQUIRED

string

default:

AddressType

REQUIRED

string

default: The Type of address can be ‘Headquarters’, ‘Billing’, ‘Shipping’ or ‘Branch’

CountryISO

REQUIRED

string

default:

FullAddressText

string

default:

GUID

REQUIRED

string

default: Unique external identifier, can be used to refer to this Business Entity in input of web services

}]

OnboardingStatus

REQUIRED

string

default: The status of the onboarding. If Onboarding as seller is successfull, then ‘seller” is returned. If Onboarding as buyer is successfull, then ‘buyer” is returned. If the company is onboarded as both buyer and seller then both are returned separated by a space.

}

GetCreditScoringResponse{

CompanyResponse

REQUIRED

CompanyResponse{

Name

string

default: The name of the Company.

VAT

string

default: The Value Added Tax number.

NationalId

string

default: The National Registration Number for tha company

Address{

simpleValue

string

default:

street

string

default:

city

string

default:

postCode

string

default:

houseNo

string

default:

postalCode

string

default:

country

string

default:

houseNumber

string

default:

}

Status

string

default: Indicates if the company is active.

SafeNo

string

string

default: The CreditSafe external identifier. Indicates if the company has been found by Creditsafe

TradingNames

string

[default:  List of other known names for this company.]

OfficeType

string

default: Indicates if it is a headquarters or a branch

ConnectId

string

default:

}

LimitData

REQUIRED

LimitData{

Rating

REQUIRED

string

default:

FinalLimitAmount

REQUIRED

number

example: 0.1

AvailableLimitAmount

REQUIRED

number

example: 0.1

}

isActive

REQUIRED

boolean

example: false
True if the company is active in Terms.Tech. Only active companies can participate in transactions. If the company is unknown to TERMS and is found in CreditSafe, it is added as non-active company.

OnboardingStatus

REQUIRED

string

default: The status of the onboarding. Enum: ‘Not Started’, ‘In Progress’, ‘Failed’, ‘Successful’

canHaveTerms

REQUIRED

boolean

example: false
Non binding promise to give TERMS, true if the company is active, has no overdue orders and has an available credit limit.

HTTPStatus

REST_ERROR_RICH{

HTTPCode

integer ($int64)

example: 1234567891234567

developerMessage

string

default:

userMessage

string

default:

errorCode

string

default:

moreInfo

string

default:

}

}

LimitData{

Rating

REQUIRED

string

default:

FinalLimitAmount

REQUIRED

number

example: 0.1

AvailableLimitAmount

REQUIRED

number

example: 0.1

}

OnboardingResponse{

OnboardingURL

REQUIRED

string

default:

HTTPStatus

REST_ERROR_RICH{

HTTPCode

integer ($int64)

example: 1234567891234567

developerMessage

string

default:

userMessage

string

default:

errorCode

string

default:

moreInfo

string

default:

}

}

REST_ERROR_RICH{

HTTPCode

integer ($int64)

example: 1234567891234567

developerMessage

string

default:

userMessage

string

default:

errorCode

string

default:

moreInfo

string

default:

}

SetEmailStructure{

countryISO

REQUIRED

string

default:

nationalID

REQUIRED

string

default:

email

REQUIRED

string

default:

}

SetLanguageStructure{

countryISO

REQUIRED

string

default:

nationalID

REQUIRED

string

default:

email

REQUIRED

string

default:

}

POST

json

/companies/{countryISO}-{searchKey}-{searchValue}

{
  "BusinessEntitySearchResultList": [
    {
      "Name": "string",
      "Description": "string",
      "CompanyType": "string",
      "CountryISO": "string",
      "VAT": "string",
      "NationalID": "string",
      "GUID": "string",
      "BusinessEntityAddressList": [
        {
          "Street": "string",
          "Number": "string",
          "Zipcode": "string",
          "City": "string",
          "AddressType": "string",
          "CountryISO": "string",
          "FullAddressText": "string",
          "GUID": "string"
        }
      ],
      "OnboardingStatus": "string"
    }
  ],
  "HTTPStatus": {
    "HTTPCode": 1234567891234567,
    "developerMessage": "string",
    "userMessage": "string",
    "errorCode": "string",
    "moreInfo": "string"
  }
}

Transactions API

Transactions API Swagger Documentation

[ Base URL: /terms42api/rest/transactions ]
https://credendo-dev.outsystemsenterprise.com/terms42api/rest/transactions/swagger.json

POST

Creates several Seller Orders (one for each Seller) financed by the requested TERMS product (given in the ‘type’ request parameter). If the call is successful the URL to the buyer agreement page is returned and the marketplace must redirect the buyer to this page.
The buyer and sellers must be known by Terms.Tech (created by calling the CreditLimit service). The sellers must be successfully onboarded if so configured in the marketplace settings.

HTTP 400:

137 - if the list of seller orders is empty or the buyer and seller have the same UBO
194 - if the length of any reference is more than 250 characters
152 - if any sellers are not successfully onboarded and seller onboarding is mandatory
214 - if the total amount for any order is less or equal to 0
223 - Invalid parameter if the type of TERMS product is invalid.

HTTP 401:

201 - if the authorization fails

HTTP 404:

222 - if marketplace cannot be found;
140 - if the buyer cannot be found;
140 - if one of the the sellers cannot be found

HTTP 409:

218 - if one of the sellers is the same as buyer;
120 - if the amount of the order is bigger than the maximum amount of a transaction for the current marketplace;
121 - if the amount of the order is bigger than the current marketplace available funds;
219 - if there is insufficient credit coverage for the buyer;
120 - the amount of the order is bigger than the current maximum transaction amount for the buyer;
151 - if the buyer has overdue orders;
104 - seller is not active;
105 - buyer is not active;

ATTRIBUTES

CreateOrderRequest

string

REQUIRED

POST

/buyer-orders

json

{
  "Type": "string",
  "BuyerReference": "string",
  "BuyerNationalID": "string",
  "MarketplaceEndTransactionOKPageURL": "string",
  "MarketplaceEndTransactionErrorPageURL": "string",
  "OrderRequestList": [
    {
      "SellerNationalID": "string",
      "SellerOrderReference": "string",
      "TotalAmount": 0.1,
      "MarketplaceFeesAmount": 0.1
    }
  ],
  "BuyerRepresentativeTitle": "string",
  "BuyerRepresentativeFirstName": "string",
  "BuyerRepresentativeLastName": "string",
  "BuyerRepresentativeEmail": "string",
  "DeliveryAddressFullText": "string",
  "SessionId": "string",
  "LanguageISO2": "string"
}

RESPONSE

{
  "TermsAndConditionsPageURL": "string",
  "HTTPStatus": {
    "HTTPCode": 1234567891234567,
    "developerMessage": "string",
    "userMessage": "string",
    "errorCode": "string",
    "moreInfo": "string"
  }
}
POST

Service for updating a Buyer Order reference

HTTP 409:

132 - if an Order is not in a status that allows update. Only orders in statuses &#39;Accepted&#39;, &#39;Review Pending&#39; or &#39;Investigation&#39; are taken into account, orders in other statuses cannot be updated.
223 - if a PO or an Order with the new reference already extists and the update operation would create a duplicate. Only Accepted, ReviewPending or Investigation are taken into account.

HTTP 401:

201 - if the authorization fails

HTTP 404:

131 - if the Order or PO was not found.

ATTRIBUTES

buyerOrderReference

string

REQUIRED

NewBuyerOrderReference

string

REQUIRED

POST

json

/buyer-orders/{buyerOrderReference}/new-reference

string

RESPONSE

{
  "HTTPStatus": {
    "HTTPCode": 1234567891234567,
    "developerMessage": "string",
    "userMessage": "string",
    "errorCode": "string",
    "moreInfo": "string"
  }
}
GET

Retuns the Fees based on total order amount and Terms payment method type.

ATTRIBUTES

NewBuyerOrderReference

string

REQUIRED

‘TERMS30’ or ‘TERMS60’

BuyerOrderTotalAmount

number

REQUIRED

POST

json

/buyer-orders/fees

string

RESPONSE

{
  "TERMSTechFeeAmount": 0.1,
  "HTTPStatus": {
    "HTTPCode": 1234567891234567,
    "developerMessage": "string",
    "userMessage": "string",
    "errorCode": "string",
    "moreInfo": "string"
  }
}
PUT

Service for updating an active Order (in statuses ‘Approved’, ‘Review Pending’, ‘Investigation’, ‘Paid-out’, ‘Overdue’) identified by its unique Seller Reference.

HTTP 400:

135 - if the new order amount is higher than initial order amount
214 - the MarketplaceFeeAmount should be grather or equal to 0
214 - the SellerAmount should be grather or equal to 0
214 - you cannot update the Order in the current status
137 - order amount or marketplace fees amount is the same as the old one (if different than 0)

HTTP 401:

201 - if the authorization fails

HTTP 404:

131 - if the Order was not found

ATTRIBUTES

sellerOrderReference

string

REQUIRED

UpdateOrderRequest

string

REQUIRED

POST

json

/buyer-orders/{buyerOrderReference}/new-reference

{
  "NewTotalAmount": 0.1,
  "NewMarketplaceFeesAmount": 0.1
}

RESPONSE

{
  "HTTPStatus": {
    "HTTPCode": 1234567891234567,
    "developerMessage": "string",
    "userMessage": "string",
    "errorCode": "string",
    "moreInfo": "string"
  }
}
DELETE

Cancel an active order (in statuses ‘Approved’, ‘Review Pending’, ‘Investigation’, ‘Paid-out’, ‘Overdue’)

HTTP 200:

OK.

HTTP 400:

214 - if the order rference is missing or the order is not in one of the active statuses mentioned above;

HTTP 401:

201 - If the authorization fails

ATTRIBUTES

sellerOrderReference

string

REQUIRED

POST

json

/seller-orders/{sellerOrderReference}

string

RESPONSE

{
  "HTTPStatus": {
    "HTTPCode": 1234567891234567,
    "developerMessage": "string",
    "userMessage": "string",
    "errorCode": "string",
    "moreInfo": "string"
  }
}
POST

Service for updating a Seller Order reference

HTTP 409:

132 - if an Order is not in a status that allows update. Only orders in statuses &#39;Accepted&#39;, &#39;Review Pending&#39; or &#39;Investigation&#39; are taken into account, orders in other statuses cannot be updated.
223 - if a PO or an Order with the new reference already extists and the update operation would create a duplicate. Only Accepted, ReviewPending or Investigation are taken into account.

HTTP 401:

201 - if the authorization fails

HTTP 404:

131 - if the Order or PO was not found.

ATTRIBUTES

sellerOrderReference

string

REQUIRED

NewSellerOrderReference

string

REQUIRED

POST

json

/seller-orders/{sellerOrderReference}/new-reference

string

RESPONSE

{
  "HTTPStatus": {
    "HTTPCode": 1234567891234567,
    "developerMessage": "string",
    "userMessage": "string",
    "errorCode": "string",
    "moreInfo": "string"
  }
}
POST

Sets the shipping data on the order. When set, it is no longer necessary to upload the Proof of Delivery document via the Document API.

ATTRIBUTES

sellerOrderReference

string

REQUIRED

ShippingRequest

string

REQUIRED

POST

json

/seller-orders/{sellerOrderReference}/shipping

{
  "TrackingNumber": "string",
  "CarrierName": "string"
}

RESPONSE

{
  "HTTPStatus": {
    "HTTPCode": 1234567891234567,
    "developerMessage": "string",
    "userMessage": "string",
    "errorCode": "string",
    "moreInfo": "string"
  }
}
GET

Retuns the Order Status Label for a specific Order.

ATTRIBUTES

sellerOrderReference

string

REQUIRED

POST

json

/seller-orders/{sellerOrderReference}/status

string

RESPONSE

{
  "HTTPStatus": {
    "HTTPCode": 1234567891234567,
    "developerMessage": "string",
    "userMessage": "string",
    "errorCode": "string",
    "moreInfo": "string"
  }
}
POST

Associates a document with an Order.
The DocumentType can be one of ‘SELLER_INVOICE’ or ‘DELIVERY_SLIP’.
The file extention must be pdf, jpeg, jpg, doc or docx.

Return codes:

HTTP 200:

if all went well and the terms are accepted.

HTTP 400:

180 - if no content for the document file;
181 - if the document is bigger than 10 MB;
214 - invalid DocumentType, DocumentName is missing, buyer agreement not found.

HTTP 401:

201 - if the authorization fails (because the OAuth2 token is missing or invalid);

HTTP 404:

101 - if the order with the SellerOrdereReference is not found;

ATTRIBUTES

sellerOrderReference

string

REQUIRED

The unique Seller Order Reference required to identify the order to link the document

DocumentType

number

REQUIRED

DocumentName

number

REQUIRED

Binary

REQUIRED

The Document data, max size 10 MB

MODELS

CreateOrderRequest{

Type

REQUIRED

string

default: The TERMS product to be associated with the order(s). Can be ‘TERMS30’ (buyer pays back after 30 days), ‘TERMS60’ (buyer pays back after 30 days);

BuyerReference

REQUIRED

string

default: Shopping order buyer reference as displayed in the marketplace. Will be used as reference for the payin from the buyer.

BuyerNationalID

REQUIRED

string

default: The Buyer National Number. The Business entity must exist in the TERMS42 database and be onboarded for the current marketplace

MarketplaceEndTransactionOK
PageURL

REQUIRED

string

default: The URL of the Marketplace end transaction successfull page. After accepting the Terms & Conditions the buyer’s browser is redirected to this url

MarketplaceEndTransactionError
PageURL

REQUIRED

string

default: The Marketplace error processing payment with TERMS42 page. If the buyer cancels the Terms & Conditions page he is redirected to this url. Can be used to present a page where the user can select a different payment method

OrderRequestList

REQUIRED

The list of Orders per seller.

SellerOrderRequest{

A request for one order with one seller.

SellerNationalID

REQUIRED

string

default:The NationalIdentifier of the seller. The business entity of the seller must exist in the TERMS42 database but the seller does not necessarily need to be onboarded (depending on parameter is seller onboarding mandatory on marketplace level)

SellerOrderReference

REQUIRED

string

default: The Seller Order reference, will be used in the Payment reference for payments to the Seller and The Marketplace

TotalAmount

REQUIRED

number

example: 0.1
The total amount of the order, including taxes and any shipping fees.

MarketplaceFees
Amount

REQUIRED

number

example: 0.1
The amount of marketplace fees. May be 0 if there is no marketplace comission.

}]

BuyerRepresentativeTitle

string

default: The Title (Mr. Mrs., etc) of the user acting on behalf of the Buyer entity

BuyerRepresentativeFirstName

string

default: The first name of the user acting on behalf of the Buyer entity (minimum 2 characters)

BuyerRepresentativeLastName

string

default: The last name of the user acting on behalf of the Buyer entity (minimum 2 characters)

BuyerRepresentativeEmail

string

default: The email address of the user acting on behalf of the Buyer entity

DeliveryAddressFullText

string

default: The one line full address text for the delivery address. Used for matching with buyer registered address for order validation but not mandatory.

SessionId

REQUIRED

string

default: The unique session identifier from the Marketplace, proving that the user performaing the request is authenticated in the Marketplace. It is an identifier that must be traceable in the Marketplace logs to establish legal proof that the user has been authenticated. If a session identifier cannot be supplied, a technical user identifier may be used, if it is possible to link this identifier to the person performing the request. This will be used as part of the Simple Digital Signature on the Buyer Product Agreement.

LanguageISO2

string

default: The language to be used in the communication with the buyer or seller. Can be “fr” or “en”, if not specified it defaults to English.

}

CreateOrderResponse{

TermsAndConditionsPageURL

REQUIRED

string

default: The URL to the T&C page that has to be agreed by the buyer.

HTTPStatus

REST_ERROR_RICH{

HTTPCode

integer ($int64)

example: 1234567891234567

developerMessage

string

default:

userMessage

string

default:

errorCode

string

default:

moreInfo

string

default:

}

}

GetOrderFeesResponse{

TERMSTechFeeAmount

REQUIRED

number

example: 0.1

HTTPStatus

REST_ERROR_RICH{

HTTPCode

integer ($int64)

example: 1234567891234567

developerMessage

string

default:

userMessage

string

default:

errorCode

string

default:

moreInfo

string

default:

}

}

GetOrderStatusStructure{

OrderStatus

string

default:

}

HTTPStatusResponse{

HTTPStatus

REST_ERROR_RICH{

HTTPCode

integer ($int64)

example: 1234567891234567

developerMessage

string

default:

userMessage

string

default:

errorCode

string

default:

moreInfo

string

default:

}

}

REST_ERROR_RICH{

HTTPCode

integer ($int64)

example: 1234567891234567

developerMessage

string

default:

userMessage

string

default:

errorCode

string

default:

moreInfo

string

default:

}

SellerOrderRequest{

A request for one order with one seller.

SellerNationalID

REQUIRED

string

default: The NationalIdentifier of the seller. The business entity of the seller must exist in the TERMS42 database but the seller does not necessarily need to be onboarded (depending on parameter is seller onboarding mandatory on marketplace level)

SellerOrderReference

REQUIRED

string

default: The Seller Order reference, will be used in the Payment reference for payments to the Seller and The Marketplace

TotalAmount

REQUIRED

number

example: 0.1
The total amount of the order, including taxes and any shipping fees.

MarketplaceFeesAmount

REQUIRED

number

example: 0.1
The amount of marketplace fees. May be 0 if there is no marketplace comission.

}

ShippingRequest{

TrackingNumber

REQUIRED

string

default:

CarrierName

REQUIRED

string

default:

}

UpdateBuyerOrderReferenceStructure{

buyerOrderReference

REQUIRED

string

default:

newBuyerOrderReference

REQUIRED

string

default:

}

UpdateOrderRequest{

NewTotalAmount

REQUIRED

number

example: 0.1

NewMarketplaceFeesAmount

REQUIRED

number

example: 0.1

}

POST

json

/seller-orders/{sellerOrderReference}-{DocumentType}-{DocumentName}/document

string

RESPONSE

{
  "HTTPStatus": {
    "HTTPCode": 1234567891234567,
    "developerMessage": "string",
    "userMessage": "string",
    "errorCode": "string",
    "moreInfo": "string"
  }
}

Webhooks

Notifications – Webhooks

Terms.Tech uses webhooks to notify your application when an event happens in your account..  Webhooks are particularly useful for asynchronous events like when your customer is redirected to our hosted page to finalise the payment.

Start using webhooks with your Terms.Tech integration in just two steps:

  1. Create a webhook endpoint on your server, so it can be called by Terms.Tech
  2. Subscribe your endpoint to specific Event Types to receive notifications.

Authentication – Webhooks

Authentication for webhooks can be set via a secret and/or basic authentication (user id/password). Both are provided by the Customer. The notification receiver (Customer) will need to verify the authentication server-side , take the appropriate action to the event and determine to whom to forward the notification.

Webhook – Requests

A POST request is sent to the configured Customer Webhook URL with the following body:

{    
"Id": "string",    
"UserId": "string",    
"OrderReference": "string",    
"OrderGUID": "string",    
"EventType": "string",    
"Payload": "string",    
"Notes": "string",    
"CreatedOn": "date-time"
}

ATTRIBUTES

Id

REQUIRED

Unique identifier for the event (GUID).

UserId

UserId as used by the notification receiver (e.g. Marketplace) only to be used if the notification is not linked to an order and targeted to a specific user.

OrderReference

Identifier of an order as used by the notification receiver (e.g. Marketplace).

OrderGUID

Identifier of an order defined by TERMS.

EventType

Code representing the type of event. Enumeration:
TERMSBuyerNotOnboarded,
TERMSCustomerOnboardingAccepted,
TERMSCustomerOnboardingPending,
TERMSCustomerOnboardingRefused,
TERMSOrderAccepted,
TERMSOrderCancelled,
TERMSOrderRefused,
TERMSPayinBuyerInDefault,
TERMSPayinExecuted,
TERMSPayoutAccepted,
TERMSPayoutExecuted,
TERMSPayoutUnderInvestigation,
TERMSSellerNotOnboarded,

Payload

Extra information, content depends on the EventType (structured).

Notes

Extra information (unstructured).

CreatedOn

example: 2014-12-31T23:59:59.938Z Timestamp of the notification creation.

EventTypes

ONBOARDING

TERMSCustomerOnboardingPending

The onboarding process (registration) with the PSP has started.

TERMSCustomerOnboardingAccepted

PSP has accepted the customer registration.

TERMSCustomerOnboardingRefused

PSP has refused the customer registration.

ORDERS

TERMSOrderAccepted

An order is eligible and has been approved by TERMS.

TERMSOrderRefused

An order is ineligible and is declined by TERMS.

TERMSBuyerNotOnboarded

An order is on hold as the buyer is not onboarded by the PSP.

TERMSSellerNotOnboarded

An order is on hold as the seller is not onboarded by the PSP.

TERMSPayoutAccepted

The pay-out is scheduled as the proof of delivery has been validated.

TERMSPayoutUnderInvestigation

The pay-out is on hold as the proof of delivery requires additional validation.

TERMSPayoutExecuted

The payment to the seller and merchant (merchant fee) was successfully processed.

TERMSPayinBuyerInDefault

The payment from the buyer via SEPA DD failed.

TERMSPayinExecuted

The payment from the buyer was received and the order was settled.

TERMSOrderCancelled

An order with TERMS has been cancelled.

Glossary

Payment terms – is an execution of a Transaction with deferred payment by Buyer through the Service, applied in connection with some Transactions, as agreed by the parties

‘Pay with Terms’ – is Terms.Tech’s Buy Now, Pay Later (BNPL) payment solution for B2B marketplaces and ecommerce merchants

Deferred payments – are interest-free payment options that allow you or your buyers to buy now and pay later.

Credit limit – the maximum amount of outstanding BNPL balances a customer may have with TERMS at any given time.

Credit amount – the initial credit provision assigned to the marketplace by Terms.Tech liquidity provider.