GuidesAPI ReferenceChangelog
Log In
Guides
  1. Moneris API
  2. Overview
  3. Concepts
  4. Payment Method

Payment Method Services

The Payment Method is composed for 5 API:

  1. Create Payment Method
  2. Retrieve Payment Method
  3. Update Payment Method [Put]
  4. Update Payment Method [Patch]
  5. Delete Payment Method

1. Create a Payment Method Request

The following sample shows a payment-method request for a credit card with paymentMethodSource = CARD and token format permanentTokenFormat = 2U, and the response includes the payment method ID (paymentMethodId), confirms the token format (permanentTokenFormat), and provides the token value (permanentToken).

{
    "idempotencyKey": "78159eb6-52e6-4d36-b9cb-0ba35321c192",
    "cardholderInformation": {
        "cardholderName": "Name",
        "companyName": "Company Name Ltd"
    },
    "contactDetails": {
        "phoneNumber": "+18663197450",
        "email": "[email protected]"
    },
    "billingAddress": {
        "unitNumber": "1234A",
        "streetNumber": "1234",
        "streetName": "Street Name",
        "city": "City Name",
        "province": "AA",
        "postalCode": "M8X 2X2",
        "country": "CA"
    },
    "paymentMethodSource": "CARD",
    "card": {
        "cardNumber": "NNNNNNNNNNNNNNNNNNN",
        "expiryMonth": MM,
        "expiryYear": YYYY,
        "cardSecurityCode": NNN
    },
    permanentTokenFormat: "2U", - default value = 0
    "customData": {
        "property1": "string",
        "property2": "string"
    }
}

2. Retrieve Payment Method

The Retrieve Payment Method API is a simple but important read operation: it lets you fetch the current state and details of an existing payment method using its ID. It also work with an existing Data Key, and will return details of an existing data key. Add the Payment Method ID or the Data Key to the header to retrieve it.

What the API returns

It returns a Payment Method object or Data Key, which typically includes identification, cardholder and billing info, and payment method details.

Why you would use it

  • Display stored payment details or data key (safe subset) - Show saved cards in account settings
  • Validate a payment method before using it - Before charging, ensure the payment method belongs to the right merchant/customer
  • Debugging and reconciliation - Verify what was actually stored or investigate issues in transactions

3. List payment methods

The List Payment Methods API is used to retrieve a collection of payment methods, typically for a merchant or a specific customer, instead of just a single one. The List Payment Methods API returns a list, paginated, of stored Payment Methods that match certain filters such as customer, merchant, or criteria. The List Payment Method API returns only Permanent Payment Methods and excludes temporary ones, even if they have not expired. The Data Key associated to a Permanent Payment Method will not return.

Why you would use it

  • Show all saved payment methods: display all payment methods a customer has stored and let customer choose one, delete one or set a default
  • Customer profile management: if your system links customers to payment methods, show them during checkout
  • Back-office and administration tools: used by internal systems to audit stored payment methods, investigate issues or support customer service workflows
  • Bulk operations and lifecycle management: identify expired cards, review inactive payment methods and clean up unused ones

What the response looks like

  • The API returns a paginated list
  • Different of Retrieve Payment Method that provide one specific payment method detail by ID, the List Payment Methods API provide all stored payment methods, paginated
  • Supports filtering: customerId, paymentMethodType, date ranges and pagination (limit, offset)
  • Pagination is required: as best practice always paginate to avoid large payloads
  • Returns safe, non-sensitive data only: card brand, last 4 digits, no full card number or CVV
📘

Retrieve vs List APIs

  • Retrieve Payment Method → Get one specific payment method or Data Key by ID
  • List Payment Methods → Get many payment methods (paginated) and no Data Key

4. Update Payment method

The Update Payment Method API is used to update editable attributes of a payment method that has already been created and stored payment method without creating a new one.

The Update Payment Method API also supports updates when the merchant provides an existing Data Key. In business terms, the Moneris API determines whether that Data Key is already linked to a stored payment method and then updates the right system of record.

Business decision guide

  • Payment method ID with a Permanent Token: Update the stored payment method in Moneris API and propagate the related Data Key update, so both records stay aligned.
  • Payment method ID without a Permanent Token: Update only the stored payment method because there is no Data Key change to synchronize.
  • Data Key with an existing mapping: Update the linked stored payment method and update the corresponding Data Key, keeping the customer payment profile consistent across systems.
  • Data Key without an existing mapping: Update the Data Key only, because there is no stored payment method relationship to update.

The response will remain standardized across all scenarios. When applicable, it should clearly return the Data Key format and the Data Key so downstream systems can process the updated payment method consistently.

What you can usually update?

  • Card information: card number and CVV
  • Cardholder detail: name
  • Contact Details: e-mail and phone
  • Billing Address

The Update Payment Method API supports two modes: PATCH and PUT. Use PUT to replace the Payment Method ID object and PATCH to update it partially.

Why you would use it?

  • Update cardholder or billing info: user updates their profile
  • Fix incorrect or incomplete data: maybe initial data was partial or incorrect, and customer enrich or correct it later
  • Manage metadata and custom fields: if your system stores these, you can update those without touching the payment credentials

What you can usually update?

  • Card information: card number and CVV
  • Cardholder detail: name
  • Contact Details: e-mail and phone
  • Billing Address

5. Delete Payment Method

The Delete Payment Method API in the Moneris model is used to permanently remove a stored payment method from the Moneris API, so it can no longer be used for future transactions. The Delete Payment Method API only works for a permanent payment method due to its applicability and Data Key as well.

The Delete Payment Method API may also remove the associated Data Key. Whether this happens depends on the type of identifier provided and whether a payment method mapping exists, as summarized below.

What gets deleted in each scenario?

  • When the request uses a permanent payment method ID, Moneris deletes both the stored payment method record and the related Data Key.
  • When the request uses a temporary payment method ID, Moneris deletes only the stored payment method record.
  • When the request uses a Data Key that is linked to a stored payment method, Moneris deletes both the stored payment method record and the Data Key.
  • When the request uses a Data Key that is not linked to a stored payment method, Moneris deletes only the Data Key.

Why you would use it?

  • User removes a saved payment method: a customer goes to Saved Cards and clicks Remove card
  • Compliance and data minimization: many regulations and best practices require not storing payment data longer than necessary or allowing users to delete their data
  • Prevent unintended future billing: no future charges using that method
  • Replace outdated payment methods

What happens after deletion?

  • No longer usable: payments or retrievals using a deleted payment method or data key will fail.
  • Create a new payment method: the user must re-enter details if they need it again
📘

Important behaviors

  • It is permanent: this is not a soft delete, no undo and no recovery
  • New payment method must be created if needed again
  • Does not affect past transactions: deleting a payment method does not cancel past payments, remove transaction history or affect settlements or reporting
  • May not delete underlying tokens: if the payment method wraps a Vault token (Data key) or a third-party wallet token, deleting the Payment Method may remove the Moneris reference, however, not necessarily delete the underlying token, depending on Vault configuration


Updated 11 days ago

Did this page help you?