Manage products and payment links via API

Create a product

Request

To create a product, send a POST request to https://epsp.fortebank.com/products with the following parameters:

Parameter	Type	Description
name * required	string	Product name.
description * required	string	Product description.
currency * required	string	A product price currency in the ISO-4217 alpha-3 code format. For example, `USD`.
amount * required	string	Product price amount in minimal units.
quantity * conditionally required	string	Products quantity available to sell. Don't send the parameter if `infinite` is `true`. The parameter is required unless `"infinite": true` is sent in the request.
infinite	boolean	Set to `true` if product's quantity is unlimited. For instance, it is a virtual product.
visible_fields	array	It is an array which may consist of the values `first_name`, `last_name`, `country`, `state`, `city`, `address`, `zip`, `phone`, `birth_date`, `email`, `taxpayer_id`. Fields for customer's data indicated in the array will be displayed at the payment page.
test	boolean	`true` or `false`. The product will be a test one if it is `true`
immortal	boolean	`true` or `false`. Set to `true` if payment period is unlimited.
expired_at * conditionally required	string	Date and time till a product can be paid. Format: `YYYY-MM-DDThh:mm:ssTZD`, where YYYY – year (for example 2019), MM – month (for example 02), DD – day (for example 09), hh – hours (for example 18), mm – minutes (for example 20), ss – seconds (for example 45), TZD – time zone (+hh:mm или –hh:mm). The parameter is required unless `"immortal": true` is sent in the request.
return_url	string	URL where to return Customer back to a merchant's shop after a payment completion. If the parameter is not defined, Customer will be redirected to a shop URL registered with Forte E-commerce.
shop_id	integer	Shop ID.
language * required	string	Change to payment page language. English (`en`) is set by default. Possible values of `language` parameter.
transaction_type	string	Transaction type. Default - `payment`. Possible values are: `payment` - combination of authorization and capture processed at a time; `authorization` - verify and hold cardholder's funds.

Request example with an unlimited product quantity and an unlimited payment period

curl https://epsp.fortebank.com/products \
-X POST -u {Your shop id}:{Your shop secret key} \
-H "Content-Type: application/json" \
-d \
'{
    "name": "product",
    "description": "description",
    "currency": "USD",
    "amount": "990",
    "infinite": true,
    "test": false,
    "immortal": true,
    "return_url": "http://return-url.com",
    "shop_id": "1",
    "language": "en",
    "transaction_type": "payment"
}'

Request example with limited product's quantity and limited payment period

curl https://epsp.fortebank.com/products \
-X POST -u shop_id:secret_key \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d \
'{
    "name": "product",
    "description": "description",
    "currency": "USD",
    "amount": "990",
    "quantity": "10",
    "infinite": false,
    "test": false,
    "immortal": false,
    "expired_at": "2023-12-31",
    "return_url": "http://return-url.com",
    "shop_id": "1",
    "language": "en",
    "transaction_type": "payment"
}`

Response

If credentials and parameters are valid, Forte E-commerce will return 201 HTTP status code and a new product object with payment links.

In case of invalid parameters in the request Forte E-commerce will return 422 HTTP status code and an error message.

Response example, HTTP status code 201

{
    "id": "prd_ed27b047d3ccd1a6",
    "name": "product",
    "description": "description of product",
    "currency": "USD",
    "amount": 990,
    "quantity": 10,
    "infinite": false,
    "language": "en",
    "transaction_type": "payment",
    "created_at": "2022-12-20T18:54:42.033Z",
    "updated_at": "2022-12-20T18:54:42.033Z",
    "test": false,
    "additional_data": {},
    "pay_url": "https://epsp.fortebank.com/products/prd_ed27b047d3ccd1a6/pay",
    "payment_url": "https://epsp.fortebank.com/products/prd_ed27b047d3ccd1a6/pay",
    "confirm_url": "https://securepayments.fortebank.com/v2/confirm_order/prd_ed27b047d3ccd1a6/1"
}

Response to the request with invalid parameters, HTTP status code 422

{
    "message": "Currency is not in ISO 4217 Alpha-3 format. Currency is unknown ISO 4217 Alpha-3 code",
    "errors": {
        "currency": [
            "is not in ISO 4217 Alpha-3 format",
            "is unknown ISO 4217 Alpha-3 code"
        ]
    }
}

Get a payment link and details for an existing product

Request

To get details of a product, send a GET request to https://epsp.fortebank.com/products/{product_id}, where {product_id} is a product identifier, the id parameter value from the response to the request to create a product.

Example the request to get details of the product with the ID prd_ed27b047d3ccd1a6

curl -u shop_id:secret \
    https://epsp.fortebank.com/products/prd_ed27b047d3ccd1a6

Response

If the product ID exists, Forte E-commerce returns 200 HTTP status code and the product details.

In case of invalid parameters in the request Forte E-commerce will return 302 HTTP status code and the response body, where an error description will be shown.

Response with a payment link, HTTP status code 200

{
    "id": "prd_ed27b047d3ccd1a6",
    "name": "product",
    "description": "description of product",
    "currency": "USD",
    "amount": 990,
    "quantity": 10,
    "infinite": false,
    "language": "en",
    "transaction_type": "payment",
    "created_at": "2022-12-20T18:54:42.033Z",
    "updated_at": "2022-12-20T18:54:42.033Z",
    "test": false,
    "additional_data": {},
    "pay_url": "https://epsp.fortebank.com/products/prd_ed27b047d3ccd1a6/pay",
    "payment_url": "https://epsp.fortebank.com/products/prd_ed27b047d3ccd1a6/pay",
    "confirm_url": "https://securepayments.fortebank.com/v2/confirm_order/prd_ed27b047d3ccd1a6/1"
}

Retrieve all products

Request

To retrieve all products, send a GET request to https://epsp.fortebank.com/products.

Request example

curl -u {Your shop id}:{Your shop secret key} \
  https://epsp.fortebank.com/products

Response

If credentials are valid, Forte E-commerce will return 200 HTTP status code and products.

Response example

[
{
    "id": "prd_4e3933e63c7490fc",
    "name": "product",
    "description": "description of product",
    "amount": 100,
    "currency": "USD",
    "language": "en",
    "infinite": true,
    "quantity": 0,
    "transaction_type": "payment",
    "created_at": "2023-05-02T17:35:14.950Z",
    "updated_at": "2023-05-02T17:35:14.950Z",
    "additional_data": {},
    "test": false,
    "pay_url": "https://epsp.fortebank.com/products/prd_4e3933e63c7490fc/pay",
    "payment_url": "https://epsp.fortebank.com/products/prd_4e3933e63c7490fc/pay",
    "confirm_url": "https://securepayments.fortebank.com/v2/confirm_order/prd_4e3933e63c7490fc/1"
},
{
    "id": "prd_1567bece456ac4aa",
    "name": "product 2",
    "description": "description of product 2",
    "amount": 990,
    "currency": "EUR",
    "language": "it",
    "infinite": false,
    "quantity": 7,
    "transaction_type": "payment",
    "created_at": "2023-02-15T11:54:59.579Z",
    "updated_at": "2023-02-15T11:54:59.579Z",
    "additional_data": {},
    "test": false,
    "pay_url": "https://epsp.fortebank.com/products/prd_1567bece456ac4aa/pay",
    "payment_url": "https://epsp.fortebank.com/products/prd_1567bece456ac4aa/pay",
    "confirm_url": "https://securepayments.fortebank.com/v2/confirm_order/prd_1567bece456ac4aa/1"
},
{
    "id": "prd_3c97b6f1bba28db7",
    "name": "test product",
    "description": "description of test product",
    "amount": 100,
    "currency": "USD",
    "language": "en",
    "infinite": true,
    "quantity": null,
    "transaction_type": "authorization",
    "created_at": "2020-01-21T10:46:20.232Z",
    "updated_at": "2020-02-17T16:53:43.770Z",
    "additional_data": {},
    "test": true,
    "pay_url": "https://epsp.fortebank.com/products/prd_3c97b6f1bba28db7/pay",
    "payment_url": "https://epsp.fortebank.com/products/prd_3c97b6f1bba28db7/pay",
    "confirm_url": "https://securepayments.fortebank.com/v2/confirm_order/prd_3c97b6f1bba28db7/1"
}
]

Update a product

Request

To update product details, send a PUT to https://epsp.fortebank.com/products/{product_id}, where {product_id} is a product identifier, the id parameter value from the response to the request to create a product.

The request parameters as the same as the parameters of the request to create a product.

Example to update an amount and a quantity of the product with the ID prd_1567bece456ac4aa

curl https://epsp.fortebank.com/products/prd_1567bece456ac4aa \
-X PUT -u {Your shop id}:{Your shop secret key} \
-H "Content-Type: application/json" \
-d \
'
{
    "amount": 950,
    "infinite": false,
    "quantity": "5"
}

Response

If the product ID exists and credentials are valid, Forte E-commerce will return 204 HTTP status code and empty body.