Developer Integration Guide

Welcome to the BagelPay Developer Interaction Guide - built to help you seamlessly integrate secure, scalable, and customizable payment solutions into your stack.

It is highly recommended that developers conduct initial testing in Test Mode.

Integration Steps

Follow these steps to integrate BagelPay API:

Step1: Set up your account

Log in using your email or sign in with Google. If you don’t have an account yet, you can create one at https://app.bagelpay.io/login.

Step2: Switch to Test Mode

It is strongly recommended that you familiarize yourself with the product configuration and API integration in test mode before switching to the production environment.

In Test Mode, all the operations and transactions are in sandbox.

Step3: Get your API keys

API Keys are secret tokens used to authenticate your requests. They are unique to your account and should be kept confidential.

On the top navbar, navigate to the “Developer” section.

Click on the "Create api key" button in the "API Keys" tab.

Copy your API key and keep it safe.

Step4: Create your first product

The step by step guides below will help you understand how to add One Time Payment products and Subscription products.

Add One Time Payment Product (One-Time Payment)

Add Subscription Product (Subscriptions)

Step5: List all the product

You can list all the products through the API.

Step6: Get the product detail

You can get the product detail through the API.

Step7: Create checkout sessions for each payment and user independently.

With checkout sessions generated dynamically instead of just using a product payment link, you are able to pass a request_id to the session. This allows you to track the payment status and the user that made the payment in your system in a more organized way, and gives you the flexibility to track that payment with any ID you choose instead of relying on BagelPay IDs.

Create a new api key

Copy the product id

Request the payment gateway

curl --request POST \
  --url https://test.bagelpay.io/api/payments/checkouts \
  --header 'x-api-key: bagel_test_609C0CF4D5F64CC7910D26D9DF3A834B' \
  --header 'Content-Type: application/json' \
  --data '{
    "product_id": "prod_1961350758759763969",
    "request_id": "request_123456789",
    "units": 1,
    "customer": {
        "email": "user@example.com"
    },
    "metadata": {
        "key_1": "value_1",
        "key_2": "value_1",
        "key_N": "value_N"
    }
}'

The response is like below:

{
	"msg": "Operation successful",
	"code": 200,
	"data": {
		"object": "checkout",
		"units": 1,
		"metadata": {
			"key_1": "value_1",
			"key_2": "value_1",
			"key_N": "value_N"
		},
		"status": "pending",
		"mode": "test",
		"payment_id": "ch_1961373726999154689",
		"product_id": "prod_1961350758759763969",
		"request_id": null,
		"success_url": "https://test.bagelpay.io/success?aggregateId=XXXX",
		"checkout_url": "https://test.bagelpay.io/checkout/prod_1961350758759763969/ch_1961373726999154689",
		"created_at": "2025-08-29T10:21:51.773+00:00",
		"updated_at": "2025-08-29T10:21:51.773+00:00",
		"expires_on": "2025-08-29T11:21:51.773+00:00"
	}
}

The above request will return a checkout session object with a checkout_url that you can use to redirect the user to the payment page.

checkout_url example:

https://test.bagelpay.io/checkout/prod_1961350758759763969/ch_1961373726999154689

Step8: Set up webhooks for real-time updates

BaygelPay uses webhooks to push real-time notifications to you about your payments, subscriptions and refund. All webhooks use HTTPS and deliver a JSON payload that can be used by your application.

For the API details, please refer to the "Webhook User Guide".

Step9: Testing the checkout session

For testing payments, you could use the test card 4242 4242 4242 4242 with any expiration and CVV.