Bohudur cURL Documentation

Developer-first payment automation API.

Base URL

https://request.bohudur.one

Authentication

All API requests must include your API Key in headers.

Required Headers

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

1. Create a payment
2. Redirect user to payment page
3. Execute (finalize) payment
4. Receive webhook (optional)
5. Query payment data (Anytime when you need)

Create Payment

Creates a new payment session.

Endpoint

POST /create/v2/

cURL Example

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": "janedoe@gmail.com",
    "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

{
  "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

{
  "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

POST /execute/v2/

cURL Example

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

{
  "full_name": "Gabriel Adams",
  "email": "jsondoe@gmail.com",
  "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

{
  "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

POST /query/v2/

cURL Example

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.

{
  "full_name": "Chloe Morales",
  "email": "demo@gmail.com",
  "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.

{
  "full_name": "Jane Doe",
  "email": "demo@gmail.com",
  "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.

{
  "full_name": "Gabriel Adams",
  "email": "demo@gmail.com",
  "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.

{
  "full_name": "Jane Doe",
  "email": "demo@gmail.com",
  "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.

{
  "full_name": "Jane Doe",
  "email": "janedoe@gmail.com",
  "amount": 1,
  "paymentkey": "CrD85r3ibMK6ip38reUcuECvVhaF0xOT",
  "status": "CANCELLED"
}

---

Webhook Payload (Success)

Sent when a payment is completed successfully.

{
  "full_name": "Jane Doe",
  "email": "janedoe@gmail.com",
  "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.