Payments API

The Payments API allows you to create and manage payment transactions.

Create Payment

Creates a new payment and returns a checkout URL.

POST /payments

Request Body

Field	Type	Required	Description
`amount`	number	Yes	Payment amount in the smallest currency unit
`currency`	string	Yes	Currency code (e.g., "BDT")
`customer_phone`	string	Yes	Customer's phone number
`customer_name`	string	No	Customer's name
`customer_email`	string	No	Customer's email
`callback_url`	string	Yes	URL for webhook notifications
`success_url`	string	No	Redirect URL after successful payment
`cancel_url`	string	No	Redirect URL if payment is cancelled
`metadata`	object	No	Custom key-value pairs

Example Request

cURL

curl -X POST https://api.shadhinpay.com/api/v1/payments \
  -H "Content-Type: application/json" \
  -H "Client-Id: your_client_id" \
  -H "Business-Id: your_business_id" \
  -H "Secret-Key: your_secret_key" \
  -d '{
    "amount": 1500,
    "currency": "BDT",
    "customer_phone": "8801712345678",
    "customer_name": "John Doe",
    "customer_email": "john@example.com",
    "callback_url": "https://yoursite.com/webhook",
    "success_url": "https://yoursite.com/success",
    "cancel_url": "https://yoursite.com/cancel",
    "metadata": {
      "order_id": "ORD-12345",
      "product": "Premium Plan"
    }
  }'

Example Response

201 Created

{
  "success": true,
  "message": "Payment initiated successfully",
  "data": {
    "payment_id": "SP_1234567890",
    "status": "INITIATED",
    "amount": 1500,
    "currency": "BDT",
    "payment_url": "https://pay.shadhinpay.com/checkout/SP_1234567890",
    "expires_at": "2024-01-01T12:15:00Z",
    "created_at": "2024-01-01T12:00:00Z"
  }
}

Get Payment

Retrieves details of a specific payment.

GET /payments/{payment_id}

Path Parameters

Parameter	Type	Description
`payment_id`	string	The unique payment identifier

Example Request

cURL

curl -X GET https://api.shadhinpay.com/api/v1/payments/SP_1234567890 \
  -H "Client-Id: your_client_id" \
  -H "Business-Id: your_business_id" \
  -H "Secret-Key: your_secret_key"

Example Response

200 OK

{
  "success": true,
  "data": {
    "payment_id": "SP_1234567890",
    "status": "COMPLETED",
    "amount": 1500,
    "currency": "BDT",
    "customer_phone": "8801712345678",
    "customer_name": "John Doe",
    "transaction_id": "TXN_ABC123",
    "payment_method": "bkash",
    "completed_at": "2024-01-01T12:05:00Z",
    "created_at": "2024-01-01T12:00:00Z",
    "metadata": {
      "order_id": "ORD-12345",
      "product": "Premium Plan"
    }
  }
}

List Payments

Retrieves a paginated list of payments for your business.

GET /payments

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`limit`	integer	20	Items per page (max 100)
`status`	string	-	Filter by status
`from_date`	string	-	Start date (ISO 8601)
`to_date`	string	-	End date (ISO 8601)

Example Request

cURL

curl -X GET "https://api.shadhinpay.com/api/v1/payments?status=COMPLETED&limit=10" \
  -H "Client-Id: your_client_id" \
  -H "Business-Id: your_business_id" \
  -H "Secret-Key: your_secret_key"

Example Response

200 OK

{
  "success": true,
  "data": {
    "payments": [
      {
        "payment_id": "SP_1234567890",
        "status": "COMPLETED",
        "amount": 1500,
        "currency": "BDT",
        "created_at": "2024-01-01T12:00:00Z"
      }
    ],
    "pagination": {
      "current_page": 1,
      "total_pages": 5,
      "total_items": 48,
      "items_per_page": 10
    }
  }
}

Refund Payment

Creates a refund for a completed payment.

POST /payments/{payment_id}/refund

Path Parameters

Parameter	Type	Description
`payment_id`	string	The payment to refund

Request Body

Field	Type	Required	Description
`amount`	number	No	Partial refund amount (defaults to full)
`reason`	string	No	Reason for the refund

Example Request

cURL

curl -X POST https://api.shadhinpay.com/api/v1/payments/SP_1234567890/refund \
  -H "Content-Type: application/json" \
  -H "Client-Id: your_client_id" \
  -H "Business-Id: your_business_id" \
  -H "Secret-Key: your_secret_key" \
  -d '{
    "amount": 500,
    "reason": "Customer requested partial refund"
  }'

Example Response

200 OK

{
  "success": true,
  "message": "Refund initiated successfully",
  "data": {
    "refund_id": "RF_9876543210",
    "payment_id": "SP_1234567890",
    "amount": 500,
    "status": "PROCESSING",
    "created_at": "2024-01-02T10:00:00Z"
  }
}

Payment Statuses

Status	Description
`INITIATED`	Payment created, waiting for customer
`PROCESSING`	Customer is completing payment
`COMPLETED`	Payment successful
`FAILED`	Payment failed
`CANCELLED`	Payment cancelled by customer
`EXPIRED`	Payment link expired
`REFUNDED`	Payment was refunded

Payments API

On this page