Payment Methods

Author: Josh S. Sakweli, Backend Lead Team
Last Updated: 2025-10-27
Version: v1.0

Base URL: https://api.nextgate.com/api/v1

Short Description: The Payment Methods API enables users to manage their payment instruments including credit/debit cards, mobile money (M-Pesa, Airtel Money), bank transfers, PayPal, cryptocurrencies, wallets, gift cards, and cash on delivery options. This API provides secure storage, retrieval, updating, and deletion of payment methods with built-in validation and duplicate detection.

Hints:

All endpoints require authentication via Bearer token in the Authorization header
Sensitive data (card numbers, account numbers, PINs) are automatically tokenized and masked in responses
Only one payment method can be set as default at a time; setting a new default automatically unsets the previous one
Payment methods support soft verification status tracking (isVerified, isActive flags)
The API uses ISO 8601 format for timestamps (YYYY-MM-DDTHH:mm:ss)
Metadata fields accept custom JSON objects for storing gateway-specific information
Duplicate payment methods (same card number, email, phone number, etc.) are automatically detected and rejected

Standard Response Format

All API responses follow a consistent structure using our Globe Response Builder pattern:

Success Response Structure

{
  "success": true,
  "httpStatus": "OK",
  "message": "Operation completed successfully",
  "action_time": "2025-10-27T10:30:45",
  "data": {
    // Actual response data goes here
  }
}

Error Response Structure

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Error description",
  "action_time": "2025-10-27T10:30:45",
  "data": "Error description"
}

Standard Response Fields

Field	Type	Description
`success`	boolean	Always `true` for successful operations, `false` for errors
`httpStatus`	string	HTTP status name (OK, BAD_REQUEST, NOT_FOUND, etc.)
`message`	string	Human-readable message describing the operation result
`action_time`	string	ISO 8601 timestamp of when the response was generated
`data`	object/string	Response payload for success, error details for failures

HTTP Method Badge Standards

For better visual clarity, all endpoints use colored badges for HTTP methods with the following standard colors:

GET - GET - Green (Safe, read-only operations)
POST - POST - Blue (Create new resources)
PUT - PUT - Yellow (Update/replace entire resource)
PATCH - PATCH - Orange (Partial updates)
DELETE - DELETE - Red (Remove resources)

Available Enums

Payment Method Types

Use these exact values for the paymentMethodType field:

Enum Value	Description	Common Use Cases
`CREDIT_CARD`	Credit card payments	Visa, Mastercard, Amex, Discover
`DEBIT_CARD`	Debit card payments	Visa Debit, Mastercard Debit
`PAYPAL`	PayPal account payments	PayPal email-based payments
`BANK_TRANSFER`	Direct bank account transfers	ACH, Wire transfers, local bank payments
`CRYPTOCURRENCY`	Crypto wallet payments	Bitcoin, Ethereum, USDT, etc.
`MOBILE_PAYMENT`	Mobile payment services	Apple Pay, Google Pay, Samsung Pay
`MNO_PAYMENT`	Mobile Network Operator payments	M-Pesa, Airtel Money, Tigo Pesa
`WALLET`	Digital wallet services	Skrill, Neteller, PayTM
`GIFT_CARD`	Gift card payments	Store gift cards, prepaid cards
`CASH_ON_DELIVERY`	Cash payment upon delivery	COD orders

Mobile Network Operators (Tanzania)

Use these exact values for the mccMnc field when paymentMethodType is MNO_PAYMENT:

Enum Value	Operator Name	Network
`M_PESA`	M-Pesa	Vodacom Tanzania
`AIRTEL_MONEY`	Airtel Money	Airtel Tanzania
`TIGO_PESA`	Tigo Pesa	Tigo Tanzania
`HALO_PESA`	Halo Pesa	Halotel Tanzania
`AZAM_PESA`	Azam Pesa	Azam Telecom
`EZY_PESA`	Ezy Pesa	Zantel

Banks (Tanzania)

Use these exact values for the bankName field when paymentMethodType is BANK_TRANSFER:

Enum Value	Bank Name
`CRDB_BANK`	CRDB Bank PLC
`NMB_BANK`	National Microfinance Bank
`EXIM_BANK`	EXIM Bank Tanzania
`KCB_BANK`	Kenya Commercial Bank
`NBC_BANK`	National Bank of Commerce
`STANBIC_BANK`	Stanbic Bank Tanzania
`DIAMOND_BANK`	Diamond Trust Bank
`ACCESS_BANK`	Access Bank Tanzania
`AZANIA_BANK`	Azania Bank
`EQUITY_BANK`	Equity Bank Tanzania
`FNB_BANK`	First National Bank

Note: While these enum values are available, you can also use free-text bank names if your bank is not listed.

Card Types

Common values for the cardType field (free-text, not strictly enforced):

Value	Description
`Visa`	Visa credit/debit cards
`Mastercard`	Mastercard credit/debit cards
`American Express`	American Express cards
`Discover`	Discover cards
`Diners Club`	Diners Club cards
`JCB`	JCB cards
`UnionPay`	China UnionPay cards

Cryptocurrency Types

Common values for the cryptoType field (free-text, not strictly enforced):

Value	Description
`Bitcoin`	Bitcoin (BTC)
`Ethereum`	Ethereum (ETH)
`Tether`	Tether USDT
`USD Coin`	USDC stablecoin
`Binance Coin`	BNB
`Cardano`	ADA
`Solana`	SOL
`Polkadot`	DOT

Account Types

Common values for the accountType field in bank transfers (free-text):

Value	Description
`Checking`	Checking/Current account
`Savings`	Savings account
`Business`	Business account
`Money Market`	Money market account

Mobile Payment Providers

Common values for the provider field (free-text, not strictly enforced):

Value	Description
`Apple Pay`	Apple Pay mobile payments
`Google Pay`	Google Pay mobile payments
`Samsung Pay`	Samsung Pay mobile payments
`WeChat Pay`	WeChat Pay
`Alipay`	Alipay

Wallet Types

Common values for the walletType field (free-text, not strictly enforced):

Value	Description
`Skrill`	Skrill digital wallet
`Neteller`	Neteller e-wallet
`PayTM`	PayTM wallet
`PayU`	PayU wallet
`Payoneer`	Payoneer account

Currency Codes

Use ISO 4217 3-letter currency codes for the currency field:

Code	Currency
`USD`	US Dollar
`EUR`	Euro
`GBP`	British Pound
`TZS`	Tanzanian Shilling
`KES`	Kenyan Shilling
`UGX`	Ugandan Shilling
`ZAR`	South African Rand
`NGN`	Nigerian Naira

Endpoints

1. Create Payment Method

Purpose: Create a new payment method for the authenticated user with support for multiple payment types

Endpoint: POST {base_url}/payment-methods

Access Level: 🔒 Protected (Requires Bearer Token Authentication)

Authentication: Bearer Token

Quick Reference - Required Fields by Payment Type:

Payment Type	Required Fields in `methodDetails`
`CREDIT_CARD` / `DEBIT_CARD`	`cardType`, `cardNumber`, `expiry`, `cardholderName`
`PAYPAL`	`email`
`BANK_TRANSFER`	`bankName`, `accountNumber`, `accountHolderName`
`CRYPTOCURRENCY`	`cryptoType`, `walletAddress`
`MOBILE_PAYMENT`	`provider`
`MNO_PAYMENT`	`phoneNumber`
`WALLET`	None (all optional, but `walletType` or `walletId` recommended)
`GIFT_CARD`	`pin`, `balance`, `currency`
`CASH_ON_DELIVERY`	None (all optional)

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication (format: "Bearer {token}")
Content-Type	string	Yes	Must be "application/json"

Request JSON Sample - Credit/Debit Card:

{
  "paymentMethodType": "CREDIT_CARD",
  "methodDetails": {
    "cardType": "Visa",
    "cardNumber": "4532015112830366",
    "expiry": "12/2027",
    "cardholderName": "John Doe"
  },
  "billingAddress": {
    "street": "123 Main Street",
    "city": "Dar es Salaam",
    "state": "Dar es Salaam",
    "postalCode": "12345",
    "country": "Tanzania"
  },
  "metadata": {
    "preferred": true,
    "notes": "Primary business card"
  },
  "isDefault": true
}

Request JSON Sample - Mobile Money (M-Pesa):

{
  "paymentMethodType": "MNO_PAYMENT",
  "methodDetails": {
    "phoneNumber": "+255712345678",
    "mccMnc": "M-PESA"
  },
  "isDefault": true
}

Request JSON Sample - PayPal:

{
  "paymentMethodType": "PAYPAL",
  "methodDetails": {
    "email": "john.doe@example.com",
    "paypalId": "johndoe123"
  },
  "isDefault": false
}

Request JSON Sample - Bank Transfer:

{
  "paymentMethodType": "BANK_TRANSFER",
  "methodDetails": {
    "bankName": "CRDB Bank",
    "accountNumber": "1234567890",
    "routingNumber": "021000021",
    "accountType": "Checking",
    "accountHolderName": "John Doe"
  },
  "billingAddress": {
    "street": "456 Bank Avenue",
    "city": "Dar es Salaam",
    "country": "Tanzania"
  },
  "isDefault": false
}

Request JSON Sample - Cryptocurrency:

{
  "paymentMethodType": "CRYPTOCURRENCY",
  "methodDetails": {
    "cryptoType": "Bitcoin",
    "walletAddress": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
    "network": "BTC Mainnet"
  },
  "isDefault": false
}

Request JSON Sample - Mobile Payment (Apple Pay/Google Pay):

{
  "paymentMethodType": "MOBILE_PAYMENT",
  "methodDetails": {
    "provider": "Apple Pay",
    "deviceId": "iPhone-12-Pro-XYZ123"
  },
  "isDefault": false
}

Request JSON Sample - Digital Wallet:

{
  "paymentMethodType": "WALLET",
  "methodDetails": {
    "walletType": "Skrill",
    "walletId": "john.doe@example.com"
  },
  "isDefault": false
}

Request JSON Sample - Gift Card:

{
  "paymentMethodType": "GIFT_CARD",
  "methodDetails": {
    "pin": "1234567890123456",
    "balance": 50.00,
    "currency": "USD"
  },
  "isDefault": false
}

Request JSON Sample - Cash on Delivery:

{
  "paymentMethodType": "CASH_ON_DELIVERY",
  "methodDetails": {
    "instructions": "Please call 30 minutes before delivery"
  },
  "isDefault": false
}

Request Body Parameters:

Parameter	Type	Required	Description	Validation
paymentMethodType	string (enum)	Yes	Type of payment method	REQUIRED ENUM: Must be one of: `CREDIT_CARD`, `DEBIT_CARD`, `PAYPAL`, `BANK_TRANSFER`, `CRYPTOCURRENCY`, `MOBILE_PAYMENT`, `MNO_PAYMENT`, `WALLET`, `GIFT_CARD`, `CASH_ON_DELIVERY` (See Payment Method Types section)
methodDetails	object	Yes	Payment method specific details	Varies by payment type (see nested fields)
methodDetails.cardType	string	Conditional	Card brand (e.g., Visa, Mastercard)	Required for CREDIT_CARD/DEBIT_CARD. See Card Types for common values
methodDetails.cardNumber	string	Conditional	Full card number	Required for CREDIT_CARD/DEBIT_CARD. Pattern: ^[0-9]{13,19}$
methodDetails.expiry	string	Conditional	Card expiration date	Required for CREDIT_CARD/DEBIT_CARD. Format: MM/YY or MM/YYYY
methodDetails.cardholderName	string	Conditional	Name on card	Required for CREDIT_CARD/DEBIT_CARD. Min: 2, Max: 100 characters
methodDetails.email	string	Conditional	PayPal email address	Required for PAYPAL. Must be valid email format
methodDetails.paypalId	string	No	PayPal account ID	Optional for PAYPAL
methodDetails.bankName	string	Conditional	Name of bank	Required for BANK_TRANSFER. See Banks (Tanzania) for enum values or use free-text. Min: 2, Max: 100 characters
methodDetails.accountNumber	string	Conditional	Bank account number	Required for BANK_TRANSFER
methodDetails.routingNumber	string	No	Bank routing number	Optional for BANK_TRANSFER
methodDetails.accountType	string	No	Account type	Optional for BANK_TRANSFER. See Account Types for common values
methodDetails.accountHolderName	string	Conditional	Account holder's name	Required for BANK_TRANSFER. Min: 2, Max: 100 characters
methodDetails.cryptoType	string	Conditional	Cryptocurrency name	Required for CRYPTOCURRENCY. See Cryptocurrency Types for common values
methodDetails.walletAddress	string	Conditional	Crypto wallet address	Required for CRYPTOCURRENCY
methodDetails.network	string	No	Blockchain network (e.g., "BTC Mainnet", "Ethereum Mainnet")	Optional for CRYPTOCURRENCY
methodDetails.provider	string	Conditional	Payment provider name	Required for MOBILE_PAYMENT. See Mobile Payment Providers for common values
methodDetails.deviceId	string	No	Device identifier	Optional for MOBILE_PAYMENT
methodDetails.walletType	string	No	Wallet service name	Optional for WALLET. See Wallet Types for common values
methodDetails.walletId	string	No	Wallet account identifier	Optional for WALLET
methodDetails.pin	string	Conditional	Gift card PIN	Required for GIFT_CARD
methodDetails.balance	number	Conditional	Gift card balance	Required for GIFT_CARD. Min: 0.01
methodDetails.currency	string	Conditional	Currency code	Required for GIFT_CARD. REQUIRED: ISO 4217 3-letter code (e.g., USD, EUR, TZS). See Currency Codes
methodDetails.instructions	string	No	Delivery instructions	Optional for CASH_ON_DELIVERY
methodDetails.phoneNumber	string	Conditional	Mobile money phone number	Required for MNO_PAYMENT. Pattern: ^+[1-9]\d{8,14}$ (E.164 format, e.g., +255712345678)
methodDetails.mccMnc	string	No	Mobile network operator	Optional for MNO_PAYMENT. ENUM: See Mobile Network Operators for available values: `M_PESA`, `AIRTEL_MONEY`, `TIGO_PESA`, `HALO_PESA`, `AZAM_PESA`, `EZY_PESA`
methodDetails.gatewayMetadata	object	No	Additional gateway-specific metadata	Optional, accepts any JSON object
billingAddress	object	No	Billing address information	Optional
billingAddress.street	string	Conditional	Street address	Required if billingAddress provided
billingAddress.city	string	Conditional	City name	Required if billingAddress provided
billingAddress.state	string	No	State or province	Optional
billingAddress.postalCode	string	No	Postal or ZIP code	Optional
billingAddress.country	string	Conditional	Country name	Required if billingAddress provided
metadata	object	No	Custom metadata as key-value pairs	Optional, accepts any JSON object
isDefault	boolean	No	Set as default payment method	Default: false

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Payment method created successfully",
  "action_time": "2025-10-27T10:30:45",
  "data": {
    "paymentMethodId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "ownerId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "ownerUserName": "johndoe",
    "paymentMethodType": "CREDIT_CARD",
    "methodDetails": {
      "cardType": "Visa",
      "maskedCardNumber": "**** **** **** 0366",
      "expiry": "12/2027",
      "cardholderName": "John Doe"
    },
    "billingAddress": {
      "street": "123 Main Street",
      "city": "Dar es Salaam",
      "state": "Dar es Salaam",
      "postalCode": "12345",
      "country": "Tanzania"
    },
    "metadata": {
      "preferred": true,
      "notes": "Primary business card"
    },
    "isDefault": true,
    "isActive": true,
    "isVerified": false,
    "createdAt": "2025-10-27T10:30:45",
    "updatedAt": "2025-10-27T10:30:45"
  }
}

Success Response Fields:

Field	Description
paymentMethodId	Unique identifier for the payment method (UUID)
ownerId	User account ID who owns this payment method
ownerUserName	Username of the payment method owner
paymentMethodType	Type of payment method created
methodDetails	Payment-specific details with sensitive data masked
methodDetails.maskedCardNumber	Card number with only last 4 digits visible (format: "** ** 1234")
methodDetails.maskedAccountNumber	Bank account with only last 4 digits visible (format: "****1234")
methodDetails.maskedPhoneNumber	Phone number partially masked (format: "+254****5678")
methodDetails.maskedWalletAddress	Crypto wallet showing first and last 4 characters (format: "1A1z...fNa")
methodDetails.maskedPin	PIN completely masked (format: "****")
billingAddress	Billing address if provided
metadata	Custom metadata object if provided
isDefault	Whether this is the default payment method
isActive	Whether the payment method is currently active
isVerified	Whether the payment method has been verified
createdAt	Timestamp when payment method was created
updatedAt	Timestamp of last update

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Payment method with similar details already exists for your account",
  "action_time": "2025-10-27T10:30:45",
  "data": "Payment method with similar details already exists for your account"
}

Standard Error Types:

Application-Level Exceptions (400-499)

400 BAD_REQUEST: Invalid payment details, duplicate payment method, or missing required fields
401 UNAUTHORIZED: Missing, invalid, or expired authentication token
404 NOT_FOUND: Authenticated user account not found
422 UNPROCESSABLE_ENTITY: Validation errors with detailed field information

Server-Level Exceptions (500+)

500 INTERNAL_SERVER_ERROR: Unexpected server errors

Error Response Examples:

Bad Request - Missing Required Fields (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Card number is required",
  "action_time": "2025-10-27T10:30:45",
  "data": "Card number is required"
}

Bad Request - Duplicate Payment Method (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Payment method with similar details already exists for your account",
  "action_time": "2025-10-27T10:30:45",
  "data": "Payment method with similar details already exists for your account"
}

Unauthorized - Invalid Token (401):

{
  "success": false,
  "httpStatus": "UNAUTHORIZED",
  "message": "Invalid or expired authentication token",
  "action_time": "2025-10-27T10:30:45",
  "data": "Invalid or expired authentication token"
}

Not Found - User Not Found (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "User not found",
  "action_time": "2025-10-27T10:30:45",
  "data": "User not found"
}

Validation Error (422):

{
  "success": false,
  "httpStatus": "UNPROCESSABLE_ENTITY",
  "message": "Validation failed",
  "action_time": "2025-10-27T10:30:45",
  "data": {
    "cardNumber": "Invalid card number",
    "expiry": "Invalid expiry format (MM/YY)",
    "email": "must be a well-formed email address"
  }
}

2. Get Payment Method by ID

Purpose: Retrieve detailed information about a specific payment method

Endpoint: GET {base_url}/payment-methods/{paymentMethodId}

Access Level: 🔒 Protected (Requires Bearer Token, Owner only)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication (format: "Bearer {token}")

Path Parameters:

Parameter	Type	Required	Description	Validation
paymentMethodId	UUID	Yes	Unique identifier of the payment method	Valid UUID format

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Payment method retrieved successfully",
  "action_time": "2025-10-27T10:30:45",
  "data": {
    "paymentMethodId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "ownerId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "ownerUserName": "johndoe",
    "paymentMethodType": "MNO_PAYMENT",
    "methodDetails": {
      "maskedPhoneNumber": "+255****5678",
      "mccMnc": "M-PESA"
    },
    "isDefault": true,
    "isActive": true,
    "isVerified": true,
    "createdAt": "2025-10-20T08:15:30",
    "updatedAt": "2025-10-27T10:30:45"
  }
}

Success Response Fields:

Field	Description
paymentMethodId	Unique identifier of the payment method
ownerId	User account ID who owns this payment method
ownerUserName	Username of the payment method owner
paymentMethodType	Type of payment method
methodDetails	Payment-specific details with sensitive information masked
billingAddress	Billing address if available
metadata	Custom metadata if available
isDefault	Whether this is the default payment method
isActive	Whether the payment method is currently active
isVerified	Whether the payment method has been verified
createdAt	Creation timestamp
updatedAt	Last update timestamp

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Payment method not found, or you do not have access to it",
  "action_time": "2025-10-27T10:30:45",
  "data": "Payment method not found, or you do not have access to it"
}

Error Response Examples:

Not Found (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Payment method not found, or you do not have access to it",
  "action_time": "2025-10-27T10:30:45",
  "data": "Payment method not found, or you do not have access to it"
}

Unauthorized (401):

{
  "success": false,
  "httpStatus": "UNAUTHORIZED",
  "message": "Authentication required",
  "action_time": "2025-10-27T10:30:45",
  "data": "Authentication required"
}

3. Get My Payment Methods

Purpose: Retrieve all payment methods belonging to the authenticated user with summary statistics

Endpoint: GET {base_url}/payment-methods/my-payment-methods

Access Level: 🔒 Protected (Requires Bearer Token)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication (format: "Bearer {token}")

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Payment methods retrieved successfully",
  "action_time": "2025-10-27T10:30:45",
  "data": {
    "paymentMethods": [
      {
        "paymentMethodId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "paymentMethodType": "CREDIT_CARD",
        "displayName": "Visa ****0366",
        "isDefault": true,
        "isActive": true,
        "isVerified": true,
        "createdAt": "2025-10-15T09:20:15",
        "details": {
          "cardType": "Visa",
          "lastFourDigits": "0366",
          "status": "Active"
        }
      },
      {
        "paymentMethodId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "paymentMethodType": "MNO_PAYMENT",
        "displayName": "M-Pesa +255****5678",
        "isDefault": false,
        "isActive": true,
        "isVerified": true,
        "createdAt": "2025-10-20T14:45:30",
        "details": {
          "maskedPhoneNumber": "+255****5678",
          "status": "Active"
        }
      },
      {
        "paymentMethodId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
        "paymentMethodType": "PAYPAL",
        "displayName": "PayPal (john.doe@example.com)",
        "isDefault": false,
        "isActive": true,
        "isVerified": false,
        "createdAt": "2025-10-22T11:30:00",
        "details": {
          "email": "john.doe@example.com",
          "status": "Pending"
        }
      }
    ],
    "totalCount": 3,
    "activeCount": 3,
    "defaultPaymentMethod": {
      "paymentMethodId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "paymentMethodType": "CREDIT_CARD",
      "displayName": "Visa ****0366",
      "isDefault": true,
      "isActive": true,
      "isVerified": true,
      "createdAt": "2025-10-15T09:20:15",
      "details": {
        "cardType": "Visa",
        "lastFourDigits": "0366",
        "status": "Active"
      }
    }
  }
}

Success Response Fields:

Field	Description
paymentMethods	Array of payment method summaries
paymentMethods[].paymentMethodId	Unique identifier of the payment method
paymentMethods[].paymentMethodType	Type of payment method
paymentMethods[].displayName	Human-readable name (e.g., "Visa 1234", "M-Pesa +2545678")
paymentMethods[].isDefault	Whether this is the default payment method
paymentMethods[].isActive	Whether the payment method is active
paymentMethods[].isVerified	Whether the payment method is verified
paymentMethods[].createdAt	Creation timestamp
paymentMethods[].details	Essential details for list display
paymentMethods[].details.cardType	Card brand (for cards)
paymentMethods[].details.lastFourDigits	Last 4 digits (for cards/accounts)
paymentMethods[].details.email	Email address (for PayPal/email-based)
paymentMethods[].details.provider	Provider name (for mobile payments)
paymentMethods[].details.bankName	Bank name (for bank transfers)
paymentMethods[].details.cryptoType	Cryptocurrency type (for crypto)
paymentMethods[].details.maskedPhoneNumber	Masked phone (for MNO)
paymentMethods[].details.currency	Currency code (for gift cards)
paymentMethods[].details.balance	Current balance (for gift cards)
paymentMethods[].details.status	Status indicator (Active, Inactive, Pending)
totalCount	Total number of payment methods
activeCount	Number of active payment methods
defaultPaymentMethod	The default payment method object (null if none set)

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "UNAUTHORIZED",
  "message": "User not authenticated",
  "action_time": "2025-10-27T10:30:45",
  "data": "User not authenticated"
}

Error Response Examples:

Unauthorized (401):

{
  "success": false,
  "httpStatus": "UNAUTHORIZED",
  "message": "User not authenticated",
  "action_time": "2025-10-27T10:30:45",
  "data": "User not authenticated"
}

Not Found - User Not Found (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "User not found",
  "action_time": "2025-10-27T10:30:45",
  "data": "User not found"
}

4. Update Payment Method

Purpose: Update an existing payment method with partial or complete changes

Endpoint: PUT {base_url}/payment-methods/{paymentMethodId}

Access Level: 🔒 Protected (Requires Bearer Token, Owner only)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication (format: "Bearer {token}")
Content-Type	string	Yes	Must be "application/json"

Path Parameters:

Parameter	Type	Required	Description	Validation
paymentMethodId	UUID	Yes	Unique identifier of the payment method to update	Valid UUID format

Request JSON Sample - Update Card Expiry:

{
  "paymentMethodType": "CREDIT_CARD",
  "methodDetails": {
    "expiry": "06/2028"
  }
}

Request JSON Sample - Update Mobile Money Number:

{
  "paymentMethodType": "MNO_PAYMENT",
  "methodDetails": {
    "phoneNumber": "+255723456789"
  }
}

Request JSON Sample - Update Billing Address:

{
  "paymentMethodType": "CREDIT_CARD",
  "billingAddress": {
    "street": "789 New Avenue",
    "city": "Arusha",
    "country": "Tanzania"
  }
}

Request JSON Sample - Set as Default:

{
  "paymentMethodType": "CREDIT_CARD",
  "isDefault": true
}

Request Body Parameters:

Parameter	Type	Required	Description	Validation
paymentMethodType	string (enum)	No	Type of payment method	Must match existing type or be a valid payment type
methodDetails	object	No	Payment method details to update	Only provided fields will be updated
billingAddress	object	No	Billing address to update	Partial updates supported
metadata	object	No	Metadata to update	Replaces existing metadata completely
isDefault	boolean	No	Update default status	Setting to true unsets other defaults

Note: All nested fields from the Create endpoint are supported. Only provided fields will be updated; null or missing fields retain their existing values.

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Payment method updated successfully",
  "action_time": "2025-10-27T10:30:45",
  "data": {
    "paymentMethodId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "ownerId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "ownerUserName": "johndoe",
    "paymentMethodType": "CREDIT_CARD",
    "methodDetails": {
      "cardType": "Visa",
      "maskedCardNumber": "**** **** **** 0366",
      "expiry": "06/2028",
      "cardholderName": "John Doe"
    },
    "billingAddress": {
      "street": "123 Main Street",
      "city": "Dar es Salaam",
      "state": "Dar es Salaam",
      "postalCode": "12345",
      "country": "Tanzania"
    },
    "isDefault": true,
    "isActive": true,
    "isVerified": false,
    "createdAt": "2025-10-15T09:20:15",
    "updatedAt": "2025-10-27T10:30:45"
  }
}

Success Response Fields:

Field	Description
paymentMethodId	Unique identifier of the updated payment method
ownerId	User account ID who owns this payment method
ownerUserName	Username of the payment method owner
paymentMethodType	Type of payment method
methodDetails	Updated payment-specific details with sensitive data masked
billingAddress	Updated billing address if modified
metadata	Updated metadata if modified
isDefault	Updated default status
isActive	Current active status
isVerified	Current verification status
createdAt	Original creation timestamp
updatedAt	Timestamp of this update

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Payment method not found",
  "action_time": "2025-10-27T10:30:45",
  "data": "Payment method not found"
}

Error Response Examples:

Not Found (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Payment method not found",
  "action_time": "2025-10-27T10:30:45",
  "data": "Payment method not found"
}

Bad Request - Duplicate (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "This payment method already exists for your account",
  "action_time": "2025-10-27T10:30:45",
  "data": "This payment method already exists for your account"
}

Validation Error (422):

{
  "success": false,
  "httpStatus": "UNPROCESSABLE_ENTITY",
  "message": "Validation failed",
  "action_time": "2025-10-27T10:30:45",
  "data": {
    "phoneNumber": "Invalid phone number",
    "expiry": "Invalid expiry format (MM/YY)"
  }
}

5. Delete Payment Method

Purpose: Permanently delete a payment method from the system

Endpoint: DELETE {base_url}/payment-methods/{paymentMethodId}

Access Level: 🔒 Protected (Requires Bearer Token, Owner only)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication (format: "Bearer {token}")

Path Parameters:

Parameter	Type	Required	Description	Validation
paymentMethodId	UUID	Yes	Unique identifier of the payment method to delete	Valid UUID format

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Payment method deleted successfully",
  "action_time": "2025-10-27T10:30:45",
  "data": null
}

Success Response Fields:

Field	Description
data	Always null for delete operations

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Payment method not found",
  "action_time": "2025-10-27T10:30:45",
  "data": "Payment method not found"
}

Error Response Examples:

Not Found (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Payment method not found",
  "action_time": "2025-10-27T10:30:45",
  "data": "Payment method not found"
}

Unauthorized (401):

{
  "success": false,
  "httpStatus": "UNAUTHORIZED",
  "message": "Authentication required",
  "action_time": "2025-10-27T10:30:45",
  "data": "Authentication required"
}

6. Set Payment Method as Default

Purpose: Set a specific payment method as the default for the authenticated user

Endpoint: PATCH {base_url}/payment-methods/{paymentMethodId}/set-default

Access Level: 🔒 Protected (Requires Bearer Token, Owner only)

Authentication: Bearer Token

Request Headers:

Header	Type	Required	Description
Authorization	string	Yes	Bearer token for authentication (format: "Bearer {token}")

Path Parameters:

Parameter	Type	Required	Description	Validation
paymentMethodId	UUID	Yes	Unique identifier of the payment method to set as default	Valid UUID format

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Payment method set as default successfully",
  "action_time": "2025-10-27T10:30:45",
  "data": {
    "paymentMethodId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "ownerId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "ownerUserName": "johndoe",
    "paymentMethodType": "MNO_PAYMENT",
    "methodDetails": {
      "maskedPhoneNumber": "+255****5678",
      "mccMnc": "M-PESA"
    },
    "isDefault": true,
    "isActive": true,
    "isVerified": true,
    "createdAt": "2025-10-20T08:15:30",
    "updatedAt": "2025-10-27T10:30:45"
  }
}

Success Response Fields:

Field	Description
paymentMethodId	Unique identifier of the payment method now set as default
isDefault	Now set to true
updatedAt	Updated to current timestamp

Note: All previously default payment methods are automatically set to isDefault: false.

Error Response JSON Sample:

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Cannot set inactive payment method as default",
  "action_time": "2025-10-27T10:30:45",
  "data": "Cannot set inactive payment method as default"
}

Error Response Examples:

Bad Request - Inactive Payment Method (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Cannot set inactive payment method as default",
  "action_time": "2025-10-27T10:30:45",
  "data": "Cannot set inactive payment method as default"
}

Not Found (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Payment method not found",
  "action_time": "2025-10-27T10:30:45",
  "data": "Payment method not found"
}

Unauthorized (401):

{
  "success": false,
  "httpStatus": "UNAUTHORIZED",
  "message": "Authentication required",
  "action_time": "2025-10-27T10:30:45",
  "data": "Authentication required"
}

Quick Reference Guide

HTTP Method Badge Code Templates

GET Badge:

<span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span>

POST Badge:

<span style="background-color: #007bff; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span>

PUT Badge:

<span style="background-color: #ffc107; color: black; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">PUT</span>

PATCH Badge:

<span style="background-color: #fd7e14; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">PATCH</span>

DELETE Badge:

<span style="background-color: #dc3545; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">DELETE</span>

Common HTTP Status Codes

200 OK: Successful GET/PUT/PATCH request
201 Created: Successful POST request
204 No Content: Successful DELETE request
400 Bad Request: Invalid request data, duplicate payment method, or business logic violation
401 Unauthorized: Authentication required/failed
403 Forbidden: Insufficient permissions
404 Not Found: Payment method or user not found
422 Unprocessable Entity: Validation errors
500 Internal Server Error: Server error

Authentication Types

Bearer Token: Include Authorization: Bearer your_token in headers

Data Format Standards

Dates: Use ISO 8601 format (2025-10-27T14:30:00)
Currency: Use standard 3-letter codes (USD, EUR, TZS)
Phone Numbers: Use E.164 format (+[country code][number])
Card Numbers: 13-19 digits (automatically tokenized and masked)
UUIDs: Standard UUID v4 format (8-4-4-4-12 hexadecimal)

Payment Method Types

CREDIT_CARD: Credit card payments
DEBIT_CARD: Debit card payments
PAYPAL: PayPal account payments
BANK_TRANSFER: Direct bank account transfers
CRYPTOCURRENCY: Crypto wallet payments (Bitcoin, Ethereum, etc.)
MOBILE_PAYMENT: Mobile payment services (Apple Pay, Google Pay)
MNO_PAYMENT: Mobile Network Operator payments (M-Pesa, Airtel Money, Tigo Pesa, etc.)
WALLET: Digital wallet services (Skrill, Neteller, etc.)
GIFT_CARD: Gift card payments
CASH_ON_DELIVERY: Cash payment upon delivery

Supported Mobile Network Operators (Tanzania)

M-Pesa (Vodacom)
Airtel Money
Tigo Pesa
Halo Pesa
Azam Pesa
Ezy Pesa

Supported Banks (Tanzania)

CRDB Bank
NMB Bank
EXIM Bank
KCB Bank
NBC Bank
Stanbic Bank
Diamond Bank
Access Bank
Azania Bank
Equity Bank
FNB Bank

Data Masking Rules

Card Numbers: Shows only last 4 digits (e.g., "**** **** **** 1234")
Account Numbers: Shows only last 4 digits (e.g., "****1234")
Phone Numbers: Masks middle digits (e.g., "+255****5678")
Wallet Addresses: Shows first and last 4 characters (e.g., "1A1z...fNa")
PINs: Completely masked (e.g., "****")

Security Notes

Sensitive data (card numbers, account numbers, PINs) should be tokenized before storage
All responses mask sensitive information
Duplicate detection prevents storing multiple identical payment methods
Only payment method owners can view, update, or delete their payment methods
Setting a payment method as default requires it to be active

Business Rules

Only one payment method can be default at a time
Setting a new default automatically unsets the previous default
Inactive payment methods cannot be set as default
Payment methods can be created without verification (isVerified: false)
Partial updates are supported - only provided fields are updated
Delete operations are permanent (hard delete)

Payment Method Type Examples

Credit/Debit Card Example

{
  "paymentMethodType": "CREDIT_CARD",
  "methodDetails": {
    "cardType": "Visa",
    "cardNumber": "4532015112830366",
    "expiry": "12/2027",
    "cardholderName": "John Doe"
  },
  "billingAddress": {
    "street": "123 Main Street",
    "city": "Dar es Salaam",
    "country": "Tanzania"
  },
  "isDefault": true
}

Mobile Money (M-Pesa) Example

{
  "paymentMethodType": "MNO_PAYMENT",
  "methodDetails": {
    "phoneNumber": "+255712345678",
    "mccMnc": "M-PESA"
  },
  "isDefault": true
}

PayPal Example

{
  "paymentMethodType": "PAYPAL",
  "methodDetails": {
    "email": "john.doe@example.com",
    "paypalId": "johndoe123"
  }
}

Bank Transfer Example

{
  "paymentMethodType": "BANK_TRANSFER",
  "methodDetails": {
    "bankName": "CRDB Bank",
    "accountNumber": "1234567890",
    "routingNumber": "021000021",
    "accountType": "Checking",
    "accountHolderName": "John Doe"
  },
  "billingAddress": {
    "street": "456 Bank Avenue",
    "city": "Dar es Salaam",
    "country": "Tanzania"
  }
}

Cryptocurrency Example

{
  "paymentMethodType": "CRYPTOCURRENCY",
  "methodDetails": {
    "cryptoType": "Bitcoin",
    "walletAddress": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
    "network": "BTC Mainnet"
  }
}

Mobile Payment (Apple Pay) Example

{
  "paymentMethodType": "MOBILE_PAYMENT",
  "methodDetails": {
    "provider": "Apple Pay",
    "deviceId": "iPhone-12-Pro-XYZ123"
  }
}

Digital Wallet Example

{
  "paymentMethodType": "WALLET",
  "methodDetails": {
    "walletType": "Skrill",
    "walletId": "john.doe@example.com"
  }
}

Gift Card Example

{
  "paymentMethodType": "GIFT_CARD",
  "methodDetails": {
    "pin": "1234567890123456",
    "balance": 50.00,
    "currency": "USD"
  }
}

Cash on Delivery Example

{
  "paymentMethodType": "CASH_ON_DELIVERY",
  "methodDetails": {
    "instructions": "Please call 30 minutes before delivery"
  }
}

Wallet

Transaction History

Payment Methods

Standard Response Format

Success Response Structure

Error Response Structure

Standard Response Fields

HTTP Method Badge Standards

Available Enums

Payment Method Types

Mobile Network Operators (Tanzania)

Banks (Tanzania)

Card Types

Cryptocurrency Types

Account Types

Mobile Payment Providers

Wallet Types

Currency Codes

Endpoints

1. Create Payment Method

Application-Level Exceptions (400-499)

Server-Level Exceptions (500+)

2. Get Payment Method by ID

3. Get My Payment Methods

4. Update Payment Method

5. Delete Payment Method

6. Set Payment Method as Default

Quick Reference Guide

HTTP Method Badge Code Templates

Common HTTP Status Codes

Authentication Types

Data Format Standards

Payment Method Types

Supported Mobile Network Operators (Tanzania)

Supported Banks (Tanzania)

Data Masking Rules

Security Notes

Business Rules

Payment Method Type Examples

Credit/Debit Card Example

Mobile Money (M-Pesa) Example

PayPal Example

Bank Transfer Example

Cryptocurrency Example

Mobile Payment (Apple Pay) Example

Digital Wallet Example

Gift Card Example

Cash on Delivery Example