Quickstart: Integrate Specific Payment Methods

Merchants can control which payment methods appear on the hosted checkout and how payment method selection is managed.

There are two integration modes, configured using payment_method_selection in options.checkout_options:

Gateway mode: Moment Checkout displays and manages payment method selection. The customer chooses how to pay within the hosted checkout. This is the default and the recommended pattern.
Merchant-controlled mode: Your checkout manages payment method selection. When the customer proceeds, you create a Payment Session for the selected method and redirect to Moment Checkout to complete the payment.

This guide builds on the One-Time Payments quickstart. If you have not created a one-time payment session before, start there.

This quickstart applies to customer-initiated payments (CIT), where the customer is present and completes payment using Moment Checkout. It applies to Payment Sessions created with the one_time and first_in_series payment types.

For merchant-initiated payments (MIT) using the next_in_series payment type, see the recurring payments guide. These payments are processed without launching Moment Checkout.

Prerequisites

A test API key. See Authentication.

Gateway mode

payment_method_selection defaults to gateway and does not need to be set explicitly.

Create a Payment Session with the payment methods you want to make available in visible_payment_methods, then redirect the customer to the returned session_url. Moment Checkout displays the available methods, manages selection, and completes the payment. On payment failure, the customer stays within Moment Checkout and can retry or switch to another available method without returning to your checkout.

This is the recommended pattern because Moment Checkout manages the complete payment experience, which typically gives better conversion with the least integration effort.

Step 1 (optional): Restrict the visible payment methods

Add visible_payment_methods to options.checkout_options. Pass an array of the payment method types you want to display. Only these methods will appear on the checkout. For example, to support Capitec Pay (capitec_pay) and Card (card):

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",
    "type": "one_time",
    "options": {
      "checkout_options": {
        "visible_payment_methods": ["capitec_pay", "card"]
      }
    }
  }'

The response is the same as a standard one-time session. The id can be used to match the webhook event.

{
  "id": "ps_kfAWZgfQIoeG0q",
  "status": "active",
  "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"
}

Redirect the customer to the session_url returned when the Payment Session is created.

An alternative to redirecting is to use our SDK to implement a modal or pop-up styled hosted checkout. See Libraries and SDKs.

The checkout will be restricted as follows:

If you pass only one payment method in visible_payment_methods, that method is pre-selected and the customer is taken straight into that payment method’s journey. For example, if cards is the only method passed, the customer is taken directly to the card details page.

Step 2 (optional): Pre-select a payment method

When visible_payment_methods contains more than one method, you can pre-select one of them with selected_payment_method. The customer is taken directly into that payment method’s journey without having to choose on the selection screen.

"options": {
   "checkout_options": {
     "visible_payment_methods": ["capitec_pay", "card"],
     "selected_payment_method": "capitec_pay"
   }
}

The checkout will directly present Capitec Pay (capitec_pay), but Card (card) remains available if the customer chooses that instead:

Merchant-controlled mode

Set payment_method_selection to merchant in options.checkout_options to enable this mode. A return_url is required. On payment failure, Moment automatically redirects the customer back to your return_url so your checkout can handle the outcome.

Your checkout displays and manages payment method selection. When the customer proceeds, create a Payment Session with visible_payment_methods, selected_payment_method, or both. Moment Checkout opens directly into the selected method’s flow.

On failure, the customer returns to your checkout. Rather than creating a new Payment Session, call Complete Payment Session on the existing session with the customer’s new selection. Moment Checkout redirects the customer to the updated method.

Step 1: Display payment methods in your checkout

Display the payment methods you want to make available using your own checkout interface. Your integration is responsible for determining which payment methods to display and mapping each option to its corresponding Moment payment method type.

Step 2: Create a Payment Session for the selected method

When the customer selects a payment method and proceeds to pay, create a Payment Session from your server. Pass visible_payment_methods, selected_payment_method, or both. Set payment_method_selection to merchant and include a return_url so Moment knows where to redirect the customer after each payment attempt. For example, if the customer selects Capitec Pay:

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",
    "type": "one_time",
    "options": {
      "checkout_options": {
        "visible_payment_methods": ["capitec_pay"],
        "payment_method_selection": "merchant",
        "return_url": "https://merchant.example/checkout/order_123/payment-result"
      }
    },
    "external_reference": "order_123"
  }'

The response is the same as a standard one-time session. The id can be used to match the webhook event.

{
  "id": "ps_kfAWZgfQIoeG0q",
  "status": "active",
  "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"
}

Redirect the customer to the session_url returned when the Payment Session is created.

An alternative to redirecting is to use our SDK to implement a modal or pop-up styled hosted checkout. See Libraries and SDKs.

The checkout will directly present Capitec Pay (capitec_pay) as the only option:

Step 3 (optional): Pre-fill payment method details

When you know the customer’s phone number in advance (for example from a previous session or their account profile), you can pass it when creating the Payment Session to reduce the steps required to complete the payment. This applies to mobile money payment methods (for example M-Pesa, MTN MoMo, Airtel Money) and Capitec Pay. Pass the phone number under payment_method_options using the corresponding key (mobile_money or capitec_pay). The phone number must be in E.164 format and its country must match the session country. Use prefill_mode to control how the checkout handles the pre-filled value:

review: The pre-filled value is shown to the customer to confirm. They can edit it before proceeding.
auto_advance: The checkout skips the review step and advances automatically. Use this when you are confident the data is correct and want to minimise the steps to complete payment.

For Capitec Pay:

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",
    "type": "one_time",
    "options": {
      "checkout_options": {
        "visible_payment_methods": ["capitec_pay"],
        "payment_method_selection": "merchant",
        "return_url": "https://merchant.example/checkout/order_123/payment-result"
      }
    },
    "payment_method_options": {
      "capitec_pay": {
        "phone_number": "+27821234567"
      },
      "prefill_mode": "auto_advance"
    },
    "external_reference": "order_123"
  }'

For mobile money, replace capitec_pay with mobile_money and supply the customer’s registered mobile money number:

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": 5000,
    "currency": "KES",
    "type": "one_time",
    "options": {
      "checkout_options": {
        "visible_payment_methods": ["mpesa"],
        "payment_method_selection": "merchant",
        "return_url": "https://merchant.example/checkout/order_456/payment-result"
      }
    },
    "payment_method_options": {
      "mobile_money": {
        "phone_number": "+254701234567"
      },
      "prefill_mode": "auto_advance"
    },
    "external_reference": "order_456"
  }'

Step 4: Handle the customer’s return

After the payment attempt succeeds or fails, Moment Checkout automatically redirects the customer to the configured return_url. When the customer returns, retrieve the Payment Session to display the latest payment status. Use webhooks as the authoritative source for asynchronous payment status updates. If the payment was unsuccessful, display the payment method selection in your checkout. When the customer proceeds with a new or the same selection, call Complete Payment Session on the existing session with the updated selected_payment_method and visible_payment_methods. This updates the session in place without requiring a new Payment Session to be created, then redirects the customer back to Moment Checkout for the new selection.

curl -X POST https://api.momentpay.net/collect/payment_sessions/ps_kfAWZgfQIoeG0q/complete \
  -H "Authorization: Bearer sk_test_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "selected_payment_method": "card",
    "visible_payment_methods": ["card"]
  }'

Supported Payment Methods

The following payment methods can be configured using visible_payment_methods and selected_payment_method:

Use the payment method category and type above to control the visible and selected payment methods. For bank payment methods, use the variant from the table below to target a specific bank.

Bank Variant Reference

For pay_by_bank, you can target a single bank by passing bank_payments.pay_by_bank.{variant} in visible_payment_methods. Only that bank will appear on the checkout.

South Africa
Kenya
Nigeria

Bank	Variant
Standard Bank	`sbsa`
Nedbank	`nedbank`
FNB	`fnb`
Tyme Bank	`tymebank`
ABSA	`absa`
Investec	`investec`
Bidvest Bank	`bidvestbank`

Bank	Variant
KCB Bank	`kcb`
Equity Bank	`equitybank`
Co-op Bank	`coopbank`
Family Bank	`familybank`
NCBA Bank	`ncba`
National Bank	`nationalbank`
Stanbic Bank	`stanbic`
Standard Chartered	`standard_chartered`
ABSA Bank	`absa`
Diamond Trust Bank	`dtb`

Bank	Variant
Access Bank	`accessbank`
Ecobank	`ecobank`
FCMB	`fcmb`
Fidelity Bank	`fidelitybank`
First Bank	`firstbank`
Globus Bank	`globusbank`
Guaranty Trust Bank	`gtb`
Keystone Bank	`keystonebank`
Stanbic IBTC	`stanbicibtcbank`
Sterling Bank	`sterlingbank`
UBA	`uba`
Union Bank	`unionbank`
Unity Bank	`unitybank`
Zenith Bank	`zenithbank`

Payment method identifier formats

visible_payment_methods and selected_payment_method accept identifiers in the following formats:

Format	Example	Effect
`category`	`bank_payments`	All types within the category
`type`	`capitec_pay`	That specific payment method
`category.type`	`bank_payments.capitec_pay`	Equivalent to `type` only
`category.type.variant`	`bank_payments.pay_by_bank.kcb`	A specific bank (`pay_by_bank` only)

Example: using category.type

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",
    "type": "one_time",
    "options": {
      "checkout_options": {
        "visible_payment_methods": ["bank_payments.capitec_pay", "cards.card"]
      }
    }
  }'

Example: using category only

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",
    "type": "one_time",
    "options": {
      "checkout_options": {
        "visible_payment_methods": ["bank_payments", "cards"]
      }
    }
  }'

Example: targeting a specific bank

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": "KES",
    "type": "one_time",
    "options": {
      "checkout_options": {
        "visible_payment_methods": ["bank_payments.pay_by_bank.kcb"]
      }
    }
  }'

For selected_payment_method, the value must resolve to a single payment method and must be present in visible_payment_methods. How it can be specified depends on how visible_payment_methods was set:

If visible_payment_methods specifies only a category, selected_payment_method can be category.type or just type.
If visible_payment_methods specifies a type, selected_payment_method cannot be a category on its own.
If visible_payment_methods specifies a category.type.variant, selected_payment_method must use the same three-level format.

Example: invalid selected_payment_method

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",
    "type": "one_time",
    "options": {
      "checkout_options": {
        "visible_payment_methods": ["capitec_pay", "card"],
        "selected_payment_method": "bank_payments"
      }
    }
  }'

{
    "title": "Invalid payment method in selected_payment_method",
    "status": 400,
    "code": "invalid_selected_payment_method",
    "detail": "The payment methods specified in selected_payment_method are invalid. Please re-check.",
    "instance": "/collect/payment_sessions"
}

Rules for visible_payment_methods:

Array of strings. Must be a strict subset of the payment methods enabled for the merchant account.
When not specified, all payment methods enabled for the merchant and available for the session’s country and currency are visible.
If only one method is passed, that method is pre-selected and the customer is taken straight into that payment method’s journey.
For pay_by_bank, target a single bank using bank_payments.pay_by_bank.{variant}. See Bank Variant Reference for valid values.

Rules for selected_payment_method:

String. Accepts one value only.
The value must be present in visible_payment_methods.
Applies only when visible_payment_methods contains more than one entry.

Match payment methods to the currency

The methods you request must be valid for the session’s country and currency. For example, a session created in ZAR must list methods supported in South Africa. If any method in visible_payment_methods is not supported for the session’s currency, the request fails with 400 Bad Request.

Launch the checkout, handle the webhook, and test

Launching the checkout, handling the payment_session.completed webhook, verifying the signature, and testing are identical to the standard flow. See Quickstart: One-Time Payments for these steps.

Getting Started

Collect

Stored Value

Billing

Webhooks

Changelog

Prerequisites

Gateway mode

Step 1 (optional): Restrict the visible payment methods

Step 2 (optional): Pre-select a payment method

Merchant-controlled mode

Step 1: Display payment methods in your checkout

Step 2: Create a Payment Session for the selected method

Step 3 (optional): Pre-fill payment method details

Step 4: Handle the customer’s return

Supported Payment Methods

Bank Variant Reference

Payment method identifier formats

Match payment methods to the currency

Launch the checkout, handle the webhook, and test

​Prerequisites

​Gateway mode

​Step 1 (optional): Restrict the visible payment methods

​Step 2 (optional): Pre-select a payment method

​Merchant-controlled mode

​Step 1: Display payment methods in your checkout

​Step 2: Create a Payment Session for the selected method

​Step 3 (optional): Pre-fill payment method details

​Step 4: Handle the customer’s return

​Supported Payment Methods

​Bank Variant Reference

​Payment method identifier formats

​Match payment methods to the currency

​Launch the checkout, handle the webhook, and test

Prerequisites

Gateway mode

Step 1 (optional): Restrict the visible payment methods

Step 2 (optional): Pre-select a payment method

Merchant-controlled mode

Step 1: Display payment methods in your checkout

Step 2: Create a Payment Session for the selected method

Step 3 (optional): Pre-fill payment method details

Step 4: Handle the customer’s return

Supported Payment Methods

Bank Variant Reference

Payment method identifier formats

Match payment methods to the currency

Launch the checkout, handle the webhook, and test