Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.gnosispay.com/llms.txt

Use this file to discover all available pages before exploring further.

Cards are their own domain, with lots of edge cases all around and a unique set of terms. On this document, we aim to present the most common concepts related to operating cards and what to expect of them. This is not an extensive guide and we encourage you to use this document as a way to start your journey. Both VISA and Mastercard have great resources and guides that you can also use.
For transaction-related concepts like payments, refunds, and reversals, see our dedicated Card Transactions guide.

​
Card Lifecycle

Cards go through several states during their lifetime:

​
Card States

  • Inactive: Card created but not yet activated
  • Active: Card activated and ready for use
  • Frozen: Temporarily disabled (can be unfrozen)
  • Lost: Reported as lost (requires replacement)
  • Stolen: Reported as stolen (requires replacement)
  • Expired: Past expiration date (requires replacement)

​
Card Activation

New cards must be activated before first use. Activation typically involves:
  • Verifying cardholder identity
  • Setting initial PIN (if required)
  • Confirming card receipt
  • Enabling spending limits

​
Card Management Operations

  • Freeze/Unfreeze: Temporarily disable card usage
  • Report Lost/Stolen: Permanently disable and request replacement
  • Update Limits: Modify spending or withdrawal limits
  • PIN Management: Change or reset PIN

​
Disputes

Disputes are used to recover funds for captured transactions. Their main use-case is to revert fraudulent transactions or problems with the product or service paid for. Fraud and non-fraud disputes have different requirements and rules, and undergo through different analysis to reach a conclusion.

​
Dispute Types

  • Fraud disputes: Unauthorized transactions
  • Non-fraud disputes: Issues with goods/services received
  • Processing errors: Technical or merchant errors

​
Dispute Process

  1. Initiation: Cardholder reports disputed transaction
  2. Investigation: Review transaction details and evidence
  3. Provisional Credit: Temporary refund while investigating
  4. Resolution: Final decision and permanent credit/debit

​
Card PINs

Visa cards have 2 places to store the PIN - the first place is on the physical card chip, called the offline PIN, and the second is the online PIN that is stored in the bank’s system. While these PINs usually have the same value, there can be cases where they differ, for instance when you change the card PIN. When paying at a point of sale (in a restaurant or in a shop), only the offline PIN may be verified, while ATMs usually connect to the bank network and check the online PIN. When using the PSE to change the PIN, only the online PIN is changed. At this point, the offline PIN is not updated since physical access to the card is needed to change the PIN on the chip. To update the offline PIN, you need to go to an ATM and perform any operation. ATM transactions always go online to the card issuer. This allows the issuer to send an “issuer script” to your card, which updates the offline PIN stored on the chip, synchronizing it with any recent PIN changes made online (with PSE). Without this synchronization, your offline PIN might be outdated and cause issues for transactions that rely on offline verification.

​
MCC: Merchant Category Code

Merchant Category Codes (MCCs) are used to classify businesses based on the types of goods or services they provide. These codes are important as they are often used for calculating interchange fees, authorizing payments, and preventing fraud. Additionally, specific MCCs are required for particular functionalities.