OnePayBD API Documentation

Introduction

The OnePayBD API enables seamless integration with the bKash payment gateway, supporting token generation, payment creation, execution, and status checking. This documentation provides detailed instructions for API key users to interact with the API endpoints.

Base URL: https://api.onepaybd.com

Authentication

All endpoints require a valid apikey header for authentication. The API key is validated against the OnePayBD database, and each successful request increments the user's request counter.

General Request Headers

Header Name Value Description
Content-Type application/json Specifies that the request body is in JSON format.
Accept application/json Indicates that the client expects a JSON response.
apikey <Your-API-Key> The API key provided by OnePayBD for authentication.

Grant Token

Generates an access token for bKash payment APIs, used as the Authorization header in subsequent requests.

Create Payment

Initiates a payment request with bKash, returning a payment ID and details for execution.

Execute Payment

Completes a payment transaction using the paymentID from the Create Payment API.

Payment Status

Retrieves the current status of a payment using the paymentID.

Demo PHP Code

Below is a sample PHP script demonstrating how to use the OnePayBD API to generate a token, create a payment, and execute it. 


<?php
// OnePayBD API Demo
$base_url = "https://api.onepaybd.com";
$api_key = "puqknyhi8cNx2LVdU5vAG0s6tlIoFSE9D3MeTZHfrJBb";

// Function to make API requests
function makeApiRequest($url, $headers, $data = null, $method = "POST") {
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
    curl_setopt($ch, CURLOPT_TIMEOUT, 30);
    
    if ($method === "POST" && $data) {
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    }
    
    $response = curl_exec($ch);
    $http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    return [
        'http_code' => $http_code,
        'response' => json_decode($response, true)
    ];
}

// Step 1: Get Token
$token_headers = [
    "Content-Type: application/json",
    "Accept: application/json",
    "apikey: $api_key"
];
$token_result = makeApiRequest("$base_url/token", $token_headers);

if ($token_result['http_code'] !== 200 || $token_result['response']['statusCode'] !== "0000") {
    die("Token Error: " . ($token_result['response']['error'] ?? "Failed to get token"));
}

$id_token = $token_result['response']['id_token'];
echo "Token Obtained: $id_token\n";

// Step 2: Create Payment
$create_headers = [
    "Content-Type: application/json",
    "Accept: application/json",
    "apikey: $api_key",
    "Authorization: Bearer $id_token"
];
$create_data = [
    "mode" => "0011",
    "payerReference" => "0011",
    "callbackURL" => "http://yourdomain.com",
    "merchantAssociationInfo" => "MI05MID54RF09123456One",
    "amount" => "50",
    "currency" => "BDT",
    "intent" => "sale",
    "merchantInvoiceNumber" => "Inv0124"
];
$create_result = makeApiRequest("$base_url/create", $create_headers, $create_data);

if ($create_result['http_code'] !== 200 || $create_result['response']['statusCode'] !== "0000") {
    die("Create Payment Error: " . ($create_result['response']['error'] ?? "Failed to create payment"));
}

$payment_id = $create_result['response']['paymentID'];
$bkash_url = $create_result['response']['bkashURL'];
echo "Payment Created: $payment_id\nRedirect to: $bkash_url\n";

// Step 3: Execute Payment (after user completes payment)
$execute_headers = [
    "Content-Type: application/json",
    "Accept: application/json",
    "apikey: $api_key",
    "Authorization: Bearer $id_token"
];
$execute_data = [
    "paymentID" => $payment_id
];
$execute_result = makeApiRequest("$base_url/execute", $execute_headers, $execute_data);

if ($execute_result['http_code'] !== 200 || $execute_result['response']['statusCode'] !== "0000") {
    die("Execute Payment Error: " . ($execute_result['response']['error'] ?? "Failed to execute payment"));
}

echo "Payment Executed: Transaction Status - " . $execute_result['response']['transactionStatus'] . "\n";
?>

Notes

  • Replace puqknyhi8cNx2LVdU5vAG0s6tlIoFSE9D3MeTZHfrJBb with your actual API key.
  • Redirect users to $bkash_url after creating the payment.
  • Handle errors appropriately in production code.

Error Handling

The API returns HTTP status codes and JSON error messages for various scenarios.

HTTP Code Description Example Response
200 Success Varies by endpoint
400 Bad Request (missing/invalid parameters) {"error": "Missing required field: amount"}
403 Forbidden (invalid API key) {"error": "Invalid API key"}
500 Server Error {"error": "Database connection failed"}

Security Considerations

  • API Key: Keep your API key confidential. Do not expose it in client-side code or public repositories.
  • HTTPS: Use HTTPS for all requests to ensure data security.
  • Authorization Token: Include the id_token in the Authorization header for /create, /execute, and /status.
  • Input Validation: Ensure all required fields are provided and correctly formatted.

Contact Support

For assistance with integration or API issues, contact OnePayBD support: