Understand payment method settings

Payment method settings control which payment types your customers can use and how Commerce validates transactions. The /payment_methods/settings endpoint returns configuration for all supported payment rails—mobile money, bank accounts, cards, and Motito—with flags that determine acceptance and security behavior. Understanding these settings helps you build checkout flows that match your risk tolerance and customer experience goals.

Fetching your settings

Call /payment_methods/settings to retrieve your current payment method configuration. No request body needed—Commerce uses your authentication context to identify your application and return the appropriate settings.

curl https://api.zebo.dev/payment_methods/settings \
  -H "Authorization: Bearer YOUR_SECRET_KEY"

The response contains a settings object with four payment type configurations—one for each supported payment rail. Each type has its own enabled state, confirmation requirements, and descriptive metadata.

Response structure overview

{
  "settings": {
    "mobile_money": {
      "type": "mobile_money",
      "name": "Mobile Money",
      "description": "Pay with MTN, Vodafone, or AirtelTigo mobile wallets",
      "enabled": true,
      "confirms_use": true
    },
    "bank_account": {
      "type": "bank_account",
      "name": "Bank Account",
      "description": "Direct bank transfer or debit",
      "enabled": true,
      "confirms_use": false
    },
    "card": {
      "type": "card",
      "name": "Card",
      "description": "Credit or debit card payments",
      "enabled": true,
      "confirms_use": true
    },
    "motito": {
      "type": "motito",
      "name": "Motito",
      "description": "Pay with your Motito balance",
      "enabled": false,
      "confirms_use": true
    }
  }
}

The settings object contains four payment type configurations. Each payment type includes:

• Identification fields (type, name, description) for UI rendering
• Acceptance flag (enabled) controlling whether the type can be used
• Security flag (confirms_use) determining transaction confirmation requirements

Understanding payment type attributes

type

The payment rail identifier that matches the type field in payment method objects. Use this as a key when building checkout UIs or filtering payment methods.

Possible values:

• mobile_money – Mobile wallet payments (MTN, Vodafone, AirtelTigo)
• bank_account – Direct bank transfers or debits
• card – Credit or debit card payments
• motito – Motito balance payments

This value never changes for a given payment type—it's the stable identifier you use in API calls when creating payment methods or filtering customer instruments.

name

Human-readable label for this payment type. Use this in your checkout UI to label payment method sections, radio buttons, or dropdown options. The name is localized and matches customer expectations for each payment rail.

description

Detailed explanation of the payment type—what networks or providers it covers, how customers use it, or what credentials they need. Use this for tooltips, help text, or explainer modals in your checkout flow.

enabled

Boolean flag controlling whether customers can use this payment type. When false, Commerce rejects attempts to create payment methods or charge orders with this type.

Behavior:

• When true: Customers can tokenize payment methods of this type, and you can charge them in orders
• When false: API calls attempting to use this type fail with a validation error

Common use cases:

1. Gradual rollout: Enable new payment types only after infrastructure is ready
2. Risk management: Disable types with high fraud rates while you investigate
3. Compliance: Turn off types that don't meet regulatory requirements in certain markets
4. Maintenance: Temporarily disable types during provider outages or upgrades

Important: Disabling a payment type doesn't delete existing tokenized payment methods—it only prevents new charges. Customers with saved payment methods of a disabled type can still see them in their account, but attempts to charge them will fail.

confirms_use

Boolean flag that determines whether Commerce forces customers to explicitly confirm each transaction using this payment type. When true, the customer must complete an additional verification step (typically an OTP) to authorize the charge.

Behavior:

• When true: Every charge requires customer confirmation via OTP or similar mechanism
• When false: Charges proceed immediately without additional customer input (after initial tokenization)

This is a critical security and fraud prevention control—it trades convenience for authorization certainty.

Why confirms_use matters

Mobile money networks and card issuers require explicit customer authorization for many transaction types. Setting confirms_use: true ensures:

1. Fraud prevention: Stolen credentials can't be used without the OTP or secondary factor
2. Regulatory compliance: Meets Strong Customer Authentication (SCA) requirements
3. Dispute protection: Customer confirmation creates audit trails for chargeback defense
4. Network requirements: Some mobile money providers mandate OTP for all transactions

Common configurations:

When to disable confirms_use

Setting confirms_use: false is appropriate for:

1. Bank account transfers – The ACH network handles authorization through account ownership verification
2. Verified payment methods – If the customer already verified ownership during tokenization
3. Low-value transactions – Where the friction of OTP outweighs fraud risk
4. Subscription billing – When customers expect automatic charges (document this in terms of service)
5. Trusted customers – High-value accounts with established payment history

Risk tradeoff:

Most merchants should keep confirms_use: true for mobile money and cards, disabling it only for bank accounts or after careful risk assessment.

Related resources

• Payment Methods API reference – Full endpoint documentation
• Accept a payment guide – Step-by-step payment integration
• Charge repeat customers guide – Using saved payment methods
• Orders API reference – Order creation and payment execution