Skip to main content
View as Markdown

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. When charging a saved method, use it with that same customer. For end-to-end payment flows, see Accept a mobile money payment and Charge repeat customers.

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​

TypeScript SDK responsePaymentMethodv12.0.0
  • Name
    active
    Type
    boolean
    Description

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

  • Name
    archivedAt
    Type
    Date | null
    Description

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

  • bankAccountPaymentMethodBankAccount | nullBank-account details when the saved method has a bank-account representation. Treat these fields as sensitive.Click or tap to expand
    • Name
      ghanaBankAccount
      Type
      { … } | null
      View ghana_bank_account attributesClick or tap to expand
      Ghana bank-account details when present.
      • Name
        accountNumber
        Type
        string
        Description
        Account number returned for the saved bank account.
      • Name
        branch
        Type
        string
        Description
        Bank branch when available.
      • Name
        name
        Type
        string
        Description
        Account name when available.
      • Name
        sortCode
        Type
        string
        Description
        Bank sort code when available.
      • Name
        swiftCode
        Type
        string
        Description
        SWIFT code when available.
    • Name
      type
      Type
      string
      Description
      Bank-account subtype.
  • Name
    createdAt
    Type
    Date
    Description

    When the method was saved.

  • Name
    customerId
    Type
    string
    Description

    Customer who owns the method.

  • customDataCustomData | nullClick or tap to expand

    Your metadata. Values are returned as strings.

  • Name
    ephemeral
    Type
    boolean
    Description

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

  • Name
    expiresOn
    Type
    Date | null
    Description

    Expiry time when the underlying payment method has one.

  • Name
    fingerprint
    Type
    string
    Description

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

  • Name
    id
    Type
    string
    Description

    Unique payment method identifier with the pm_ prefix.

  • mobileMoneyPaymentMethodMobileMoney | nullMasked mobile money details.Click or tap to expand
  • ownerPaymentMethodOwner | nullOwner details captured with the method.Click or tap to expand
    • Name
      address
      Type
      PaymentMethodOwnerAddress | null
      View address attributesClick or tap to expand
      Owner postal address.
      • Name
        city
        Type
        string | null
        Description
        City or locality.
      • Name
        country
        Type
        string
        Description
        Country code supplied when the address was saved.
      • Name
        line1
        Type
        string
        Description
        First address line. Requests use line1; responses use owner.address.line1.
      • Name
        line2
        Type
        string
        Description
        Second address line. Requests use line2; responses use owner.address.line2.
      • Name
        name
        Type
        string | null
        Description
        Recipient name for the address.
      • Name
        phoneNumber
        Type
        string | null
        Description
        Address contact number.
      • Name
        postCode
        Type
        string | null
        Description
        Postal or ZIP code.
      • Name
        region
        Type
        string | null
        Description
        Region, state, or province.
    • Name
      name
      Type
      string
      Description
      Payment-method owner name.
  • suppliedPaymentMethodSupplied | nullHow and when the payment method was added to the customer's account.Click or tap to expand
    • Name
      attemptId
      Type
      string | null
      Description
      Collection attempt that supplied the method, when applicable.
    • Name
      by
      Type
      string
      Required
      required
      Description
      Who supplied the method: "customer" or "merchant".
    • Name
      channel
      Type
      string | null
      Description
      Where the method was collected, such as "api", "buy_link", "ego", "hosted_collection", or "hosted_invoice".
    • Name
      resourceId
      Type
      string | null
      Description
      Source resource that collected the method, when applicable.
    • Name
      resourceType
      Type
      string | null
      Description
      Type of source resource that collected the method.
    • Name
      suppliedAt
      Type
      Date
      Required
      required
      Description
      When the method was supplied.
  • Name
    type
    Type
    PaymentMethodType
    Description

    Payment method type:

    Inttegro.PaymentMethodTypes.BankAccount

    ,

    Inttegro.PaymentMethodTypes.Card

    , or

    Inttegro.PaymentMethodTypes.MobileMoney

    .

  • verificationPaymentMethodVerification | nullVerification evidence when the method has entered a verification flow.Click or tap to expand
    • Name
      completedAt
      Type
      Date | null
      Description
      When verification completed. Omitted while incomplete.
    • Name
      initiatedAt
      Type
      Date
      Description
      When verification began.
    • Name
      mechanism
      Type
      string
      Description
      Verification mechanism when available.
    • Name
      requestId
      Type
      string
      Description
      Identifier for the verification request.
    • Name
      type
      Type
      string
      Description
      Verification type.
  • Name
    verifiedAt
    Type
    Date | null
    Description

    When verification completed. Omitted until completion.

POST/payment_methods/tokenize

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​

TypeScript SDK requestTokenizePaymentMethodRequestv12.0.0

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
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.paymentMethods.tokenize({
  customerId: "cu_a1b2c3d4e5",
  customData: {
    checkout_source: "account",
  },
  mobileMoney: {
    accountNumber: "0242057831",
    network: Inttegro.MobileMoneyNetworks.MTN,
  },
  owner: {
    address: {
      country: "GH",
    },
    name: "Jane Mensah",
  },
  type: Inttegro.PaymentMethodTypes.MobileMoney,
})

Response

SDK versionv12.0.0
PaymentMethodResponse {
  paymentMethod: { … },
}
POST/payment_methods/lookup

Lookup a payment method

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

Request attributes​

TypeScript SDK requestLookupPaymentMethodRequestv12.0.0
  • Name
    paymentMethodId
    Type
    string
    Required
    required
    Description

    Payment method to fetch.

Request

POST/payment_methods/lookup
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.paymentMethods.lookup({
  paymentMethodId: "pm_z7Qx4Lm9Pc2Vb8Nt6Ks1Ha3D",
})

Response

SDK versionv12.0.0
PaymentMethodResponse {
  paymentMethod: { … },
}
POST/payment_methods/update

Update a payment method

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

Request attributes​

TypeScript SDK requestUpdatePaymentMethodRequestv12.0.0
  • Name
    active
    Type
    boolean
    Description

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

  • Name
    archived
    Type
    boolean
    Description

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

  • customDataCustomDataPatchClick or tap to expand

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

  • ownerPaymentMethodOwnerPatchOwner patch. Include at least one of owner.address or owner.name; values cannot be empty.Click or tap to expand
    • Name
      address
      Type
      PaymentMethodOwnerAddressPatch | null
      View address attributesClick or tap to expand
      Address patch. Include at least one field. When adding the first address to a method, owner.address.country is required.
      • Name
        city
        Type
        string | null
        Description
        City or locality.
      • Name
        country
        Type
        string | null
        Description
        Country code.
      • Name
        line1
        Type
        string | null
        Description
        First address line.
      • Name
        line2
        Type
        string | null
        Description
        Second address line.
      • Name
        name
        Type
        string | null
        Description
        Recipient name for the address.
      • Name
        phoneNumber
        Type
        string | null
        Description
        Address contact number.
      • Name
        postCode
        Type
        string | null
        Description
        Postal or ZIP code.
      • Name
        region
        Type
        string | null
        Description
        Region, state, or province.
    • Name
      name
      Type
      string | null
      Description
      Payment-method owner name.
  • Name
    paymentMethodId
    Type
    string
    Required
    required
    Description

    Payment method to update.

Provide at least one change in addition to paymentMethodId. 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
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.paymentMethods.update({
  customData: {
    legacy_note: null,
    segment: "vip",
  },
  owner: {
    address: {
      line1: "1 High Street",
      region: "Greater Accra",
    },
    name: "Jane Mensah",
  },
  paymentMethodId: "pm_z7Qx4Lm9Pc2Vb8Nt6Ks1Ha3D",
})

Response

SDK versionv12.0.0
PaymentMethodResponse {
  paymentMethod: { … },
}
POST/payment_methods/activate

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​

TypeScript SDK requestPaymentMethodActionRequestv12.0.0
  • Name
    paymentMethodId
    Type
    string
    Required
    required
    Description

    Payment method to activate.

Response​

The response is a paymentMethod envelope with paymentMethod.active set to true and no paymentMethod.archivedAt.

Request

POST/payment_methods/activate
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.paymentMethods.activate({
  paymentMethodId: "pm_z7Qx4Lm9Pc2Vb8Nt6Ks1Ha3D",
})
POST/payment_methods/disactivate

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​

TypeScript SDK requestPaymentMethodActionRequestv12.0.0
  • Name
    paymentMethodId
    Type
    string
    Required
    required
    Description

    Payment method to deactivate.

Response​

The response is a paymentMethod envelope with paymentMethod.active set to false.

Request

POST/payment_methods/disactivate
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.paymentMethods.disactivate({
  paymentMethodId: "pm_z7Qx4Lm9Pc2Vb8Nt6Ks1Ha3D",
})
POST/payment_methods/archive

Archive a payment method

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

Request attributes​

TypeScript SDK requestPaymentMethodActionRequestv12.0.0
  • Name
    paymentMethodId
    Type
    string
    Required
    required
    Description

    Payment method to archive.

Response​

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

Request

POST/payment_methods/archive
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.paymentMethods.archive({
  paymentMethodId: "pm_z7Qx4Lm9Pc2Vb8Nt6Ks1Ha3D",
})
POST/payment_methods/unarchive

Unarchive a payment method

Restore an archived payment method so it can be updated again. Unarchiving clears archivedAt but leaves active set to false; call Activate a payment method separately before offering it to the customer. A method that is not archived cannot be unarchived.

Request attributes​

TypeScript SDK requestPaymentMethodActionRequestv12.0.0
  • Name
    paymentMethodId
    Type
    string
    Required
    required
    Description

    Payment method to unarchive.

Response​

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

Request

POST/payment_methods/unarchive
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.paymentMethods.unarchive({
  paymentMethodId: "pm_z7Qx4Lm9Pc2Vb8Nt6Ks1Ha3D",
})
POST/payment_methods/page

Page through payment methods

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

Available through MCP

AI clients can use prepare_order_payment or pay_order for this operation. Confirmed MCP actions still require explicit form confirmation before Inttegro changes state.

Request attributes​

TypeScript SDK requestPagePaymentMethodsRequestv12.0.0
  • Name
    customerId
    Type
    string
    Description

    Customer whose saved payment methods you want to list.

  • Name
    pageNumber
    Type
    number
    Description

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

  • Name
    pageSize
    Type
    number
    Description

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

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

Request

POST/payment_methods/page
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.paymentMethods.page({
  customerId: "cu_a1b2c3d4e5",
  pageNumber: 1,
  pageSize: 50,
})

Response

SDK versionv12.0.0
PageResponse {
  page: { … },
}
POST/payment_methods/settings

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 bankAccount, card, and mobileMoney entries.

Each entry has required mobileMoney.confirmsUse and mobileMoney.enabled booleans. mobileMoney.type, mobileMoney.name, and mobileMoney.description are included when configured. When mobileMoney.confirmsUse 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 for how these settings affect checkout.

Available through MCP

AI clients can use get_payment_method_settings for this operation. MCP read tools return minimized business data and do not change Inttegro state.

Request

POST/payment_methods/settings
SDK versionv12.0.0
import * as Inttegro from '@inttegro/inttegro-sdk'

const inttegro = new Inttegro.InttegroClient({
  apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.paymentMethods.settings()

Response

SDK versionv12.0.0
SettingsResponse {
  settings: { … },
}