Request Payment

POST {{base-url}}/payment/create

Request a new payment. This API will return a payment id, a success status indicator, a redirect url and a trust signature. It also contains an array of the products containing the product sku, if the product was accepted or rejected and the cheapest price that Teljoy have on each product. The payment id can be used to check the status of the payment. The redirect url can be used to redirect the user to the Teljoy payment page. The trust signature can be used to verify the integrity of the response. The trust signature is a SHA256 hash of the provided trust seed and value.

Parameters

Headers

Name	Type	Required	Description
api-key	string	Yes	The API key for access

Request

{
  "customer": {
    "first_Name": "string",
    "last_Name": "string",
    "email": "string",
    "mobile": "string",
    "salary": "string|null",
    "is_under_debt_review": "boolean|null",
    "registration_document_number": "string|null"
  },
  "billing_Address": {
    "building": "string",
    "street": "string",
    "suburb": "string",
    "city": "string",
    "province": "string",
    "postal_Code": "string",
    "country": "string",
    "longitude": 0,
    "latitude": 0
  },
  "shipping_Address": {
    "building": "string",
    "street": "string",
    "suburb": "string",
    "city": "string",
    "province": "string",
    "postal_Code": "string",
    "country": "string",
    "longitude": 0,
    "latitude": 0
  },
  "products": [
    {
      "name": "string",
      "description": "string",
      "short_Description": "string",
      "brand": "string",
      "images": ["string"],
      "url": "string",
      "price": 0,
      "sku": "string",
      "barcodes": ["string"],
      "quantity": 1,
      "categories": [
        {
          "categoryId": "string",
          "name": "string",
          "url": "string"
        }
      ],
      "properties": [
        {
          "key": "string",
          "value": "string"
        }
      ]
    }
  ],
  "redirects": {
    "order_Id": "string",
    "success_Redirect_Url": "string",
    "failure_Redirect_Url": "string",
    "final_Amount": 0,
    "tax_Amount": 0,
    "shipping_Amount": 0,
    "discount": 0,
    "trust_Value": "string",
    "trust_Seed": "string",
    "merchant_Store": "string"
  },
  "personal": {
     "employerName": "Test",
     "employerContactNumber": "0123456789",
     "nextOfKinName": "Test",
     "nextOfKinContactNumber": "0123456798",
     "maritalStatus": 0,
     "nextOfKinRelationshipType": 0
    }
}

payload

Name	Type	Required	Description
apiKey	string	Yes	The API key for access
customer	RequestPaymentCustomerDTO	Yes	Customer information
billing_Address	RequestPaymentAddressDTO	Yes	Billing address information
shipping_Address	RequestPaymentAddressDTO	Yes	Shipping address information
products	array of RequestPaymentProductDTO	Yes	Array of products
redirects	RequestPaymentRedirectsDTO	Yes	Redirect URLs and related details
personal	PersonalInfoDTO	No	Further customer information

RequestPaymentCustomerDTO

Name	Type	Required	Description
first_Name	string	Yes	Customer's first name
last_Name	string	Yes	Customer's last name
email	string	Yes	Customer's email
mobile	string	Yes	Customer's mobile
salary	string	No	Net Salary
is_under_debt_review	bool	No	Is customer under debt review
registration_document_number	string	No	Identity Number

RequestPaymentAddressDTO

Name	Type	Required	Description
building	string	Yes	Building name/number
street	string	Yes	Street name
suburb	string	Yes	Suburb name
city	string	Yes	City name
province	string	Yes	Province name
postal_Code	string	Yes	Postal code
country	string	Yes	Country name
longitude	number	Yes	Longitude coordinate
latitude	number	Yes	Latitude coordinate

RequestPaymentProductDTO

Name	Type	Required	Description
name	string	Yes	Product name
description	string	Yes	Product description
short_Description	string	Yes	Short product description
brand	string	Yes	Product brand
images	array of string	Yes	Array of product image URLs
url	string	Yes	Product URL
price	number	Yes	Product price
sku	string	Yes	Product SKU
quantity	int	Yes	Product Quantity
barcodes	array of string	Yes	Array of product barcodes
categories	array of RequestPaymentProductCategoryDTO	Yes	Array of product categories
properties	array of RequestPaymentProductPropertyDTO	Yes	Array of product properties

RequestPaymentProductCategoryDTO

Name	Type	Required	Description
categoryId	string	Yes	Category ID
name	string	Yes	Category name
url	string	Yes	Category URL

RequestPaymentProductPropertyDTO

Name	Type	Required	Description
key	string	Yes	Property key
value	string	Yes	Property value

RequestPaymentRedirectsDTO

Name	Type	Required	Description
order_Id	string	Yes	Order ID
success_Redirect_Url	string	Yes	Success redirect URL
failure_Redirect_Url	string	Yes	Failure redirect URL
final_Amount	number	Yes	Final amount
tax_Amount	number	Yes	Tax amount
shipping_Amount	number	Yes	Shipping amount
discount	number	Yes	Discount amount
merchant_Store	string	No	Store Name
trust_Value	string	Yes	Trust value
trust_Seed	string	Yes	Trust seed

PersonalInfoDTO

Name	Type	Required	Description
employerName	string	Yes	Employers name
employerContactNumber	string	Yes	Employer's contact no
maritalStatus	MaritalStatusEnum	Yes	Marital Status
nextOfKinName	string	Yes	Next of kin name
nextOfKinContactNumber	string	Yes	Next of kin contact no
nextOfKinRelationshipType	RelationshipStatusEnum	Yes	Next of kin relationship

MaritalStatusEnum

Label	Value
Married	0
Single	1
Divorced	2
Widowed	3
Living Together	4

RelationshipStatusEnum

Label	Value
Spouse	0
Partner	1
Family	2
Friend	3
Colleague	4

Response

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "success": true,
  "trust_signature": "string",
  "redirect_url": "string",
  "products": [
    {
      "sku": "string",
      "accepted": true,
      "price": 0
    }
  ]
}

payload

Name	Type	Description
id	string	Payment ID
success	boolean	Success status
trust_signature	string	Trust signature
redirect_url	string	Redirect URL
products	array of RequestPaymentResponseProductDTO	Array of response products

RequestPaymentResponseProductDTO

Name	Type	Required	Description
sku	string	Yes	Product SKU
accepted	boolean	Yes	Product acceptance
price	number	Yes	Product price

Errors

Code	Description
400	One or more validation errors
500	Server Error

Bad Request Example

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "traceId": "1ed63b98-eda9-4634-9738-8ec74bac3bd6",
  "errors": {
    "apiKey": ["The apiKey field is required."],
    "customer": ["The customer field is required."]
  }
}

Internal Server Error Example

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.6.1",
  "title": "An error occurred.",
  "status": 500,
  "traceId": "ced4db70-527d-41d6-9a90-e7eb165df5b6"
}

Example Usage

Here's an example of how to make a POST request to the /api/payment/create endpoint using Javascript and the fetch API:

let headersList = {
 "Accept": "*/*",
 "api-key": "your_api_key",
 "Content-Type": "application/json"
}

let bodyContent = JSON.stringify({
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "mobile": "+27821112233",
    "salary": "8500",
    "is_under_debt_review": false,
    "registration_document_number": "1234567891023"
  },
  "shipping_address": {
    "building": "Building A",
    "street": "123 Street",
    "suburb": "Suburb",
    "city": "City",
    "province": "GP",
    "country": "ZA",
    "postal_code": "2060",
  },
  "billing_address": {
    "building": "Building A",
    "street": "123 Street",
    "suburb": "Suburb",
    "city": "City",
    "province": "GP",
    "country": "ZA",
    "postal_code": "2060",
  },
  "products": [
    {
      "name": "HISENSE 100L5F 10\" LASER TV1",
      "description": "string",
      "short_description": "The L5 Laser TV immerses you into a whole new 4K UHD viewing experience.",
      "brand": "HISENSE",
      "images": [
        "https://atomictest.co.za/wp-content/uploads/2021/11/100L5F.jpeg"
      ],
      "url": "https://www.amazon.co.za/Pampers-Anti-Rash-Shield-Pants-Diapers/dp/B0CMV81RBJ/ref=asc_df_B0CMV81RBJ",
      "sku": "100L5F",
      "quantity": "1",
      "price": "12657.00"
    }
  ],
  "redirects": {
    "order_id": "76144",
    "trust_value": "c10cd9445121e4ed6ad0ab47cdde2882",
    "trust_seed": "ew0KCQkJCQkJIm5hbWUiOiJISVNFTlNFIDEwMEw1RiAxMDAmcXVvdDsgTEFTRVIgVFYxIiwNCgkJCQkJCSJza3UiOiIxMDBMNUYiLA0KCQkJCQkJInF1YW50aXR5IjoiMSIsDQoJCQkJCQkicHJpY2UiOiIxMjY1Ny4wMCIsDQoJCQkJCQkiZGVzY3JpcHRpb24iOiAic3RyaW5nIiwNCgkJCQkJCSJicmFuZCI6ICJzdHJpbmciLA0KCQkJCQkJIm1lcmNoYW50X3Byb2R1Y3RfaWQiOiI1Mzc4MyIsDQoJCQkJCQkidmVuZG9yIjogew0KCQkJCQkJCSJ2ZW5kb3JfaWQiOiAic3RyaW5nIiwNCgkJCQkJCQkidXJsIjogInN0cmluZyIsDQoJCQkJCQkJIm5hbWUiOiAic3RyaW5nIg0KCQkJCQkJfSwNCgkJCQkJCSJpbWFnZXMiOiBbDQoJCQkJCQkJImh0dHBzOi8vYXRvbWljdGVzdC5jby56YS93cC1jb250ZW50L3VwbG9hZHMvMjAyMS8xMS8xMDBMNUYuanBlZyIgDQoJCQkJCQldLA0KCQkJCQkJImJhcmNvZGVzIjogWw0KCQkJCQkJCSIiDQoJCQkJCQldLA0KCQkJCQkJImNhdGVnb3JpZXMiOiBbIA0KCQkJCQkJXSwNCgkJCQkJCSJwcm9wZXJ0aWVzIjogWw0KCQkJCQkJCXsNCgkJCQkJCQkia2V5IjogInN0cmluZyIsDQoJCQkJCQkJInZhbHVlIjogInN0cmluZyINCgkJCQkJCQl9DQoJCQkJCQldDQoJCQkJCX0s",
    "success_redirect_url": "https://masons.teljoy.sinappsus.co.za/checkout/order-received/76144/?key=wc_order_KNvI7qWItjO7a&utm_nooverride=1&order_id=76144&wc-api=WC_Gateway_Teljoy",
    "failure_redirect_url": "https://masons.teljoy.sinappsus.co.za/checkout/order-received/76144/?key=wc_order_KNvI7qWItjO7a&utm_nooverride=1&status=cancelled",
    "final_amount": 12657.00,
    "tax_amount": 0,
    "shipping_amount": 0,
    "discount": "0",
    "merchant_Store": "Rosebank Mall"
  }
});

let response = await fetch("http://localhost:3000/api/payment/create", { 
  method: "POST",
  body: bodyContent,
  headers: headersList
});

let data = await response.text();
console.log(data);

Replace your_api_key with your actual API key.

Expected Response

This is an example of the expected response:

{
  "id": "be5a83ab-5b57-46f9-95ac-08db35c30d2b",
  "success": true,
  "trust_signature": "c14593cd6c9a24ac6257ab7cac1bb45f0ff272389e600b21580b0261752b04ae",
  "redirect_url": "https://pay.teljoy.dev/payment/be5a83ab-5b57-46f9-95ac-08db35c30d2b",
  "products": [
    {
      "sku": "100L5F",
      "accepted": true,
      "price": 299
    }
  ]
}