Payment Methods

Payment methods let you save a customer payment instrument once and reuse it later. Commerce stores the instrument behind a payment method ID, returns masked rail details in responses, and keeps the saved method linked to the customer who owns it. Use this API when you want faster repeat checkout, cleaner retry flows, or account-on-file billing.

Tokenize and update support idempotency. For either operation, a successful response can be replayed with the same idempotency key and request body for 24 hours. Lookup, page, and settings do not opt in to idempotent replay.

The payment method object

A payment method is the saved record you reuse later. It keeps the customer link, the payment rail, masked rail-specific details, optional metadata, and verification state when that flow is in use for the method.

Properties

Name
active
Type
boolean
Description
Whether this payment method is active and reusable in new payment flows.
Name
archived_at
Type
timestamp
Description
When this payment method was archived. Omitted while the payment method remains unarchived.
Name
bank_account
Type
object
Description
Present when the method is a bank account. Contains the saved bank-account details for that rail.
Name
card
Type
object
Description
Present when the method is a card. Contains the saved card summary for that rail.
Name
created_at
Type
timestamp
Description
When this payment method was first saved.
Name
custom_data
Type
object
Description
Your own key-value metadata for internal tracking, reconciliation, or segmentation.
Name
customer_id
Type
string
Description
Customer who owns this payment method.
Name
expires_on
Type
timestamp
Description
Expiry timestamp when the underlying rail has one. Omitted otherwise.
Name
id
Type
string
Description
Unique identifier for this payment method.
Name
mobile_money
Type
object
Description
Present when the method is mobile money. Contains the network and the masked wallet number.
ownerobjectOwner details captured with the payment method when available.Click or tap to expand
- Name
  address
  Type
  object
  Description
  Postal address for the owner when available.
  View address attributesClick or tap to expand
  Name
  city
  Type
  string
  Description
  City or locality.
  Name
  country
  Type
  string
  Description
  Two-letter ISO country code.
  Name
  line_1
  Type
  string
  Description
  First line of the street address.
  Name
  line_2
  Type
  string
  Description
  Second line of the street address.
  Name
  name
  Type
  string
  Description
  Recipient name for this address when different.
  Name
  phone_number
  Type
  string
  Description
  Phone number for this address.
  Name
  post_code
  Type
  string
  Description
  Postal or ZIP code.
  Name
  region
  Type
  string
  Description
  Region, state, or province.
- Name
  name
  Type
  string
  Description
  Owner full legal name.
Name
type
Type
string
Description
Payment rail such as mobile_money, bank_account, card, or motito.
Name
verification
Type
object
Description
Most recent verification record when the method has entered a verification flow.
Name
verified_at
Type
timestamp
Description
When verification was completed. Omitted until the method is verified.

Tokenize payment method

Save a payment method to a customer without starting a charge. The request is a top-level discriminated union: set type to mobile_money, bank_account, motito, or card, then provide the matching type-specific object when one is required.

This operation supports idempotency. Send the same idempotency_key and request body to replay a successful response for up to 24 hours.

Required attributes

Name
customer_id
Type
string
Description
Customer who will own the saved payment method.
Name
type
Type
enum
Description
Payment method type: bank_account, card, mobile_money, or motito.

Conditional attributes

bank_accountobjectRequired when type is bank_account.Click or tap to expand
- Name
  ghana_bank_account
  Type
  object
  Description
  Required when bank_account.type is ghana_bank_account.
  View ghana_bank_account attributesClick or tap to expand
  Name
  account_number
  Type
  string
  Description
  Ghana bank account number.
  Name
  bank_code
  Type
  string
  Description
  Bank code used to identify the institution.
- Name
  type
  Type
  enum
  Description
  Currently ghana_bank_account.
mobile_moneyobjectRequired when type is mobile_money.Click or tap to expand
- Name
  account_number
  Type
  string
  Description
  Wallet number in local or international format.
- Name
  network
  Type
  enum
  Description
  One of airtel, mtn, telecel, or vodafone.
ownerobjectRequired for bank_account and mobile_money; optional for card and motito.Click or tap to expand
- Name
  address
  Type
  object
  Description
  Owner address. country is required; city, line1, line2, name, phone_number, post_code, and region are optional.
- Name
  name
  Type
  string
  Description
  Owner name.

Optional attributes

Name
custom_data
Type
object
Description
String key-value metadata to store with the payment method.

Request

POST

/payment_methods/tokenize

curl https://api.zebo.dev/payment_methods/tokenize \
  -H "Authorization: Bearer $COMMERCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cu_a1b2c3d4e5",
    "type": "mobile_money",
    "mobile_money": {
      "account_number": "0242057831",
      "network": "mtn"
    },
    "owner": {
      "name": "Jane Mensah",
      "address": { "country": "GH" }
    }
  }'

{
  "payment_method": {
    "id": "pm_xyz789",
    "active": true,
    "customer_id": "cu_a1b2c3d4e5",
    "type": "mobile_money",
    "mobile_money": {
      "network": "mtn",
      "account_number": "****7831",
      "last4": "7831"
    },
    "owner": {
      "name": "Jane Mensah",
      "address": { "country": "GH" }
    },
    "created_at": "2025-11-23T13:00:00Z"
  }
}

Verify payment method

Payment-method verification is currently unavailable. Requests to this operation return 501 Not Implemented, so no public request example is provided.

Lookup payment method

Fetch one saved payment method by ID. Use this when you want to show the method back to the customer, inspect its verification state, or confirm which saved instrument you are about to reuse.

Send only payment_method_id here. You do not need a customer_id, and this endpoint rejects it.

Required attributes

Name
payment_method_id
Type
string
Description
Payment method to fetch.

Request

POST

/payment_methods/lookup

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

{
  "payment_method": {
    "id": "pm_xyz789",
    "customer_id": "cu_a1b2c3d4e5",
    "type": "mobile_money",
    "mobile_money": {
      "network": "mtn",
      "account_number": "024205****"
    },
    "custom_data": {
      "segment": "vip"
    },
    "owner": {
      "name": "Jane Mensah",
      "address": {
        "country": "GH",
        "line_1": "1 High Street",
        "region": "Greater Accra"
      }
    },
    "verification": {
      "request_id": "ver_abc123",
      "type": "otp",
      "mechanism": "sms",
      "initiated_at": "2025-11-23T13:05:00Z",
      "completed_at": "2025-11-23T13:07:00Z"
    },
    "created_at": "2025-11-23T13:00:00Z",
    "verified_at": "2025-11-23T13:07:00Z"
  }
}

Update payment method

Update payment-method metadata without re-tokenizing the underlying instrument. Use this when you want to attach internal annotations, clean up owner details, or remove stale metadata keys.

Required attributes

Name
payment_method_id
Type
string
Description
Payment method you want to update.

Optional attributes

Name
active
Type
boolean
Description
Set whether the payment method can be reused. Do not send this together with archived.
Name
archived
Type
boolean
Description
Set the payment method's archived state. Do not send this together with active.
Name
custom_data
Type
object
Description
Metadata to merge into the existing custom_data object. New keys are added, existing keys are replaced, and keys sent as null are deleted.
ownerobjectOwner fields to patch onto the saved payment method. Omitted fields are left alone.Click or tap to expand
- Name
  address
  Type
  object
  Description
  Address fields to patch. If the method does not already have an owner address, include country when adding one.
  View address attributesClick or tap to expand
  Name
  city
  Type
  string
  Description
  City or locality.
  Name
  country
  Type
  string
  Description
  Two-letter ISO country code.
  Name
  line1
  Type
  string
  Description
  Street address line 1.
  Name
  line2
  Type
  string
  Description
  Street address line 2.
  Name
  name
  Type
  string
  Description
  Recipient name for the address when different.
  Name
  phone_number
  Type
  string
  Description
  Contact phone number for the address.
  Name
  post_code
  Type
  string
  Description
  Postal or ZIP code.
  Name
  region
  Type
  string
  Description
  Region, state, or province.
- Name
  name
  Type
  string
  Description
  Owner full legal name.

This operation supports idempotency. Send the same idempotency_key and request body to replay a successful response for up to 24 hours.

Request

POST

/payment_methods/update

curl https://api.zebo.dev/payment_methods/update \
  -H "Authorization: Bearer $COMMERCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method_id": "pm_xyz789",
    "active": false,
    "custom_data": {
      "segment": "vip",
      "legacy_note": null
    },
    "owner": {
      "name": "Jane Mensah",
      "address": {
        "country": "GH",
        "line1": "1 High Street",
        "region": "Greater Accra"
      }
    }
  }'

{
  "payment_method": {
    "id": "pm_xyz789",
    "customer_id": "cu_a1b2c3d4e5",
    "type": "mobile_money",
    "mobile_money": {
      "network": "mtn",
      "account_number": "024205****"
    },
    "custom_data": {
      "segment": "vip"
    },
    "owner": {
      "name": "Jane Mensah",
      "address": {
        "country": "GH",
        "line_1": "1 High Street",
        "region": "Greater Accra"
      }
    },
    "created_at": "2025-11-23T13:00:00Z",
    "verified_at": "2025-11-23T13:07:00Z"
  }
}

Page through payment methods

List the payment methods saved under the authenticated application. Results are newest first, so page 1 shows the most recently saved methods.

Provide customer_id when you want only one customer's saved methods. Leave it out when you want the broader application-level list.

Optional attributes

Name
customer_id
Type
string
Description
Optional customer filter for a single saved-method list.
Name
page_number
Type
integer
Description
1-based page index to fetch. Defaults to 1 when omitted.
Name
page_size
Type
integer
Description
Number of payment methods to return. Must be between 1 and 256. Defaults to 256.

Response shape

The top-level page object includes number, size, and payment_methods.
Each entry is the same payment method object returned by lookup.
When customer_id is present, every item in the page belongs to that customer.

Request

POST

/payment_methods/page

curl https://api.zebo.dev/payment_methods/page \
  -H "Authorization: Bearer $COMMERCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cu_a1b2c3d4e5",
    "page_number": 1,
    "page_size": 50
  }'

{
  "page": {
    "number": 1,
    "size": 1,
    "payment_methods": [
      {
        "id": "pm_xyz789",
        "customer_id": "cu_a1b2c3d4e5",
        "type": "mobile_money",
        "mobile_money": {
          "network": "mtn",
          "account_number": "****7831",
          "last4": "7831"
        },
        "created_at": "2025-11-23T13:00:00Z"
      }
    ]
  }
}

Delete payment method

Payment-method deletion is currently unavailable. Requests to this operation return 501 Not Implemented, so no public request example is provided. To prevent reuse, call Update payment method with active: false.

Payment method settings

Read which payment method types your application can present at checkout. Use the response to decide what to render and whether a rail needs explicit customer confirmation before use.

Response structure

The settings object returns one entry per payment method type. Each entry tells you:

whether the type is enabled
whether the type requires explicit customer confirmation via confirms_use
the display name and description you can use in your own UI

Request

POST

/payment_methods/settings

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

{
  "settings": {
    "mobile_money": {
      "type": "mobile_money",
      "name": "Mobile Money",
      "description": "Pay with Airtel, MTN, Telecel, or Vodafone 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.