API References

Payment APIs #

Live payment APIs for creating, tracking, and cancelling payments

x-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.

Payment Env #

The payment environment is determined automatically by your credentials. #

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)

Env variables (For postman) #

Create a Postman environment (e.g., Rasedi Env) with the following minimal variables:

Variable Name	Description
x_id	Your merchant secret key from the Rasedi management panel
private_key	Your private key in PEM format
x_signature	Auto-generated by pre-request scripts
reference_code	Auto-generated after creating a payment; used in status/cancel requests

Note: Users only need to set x_id and private_key. The scripts handle the rest automatically.

‌If you don’t want to generate the x-signature manually #

You can use a Postman pre-request script to handle it for you automatically.

Set environment variables:
- x_id → your merchant secret key from the management panel
- private_key → your private key (PEM format)
Pre-request script will:
- Generate the x-signature for each request
- Use the current request method and relative URL
- Base64-encode the signature
Add headers to your request:
- x-id: Your secret key
- x-signature: {{x_signature}} (generated automatically by the pre-request script)

This way, every request is signed correctly without manual computation.

🔐 x-signature Generation (If you want to do it yourself) #

To 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>

Example

POST || sk_live_xxx || /v1/payment/rest/live/init

METHOD → HTTP method (GET, POST, …)
SECRET → your merchant secret key
RELATIVE_URL → path only (no domain, no query params)

Signing algorithm #

Algorithm: RSA (PKCS#1)
Encoding: Base64
Key: Your Secret key that you got from the panel
Passphrase: Your secret key

Reference (Node.js) #

import { sign } from "crypto";
function generateXSignature({
  method,
  secret,
  relativeUrl,
  privateKeyPem,
}) {
  if (!privateKeyPem) {
    throw new Error("privateKeyPem is undefined");
  }
  const rawSign = `${method} || ${secret} || ${relativeUrl}`;
  const bufSign = Buffer.from(rawSign, "utf-8");
  const signature = sign(null, bufSign, {
    key: privateKeyPem,
    passphrase: secret,
  });
  return signature.toString("base64");
}
// 🔴 HARDCODE TEMPORARILY (for debugging)
const PRIVATE_KEY = `
-----BEGIN ENCRYPTED PRIVATE KEY-----
MIIFHDBOBgkqhkiG9w0BBQ0wQTApBgkqhkiG9w0BBQwwHAQI...
-----END ENCRYPTED PRIVATE KEY-----
`;
const sig = generateXSignature({
  method: "POST",
  secret: "sk_live_xxx", // * Secret that you got from your panel 
  relativeUrl: "/v1/payment/rest/live/create",
  privateKeyPem: PRIVATE_KEY,
});
console.log(sig);

Using the Signature in API Requests #

Use the generated signature as the value of the x-signature header when calling the APIs.

POSTCreate Payment #

https://api.rasedi.com/v1/payment/rest/live/create

Create Payment API #

Overview #

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.

Authentication #

This API uses a custom authentication mechanism with two required headers:

Headers #

Header	Type	Description
`x-signature`	string	Required. HMAC signature for request verification. Generated using your merchant secret key and request payload.
`x-id`	string	Required. Your unique Secret key that you got from your panel
`Content-Type`	string	Required. Must be `application/json`

Request Body (JSON) #

Field	Type	Required	Description	Example
`amount`	string	Yes	Payment amount in the smallest currency unit (e.g., cents for USD, fils for IQD). For 1500 IQD, send “150000”.	`"150000"`
`gateways`	array	Yes	Array of payment gateway codes to enable for this payment. At least one gateway must be specified.	`["FAST_PAY", "FIB"]`
`title`	string	Yes	Short title for the payment. Displayed to the customer on the payment page. Max 100 characters.	`"Order #1241"`
`description`	string	Yes	Detailed description of the payment. Helps customers understand what they’re paying for. Max 500 characters.	`"Payment for premium subscription"`
`collectFeeFromCustomer`	boolean	Yes	If `true`, payment gateway fees are added to the customer’s total. If `false`, fees are deducted from the merchant’s received amount.	`true`
`collectCustomerEmail`	boolean	Yes	If `true`, customer must provide their email address during payment.	`true`
`collectCustomerPhoneNumber`	boolean	Yes	If `true`, customer must provide their phone number during payment.	`false`
`redirectUrl`	string	Yes	URL where customers are redirected after successful payment. Must be a valid HTTPS URL.	`"https://merchant.com/payment/success"`
`callbackUrl`	string	Yes	Webhook URL where payment status updates are sent. Must be a valid HTTPS URL that can receive POST requests.	`"https://merchant.com/api/payment/callback"`
`allowPromoCode`	boolean	Yes	If `true`, customers can apply promotional discount codes during checkout.	`true`

Available Payment Gateways #

Gateway Code	Description	Currency
`FAST_PAY`	FastPay digital wallet	IQD
`FIB`	First Iraqi Bank	IQD
`ZAIN`	Zain Cash mobile wallet	IQD
`ASIA_PAY`	Asia Hawala payment gateway	IQD
`NASS_WALLET`	Nass digital wallet	IQD
`CREDIT_CARD`	International credit/debit cards	Multiple

Response Structure #

Success Response (200 OK) #

{
    "referenceCode": "7676c702-a2a7-4996-baf3-09a8d012ed09",
    "amount": "150000",
    "paidVia": null,
    "paidAt": null,
    "redirectUrl": "https://pay.pallawan.com/pay/live/7676c702-a2a7-4996-baf3-09a8d012ed09",
    "status": "PENDING",
    "payoutAmount": null
}

Response Fields #

Field	Type	Description
`referenceCode`	string	Human-readable reference code for tracking
`amount`	string	Payment amount
`paidAt`	Date	null
`redirectUrl`	string	The payment url

Error Handling #

Common Error Codes #

Status Code	Error Code	Description	Solution
`400`	`INVALID_AMOUNT`	Amount is invalid or below minimum	Ensure amount is a positive number in smallest currency unit
`400`	`INVALID_GATEWAY`	One or more gateway codes are invalid	Use only supported gateway codes from the list above
`400`	`MISSING_REQUIRED_FIELD`	Required field is missing from request	Check all required fields are included
`401`	`INVALID_SIGNATURE`	x-signature verification failed	Regenerate signature using correct secret key and request body
`401`	`INVALID_CREDENTIALS`	x-id or API key is invalid	Verify your merchant credentials
`403`	`GATEWAY_NOT_ENABLED`	Requested gateway is not enabled for your account	Contact support to enable the gateway
`403`	`INSUFFICIENT_PERMISSIONS`	API key lacks required permissions	Use an API key with payment creation permissions
`422`	`INVALID_URL`	redirectUrl or callbackUrl is malformed	Ensure URLs are valid HTTPS endpoints
`429`	`RATE_LIMIT_EXCEEDED`	Too many requests in short period	Implement exponential backoff and retry logic
`500`	`INTERNAL_ERROR`	Server error occurred	Retry the request after a few seconds

Error Response Format #

{
    "statusCode":400,
    "messages":["amount must be a valid price."]
}

Usage Notes #

Important Considerations #

Amount Format: Always send amounts in the smallest currency unit. For IQD (Iraqi Dinar), multiply the amount by 100. Example: 1,500 IQD = “150000”
Signature Security: Never expose your merchant secret key in client-side code. Generate signatures on your backend server.
Callback URL: Your callback endpoint must:
- Accept POST requests with JSON payload
- Respond with 200 OK status within 5 seconds
- Verify the callback signature to ensure authenticity
- Be publicly accessible (not localhost)
Payment Link Expiration: Payment links expire after 24 hours by default. Expired links cannot be used for payment.
Gateway Availability: Gateway availability may vary by region and time. Always handle cases where a gateway might be temporarily unavailable.
Fee 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.
Testing: Use the test environment with test credentials before going live. Test gateway codes may differ from production.

Best Practices #

Validate Input: Validate all input data before sending to the API
Handle Errors Gracefully: Implement proper error handling and user-friendly error messages
Log Requests: Log all API requests and responses for debugging and audit purposes
Monitor Callbacks: Set up monitoring for your callback endpoint to ensure you receive payment updates
Secure Storage: Store payment IDs and reference codes securely in your database
Customer Communication: Send payment links via secure channels (email, SMS, in-app notification)

Example Request #

curl -X POST https://api.rasedi.com/v1/payment/rest/live/create \
  -H "Content-Type: application/json" \
  -H "x-signature: a1b2c3d4e5f6..." \
  -H "x-id: merchant_12345" \
  -d '{
    "amount": "150000",
    "gateways": ["FAST_PAY", "FIB"],
    "title": "Order #1241",
    "description": "Payment for premium subscription",
    "collectFeeFromCustomer": true,
    "collectCustomerEmail": true,
    "collectCustomerPhoneNumber": false,
    "redirectUrl": "https://merchant.com/payment/success",
    "callbackUrl": "https://merchant.com/api/payment/callback",
    "allowPromoCode": true
  }'

Webhook Callback Structure #

When payment status changes, a POST request is sent to your callbackUrl:

{
    "referenceCode": "ref-292929",
    "status": "PAID",
    "payoutAmount": "15000",
}

Statuses will be:

export enum EXTERNAL_PAYMENT_STATUS {
  PENDING = "PENDING",
  PAID = "PAID",
  CANCELED = "CANCELED",
  FAILED = "FAILED",
  TIMED_OUT = "TIMED_OUT",
}

HEADERS

Content-Type: application/json

x-signature: {{x_signature}} – HMAC signature for request authentication (Auto generated using a script)

x-id: {{x_id}} API identifier for merchant authentication

Bodyraw

{
  "amount": "150000",
  "gateways": ["FAST_PAY"],
  "title": "Order #1241",
  "description": "Payment for premium subscription",
  "collectFeeFromCustomer": true,
  "collectCustomerEmail": true,
  "collectCustomerPhoneNumber": false,
  "redirectUrl": "https://merchant.com/payment/success",
  "callbackUrl": "https://merchant.com/api/payment/callback",
  "allowPromoCode": true
}

GET Get Payment Status #

https://api.rasedi.com/v1/payment/rest/live/status/{{reference_code}}

Get Payment Status #

Overview #

This 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.

Endpoint #

GET https://api.rasedi.com/v1/payment/rest/live/status/PAY_XXXXXX

Path Variables #

Parameter	Type	Required	Description
`referenceCode`	string	Yes	The unique reference code assigned to the payment transaction when it was created. This identifier is used to retrieve the specific payment’s status.

Headers #

Header	Type	Required	Description
`Content-Type`	string	Yes	Must be set to `application/json` to indicate the expected response format.
`x-signature`	string	Yes	A cryptographic signature used to verify the authenticity of the request. This is typically generated using your merchant secret key and request parameters to ensure the request hasn’t been tampered with.
`x-id`	string	Yes	Required. Your unique Secret key that you got from your panel

Authentication & Security #

This endpoint uses a combination of authentication mechanisms:

Merchant 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
- Include relevant request parameters (reference code, timestamp, etc.) in the signature calculation
- Consult the Pallawan API documentation for the exact signature generation algorithm

Security Best Practices:

Store your merchant secret key securely (use environment variables)
Never expose your x-id or signature generation logic in client-side code
Implement request timeout handling
Use HTTPS for all API communications (enforced by the endpoint)

Response #

Success Response (200 OK) #

The endpoint returns the current payment status along with transaction details.

Possible Payment Statuses:

PENDING – Payment has been initiated but not yet completed
PAID – Payment was successfully processed
FAILED – Payment processing failed
CANCELED – Payment was cancelled by the user or merchant
TIMED_OUT – Payment link timed out

Error Responses #

Status Code	Description
`400 Bad Request`	Invalid reference code format or missing required parameters
`401 Unauthorized`	Invalid or missing authentication credentials (`x-id` or `x-signature`)
`403 Forbidden`	Valid credentials but insufficient permissions to access this payment
`404 Not Found`	No payment found with the provided reference code
`429 Too Many Requests`	Rate limit exceeded, retry after a delay
`500 Internal Server Error`	Server-side error, contact support if persistent

Use Cases #

Order Confirmation: Check payment status before fulfilling an order
Webhook Verification: Verify webhook notifications by querying the actual payment status
Customer Support: Look up payment status when handling customer inquiries
Reconciliation: Verify payment states during financial reconciliation processes
Polling: Periodically check status for payments awaiting completion (implement exponential backoff)

Example Usage #

// Example: Checking payment status
const referenceCode = "PAY-123456789";
const merchantId = "your-secret-key";
const signature = generateSignature(referenceCode); // Your signature generation function
const response = await fetch(`https://api.rasedi.com/v1/payment/rest/live/status/${referenceCode}`, {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'x-id': merchantId,
    'x-signature': signature
  }
});
const paymentStatus = await response.json();
console.log('Payment Status:', paymentStatus);

Notes #

Reference codes are unique and case-sensitive
Status updates may have a slight delay (typically < 30 seconds)
Implement proper error handling for all possible response codes
Consider caching successful status checks to reduce API calls
For real-time updates, consider using webhooks instead of polling

HEADERS

Content-Type

application/json

x-signature

x-id

Example Request

Get Payment Status

curl

curl --location -g 'https://api.rasedi.com/v1/payment/rest/live/status/{{reference_code}}' \
--header 'Content-Type: application/json' \
--header 'x-signature: {{x_signature}}' \
--header 'x-id: {{x_id}}'

Example Response

Body
Headers (0)

No response body

This request doesn’t return any response body

PATCH Cancel Payment #

https://api.rasedi.com/v1/payment/rest/live/cancel/{{reference_code}}

Cancel Payment #

This endpoint cancels an existing payment transaction using its unique reference code.

Request Details #

Method: PATCH

Endpoint: https://api.rasedi.com/v1/payment/rest/live/cancel/PAY_XXXXXX

Path Variables #

Variable	Type	Required	Description
`referenceCode`	string	Yes	The unique reference code of the payment transaction to be cancelled

Headers #

Header	Type	Required	Description
`x-id`	string	Yes	Your secret key you got from you panel
`x-signature`	string	Yes	Request signature for authentication and integrity verification
`Content-Type`	string	Yes	Must be set to `application/json`

Request Body #

This endpoint does not require a request body.

Authentication & Security #

This endpoint uses a signature-based authentication mechanism:

The 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

Response #

Success Response (200 OK) #

The payment has been successfully cancelled. The response will contain the updated payment status.

Error Responses #

400 Bad Request – Invalid reference code or payment cannot be cancelled (e.g., already completed or refunded)
401 Unauthorized – Invalid or missing authentication credentials (x-id or x-signature)
404 Not Found – Payment with the specified reference code does not exist
500 Internal Server Error – Server-side error occurred while processing the cancellation

Use Cases #

Cancel a payment before it is processed
Handle user-initiated cancellation requests
Implement timeout-based automatic cancellations
Rollback failed or incomplete transactions

Notes #

Payment cancellation may only be possible within a specific time window or payment state
Once a payment is successfully processed or settled, cancellation may not be available (refund may be required instead)
Always verify the payment status before attempting cancellation

Payment APIs #

Payment Env #

The payment environment is determined automatically by your credentials. #

Env variables (For postman) #

‌If you don’t want to generate the x-signature manually #

🔐 x-signature Generation (If you want to do it yourself) #

Signing algorithm #

Reference (Node.js) #

Using the Signature in API Requests #

POSTCreate Payment #

Create Payment API #

Overview #

Authentication #

Headers #

Request Body (JSON) #

Available Payment Gateways #

Response Structure #

Success Response (200 OK) #

Response Fields #

Error Handling #

Common Error Codes #

Error Response Format #

Usage Notes #

Important Considerations #

Best Practices #

Example Request #

Webhook Callback Structure #

GET Get Payment Status #

Get Payment Status #

Overview #

Endpoint #

Path Variables #

Headers #

Authentication & Security #

Response #

Success Response (200 OK) #

Error Responses #

Use Cases #

Example Usage #

Notes #

PATCH Cancel Payment #

Cancel Payment #

Request Details #

Path Variables #

Headers #

Request Body #

Authentication & Security #

Response #

Success Response (200 OK) #

Error Responses #

Use Cases #

Notes #

Share This Article :

Leave a Reply Cancel reply