Quickstart: One-Time Payments

This guide walks through creating a one-time payment session, launching the hosted checkout, and handling the completion webhook. It also covers how to save a customer’s payment method for faster future checkouts.

Prerequisites

A test API key. See Authentication.
A registered webhook endpoint. See Webhook Setup to register your URL and obtain your signing key.

Step 1: Create a payment session

Create a session server-side using your secret key. The minimum required fields are amount and currency.

curl -X POST https://api.momentpay.net/collect/payment_sessions \
  -H "Authorization: Bearer sk_test_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10000,
    "currency": "ZAR"
  }'

amount is always specified in minor units. See Monetary Amounts for details.

The response includes a session_url (the hosted checkout page your customer will use to complete payment) and an id you will use to match the subsequent webhook event.

{
  "id": "ps_kfAWZgfQIoeG0q",
  "status": "active",
  "payment_status": "unpaid",
  "payment_outcome": "not_started",
  "amount": 10000,
  "currency": "ZAR",
  "session_url": "https://checkout.momentpay.net/ckt802zEb2P2uS4Ql",
  "created_at": "2025-03-18T14:06:51.149Z",
  "updated_at": "2025-03-18T14:06:51.149Z"
}

Saving a payment method

To save the customer’s payment method at checkout, add options.checkout_options.save_payment_method to the request body.

{
  "amount": 2001,
  "currency": "ZAR",
  "options": {
    "customer": {
      "name": "John Doe"
    },
    "checkout_options": {
      "save_payment_method": "prompt"
    }
  }
}

{
  "amount": 2001,
  "currency": "ZAR",
  "options": {
    "customer": {
      "name": "John Doe"
    },
    "checkout_options": {
      "save_payment_method": "always"
    }
  }
}

prompt — the customer is given the choice to save their payment method at checkout.
always — the payment method is saved automatically with no prompt.

Card details are tokenized and stored securely by Moment. Your server never handles or stores raw card numbers.

The response has the same shape as above, with one addition — a customer_id identifying the saved customer. Store this against your own customer record so you can present their saved payment methods on future checkouts.

{
  "customer_id": "cus_rlpqOZEA9M0PEhrA9ZDdN"
}

Checkout page showing the save payment method prompt

The customer is prompted with the option to save their card for future checkouts.

Step 2: Launch the checkout

Redirect your customer to the session_url, or embed it using the JavaScript SDK for an in-page modal or inline experience. The session remains active until the customer completes payment or the session expires. Do not poll for status. Use the webhook in the next step instead.

Step 3: Handle the completion webhook

When the customer completes payment, Moment sends a payment_session.completed event to your registered webhook endpoint.

{
  "id": "wh_e5cf73f1b3e4451c8c474fe56bfc688d",
  "type": "payment_session.completed",
  "data": {
    "id": "ps_kfAWZgfQIoeG0q",
    "status": "completed",
    "payment_status": "paid",
    "payment_outcome": "paid",
    "amount": 10000,
    "currency": "ZAR",
    "payment_id": "pay_87C7PAP35KcdpzAgckBvB"
  }
}

Match data.id in the event to the session you created in Step 1 to confirm which order was paid. Before processing, verify the event signature to confirm it originated from Moment. See Webhook Verification for the full verification steps and code samples. Respond with a 2xx status code to acknowledge receipt. If your endpoint does not respond in time, Moment will retry delivery.

Presenting a returning customer with their saved payment method

When a customer with a saved payment method returns, pass the saved customer_id in the options.customer field. Moment will present their saved payment methods at checkout, enabling a faster checkout experience.

{
  "amount": 2001,
  "currency": "ZAR",
  "options": {
    "customer": "cus_rlpqOZEA9M0PEhrA9ZDdN",
    "checkout_options": {
      "save_payment_method": "prompt"
    }
  }
}

You can still include save_payment_method for returning customers. Set it to "prompt" to give them the option to save a new payment method at checkout.

Checkout page showing saved payment methods for a returning customer

The customer is presented with their saved payment methods at checkout.

Saveable payment methods

The following payment methods can be saved for faster checkout on future transactions:

Cards — Visa, Mastercard, and other supported card schemes
Capitec Pay — Customers can save their Capitec Pay phone number for quicker checkout without re-entering details

Testing

Use test card 4242 4242 4242 4242 with any future expiry date and any 3-digit CVC to simulate a successful payment. See Integration Testing for the full list of test cards and error scenarios.

Next steps

Quickstart: Recurring Payments

Set up a mandate and collect future payments without customer interaction.

Authorisation and Capture

Reserve funds at checkout and capture or void them later.

Payment Method Verification

Verify and save a card without charging the customer.

JavaScript SDK

Embed checkout directly in your page with the Moment JS SDK.

Getting Started

Collect

Stored Value

Billing

Webhooks

Changelog

Prerequisites

Step 1: Create a payment session

Saving a payment method

Step 2: Launch the checkout

Step 3: Handle the completion webhook

Presenting a returning customer with their saved payment method

Saveable payment methods

Testing

Next steps

Quickstart: Recurring Payments

Authorisation and Capture

Payment Method Verification

JavaScript SDK

​Prerequisites

​Step 1: Create a payment session

​Saving a payment method

​Step 2: Launch the checkout

​Step 3: Handle the completion webhook

​Presenting a returning customer with their saved payment method

​Saveable payment methods

​Testing

​Next steps

Quickstart: Recurring Payments

Authorisation and Capture

Payment Method Verification

JavaScript SDK

Prerequisites

Step 1: Create a payment session

Saving a payment method

Step 2: Launch the checkout

Step 3: Handle the completion webhook

Presenting a returning customer with their saved payment method

Saveable payment methods

Testing

Next steps