Bohudur cURL Documentation

Developer-first payment automation API.

Base URL

text

https://request.bohudur.one

Authentication

All API requests must include your API Key in headers.

Required Headers

http

Content-Type: application/json
AH-BOHUDUR-API-KEY: YOUR_API_KEY

Note

Keep your API key secret. Never expose it in frontend or client-side code.

API Flow Overview

Create a payment
Redirect user to payment page
Execute (finalize) payment
Receive webhook (optional)
Query payment data (Anytime when you need)

Create Payment

Creates a new payment session.

Endpoint

http

POST /create/v2/

cURL Example

bash

curl -X POST "https://request.bohudur.one/create/v2/" \
  -H "Content-Type: application/json" \
  -H "AH-BOHUDUR-API-KEY: YOUR_API_KEY" \
  -d '{
    "full_name": "Jane Doe",
    "email": "[email protected]",
    "amount": 10,
    "return_type": "GET",
    "redirect_url": "default",
    "cancel_url": "default",
    "metadata": {
      "data1": "value1",
      "data2": "value2"
    },
    "webhook": {
      "success": "https://example.com/success.php",
      "cancel": "https://example.com/cancel.php"
    }
  }'

Request Parameters

Field	Type	Required	Description
`full_name`	string	YES	Customer full name
`email`	string	YES	Customer email
`amount`	number	YES	Payment amount
`return_type`	string	YES	`GET` or `POST`
`redirect_url`	string	YES	Redirect URL after success
`cancel_url`	string	YES	Redirect URL after cancel
`metadata`	object	NO	Custom key-value data
`webhook.success`	string	NO	Success webhook URL
`webhook.cancel`	string	NO	Cancel webhook URL

Success Response

Returned when a payment link is created successfully.

Example Response

json

{
  "responseCode": 200,
  "message": "Payment created successfully",
  "status": "success",
  "paymentkey": "5RWS4w2w1R5nFAvoP5U0JS4O74UrMXGt",
  "payment_url": "https://checkout.bohudur.one/payment/5RWS4w2w1R5nFAvoP5U0JS4O74UrMXGt"
}

Response Parameters

Field	Type	Description
`responseCode`	number	HTTP-like response code. `200` indicates success.
`message`	string	Human-readable message describing the result.
`status`	string	Payment creation status. Always `success` on success.
`paymentkey`	string	A unique 32-character alphanumeric key generated for each payment.
`payment_url`	string	Hosted checkout URL where the customer completes the payment.

Failed Response

Returned when the payment request cannot be processed.

Example Response

json

{
  "responseCode": 3018,
  "message": "Oops! Internal error. Try again",
  "status": "failed"
}

Failed Response Parameters

Field	Type	Description
`responseCode`	number	Error code indicating the reason for failure.
`message`	string	Descriptive error message explaining what went wrong.
`status`	string	Request status. Always `failed` for errors.

Error Codes Reference

The following table lists all possible error codes returned by the Create Payment API.

Code	Message	Description
`3000`	API key not found	API key header is missing from the request.
`3001`	Required parameters not found	One or more mandatory fields are missing.
`3002`	Invalid Full Name Format	`full_name` must be a valid string.
`3003`	Invalid Email Format	Email address format is invalid.
`3004`	Invalid Amount Format	Amount must be a valid numeric value.
`3005`	Invalid Return Type Format	Only `GET` or `POST` is allowed.
`3006`	Invalid Return URL Format	`redirect_url` is not a valid URL.
`3007`	Invalid JSON format in metadata	`metadata` must be a valid JSON object.
`3008`	Invalid JSON format in webhook	`webhook` must be a valid JSON object.
`3009`	Invalid Cancel URL Format	`cancel_url` is not a valid URL.
`3010`	Invalid JSON format in metadata	`metadata` must be a valid JSON object.
`3011`	Invalid JSON format in webhook	`webhook` must be a valid JSON object.
`3012`	Invalid webhook actions	Only `success` and `cancel` actions are allowed.
`3013`	Invalid JSON format in metadata or webhook	One or both JSON objects are malformed.
`3014`	Invalid API key	Provided API key is incorrect or inactive.
`3015`	Oops! internal error. Try again.	Temporary server-side issue.
`3016`	Unknown amount provided	Amount value is not acceptable or supported.
`3017`	You don't have access	Request blocked due to IP restriction.
`3018`	Oops! Internal error. Try again.	Unexpected internal server error.
`3019`	Unable to create payment	Payment session could not be generated.

Error Handling Best Practices

Developer Tip

Always handle failed responses gracefully. Do not assume payment creation was successful without checking status and responseCode.

Important

Never rely solely on client-side responses. Always verify payment status using the Query API.

Execute Payment

Execute Payment and finalizes a payment.

Endpoint

http

POST /execute/v2/

cURL Example

bash

curl -X POST "https://request.bohudur.one/execute/v2/" \
  -H "Content-Type: application/json" \
  -H "AH-BOHUDUR-API-KEY: YOUR_API_KEY" \
  -d '{
    "paymentkey": "PAYMENT_KEY_HERE"
  }'

Success Response Example

json

{
  "full_name": "Gabriel Adams",
  "email": "[email protected]",
  "amount": 40,
  "converted_amount": 4878,
  "total_amount": 40,
  "transaction_fee": 0,
  "default_currency": "USD",
  "payment_currency": "BDT",
  "currency_value": 121.951,
  "metadata": [],
  "created_time": "2026-01-04 16:04:35",
  "payment_time": "2026-01-04 16:12:37",
  "paymentkey": "fnPwIkdIsMjN4FJxYxw6DF75GuW9qStn",
  "webhook": [],
  "payment_info": {
    "m0": "Stripe",
    "status": "VALID",
    "tran_date": "2026-01-04 16:05:04",
    "tran_id": "IGQM_695a3b59h6a9"
  },
  "status": "EXECUTED"
}

Response Parameters

Field	Type	Description
`full_name`	string	Customer’s full name
`email`	string	Customer’s email address
`amount`	number	Original payment amount in default currency
`converted_amount`	number	Amount converted to the payment currency
`total_amount`	number	Total amount charged (amount + fees)
`transaction_fee`	number	Transaction fees applied (if any)
`default_currency`	string	Your account default currency
`payment_currency`	string	Currency used for the payment
`currency_value`	number	Conversion rate applied (default → payment currency)
`metadata`	array	Optional metadata submitted during creation
`created_time`	string	Payment creation timestamp
`payment_time`	string	Time when the payment was completed by the customer
`paymentkey`	string	Unique key identifying this payment
`webhook`	array	Webhook URLs configured for this payment
`payment_info`	object	Transaction-specific info
`status`	string	Payment execution status. Always `EXECUTED` on success

Error Response Example

json

{
  "responseCode": 3108,
  "message": "Payment already executed!",
  "status": "failed"
}

Common Error Codes

Code	Message	Description
`3100`	API key not found	The request did not include an API key. Ensure the `AH-BOHUDUR-API-KEY` header is set.
`3101`	API key not valid	The provided API key is invalid or inactive.
`3102`	Invalid Payment Key	The `paymentkey` provided is malformed or does not exist.
`3103`	Invalid api key	The API key used does not match any active account.
`3104`	You don't have access! Your IP: ...	Your IP address is not authorized to perform this request. Replace `...` with your server IP in the message.
`3105`	Payment Data Not Found	No payment data exists for the given `paymentkey`.
`3106`	Payment is pending!	The payment has not yet been completed by the customer. Execute is only allowed after completion.
`3107`	Payment is cancelled!	The payment was cancelled by the customer or system.
`3108`	Payment already executed!	This payment has already been executed. Execution can only happen once.
`3109`	Failed to execute payment	The payment could not be executed due to a server or processing error.

Important

The Execute API is idempotent by design.
A payment can only be executed once. Any attempt to execute the same payment again will return Payment already executed!.
This prevents duplicate payments.

Query Payment API

The Query Payment API allows you to check the status and details of a payment using the paymentkey. This is useful for verifying payment status, retrieving transaction details, or confirming before executing a payment.

Endpoint

http

POST /query/v2/

cURL Example

bash

curl -X POST "https://request.bohudur.one/query/v2/" \
  -H "Content-Type: application/json" \
  -H "AH-BOHUDUR-API-KEY: YOUR_API_KEY" \
  -d '{
    "paymentkey": "PAYMENT_KEY_HERE"
  }'

Response Types

The Query API can return four types of responses, depending on the payment status.

1. PENDING Payment

Payment created but not yet completed by the user.

json

{
  "full_name": "Chloe Morales",
  "email": "[email protected]",
  "amount": 1,
  "converted_amount": 1,
  "total_amount": 1,
  "transaction_fee": 0,
  "default_currency": "USD",
  "payment_currency": "USD",
  "currency_value": 1,
  "metadata": [],
  "created_time": "2026-01-07 10:02:20",
  "payment_time": "NONE",
  "paymentkey": "7QWQsOhg9X7dgQlfRO4EPxWKK9qaCWka",
  "webhook": [],
  "payment_info": [],
  "status": "PENDING"
}

2. COMPLETED Payment

Payment successfully completed by the user.

json

{
  "full_name": "Jane Doe",
  "email": "[email protected]",
  "amount": 150,
  "converted_amount": 150,
  "total_amount": 150,
  "transaction_fee": 0,
  "default_currency": "USD",
  "payment_currency": "USD",
  "currency_value": 1,
  "metadata": [],
  "created_time": "2025-12-11 21:47:11",
  "payment_time": "2025-12-11 23:11:25",
  "paymentkey": "TYtsYll15iqsDqsR4h8EJrMfou9NavE2",
  "webhook": [],
  "payment_info": {
    "m0": "Stripe",
    "status": "succeeded",
    "tran_id": "IGQM_695a3b59h6a9"
  },
  "status": "COMPLETED"
}

Explanation

payment_time → Timestamp when payment was completed
payment_info → Contains transaction details (processor-specific info)
status → COMPLETED indicates payment is successful and ready for execution

3. EXECUTED Payment

Payment has been executed/confirmed via the Execute API.

json

{
  "full_name": "Gabriel Adams",
  "email": "[email protected]",
  "amount": 40,
  "converted_amount": 4878,
  "total_amount": 40,
  "transaction_fee": 0,
  "default_currency": "USD",
  "payment_currency": "BDT",
  "currency_value": 121.951,
  "metadata": [],
  "created_time": "2026-01-04 16:04:35",
  "payment_time": "2026-01-04 16:12:37",
  "paymentkey": "fnPwIkdIsMjN4FJxYxw6DF0I92W9qStn",
  "webhook": [],
  "payment_info": {
    "m0": "SSLCommerz",
    "status": "VALID",
    "tran_date": "2026-01-04 16:05:04",
    "tran_id": "SSLCZ_695a3b501c0a9",
    "val_id": "2601041612331iZhrh0JGKL0TyN",
    "currency": "BDT",
    "bank_tran_id": "2601041612331PW4mLgtug0uJ6x"
  },
  "status": "EXECUTED"
}

Important

An executed payment is final and cannot be executed again. This protects your system from duplicate payments and ensures each payment key is one-time use only.

4. CANCELLED Payment

Payment that was cancelled by the user or system.

json

{
  "full_name": "Jane Doe",
  "email": "[email protected]",
  "amount": 1,
  "converted_amount": 1,
  "total_amount": 1,
  "transaction_fee": 0,
  "default_currency": "USD",
  "payment_currency": "USD",
  "currency_value": 1,
  "metadata": {
    "data1": "value1",
    "data2": "value2"
  },
  "created_time": "2026-01-18 19:30:56",
  "payment_time": "NONE",
  "paymentkey": "P4m1OEiopqPy4cFx9QO0mARuzqxx7bsf",
  "webhook": {
    "success": "https://example.com/success.php",
    "cancel": "https://example.com/cancel.php"
  },
  "payment_info": [],
  "status": "CANCELLED"
}

Notice

A cancelled payment cannot be executed. If a user cancels a payment, the payment link becomes inactive and the status is set to CANCELLED.

Explanation

Field	Type	Description
`full_name`	string	Customer’s full name
`email`	string	Customer’s email
`amount`	number	Original payment amount
`converted_amount`	number	Amount converted to payment currency
`total_amount`	number	Total amount including fees
`transaction_fee`	number	Transaction fee applied (if any)
`default_currency`	string	Your account default currency
`payment_currency`	string	Payment currency
`currency_value`	number	Conversion rate applied
`metadata`	array	Optional metadata sent during creation
`created_time`	string	Payment creation timestamp
`payment_time`	string	Time payment completed (`NONE` if pending)
`paymentkey`	string	Unique identifier for this payment
`webhook`	array	Webhook URLs (if configured)
`payment_info`	array	Empty while pending
`status`	string	`PENDING`

Error Codes

Code	Message	Description
`3050`	API key not found	Request missing the `AH-BOHUDUR-API-KEY` header
`3051`	API key not valid	API key is invalid or inactive
`3052`	Invalid Payment Key	Provided `paymentkey` does not exist or is malformed
`3053`	Invalid api key	API key does not match an active account
`3054`	You don't have access! Your IP: ...	Request blocked due to IP restrictions
`3055`	Payment Data Not Found	No payment found for the given `paymentkey`

Webhooks

Bohudur sends webhook notifications to your server when a payment is successfully completed or cancelled. Webhook requests are sent using the HTTP POST method in JSON format.

Webhooks allow your system to automatically receive payment updates without polling the Query API.

When Webhooks Are Triggered

Success webhook → Sent when a payment is completed
Cancel webhook → Sent when a payment is cancelled by the user or system

Webhook Payload (Cancel)

Sent when a payment is cancelled.

json

{
  "full_name": "Jane Doe",
  "email": "[email protected]",
  "amount": 1,
  "paymentkey": "CrD85r3ibMK6ip38reUcuECvVhaF0xOT",
  "status": "CANCELLED"
}

Webhook Payload (Success)

Sent when a payment is completed successfully.

json

{
  "full_name": "Jane Doe",
  "email": "[email protected]",
  "amount": 1,
  "paymentkey": "CrD85r3ibMK6ip38reUcuECvVhaF0xOT",
  "status": "COMPLETED"
}

Webhook Parameters

Field	Type	Description
`full_name`	string	Customer’s full name
`email`	string	Customer’s email address
`amount`	number	Payment amount
`paymentkey`	string	Unique payment identifier
`status`	string	Payment status (`COMPLETED` or `CANCELLED`)

Best Practice

Always verify the payment status using the Query Payment API after receiving a webhook. Webhooks are reliable but should not be the only source of truth.

Important

Your webhook endpoint must return HTTP 200 OK to acknowledge successful receipt. Failure to respond correctly may slow down payment verification speed.

Summary

Webhooks are sent via POST
Data format is JSON
Triggered on payment success or cancellation
Use Query API for final verification

API Versioning

Current Version: v2
Base path includes versioning for stability

Changelog

v2: Improved response structure, webhook support, metadata support

Support

For technical support or integration issues, contact in Bohudur Telegram Support.

Bohudur cURL Documentation ​

Base URL ​

Authentication ​

Required Headers ​

API Flow Overview ​

Create Payment ​

Endpoint ​

cURL Example ​

Request Parameters ​

Success Response ​

Example Response ​

Response Parameters ​

Failed Response ​

Example Response ​

Failed Response Parameters ​

Error Codes Reference ​

Error Handling Best Practices ​

Execute Payment ​

Endpoint ​

cURL Example ​

Success Response Example ​

Response Parameters ​

Error Response Example ​

Common Error Codes ​

Query Payment API ​

Endpoint ​

cURL Example ​

Response Types ​

1. PENDING Payment ​

2. COMPLETED Payment ​

Explanation ​

3. EXECUTED Payment ​

4. CANCELLED Payment ​

Explanation ​

Error Codes ​

Webhooks ​

When Webhooks Are Triggered ​

Webhook Payload (Cancel) ​

Webhook Payload (Success) ​

Webhook Parameters ​

Summary ​

API Versioning ​

Changelog ​

Support ​

Bohudur cURL Documentation

Base URL

Authentication

Required Headers

API Flow Overview

Create Payment

Endpoint

cURL Example

Request Parameters

Success Response

Example Response

Response Parameters

Failed Response

Example Response

Failed Response Parameters

Error Codes Reference

Error Handling Best Practices

Execute Payment

Endpoint

cURL Example

Success Response Example

Response Parameters

Error Response Example

Common Error Codes

Query Payment API

Endpoint

cURL Example

Response Types

1. PENDING Payment

2. COMPLETED Payment

Explanation

3. EXECUTED Payment

4. CANCELLED Payment

Explanation

Error Codes

Webhooks

When Webhooks Are Triggered

Webhook Payload (Cancel)

Webhook Payload (Success)

Webhook Parameters

Summary

API Versioning

Changelog

Support