Manage products and payment links via API

Create a product

Request

To create a product, send a POST request to https://api.begateway.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	string	Products quantity available to sell. Don't send the parameter if `infinite` is `true`
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	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)
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 Demo PSP.
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://api.begateway.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://api.begateway.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, Demo PSP will return 201 HTTP status code and a new product object with payment links.

In case of invalid parameters in the request Demo PSP 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://api.begateway.com/products/prd_ed27b047d3ccd1a6/pay",
    "payment_url": "https://api.begateway.com/products/prd_ed27b047d3ccd1a6/pay",
    "confirm_url": "https://checkout.begateway.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://api.begateway.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://api.begateway.com/products/prd_ed27b047d3ccd1a6

Response

If the product ID exists, Demo PSP returns 200 HTTP status code and the product details.

In case of invalid parameters in the request Demo PSP 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://api.begateway.com/products/prd_ed27b047d3ccd1a6/pay",
    "payment_url": "https://api.begateway.com/products/prd_ed27b047d3ccd1a6/pay",
    "confirm_url": "https://checkout.begateway.com/v2/confirm_order/prd_ed27b047d3ccd1a6/1"
}

Retrieve all products

Request

To retrieve all products, send a GET request to https://api.begateway.com/products.

Request example

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

Response

If credentials are valid, Demo PSP 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://api.begateway.com/products/prd_4e3933e63c7490fc/pay",
    "payment_url": "https://api.begateway.com/products/prd_4e3933e63c7490fc/pay",
    "confirm_url": "https://checkout.begateway.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://api.begateway.com/products/prd_1567bece456ac4aa/pay",
    "payment_url": "https://api.begateway.com/products/prd_1567bece456ac4aa/pay",
    "confirm_url": "https://checkout.begateway.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://api.begateway.com/products/prd_3c97b6f1bba28db7/pay",
    "payment_url": "https://api.begateway.com/products/prd_3c97b6f1bba28db7/pay",
    "confirm_url": "https://checkout.begateway.com/v2/confirm_order/prd_3c97b6f1bba28db7/1"
}
]

Update a product

Request

To update product details, send a PUT to https://api.begateway.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://api.begateway.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, Demo PSP will return 204 HTTP status code and empty body.