Payment Methods

Payment methods let you securely tokenize customer instruments—mobile money wallets, bank accounts, and cards—for future use. Once saved, you can charge them without re-collecting sensitive details, enabling one-click checkouts, subscription billing, and retry logic for failed payments.

The payment method object

A payment method represents a tokenized instrument tied to a customer. It includes the payment rail (type), network provider (issuer), and a masked or tokenized account identifier. After tokenization, you can verify the method to confirm ownership and unlock frictionless charging.

Properties

Name
created_at
Type
timestamp
Description
When this payment method was tokenized and saved.
Name
customer_id
Type
string
Description
Customer who owns this payment method. All methods are scoped to a single customer.
Name
enabled
Type
boolean
Description
Whether this payment method can currently be charged. You can disable methods to prevent charges without deleting them.
Name
id
Type
string
Description
Unique identifier for this payment method—use it to charge or look up the method later.
Name
issuer
Type
string
Description
Network provider—mtn, vodafone, airteltigo for mobile money; bank name or card network for others.
Name
number
Type
string
Description
Masked or tokenized account identifier (e.g., 024205**** for mobile money, 4242********4242 for cards).
Name
type
Type
string
Description
Payment rail: mobile_money, bank_account, card, or motito.
Name
verified
Type
boolean
Description
Whether the customer has confirmed ownership via OTP or other verification flow. Verified methods enable seamless charging.

POST/payment_methods/tokenize

Tokenize payment method

Save a new payment method for a customer without charging it. The method is tokenized and stored for future use. Currently supports mobile money wallets—cards and bank accounts coming soon.

Use cases

Onboarding flow: Collect payment details during signup for later billing.
Add payment method: Let customers save multiple instruments for checkout flexibility.
Subscription setup: Tokenize before the first billing cycle starts.

Required attributes

Name
customer_id
Type
string
Description
Customer who will own this payment method. Must exist in your account.
payment_method_dataobjectPayment instrument details to tokenize.Click or tap to expand
- Name
  type
  Type
  enum
  Description
  Payment rail type. Currently only mobile_money is supported for tokenization.
- Name
  mobile_money
  Type
  object
  Description
  Required when type is mobile_money. Contains wallet details.
  View mobile_money attributesClick or tap to expand
  Name
  issuer
  Type
  enum
  Description
  Mobile money network: mtn, vodafone, or airteltigo.
  Name
  number
  Type
  string
  Description
  Mobile money account number in international format (e.g., +233242057831) or local format (e.g., 0242057831). We normalize it automatically.

Optional attributes

Name
verify_immediately
Type
boolean
Description
Send verification OTP right after tokenization. Defaults to false—you'll call /verify separately.

Request

POST

/payment_methods/tokenize

curl https://api.zebo.dev/payment_methods/tokenize \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cu_a1b2c3d4e5",
    "payment_method_data": {
      "type": "mobile_money",
      "mobile_money": {
        "issuer": "mtn",
        "number": "+233242057831"
      }
    },
    "verify_immediately": false
  }'

Response

{
  "payment_method": {
    "id": "pm_xyz789",
    "customer_id": "cu_a1b2c3d4e5",
    "type": "mobile_money",
    "issuer": "mtn",
    "number": "024205****",
    "created_at": "2025-11-23T13:00:00Z",
    "verified": false,
    "enabled": true
  }
}

POST/payment_methods/verify

Verify payment method

Send an OTP to confirm customer ownership of a payment method. For mobile money, we send a 6-digit code via SMS to the registered wallet number. The customer submits the token to complete verification—once verified, the method can be charged without additional confirmation.

Why verify?

Fraud prevention: Ensures the customer controls the payment instrument.
Compliance: Meets network provider requirements for stored credentials.
Better authorization rates: Verified methods skip OTP during charges, reducing friction and abandonment.

Required attributes

Name
payment_method_id
Type
string
Description
ID of the payment method to verify. Must belong to a customer in your account.

Request

POST

/payment_methods/verify

curl https://api.zebo.dev/payment_methods/verify \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method_id": "pm_xyz789"
  }'

Response

{
  "verification": {
    "payment_method_id": "pm_xyz789",
    "status": "pending",
    "token_sent_at": "2025-11-23T13:05:00Z",
    "expires_at": "2025-11-23T13:13:00Z",
    "delivery": {
      "recipient": "0242057831",
      "channel": "sms",
      "sender_id": "zverify"
    }
  }
}

POST/payment_methods/confirm_verification

Confirm verification

Submit the OTP the customer received to complete payment method verification. On success, the method's verified flag is set to true and it can be charged without additional confirmation steps.

Rules

Tokens expire after 8 minutes (480 seconds).
Failed attempts are logged—after 5 failures, the verification request is locked and you'll need to call /verify again.
One successful verification per payment method—once verified, the status persists.

Required attributes

Name
payment_method_id
Type
string
Description
Payment method being verified.
Name
token
Type
string
Description
6-digit OTP the customer received via SMS.

Request

POST

/payment_methods/confirm_verification

curl https://api.zebo.dev/payment_methods/confirm_verification \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method_id": "pm_xyz789",
    "token": "847261"
  }'

Response

{
  "payment_method": {
    "id": "pm_xyz789",
    "customer_id": "cu_a1b2c3d4e5",
    "type": "mobile_money",
    "issuer": "mtn",
    "number": "024205****",
    "created_at": "2025-11-23T13:00:00Z",
    "verified": true,
    "verified_at": "2025-11-23T13:07:00Z",
    "enabled": true
  }
}

POST/payment_methods/lookup

Lookup payment method

Retrieve details for a specific payment method by ID. Returns the full payment method object including verification status, creation timestamp, and masked account details.

Required attributes

Name
payment_method_id
Type
string
Description
ID of the payment method to fetch.

Request

POST

/payment_methods/lookup

curl https://api.zebo.dev/payment_methods/lookup \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method_id": "pm_xyz789"
  }'

Response

{
  "payment_method": {
    "id": "pm_xyz789",
    "customer_id": "cu_a1b2c3d4e5",
    "type": "mobile_money",
    "issuer": "mtn",
    "number": "024205****",
    "created_at": "2025-11-23T13:00:00Z",
    "verified": true,
    "verified_at": "2025-11-23T13:07:00Z",
    "enabled": true
  }
}

POST/payment_methods/delete

Delete payment method

Permanently remove a payment method from a customer's account. This action is irreversible—the tokenized credentials are deleted and the payment method can no longer be charged. Use this when customers explicitly request removal or when cleaning up unused methods.

Important notes

Deleting a payment method does not affect past transactions or balance transactions that used it.
Any subscriptions or recurring billing using this method will fail on the next charge attempt—update them with a new payment method first.
For temporary disabling (e.g., suspected fraud), consider using an update endpoint to set enabled: false instead of deleting (coming soon).

Required attributes

Name
payment_method_id
Type
string
Description
ID of the payment method to delete. Must belong to a customer in your account.

Request

POST

/payment_methods/delete

curl https://api.zebo.dev/payment_methods/delete \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method_id": "pm_xyz789"
  }'

Response

{
  "deleted": true,
  "payment_method_id": "pm_xyz789"
}

POST/payment_methods/settings

Payment method settings

Retrieve payment method acceptance settings for your application. This endpoint returns configuration for all supported payment types—mobile money, bank accounts, cards, and Motito—including whether each type is enabled and requires customer confirmation before use.

Use cases

Checkout UI: Show only enabled payment methods in your checkout flow.
Conditional flows: Require explicit consent when confirms_use is true for a payment type.
Settings dashboard: Display current acceptance preferences to merchants.

Response structure

The settings object contains an entry for each payment method type with:

enabled: Whether this type can be used for payments
confirms_use: Whether customers must explicitly agree before using this type
name and description: Human-readable labels for UI display

Request

POST

/payment_methods/settings

curl https://api.zebo.dev/payment_methods/settings \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json"

Response

{
  "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
    }
  }
}

For more details about payment method settings and how to use them in your integration, see the Understanding Payment Method Settings guide.