Payments

A Payment represents an attempt to collect money from your customer.

POST/v1/payments

Create a new payment

Create a Payment

Creates a new payment and returns a checkout URL.

Request Body

Parameter	Type	Required	Description
amount	integer	✓	Amount in cents (e.g., 1000 = RM 10.00)
currency	string		Three-letter ISO currency code. Default: MYR
description	string		Payment description (max 255 chars)
success_url	string	✓	URL to redirect on success
cancel_url	string	✓	URL to redirect on cancellation
callback_url	string		Webhook URL for this payment
metadata	object		Custom key-value pairs (max 10 keys)

Example Request

cURL

curl https://api.salamgateway.com/v1/payments \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "description": "Order #1234",
    "success_url": "https://example.com/success",
    "cancel_url": "https://example.com/cancel"
  }'

Node.js

const salam = new Salam({ apiKey: 'sk_live_xxx' });

const payment = await salam.payments.create({
  amount: 10000,
  description: 'Order #1234',
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/cancel',
});

Browser

const salam = new SalamJS('pk_live_xxx');

const payment = await salam.payments.create({
  amount: 10000,
  description: 'Order #1234',
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/cancel',
});

Response

{
  "id": "pay_abc123xyz",
  "object": "payment",
  "amount": 10000,
  "currency": "MYR",
  "status": "pending",
  "description": "Order #1234",
  "redirect_url": "https://checkout.salamgateway.com/pay/pay_abc123xyz",
  "success_url": "https://example.com/success",
  "cancel_url": "https://example.com/cancel",
  "expires_at": "2024-01-15T12:00:00Z",
  "created_at": "2024-01-15T11:30:00Z"
}

---

GET/v1/payments/:id

Retrieve a payment

Retrieve a Payment

Retrieves the details of an existing payment.

Path Parameters

Parameter	Description
id	The payment ID

Example

cURL

curl https://api.salamgateway.com/v1/payments/pay_abc123 \
  -H "Authorization: Bearer sk_live_xxx"

Node.js

const payment = await salam.payments.retrieve('pay_abc123');

Browser

const payment = await salam.payments.retrieve('pay_abc123');

Response

{
  "id": "pay_abc123xyz",
  "object": "payment",
  "amount": 10000,
  "currency": "MYR",
  "status": "captured",
  "description": "Order #1234",
  "payment_method": "fpx",
  "payment_method_details": {
    "bank": "Maybank2U",
    "bank_code": "MB2U0227"
  },
  "captured": true,
  "captured_at": "2024-01-15T11:35:00Z",
  "success_url": "https://example.com/success",
  "cancel_url": "https://example.com/cancel",
  "metadata": {},
  "created_at": "2024-01-15T11:30:00Z"
}

---

GET/v1/payments

List all payments

List Payments

Returns a paginated list of payments.

Query Parameters

Parameter	Description
status	Filter by status: pending, authorized, captured, failed, cancelled
from	Start date (ISO 8601)
to	End date (ISO 8601)
page	Page number (default: 1)
limit	Items per page (default: 20, max: 100)

Example

cURL

curl "https://api.salamgateway.com/v1/payments?status=captured&limit=10" \
  -H "Authorization: Bearer sk_live_xxx"

Node.js

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

Response

{
  "data": [
    {
      "id": "pay_abc123",
      "object": "payment",
      "amount": 10000,
      "currency": "MYR",
      "status": "captured",
      "created_at": "2024-01-15T11:30:00Z"
    }
  ],
  "meta": {
    "total": 150,
    "page": 1,
    "limit": 10,
    "totalPages": 15
  }
}

---

POST/v1/payments/:id/capture

Capture an authorized payment

Capture a Payment

Captures an authorized payment.

Path Parameters

Parameter	Description
id	The payment ID

Request Body

Parameter	Type	Description
amount	integer	Optional partial capture amount

Example

cURL

curl https://api.salamgateway.com/v1/payments/pay_abc123/capture \
  -X POST \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{}'

Node.js

const payment = await salam.payments.capture('pay_abc123');

---

POST/v1/payments/:id/void

Void an authorized payment

Void a Payment

Voids an authorized payment that has not been captured.

Path Parameters

Parameter	Description
id	The payment ID

Example

cURL

curl https://api.salamgateway.com/v1/payments/pay_abc123/void \
  -X POST \
  -H "Authorization: Bearer sk_live_xxx"

Node.js

const payment = await salam.payments.void('pay_abc123');

Payment Object

Attributes

Attribute	Type	Description
id	string	Unique payment identifier
object	string	Always "payment"
amount	integer	Amount in cents
currency	string	Three-letter ISO currency code
status	string	Payment status
description	string	Payment description
payment_method	string	Payment method used (fpx, card)
payment_method_details	object	Details about the payment method
captured	boolean	Whether the payment has been captured
captured_at	string	Timestamp when captured
refunded	boolean	Whether the payment has been refunded
refunded_amount	integer	Amount refunded in cents
metadata	object	Custom metadata
created_at	string	Creation timestamp
updated_at	string	Last update timestamp

Payment Status

Status	Description
pending	Payment created, awaiting customer action
authorized	Payment authorized but not captured
captured	Payment captured successfully
failed	Payment failed
cancelled	Payment cancelled by customer or merchant
expired	Payment expired without completion