API Reference

The Salam Gateway API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes.

Base URL

Production

https://api.salamgateway.com/v1

Sandbox

https://sandbox-api.salamgateway.com/v1

Authentication

The API uses API keys for authentication. Include your secret key in the Authorization header:

Authorization: Bearer sk_live_your_api_key

WARNING

Never expose your secret API key in client-side code. Use the publishable key for frontend integrations.

Request Format

All POST and PUT requests must include:

Content-Type: application/json

Response Format

All responses return JSON:

{
  "id": "pay_abc123",
  "object": "payment",
  "amount": 10000,
  "currency": "MYR",
  "status": "captured"
}

Pagination

List endpoints support pagination:

Parameter	Description
page	Page number (default: 1)
limit	Items per page (default: 20, max: 100)

Response includes metadata:

{
  "data": [...],
  "meta": {
    "total": 150,
    "page": 1,
    "limit": 20,
    "totalPages": 8
  }
}

Error Handling

Errors return appropriate HTTP status codes and a JSON error object:

{
  "error": {
    "type": "card_error",
    "code": "card_declined",
    "message": "Your card was declined.",
    "param": "payment_method"
  }
}

HTTP Status Codes

Code	Meaning
200	OK - Request succeeded
201	Created - Resource created
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid API key
402	Request Failed - Valid request but failed
404	Not Found - Resource doesn't exist
409	Conflict - Request conflicts with current state
429	Too Many Requests - Rate limit exceeded
500	Server Error - Something went wrong

Error Types

Type	Description
api_error	Server error
authentication_error	Authentication failed
card_error	Card was declined
invalid_request_error	Invalid parameters
rate_limit_error	Too many requests

Idempotency

Safely retry requests by including an idempotency key:

curl https://api.salam.com/v1/payments \
  -H "Authorization: Bearer sk_test_xxxxx" \
  -H "Idempotency-Key: unique-key-123" \
  -d "amount=10000" \
  -d "currency=MYR"

Repeated requests with the same key return the same result.

Pagination

List endpoints support cursor-based pagination:

{
  "object": "list",
  "data": [...],
  "has_more": true,
  "url": "/v1/payments"
}

Parameters:

• limit - Number of results (default: 10, max: 100)
• starting_after - Cursor for next page
• ending_before - Cursor for previous page

Example:

const payments = await salam.payments.list({
  limit: 10,
  starting_after: 'pay_xxxxx',
});

Metadata

Most resources support custom metadata (up to 50 key-value pairs):

const payment = await salam.payments.create({
  amount: 10000,
  currency: 'MYR',
  payment_method: 'pm_xxxxx',
  metadata: {
    order_id: '12345',
    customer_name: 'John Doe',
  },
});

Expanding Resources

Use the expand parameter to include related objects:

const payment = await salam.payments.retrieve('pay_xxxxx', {
  expand: ['customer', 'payment_method'],
});

// payment.customer is now a full Customer object
// instead of just an ID

Core Resources

Payments

Create and manage payments. The core resource for processing transactions.

Refunds

Issue full or partial refunds for payments.

Customers

Store customer information and payment methods.

Payment Methods

Represent customer payment methods (cards, FPX).

Webhooks

Receive real-time notifications for events.

Rate Limits

• General: 100 requests per second
• Payment Creation: 50 requests per second
• Webhooks: Unlimited

Learn more about rate limits →

SDKs

Official SDKs available:

• Node.js
• JavaScript (Browser)
• PHP (Coming soon)
• Python (Coming soon)

Support

Need help? Contact us:

• 📧 support@salam.com
• 💬 Discord Community
• 🐛 GitHub Issues