Live payment APIs for creating, tracking, and cancelling payments
\nx-id: The merchant’s private Secret key issued via the management panel
x-signature: HMAC signature for request verification. Generated using your merchant secret key and request payload.
If you use v1/payment/rest/live → requests are processed in live mode (Provide your live and secret)
If you use v1/payment/rest/test → requests are processed in Test mode (Provide your test private and secret)
Create a Postman environment (e.g., Rasedi Env) with the following minimal variables:
\n\n\nNote: Users only need to set x_id and private_key. The scripts handle the rest automatically.
\n
You can use a Postman pre-request script to handle it for you automatically.
\nSet environment variables:
\nx_id → your merchant secret key from the management panel
\nprivate_key → your private key (PEM format)
\nPre-request script will:
\nGenerate the x-signature for each request
\nUse the current request method and relative URL
\nBase64-encode the signature
\nAdd headers to your request:
\nx-id: Your secret key
\nx-signature: {{x_signature}} (generated automatically by the pre-request script)
\nThis way, every request is signed correctly without manual computation.
\nTo authenticate requests, each API call must include a valid x-signature header.
How x-signature is created
The signature is generated by signing a raw string with your private key, then encoding the result in Base64.
*Raw string format*
<METHOD> || <SECRET> || <RELATIVE_URL>\n\nExample
\nPOST || sk_live_xxx || /v1/payment/rest/live/init\n\nMETHOD → HTTP method (GET, POST, …)
\nSECRET → your merchant secret key
\nRELATIVE_URL → path only (no domain, no query params)
\nAlgorithm: RSA (PKCS#1)
\nEncoding: Base64
\nKey: Your Secret key that you got from the panel
Passphrase: Your secret key
\nimport { sign } from \"crypto\";\nfunction generateXSignature({\n method,\n secret,\n relativeUrl,\n privateKeyPem,\n}) {\n if (!privateKeyPem) {\n throw new Error(\"privateKeyPem is undefined\");\n }\n const rawSign = `${method} || ${secret} || ${relativeUrl}`;\n const bufSign = Buffer.from(rawSign, \"utf-8\");\n const signature = sign(null, bufSign, {\n key: privateKeyPem,\n passphrase: secret,\n });\n return signature.toString(\"base64\");\n}\n// 🔴 HARDCODE TEMPORARILY (for debugging)\nconst PRIVATE_KEY = `\n-----BEGIN ENCRYPTED PRIVATE KEY-----\nMIIFHDBOBgkqhkiG9w0BBQ0wQTApBgkqhkiG9w0BBQwwHAQI...\n-----END ENCRYPTED PRIVATE KEY-----\n`;\nconst sig = generateXSignature({\n method: \"POST\",\n secret: \"sk_live_xxx\", // * Secret that you got from your panel \n relativeUrl: \"/v1/payment/rest/live/create\",\n privateKeyPem: PRIVATE_KEY,\n});\nconsole.log(sig);\n\nUse the generated signature as the value of the x-signature header when calling the APIs.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"Payment Env","slug":"payment-env"},{"content":"Env variables (For postman)","slug":"env-variables-for-postman"},{"content":"If you don’t want to generate the x-signature manually","slug":"if-you-dont-want-to-generate-the-x-signature-manually"},{"content":"🔐 x-signature Generation (If you want to do it yourself)","slug":"x-signature-generation-if-you-want-to-do-it-yourself"},{"content":"Signing algorithm","slug":"signing-algorithm"}],"owner":"52657755","collectionId":"b9c347a0-29e7-4d0b-b794-17bbafefe9ea","publishedId":"2sBXcGDKeT","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"0118d9"},"publishDate":"2026-02-25T07:15:12.000Z"},"item":[{"name":"Create Payment","event":[{"listen":"prerequest","script":{"id":"d4ae6566-6027-4835-b865-7b8a6ad208fb","exec":["// ----- INPUTS -----","const method = pm.request.method;","const secret = pm.environment.get(\"x_id\");","const url = pm.request.url;","const relativeUrl = \"/\" + url.path.join(\"/\");","","if (!secret) throw new Error(\"x_id (merchant secret) not set in environment variables\");","const PRIVATE_KEY_PEM = pm.environment.get(\"private_key\");","if (!PRIVATE_KEY_PEM) throw new Error(\"Private key not set in environment variables\");","","// ----- HELPERS -----","function pemToArrayBuffer(pem) {"," const b64 = pem"," .replace(/-----BEGIN PRIVATE KEY-----/, \"\")"," .replace(/-----END PRIVATE KEY-----/, \"\")"," .replace(/\\s+/g, \"\");"," const binary = atob(b64);"," const bytes = new Uint8Array(binary.length);"," for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);"," return bytes.buffer;","}","","// ----- SIGNING -----","(async () => {"," const rawSign = `${method} || ${secret} || ${relativeUrl}`;"," const data = new TextEncoder().encode(rawSign);",""," // Import Ed25519 private key"," const privateKey = await crypto.subtle.importKey("," \"pkcs8\","," pemToArrayBuffer(PRIVATE_KEY_PEM),"," { name: \"Ed25519\" },"," false,"," [\"sign\"]"," );",""," // Sign the data"," const signature = await crypto.subtle.sign(\"Ed25519\", privateKey, data);",""," // Convert to Base64"," const base64Signature = btoa(String.fromCharCode(...new Uint8Array(signature)));",""," // Store in environment variable"," pm.environment.set(\"x_signature\", base64Signature);"," console.log(\"X-Signature:\", base64Signature);","})();"],"type":"text/javascript","packages":{},"requests":{}}},{"listen":"test","script":{"id":"819d741d-1a37-4466-8569-d07af5743cbb","exec":["// Parse response JSON first","const response = pm.response.json();","","// Get reference code","const referenceCode = response.referenceCode;","","if (!referenceCode) {"," throw new Error(\"reference_code not found in response\");","}","","// Set environment variable","pm.environment.set(\"reference_code\", referenceCode);"],"type":"text/javascript","packages":{},"requests":{}}}],"id":"14debf60-9232-4d34-89dd-cdf199317062","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"},{"key":"x-signature","value":"{{x_signature}}","description":"HMAC signature for request authentication (Auto generated using a script)
\n"},{"key":"x-id","value":"YOUR_API_KEY","description":"API identifier for merchant authentication
\n"}],"body":{"mode":"raw","raw":"{\n \"amount\": \"150000\",\n \"gateways\": [\n \"FAST_PAY\",\n \"FIB\",\n \"ZAIN\",\n \"ASIA_PAY\",\n \"NASS_WALLET\",\n \"CREDIT_CARD\"\n ],\n \"title\": \"Order #1241\",\n \"description\": \"Payment for premium subscription\",\n \"collectFeeFromCustomer\": true,\n \"collectCustomerEmail\": true,\n \"collectCustomerPhoneNumber\": false,\n \"redirectUrl\": \"https://merchant.com/payment/success\",\n \"callbackUrl\": \"https://merchant.com/api/payment/callback\",\n \"allowPromoCode\": true\n}","options":{"raw":{"language":"json"}}},"url":"https://api.rasedi.com/v1/payment/rest/live/create","description":"This endpoint creates a new payment request in the Rasedi payment system. It generates a payment link that can be shared with customers to collect payments through various payment gateways. The API supports multiple payment methods and provides flexible configuration options for fee collection, customer data collection, and payment flow customization.
\nThis API uses a custom authentication mechanism with two required headers:
\n{\n \"referenceCode\": \"7676c702-a2a7-4996-baf3-09a8d012ed09\",\n \"amount\": \"150000\",\n \"paidVia\": null,\n \"paidAt\": null,\n \"redirectUrl\": \"https://pay.pallawan.com/pay/live/7676c702-a2a7-4996-baf3-09a8d012ed09\",\n \"status\": \"PENDING\",\n \"payoutAmount\": null\n}\n\n{\n \"statusCode\":400,\n \"messages\":[\"amount must be a valid price.\"]\n}\n\nAmount Format: Always send amounts in the smallest currency unit. For IQD (Iraqi Dinar), multiply the amount by 100. Example: 1,500 IQD = \"150000\"
\nSignature Security: Never expose your merchant secret key in client-side code. Generate signatures on your backend server.
\nCallback URL: Your callback endpoint must:
\nAccept POST requests with JSON payload
\nRespond with 200 OK status within 5 seconds
\nVerify the callback signature to ensure authenticity
\nBe publicly accessible (not localhost)
\nPayment Link Expiration: Payment links expire after 24 hours by default. Expired links cannot be used for payment.
\nGateway Availability: Gateway availability may vary by region and time. Always handle cases where a gateway might be temporarily unavailable.
\nFee Collection: When collectFeeFromCustomer is true, the customer sees the total amount including fees. When false, you receive the amount minus gateway fees.
Idempotency: To prevent duplicate payments, implement idempotency on your side by tracking payment creation requests.
\nTesting: Use the test environment with test credentials before going live. Test gateway codes may differ from production.
\nValidate Input: Validate all input data before sending to the API
\nHandle Errors Gracefully: Implement proper error handling and user-friendly error messages
\nLog Requests: Log all API requests and responses for debugging and audit purposes
\nMonitor Callbacks: Set up monitoring for your callback endpoint to ensure you receive payment updates
\nSecure Storage: Store payment IDs and reference codes securely in your database
\nCustomer Communication: Send payment links via secure channels (email, SMS, in-app notification)
\ncurl -X POST https://api.rasedi.com/v1/payment/rest/live/create \\\n -H \"Content-Type: application/json\" \\\n -H \"x-signature: a1b2c3d4e5f6...\" \\\n -H \"x-id: merchant_12345\" \\\n -d '{\n \"amount\": \"150000\",\n \"gateways\": [\"FAST_PAY\", \"FIB\"],\n \"title\": \"Order #1241\",\n \"description\": \"Payment for premium subscription\",\n \"collectFeeFromCustomer\": true,\n \"collectCustomerEmail\": true,\n \"collectCustomerPhoneNumber\": false,\n \"redirectUrl\": \"https://merchant.com/payment/success\",\n \"callbackUrl\": \"https://merchant.com/api/payment/callback\",\n \"allowPromoCode\": true\n }'\n\nWhen payment status changes, a POST request is sent to your callbackUrl:
{\n \"referenceCode\": \"ref-292929\",\n \"status\": \"PAID\",\n \"payoutAmount\": \"15000\",\n}\n\nStatuses will be:
\nexport enum EXTERNAL_PAYMENT_STATUS {\n PENDING = \"PENDING\",\n PAID = \"PAID\",\n CANCELED = \"CANCELED\",\n FAILED = \"FAILED\",\n TIMED_OUT = \"TIMED_OUT\",\n}\n\nThis endpoint retrieves the current status of a payment transaction using a unique reference code. It allows merchants to track and verify payment states in real-time.
\nGET https://api.rasedi.com/v1/payment/rest/live/status/PAY_XXXXXX\n\nThis endpoint uses a combination of authentication mechanisms:
\nMerchant Identification: The x-id header identifies your merchant account
Request Signing: The x-signature header provides request integrity verification
The signature should be generated using HMAC-SHA256 or similar cryptographic algorithm
\nInclude relevant request parameters (reference code, timestamp, etc.) in the signature calculation
\nConsult the Pallawan API documentation for the exact signature generation algorithm
\nSecurity Best Practices:
\nStore your merchant secret key securely (use environment variables)
\nNever expose your x-id or signature generation logic in client-side code
Implement request timeout handling
\nUse HTTPS for all API communications (enforced by the endpoint)
\nThe endpoint returns the current payment status along with transaction details.
\nPossible Payment Statuses:
\nPENDING - Payment has been initiated but not yet completed
\nPAID - Payment was successfully processed
\nFAILED - Payment processing failed
\nCANCELED - Payment was cancelled by the user or merchant
\nTIMED_OUT - Payment link timed out
\nOrder Confirmation: Check payment status before fulfilling an order
\nWebhook Verification: Verify webhook notifications by querying the actual payment status
\nCustomer Support: Look up payment status when handling customer inquiries
\nReconciliation: Verify payment states during financial reconciliation processes
\nPolling: Periodically check status for payments awaiting completion (implement exponential backoff)
\n// Example: Checking payment status\nconst referenceCode = \"PAY-123456789\";\nconst merchantId = \"your-secret-key\";\nconst signature = generateSignature(referenceCode); // Your signature generation function\nconst response = await fetch(`https://api.rasedi.com/v1/payment/rest/live/status/${referenceCode}`, {\n method: 'GET',\n headers: {\n 'Content-Type': 'application/json',\n 'x-id': merchantId,\n 'x-signature': signature\n }\n});\nconst paymentStatus = await response.json();\nconsole.log('Payment Status:', paymentStatus);\n\nReference codes are unique and case-sensitive
\nStatus updates may have a slight delay (typically < 30 seconds)
\nImplement proper error handling for all possible response codes
\nConsider caching successful status checks to reduce API calls
\nFor real-time updates, consider using webhooks instead of polling
\nThis endpoint cancels an existing payment transaction using its unique reference code.
\nMethod: PATCH
Endpoint: https://api.rasedi.com/v1/payment/rest/live/cancel/PAY_XXXXXX
This endpoint does not require a request body.
\nThis endpoint uses a signature-based authentication mechanism:
\nThe x-id is Client secret key that you got from your panel
The x-signature header contains a cryptographic signature to verify the request authenticity and prevent tampering
Ensure both credentials are kept secure and never exposed in client-side code
\nThe payment has been successfully cancelled. The response will contain the updated payment status.
\n400 Bad Request - Invalid reference code or payment cannot be cancelled (e.g., already completed or refunded)
\n401 Unauthorized - Invalid or missing authentication credentials (x-id or x-signature)
\n404 Not Found - Payment with the specified reference code does not exist
\n500 Internal Server Error - Server-side error occurred while processing the cancellation
\nCancel a payment before it is processed
\nHandle user-initiated cancellation requests
\nImplement timeout-based automatic cancellations
\nRollback failed or incomplete transactions
\nPayment cancellation may only be possible within a specific time window or payment state
\nOnce a payment is successfully processed or settled, cancellation may not be available (refund may be required instead)
\nAlways verify the payment status before attempting cancellation
\n