---
title: "Payment methods"
description: "Save a customer's payment method once, reuse it in later orders, and control when it remains available."
canonical: "https://studio.inttegro.com/api/payment-methods"
format: inttegro-machine-docs/v1
language: "cURL"
reader_profile: optional
reader_manifest: "https://studio.inttegro.com/machine/curl/readers/index.json"
reader_identification: "Optional: declare your client only if known and your current-session capabilities; use reader_manifest for supplemental recommendations."
preamble_estimated_tokens: 699
model_token_report: "https://studio.inttegro.com/machine/token-report.json"
preamble_questions: 5
preamble_source: "machine-only-decisions"
recommended_mcp_tools: ["get_payment_method_settings","prepare_order_payment","pay_order"]
estimated_tokens: 5787
token_estimate_method: "utf8_bytes_divided_by_4"
---

## Machine preamble

**Summary:** Save a customer's payment method once, reuse it in later orders, and control when it remains available. This cURL representation preserves HTTP paths and JSON wire names.

### Five questions

#### Q1. Is Payment methods the right source for this task?

Use this reference for save a customer's payment method once, reuse it in later orders, and control when it remains available. For the complete outcome or lifecycle, start with [Understand payment method settings](https://studio.inttegro.com/machine/curl/guides/understand-payment-method-settings.md); return here for exact operations and fields.

#### Q2. How do I verify the customer boundary?

**Match the customer boundary first.** A saved method can be used only with
the customer that owns it. Retrieve both records rather than accepting a
caller-supplied pairing without verification.

#### Q3. Does tokenization charge an order?

**Tokenization stores a method; it does not create or charge an order.** For a
payment workflow, continue with [Orders](https://studio.inttegro.com/machine/curl/api/orders.md) or [Charge repeat
customers](https://studio.inttegro.com/machine/curl/guides/charge-repeat-customers.md) after tokenization succeeds.

#### Q4. Which lifecycle signals determine reuse?

**Evaluate all lifecycle signals.** A method is not reusable merely because `payment_method.active`is true; archived and ephemeral methods remain unavailable. Unarchiving does
not reactivate a method.

#### Q5. Which operation should change lifecycle state?

**Prefer the dedicated lifecycle operation for a state-only change.** Use
activate, deactivate, archive, or unarchive instead of combining state fields
in update. This avoids invalid combinations and makes the intended transition
explicit.

### Recommended MCP assistance

Use these through an authenticated Inttegro MCP connection. This document remains the contract source.

- [`get_payment_method_settings`](https://studio.inttegro.com/machine/curl/inttegro-mcp/tools.md#get_payment_method_settings) — read; no mutation confirmation. Gets enabled and confirmation-required settings for each payment method type without exposing payment credentials.
- [`prepare_order_payment`](https://studio.inttegro.com/machine/curl/inttegro-mcp/tools.md#prepare_order_payment) — read; no mutation confirmation. Returns the exact major-unit order total, only masked active payment-method choices, and a trusted secure-checkout URL without exposing payment credentials.
- [`pay_order`](https://studio.inttegro.com/machine/curl/inttegro-mcp/tools.md#pay_order) — action; exact user confirmation required. Starts or deliberately retries a real payment after a masked method choice and exact confirmation. New details and OTP stay in secure Inttegro Checkout.

## Document content

# Payment methods

Payment methods let customers save how they pay and reuse it on later orders. Use this API to save a method, retrieve it, update its owner or metadata, and control whether it can be used again.

Each payment method belongs to one [customer](https://studio.inttegro.com/machine/curl/api/customers.md). When charging a saved method, use it with that same customer. For end-to-end payment flows, see [Accept a mobile money payment](https://studio.inttegro.com/machine/curl/guides/accept-mobile-money-payment.md) and [Charge repeat customers](https://studio.inttegro.com/machine/curl/guides/charge-repeat-customers.md).

## Decide whether a saved payment method is actually reusable

The four decision rules are in the machine preamble above.

## The payment method object

The API returns a `payment_method` envelope for tokenization, lookup, update, and lifecycle operations. Optional properties are omitted when they do not apply or have no value.

### Properties

- `active` — `boolean`

  Whether the method is enabled for reuse. An archived or ephemeral method is
  not reusable even if this field is
  `true`.

- `archived_at` — `timestamp`

  When the method was archived. Omitted while the method is unarchived.

- `bank_account`

  Bank-account details when the saved method has a bank-account representation. Treat these fields as sensitive.

  - `bank_account.ghana_bank_account` — `object`

    Ghana bank-account details when present.

    - `bank_account.ghana_bank_account.account_number` — `string`

      Account number returned for the saved bank account.

    - `bank_account.ghana_bank_account.branch` — `string`

      Bank branch when available.

    - `bank_account.ghana_bank_account.name` — `string`

      Account name when available.

    - `bank_account.ghana_bank_account.sort_code` — `string`

      Bank sort code when available.

    - `bank_account.ghana_bank_account.swift_code` — `string`

      SWIFT code when available.

  - `bank_account.type` — `string`

    Bank-account subtype.

- `created_at` — `timestamp`

  When the method was saved.

- `customer_id` — `string`

  Customer who owns the method.

- `custom_data` — `object`

  Your metadata. Values are returned as strings.

- `ephemeral` — `boolean`

  Present and `true` for a
  limited-use method that cannot be reused as a saved method.

- `expires_on` — `timestamp`

  Expiry time when the underlying payment method has one.

- `fingerprint` — `string`

  A customer-specific fingerprint that helps identify duplicate saved payment
  methods.

- `id` — `string`

  Unique payment method identifier with the `pm_` prefix.

- `mobile_money`

  Masked mobile money details.

  - `mobile_money.account_number` — `string`

    Masked wallet number in the form \*\*\*\*1234.

  - `mobile_money.last4` — `string`

    Final four digits of the normalized wallet number.

  - `mobile_money.network` — `enum`

    Wallet network: `"airtel"` , `"mtn"` , `"telecel"` , or `"vodafone"` .

- `owner`

  Owner details captured with the method.

  - `owner.address` — `object`

    Owner postal address.

    - `owner.address.city` — `string`

      City or locality.

    - `owner.address.country` — `string`

      Country code supplied when the address was saved.

    - `owner.address.line_1` — `string`

      First address line. Requests use line1; responses use `payment_method.owner.address.line_1`.

    - `owner.address.line_2` — `string`

      Second address line. Requests use line2; responses use `payment_method.owner.address.line_2`.

    - `owner.address.name` — `string`

      Recipient name for the address.

    - `owner.address.phone_number` — `string`

      Address contact number.

    - `owner.address.post_code` — `string`

      Postal or ZIP code.

    - `owner.address.region` — `string`

      Region, state, or province.

  - `owner.name` — `string`

    Payment-method owner name.

- `supplied`

  How and when the payment method was added to the customer's account.

  - `supplied.attempt_id` — `string`

    Collection attempt that supplied the method, when applicable.

  - `supplied.by` — `string` — required

    Who supplied the method: `"customer"` or `"merchant"`.

  - `supplied.channel` — `string`

    Where the method was collected, such as `"api"`, `"buy_link"` , `"ego"`, `"hosted_collection"` , or `"hosted_invoice"` .

  - `supplied.resource_id` — `string`

    Source resource that collected the method, when applicable.

  - `supplied.resource_type` — `string`

    Type of source resource that collected the method.

  - `supplied.supplied_at` — `timestamp` — required

    When the method was supplied.

- `type` — `enum`

  Payment method type: `"bank_account"`, `"card"`, or `"mobile_money"`.

- `verification`

  Verification evidence when the method has entered a verification flow.

  - `verification.completed_at` — `timestamp`

    When verification completed. Omitted while incomplete.

  - `verification.initiated_at` — `timestamp`

    When verification began.

  - `verification.mechanism` — `string`

    Verification mechanism when available.

  - `verification.request_id` — `string`

    Identifier for the verification request.

  - `verification.type` — `string`

    Verification type.

- `verified_at` — `timestamp`

  When verification completed. Omitted until completion.

## Tokenize a payment method

Save a customer's mobile money wallet so they can select it on later orders. This operation does not create an order or charge the wallet. The response returns a `pm_...` ID for future payments.

### Request attributes

- `customer_id` — `string` — required

  Customer who will own the saved payment method.

- `custom_data` — `object`

  Optional metadata. The serialized object must not exceed 25 KB and each key must not exceed 256 characters. Non-string values are stored as JSON strings.

- `mobile_money` — required

  Mobile money wallet to save.

  - `mobile_money.account_number` — `string` — required

    Valid local or international wallet phone number.

  - `mobile_money.network` — `enum` — required

    `"airtel"`, `"mtn"`, `"telecel"`, or `"vodafone"`.

- `owner` — required

  Owner identity for the wallet.

  - `owner.address` — `object` — required

    Postal address associated with the owner.

    - `owner.address.city` — `string`

      City or locality.

    - `owner.address.country` — `string` — required

      Country associated with the owner address.

    - `owner.address.line1` — `string`

      First address line.

    - `owner.address.line2` — `string`

      Second address line.

    - `owner.address.name` — `string`

      Recipient name for the address.

    - `owner.address.phone_number` — `string`

      Contact number for the address.

    - `owner.address.post_code` — `string`

      Postal or ZIP code.

    - `owner.address.region` — `string`

      Region, state, or province.

  - `owner.name` — `string` — required

    Payment method owner name.

- `type` — `enum` — required

  Set to `"mobile_money"` for the supported direct-tokenization flow.

The account number must be valid for the selected mobile money network. Use an idempotency key when retrying so the same wallet is not saved twice.

**Request — POST /payment\_methods/tokenize**

```bash
curl https://api.inttegro.com/payment_methods/tokenize \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: save-wallet-cu-a1b2-001" \
  -d '{
    "customer_id": "cu_a1b2c3d4e5",
    "custom_data": {
      "checkout_source": "account"
    },
    "mobile_money": {
      "account_number": "0242057831",
      "network": "mtn"
    },
    "owner": {
      "address": {
        "country": "GH"
      },
      "name": "Jane Mensah"
    },
    "type": "mobile_money"
  }'
```

```json
{
  "payment_method": {
    "active": true,
    "created_at": "2026-08-30T13:00:00Z",
    "customer_id": "cu_a1b2c3d4e5",
    "custom_data": {
      "checkout_source": "account"
    },
    "fingerprint": "ifp_v1_app_customer",
    "id": "pm_z7Qx4Lm9Pc2Vb8Nt6Ks1Ha3D",
    "mobile_money": {
      "account_number": "****7831",
      "last4": "7831",
      "network": "mtn"
    },
    "owner": {
      "address": {
        "country": "GH"
      },
      "name": "Jane Mensah"
    },
    "type": "mobile_money"
  }
}
```

## Lookup a payment method

Retrieve a saved payment method by ID. Lookup also returns inactive, archived, and ephemeral methods, so check `payment_method.active`, `payment_method.archived_at`, and `payment_method.ephemeral` before offering it as a payment choice.

### Request attributes

- `payment_method_id` — `string` — required

  Payment method to fetch.

**Request — POST /payment\_methods/lookup**

```bash
curl https://api.inttegro.com/payment_methods/lookup \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method_id": "pm_z7Qx4Lm9Pc2Vb8Nt6Ks1Ha3D"
  }'
```

```json
{
  "payment_method": {
    "active": true,
    "created_at": "2026-08-30T13:00:00Z",
    "customer_id": "cu_a1b2c3d4e5",
    "fingerprint": "ifp_v1_app_customer",
    "id": "pm_z7Qx4Lm9Pc2Vb8Nt6Ks1Ha3D",
    "mobile_money": {
      "account_number": "****7831",
      "last4": "7831",
      "network": "mtn"
    },
    "type": "mobile_money"
  }
}
```

## Update a payment method

Patch mutable metadata or state without replacing the underlying payment instrument. Omitted fields remain unchanged.

### Request attributes

- `active` — `boolean`

  Set the active state. Do not send this together with `archived`.

- `archived` — `boolean`

  Set the archived state. Do not send this together with `active`.

- `custom_data` — `object`

  Metadata to merge. New keys are added, existing keys are replaced, `null` deletes a key, and omitted keys remain unchanged.

- `owner`

  Owner patch. Include at least one of owner.address or owner.name; values cannot be empty.

  - `owner.address` — `object`

    Address patch. Include at least one field. When adding the first address to a method, `owner.address.country` is required.

    - `owner.address.city` — `string`

      City or locality.

    - `owner.address.country` — `string`

      Country code.

    - `owner.address.line1` — `string`

      First address line.

    - `owner.address.line2` — `string`

      Second address line.

    - `owner.address.name` — `string`

      Recipient name for the address.

    - `owner.address.phone_number` — `string`

      Address contact number.

    - `owner.address.post_code` — `string`

      Postal or ZIP code.

    - `owner.address.region` — `string`

      Region, state, or province.

  - `owner.name` — `string`

    Payment-method owner name.

- `payment_method_id` — `string` — required

  Payment method to update.

Provide at least one change in addition to `payment_method_id`. An archived method must be unarchived before you can change anything else. Unarchiving does not reactivate it.

Prefer the dedicated lifecycle operations below when you are changing only state. They make intent clearer and reduce accidental combinations.

**Request — POST /payment\_methods/update**

```bash
curl https://api.inttegro.com/payment_methods/update \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: update-wallet-owner-001" \
  -d '{
    "custom_data": {
      "legacy_note": null,
      "segment": "vip"
    },
    "owner": {
      "address": {
        "line1": "1 High Street",
        "region": "Greater Accra"
      },
      "name": "Jane Mensah"
    },
    "payment_method_id": "pm_z7Qx4Lm9Pc2Vb8Nt6Ks1Ha3D"
  }'
```

```json
{
  "payment_method": {
    "active": true,
    "created_at": "2026-08-30T13:00:00Z",
    "customer_id": "cu_a1b2c3d4e5",
    "custom_data": {
      "segment": "vip"
    },
    "fingerprint": "ifp_v1_app_customer",
    "id": "pm_z7Qx4Lm9Pc2Vb8Nt6Ks1Ha3D",
    "owner": {
      "address": {
        "country": "GH",
        "line_1": "1 High Street",
        "region": "Greater Accra"
      },
      "name": "Jane Mensah"
    },
    "type": "mobile_money"
  }
}
```

## Activate a payment method

Make an inactive payment method available for reuse. An archived method must be unarchived first; a method that is already active cannot be activated again.

### Request attributes

- `payment_method_id` — `string` — required

  Payment method to activate.

### Response

The response is a `payment_method` envelope with `payment_method.active` set to `true` and no `payment_method.archived_at`.

**Request — POST /payment\_methods/activate**

```bash
curl https://api.inttegro.com/payment_methods/activate \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: activate-wallet-001" \
  -d '{
    "payment_method_id": "pm_z7Qx4Lm9Pc2Vb8Nt6Ks1Ha3D"
  }'
```

## Deactivate a payment method

Temporarily prevent a payment method from being reused without archiving it. The method can still be retrieved and updated, then activated again when the customer wants to use it. A method that is already inactive cannot be deactivated again.

### Request attributes

- `payment_method_id` — `string` — required

  Payment method to deactivate.

### Response

The response is a `payment_method` envelope with `payment_method.active` set to `false`.

**Request — POST /payment\_methods/disactivate**

```bash
curl https://api.inttegro.com/payment_methods/disactivate \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: deactivate-wallet-001" \
  -d '{
    "payment_method_id": "pm_z7Qx4Lm9Pc2Vb8Nt6Ks1Ha3D"
  }'
```

## Archive a payment method

Archive a payment method when the customer no longer wants it offered. Archiving sets `payment_method.active` to `false` and records `payment_method.archived_at`. An archived method cannot be archived again.

### Request attributes

- `payment_method_id` — `string` — required

  Payment method to archive.

### Response

The response is a `payment_method` envelope with `payment_method.active` set to `false` and a populated `payment_method.archived_at` timestamp.

**Request — POST /payment\_methods/archive**

```bash
curl https://api.inttegro.com/payment_methods/archive \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: archive-wallet-001" \
  -d '{
    "payment_method_id": "pm_z7Qx4Lm9Pc2Vb8Nt6Ks1Ha3D"
  }'
```

## Unarchive a payment method

Restore an archived payment method so it can be updated again. Unarchiving clears `payment_method.archived_at` but leaves `payment_method.active` set to `false`; call [Activate a payment method](#activate-a-payment-method) separately before offering it to the customer. A method that is not archived cannot be unarchived.

### Request attributes

- `payment_method_id` — `string` — required

  Payment method to unarchive.

### Response

The response is a `payment_method` envelope with `payment_method.active` set to `false` and no `payment_method.archived_at`.

**Request — POST /payment\_methods/unarchive**

```bash
curl https://api.inttegro.com/payment_methods/unarchive \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unarchive-wallet-001" \
  -d '{
    "payment_method_id": "pm_z7Qx4Lm9Pc2Vb8Nt6Ks1Ha3D"
  }'
```

## Page through payment methods

Browse saved payment methods, optionally limiting the results to one customer. The API does not guarantee newest-first ordering.

> Mcp Endpoint Tools is interactive content. Use the canonical page to view it.

### Request attributes

- `customer_id` — `string`

  Customer whose saved payment methods you want to list.

- `page_number` — `integer`

  1-based page number to retrieve. Omit it to use page `1`. Supported
  pages are `1` through `10`.

- `page_size` — `integer`

  Maximum number of payment methods to return, from `1` through `256`. Defaults to `256`.

The response contains `page.number`, `page.payment_methods`, and `page.size`. `page.size` is the number of payment methods returned. Increase `page_number` to request the next page, up to page `10`.

**Request — POST /payment\_methods/page**

```bash
curl https://api.inttegro.com/payment_methods/page \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cu_a1b2c3d4e5",
    "page_number": 1,
    "page_size": 50
  }'
```

```json
{
  "page": {
    "number": 1,
    "payment_methods": [
      {
        "active": true,
        "created_at": "2026-08-30T13:00:00Z",
        "customer_id": "cu_a1b2c3d4e5",
        "fingerprint": "ifp_v1_app_customer",
        "id": "pm_z7Qx4Lm9Pc2Vb8Nt6Ks1Ha3D",
        "mobile_money": {
          "account_number": "****7831",
          "last4": "7831",
          "network": "mtn"
        },
        "type": "mobile_money"
      }
    ],
    "size": 1
  }
}
```

## Payment method settings

See which payment methods your account accepts and whether each one requires customer confirmation. Send an empty JSON object. The response can contain `settings.bank_account`, `settings.card`, and `settings.mobile_money` entries.

Each entry has required `settings.mobile_money.confirms_use` and `settings.mobile_money.enabled` booleans. `settings.mobile_money.type`, `settings.mobile_money.name`, and `settings.mobile_money.description` are included when configured. When `settings.mobile_money.confirms_use` is `true`, the payment flow should require customer confirmation before completing use of that payment type; it is not the same as the method's verification state.

New accounts enable recognized payment types and require confirmation by default, unless their configuration has been changed. See [Understand payment method settings](https://studio.inttegro.com/machine/curl/guides/understand-payment-method-settings.md) for how these settings affect checkout.

> Mcp Endpoint Tools is interactive content. Use the canonical page to view it.

**Request — POST /payment\_methods/settings**

```bash
curl https://api.inttegro.com/payment_methods/settings \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

```json
{
  "settings": {
    "bank_account": {
      "confirms_use": true,
      "enabled": true,
      "type": "bank_account"
    },
    "card": {
      "confirms_use": true,
      "enabled": true,
      "type": "card"
    },
    "mobile_money": {
      "confirms_use": true,
      "enabled": true,
      "type": "mobile_money"
    }
  }
}
```

## Related resources

- [Create customer](https://studio.inttegro.com/machine/curl/api/customers.md#create-customer) - Create the owner before tokenizing a method.
- [Create an order](https://studio.inttegro.com/machine/curl/api/orders.md#create-an-order) - Use a saved method with its owning customer.
- [Pay an order](https://studio.inttegro.com/machine/curl/api/orders.md#pay-for-an-order) - Attach a saved method when collecting payment after order creation.
- [Confirm a payment](https://studio.inttegro.com/machine/curl/api/orders.md#confirm-a-payment) - Complete required customer confirmation.