API · scope create_payment

Create charge

Creates a payment and returns the hosted checkout link. This endpoint is compatible with PipraPay-style clients. If you are writing a new integration, you can use it or the native checkout endpoint. Both create the same kind of payment.

POST https://payment.yamin.bd/api/create-charge
Content-Type: application/json
MHS-GUARANTEEPAY-API-KEY: YOUR_API_KEY

Body fields

Field	Required	Notes
`full_name`	yes	Customer name shown on checkout.
`email_mobile`	yes*	Customer email or mobile number. An email fills `email_address`; anything else fills `mobile_number`.
`email_address`	no	Used when `email_mobile` is a mobile number. Defaults to `customer@example.com`.
`mobile_number`	no	Used when `email_mobile` is an email. Defaults to `0000000000`.
`amount`	yes	Positive plain decimal, e.g. `"500"` or `"150.50"`. No commas or currency symbols.
`currency`	no	Defaults to `BDT`. Must be enabled under Currency Settings, or you get `INVALID_CURRENCY`.
`metadata`	no	JSON object (or JSON string). Returned unchanged in verify, refund and webhook payloads. Put your order ID here.
`redirect_url`	no	Where the customer returns after checkout. `return_url` is accepted as an alias. The host must be whitelisted.
`webhook_url`	no	Your server endpoint for payment webhooks. The host must be whitelisted.
`cancel_url`, `return_type`	no	Accepted for compatibility but not used. Cancelled payments return to `redirect_url` with `pp_status=canceled`.

* A valid email is required overall. Send it in email_mobile or email_address.

Example request

{
  "full_name": "Rahim Uddin",
  "email_mobile": "rahim@example.com",
  "mobile_number": "01700000000",
  "amount": "500",
  "currency": "BDT",
  "metadata": { "order_id": "ORD-1001" },
  "redirect_url": "https://shop.example.com/pay/return?order_id=ORD-1001",
  "webhook_url": "https://shop.example.com/hooks/guaranteepay"
}

Success response HTTP 200

{
  "status": true,
  "pp_id": "k3J9x…",
  "pp_url": "https://payment.yamin.bd/payment/k3J9x…"
}

Redirect the customer's browser to pp_url.
Save pp_id with your order. You need it to verify or refund the payment.
Any other response is an error in the form {"error":{"code":"…","message":"…"}}. See Errors.

When your monthly transaction limit is reached, you get HTTP 403 PLAN_LIMIT with an upgrade_url instead of a checkout link.