Create a Payment

Creates a new payment. You can create a payment with an existing payment method or provide payment method details directly.

POST/v1/payments

Parameters

Required Parameters

amount required integer

Amount in smallest currency unit. For MYR, use cents (e.g., 10000 for RM 100.00).

currency required string

Three-letter ISO currency code (e.g., myr, usd, sgd).

Optional Parameters

payment_method optional string

ID of an existing PaymentMethod to use for this payment.

payment_method_data optional object

Payment method details to create a new payment method. See payment_method_data below.

customer optional string

ID of an existing Customer. If provided, the payment method can be saved for future use.

description optional string

An arbitrary string describing the payment.

metadata optional object

Custom key-value pairs (up to 50 pairs).

capture_method optional string

Controls when the funds are captured. Options:

• automatic (default) - Capture immediately
• manual - Authorize now, capture later

receipt_email optional string

Email address to send the receipt to.

return_url optional string

URL to redirect the customer to after authentication (required for FPX and 3D Secure).

save_payment_method optional boolean

Set to true to save the payment method for future use. Requires customer to be set.

payment_method_data

Card Payments

{
  "type": "card",
  "card": {
    "number": "4242424242424242",
    "exp_month": 12,
    "exp_year": 2025,
    "cvc": "123"
  }
}

Or with a token:

{
  "type": "card",
  "card": {
    "token": "tok_xxxxx"
  }
}

FPX Payments

{
  "type": "fpx",
  "fpx": {
    "bank_code": "MBBEMYKL"
  }
}

Returns

Returns the Payment object if successful.

Examples

Basic Card Payment

cURL

curl https://api.salam.com/v1/payments \
  -H "Authorization: Bearer sk_test_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "currency": "myr",
    "payment_method_data": {
      "type": "card",
      "card": {
        "number": "4242424242424242",
        "exp_month": 12,
        "exp_year": 2025,
        "cvc": "123"
      }
    },
    "description": "Order #12345"
  }'

Node.js

const payment = await salam.payments.create({
  amount: 10000,
  currency: 'myr',
  payment_method_data: {
    type: 'card',
    card: {
      number: '4242424242424242',
      exp_month: 12,
      exp_year: 2025,
      cvc: '123',
    },
  },
  description: 'Order #12345',
});

PHP

$payment = $salam->payments->create([
    'amount' => 10000,
    'currency' => 'myr',
    'payment_method_data' => [
        'type' => 'card',
        'card' => [
            'number' => '4242424242424242',
            'exp_month' => 12,
            'exp_year' => 2025,
            'cvc' => '123',
        ],
    ],
    'description' => 'Order #12345',
]);

Payment with Existing Payment Method

const payment = await salam.payments.create({
  amount: 10000,
  currency: 'myr',
  customer: 'cus_xxxxx',
  payment_method: 'pm_xxxxx',
  description: 'Subscription payment',
});

FPX Payment

const payment = await salam.payments.create({
  amount: 10000,
  currency: 'myr',
  payment_method_data: {
    type: 'fpx',
    fpx: {
      bank_code: 'MBBEMYKL', // Maybank
    },
  },
  return_url: 'https://yoursite.com/payment/complete',
});

// Redirect customer to complete payment
if (payment.status === 'requires_action') {
  res.redirect(payment.next_action.redirect_to_url);
}

Manual Capture

// Authorize the payment
const payment = await salam.payments.create({
  amount: 10000,
  currency: 'myr',
  payment_method: 'pm_xxxxx',
  capture_method: 'manual',
});

// Later, capture the payment
await salam.payments.capture(payment.id);

Save Payment Method for Future Use

const payment = await salam.payments.create({
  amount: 10000,
  currency: 'myr',
  customer: 'cus_xxxxx',
  payment_method_data: {
    type: 'card',
    card: {
      number: '4242424242424242',
      exp_month: 12,
      exp_year: 2025,
      cvc: '123',
    },
  },
  save_payment_method: true,
});

// The payment method is now saved to the customer

Response

{
  "id": "pay_1234567890abcdef",
  "object": "payment",
  "amount": 10000,
  "currency": "myr",
  "status": "succeeded",
  "payment_method": "pm_xxxxx",
  "description": "Order #12345",
  "metadata": {},
  "captured": true,
  "refunded": false,
  "refunded_amount": 0,
  "receipt_email": null,
  "receipt_url": "https://pay.salam.com/receipts/pay_xxxxx",
  "client_secret": "pay_xxxxx_secret_xxxxx",
  "next_action": null,
  "last_payment_error": null,
  "created": 1704067200,
  "livemode": false
}

Error Responses

Card Declined

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

Insufficient Funds

{
  "error": {
    "type": "card_error",
    "code": "card_declined",
    "message": "Your card has insufficient funds.",
    "decline_code": "insufficient_funds"
  }
}

Invalid Parameters

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "Missing required parameter: amount",
    "param": "amount"
  }
}

Error Codes

Code	Description
card_declined	The card was declined
insufficient_funds	Insufficient funds on the card
expired_card	The card has expired
incorrect_cvc	The CVC code is incorrect
processing_error	Payment processor error
invalid_number	Invalid card number
invalid_expiry_month	Invalid expiration month
invalid_expiry_year	Invalid expiration year
parameter_missing	Required parameter is missing
payment_method_not_available	Payment method not available

Idempotency

To safely retry payment creation, include an idempotency key:

const payment = await salam.payments.create({
  amount: 10000,
  currency: 'myr',
  payment_method: 'pm_xxxxx',
}, {
  idempotencyKey: 'unique-key-123',
});

Repeated requests with the same key will return the same payment object.

Related

• Retrieve a payment
• Capture a payment
• Cancel a payment
• Create a refund