Payment Methods

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

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

Short Description: The Payment Methods API enables users to manage their payment ~~methods for transactions. Supports multiple payment types~~instruments including credit/debit cards, mobile money (M-Pesa, Airtel ~~Money, Tigo Pesa)~~Money), bank transfers, PayPal, ~~cryptocurrency~~cryptocurrencies, wallets, gift cards, and cash on ~~delivery.~~delivery ~~Features~~options. ~~include~~This ~~setting~~API ~~default~~provides secure storage, retrieval, updating, and deletion of payment ~~methods,~~methods ~~masking~~with ~~sensitive~~built-in ~~data,~~validation and ~~validation to prevent~~ duplicate ~~entries.~~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~~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 ~~prevented~~

~~All payment methods require verification before use in transactions~~

~~Inactive payment methods cannot be set as default~~

~~Cash on Delivery requires no sensitive information~~

~~Mobile money (MNO_PAYMENT) requires valid Tanzanian phone number format~~

~~Card numbers must be 13-19 digits~~

~~All datetime fields use ISO 8601 format~~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-02T10:27T10:30:45",
  "data": {
    // Actual response data goes here
  }
}

Error Response Structure

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Error description",
  "action_time": "2025-10-02T10: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: ~~Creates~~Create a new payment method for the authenticated ~~user.~~user ~~Validates~~with ~~details~~support ~~based~~for onmultiple payment ~~type and prevents duplicate entries.~~types

Endpoint: POST {base_url}/payment-methods

Access Level: 🔒 Protected (Requires Bearer Token Authentication)

Authentication: Bearer Token

~~required~~

Quick Reference - Required Fields by Payment Type:

~~header~~

Payment Type	Required Fields in ~~Authorization~~`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 ~~authenticated~~authentication ~~user~~(format: "Bearer {token}")
Content-Type	string	Yes	Must be `"application/json`json"

Request JSON Sample - Credit/Debit Card ~~(Credit Card)~~:

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

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

{
  "paymentMethodType": "MNO_PAYMENT",
  "methodDetails": {
    "phoneNumber": "+255712345678",
    "mccMnc": "640-02"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": null,{
    "metadata"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": "M-Pesa"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:

~~paymentmethod~~ ~~banktransfers~~

Parameter	Type	Required	Description	Validation
paymentMethodType	string (enum)	Yes	Type of payment method	~~enum:~~REQUIRED ~~CREDIT_CARD,~~ENUM: ~~DEBIT_CARD,~~Must ~~PAYPAL,~~be ~~BANK_TRANSFER,~~one ~~CRYPTOCURRENCY,~~of: ~~MOBILE_PAYMENT,~~`CREDIT_CARD`, ~~MNO_PAYMENT,~~`DEBIT_CARD`, ~~WALLET,~~`PAYPAL`, ~~GIFT_CARD,~~`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 ~~for~~information	Optional
billingAddress.street	string	Conditional	Street address	Required ~~for~~if ~~cards~~billingAddress ~~and~~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	~~Additional~~Custom ~~custom~~metadata ~~data~~as key-value pairs	~~Key-value~~Optional, ~~pairs~~accepts any JSON object
isDefault	boolean	No	Set as default payment method	Default: false

~~Method Details by Payment Type~~:

~~CREDIT_CARD / DEBIT_CARD:~~

~~Field~~	~~Type~~	~~Required~~	~~Validation~~
~~cardType~~	~~string~~	No	~~e.g., "Visa", "Mastercard"~~
~~cardNumber~~	~~string~~	~~Yes~~	~~13-19 digits~~
~~expiry~~	~~string~~	~~Yes~~	~~Format: MM/YY or MM/YYYY~~
~~cardholderName~~	~~string~~	~~Yes~~	~~Min: 2, Max: 100 characters~~

~~MNO_PAYMENT (M-Pesa, Airtel Money, Tigo Pesa):~~

~~Field~~	~~Type~~	~~Required~~	~~Validation~~
~~phoneNumber~~	~~string~~	~~Yes~~	~~Format: +255XXXXXXXXX (Tanzanian format)~~
~~mccMnc~~	~~string~~	No	~~Mobile Country Code - Mobile Network Code~~

~~PAYPAL:~~

~~Field~~	~~Type~~	~~Required~~	~~Validation~~
~~email~~	~~string~~	~~Yes~~	~~Valid email format~~
~~paypalId~~	~~string~~	No	~~PayPal account ID~~

~~BANK_TRANSFER:~~

~~Field~~	~~Type~~	~~Required~~	~~Validation~~
~~bankName~~	~~string~~	~~Yes~~	~~Min: 2, Max: 100 characters~~
~~accountNumber~~	~~string~~	~~Yes~~	~~Bank account number~~
~~routingNumber~~	~~string~~	No	~~Bank routing/SWIFT code~~
~~accountType~~	~~string~~	No	~~e.g., "Checking", "Savings"~~
~~accountHolderName~~	~~string~~	~~Yes~~	~~Min: 2, Max: 100 characters~~

~~CRYPTOCURRENCY:~~

~~Field~~	~~Type~~	~~Required~~	~~Validation~~
~~cryptoType~~	~~string~~	~~Yes~~	~~e.g., "Bitcoin", "Ethereum"~~
~~walletAddress~~	~~string~~	~~Yes~~	~~Cryptocurrency wallet address~~
~~network~~	~~string~~	No	~~e.g., "Mainnet", "Testnet"~~

~~GIFT_CARD:~~

~~Field~~	~~Type~~	~~Required~~	~~Validation~~
~~pin~~	~~string~~	~~Yes~~	~~Gift card PIN~~
~~balance~~	~~number~~	~~Yes~~	~~Must be greater than 0~~
~~currency~~	~~string~~	~~Yes~~	~~3-letter currency code (e.g., "TZS")~~

~~CASH_ON_DELIVERY:~~

~~Field~~	~~Type~~	~~Required~~	~~Validation~~
~~instructions~~	~~string~~	No	~~Special instructions for delivery~~

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Payment method created successfully",
  "action_time": "2025-10-02T14:27T10:30:45",
  "data": {
    "paymentMethodId": "pm123456-a1b2c3d4-e5f6-7890-abcd-ef12-345678901234"ef1234567890",
    "ownerId": "user1234-5678-90ab-cdef-123456789012"b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "ownerUserName": "john_doe"johndoe",
    "paymentMethodType": "CREDIT_CARD",
    "methodDetails": {
      "cardType": "Visa",
      "maskedCardNumber": "**** **** **** 4242"0366",
      "expiry": "12/2028"2027",
      "cardholderName": "John Doe"
    },
    "billingAddress": {
      "street": "123 Main Street",
      "city": "Dar es Salaam",
      "state": "Dar es Salaam Region"Salaam",
      "postalCode": "12345",
      "country": "Tanzania"
    },
    "metadata": {
      "nickname"preferred": true,
      "notes": "My Primary Card"business card"
    },
    "isDefault": true,
    "isActive": true,
    "isVerified": false,
    "createdAt": "2025-10-02T14:27T10:30:45",
    "updatedAt": "2025-10-02T14: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 method~~Payment-specific details with sensitive data masked
methodDetails.maskedCardNumber	Card number with only last 4 digits visible (format: "** ** 1234")
methodDetails.maskedAccountNumber	~~Account~~Bank ~~number~~account with only last 4 digits visible (format: "****1234")
methodDetails.maskedPhoneNumber	Phone number ~~with middle digits~~partially masked (format: "+254****5678")
methodDetails.maskedWalletAddress	Crypto wallet ~~with~~showing ~~middle~~first ~~section~~and ~~masked~~last 4 characters (format: "1A1z...fNa")
methodDetails.maskedPin	PIN completely masked as(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 ishas been verified
createdAt	~~Creation~~Timestamp ~~timestamp~~when payment method was created
updatedAt	~~Last~~Timestamp of last update ~~timestamp~~

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-02T14: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-02T14: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-02T14:27T10:30:45",
  "data": {
    "methodDetails.cardNumber": "Invalid card number",
    "methodDetails.expiry": "Invalid expiry format (MM/YY)",
    "billingAddress.street"email": "Streetmust isbe required"a well-formed email address"
  }
}

2. Get Payment Method by ID

Purpose: ~~Retrieves~~Retrieve detailed information about a specific payment ~~method. Only the owner can access their payment methods.~~method

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

Access Level: 🔒 Protected (Requires ~~Authentication~~Bearer ~~and~~Token, ~~Ownership)~~Owner only)

Authentication: Bearer Token ~~required in Authorization header~~

Request Headers:

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

Path Parameters:

Parameter	Type	Required	Description	Validation
paymentMethodId	~~string (UUID)~~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-02T14:35:27T10:30:45",
  "data": {
    "paymentMethodId": "pm123456-a1b2c3d4-e5f6-7890-abcd-ef12-345678901234"ef1234567890",
    "ownerId": "user1234-5678-90ab-cdef-123456789012"b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "ownerUserName": "john_doe"johndoe",
    "paymentMethodType": "MNO_PAYMENT",
    "methodDetails": {
      "maskedPhoneNumber": "+255****5678",
      "mccMnc": "640-02"
    },
    "billingAddress": null,
    "metadata": {
      "provider": "M-Pesa"PESA"
    },
    "isDefault": true,
    "isActive": true,
    "isVerified": true,
    "createdAt": "2025-10-01T10:20:20T08:15:30",
    "updatedAt": "2025-10-02T14:35: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-02T14:35: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: ~~Retrieves~~Retrieve all payment methods belonging to the authenticated user with summary ~~information and statistics.~~statistics

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

Access Level: 🔒 Protected (Requires ~~Authentication)~~Bearer Token)

Authentication: Bearer Token ~~required in Authorization header~~

Request Headers:

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

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Payment methods retrieved successfully",
  "action_time": "2025-10-02T14:40:27T10:30:45",
  "data": {
    "paymentMethods": [
      {
        "paymentMethodId": "pm123456-a1b2c3d4-e5f6-7890-abcd-ef12-345678901234"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": true,false,
        "isActive": true,
        "isVerified": true,
        "createdAt": "2025-10-01T10:20:20T14:45:30",
        "details": {
          "maskedPhoneNumber": "+255****5678",
          "status": "Active"
        }
      },
      {
        "paymentMethodId": "pm234567-8901-bcde-f123-456789012345"c3d4e5f6-a7b8-9012-cdef-123456789012",
        "paymentMethodType": "CREDIT_CARD"PAYPAL",
        "displayName": "VisaPayPal ****4242"(john.doe@example.com)",
        "isDefault": false,
        "isActive": true,
        "isVerified": false,
        "createdAt": "2025-10-02T14:22T11:30:45"00",
        "details": {
          "cardType"email": "Visa",
          "lastFourDigits": "4242"john.doe@example.com",
          "status": "Pending"
        }
      },
      {
        "paymentMethodId": "pm345678-9012-cdef-1234-567890123456",
        "paymentMethodType": "CASH_ON_DELIVERY",
        "displayName": "Cash on Delivery",
        "isDefault": false,
        "isActive": true,
        "isVerified": true,
        "createdAt": "2025-09-28T08:15:20",
        "details": {
          "status": "Active"
        }
      }
    ],
    "totalCount": 3,
    "activeCount": 3,
    "defaultPaymentMethod": {
      "paymentMethodId": "pm123456-a1b2c3d4-e5f6-7890-abcd-ef12-345678901234"ef1234567890",
      "paymentMethodType": "MNO_PAYMENT"CREDIT_CARD",
      "displayName": "M-PesaVisa +255****5678"*0366",
      "isDefault": true,
      "isActive": true,
      "isVerified": true,
      "createdAt": "2025-10-01T10:15T09:20:30"15",
      "details": {
        "maskedPhoneNumber"cardType": "+255****5678"Visa",
        "lastFourDigits": "0366",
        "status": "Active"
      }
    }
  }
}

Success Response Fields:

Field	Description
paymentMethods	Array of ~~all~~ payment ~~methods~~method summaries
paymentMethods[].paymentMethodId	Unique identifier of the payment method
paymentMethods[].paymentMethodType	Type of payment method
paymentMethods[].displayName	Human-readable ~~display~~ name (e.g., "Visa ~~**~~1234", "M-Pesa +254**5678")
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	~~Summary~~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 ~~text:~~indicator ~~"Active",~~(Active, ~~"Inactive",~~Inactive, ~~or "Pending"~~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: ~~Updates~~Update an existing payment ~~method. Can update~~ method ~~details,~~with ~~billing address, metadata,~~partial or ~~default~~complete ~~status.~~changes

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

Access Level: 🔒 Protected (Requires ~~Authentication~~Bearer ~~and~~Token, ~~Ownership)~~Owner only)

Authentication: Bearer Token ~~required in Authorization header~~

Request Headers:

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

Path Parameters:

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

Request JSON Sample - Update Card Expiry:

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

Request JSON Sample - Update Mobile Money Number:

{
  "paymentMethodType": "MNO_PAYMENT",
  "cardholderName"methodDetails": {
    "phoneNumber": "John Michael Doe"+255723456789"
  }
}

Request JSON Sample - Update Billing Address:

{
  "paymentMethodType": "CREDIT_CARD",
  "billingAddress": {
    "street": "456789 New Address Street"Avenue",
    "city": "Dar es Salaam",
    "state": "Dar es Salaam Region",
    "postalCode": "12346"Arusha",
    "country": "Tanzania"
  },
"metadata"}

Request JSON Sample - Set as Default:

{
  "nickname"paymentMethodType": "Updated Primary Card"
  }CREDIT_CARD",
  "isDefault": true
}

Request Body Parameters:

~~(must~~existing

Parameter	Type	Required	Description	Validation
paymentMethodType	string (enum)	~~Yes~~No	Type of payment method	Must match ~~existing)~~	~~Same~~type ~~validation~~or asbe ~~create~~a valid payment type
methodDetails	object	~~Yes~~No	~~Updated payment~~Payment method details to update	Only provided fields ~~are~~will be updated
billingAddress	object	No	~~Updated billing~~Billing address to update	Partial updates supported
metadata	object	No	~~Updated~~Metadata ~~metadata~~to update	Replaces existing metadata completely
isDefault	boolean	No	Update default status	IfSetting ~~true,~~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-02T14:50:27T10:30:45",
  "data": {
    "paymentMethodId": "pm123456-a1b2c3d4-e5f6-7890-abcd-ef12-345678901234"ef1234567890",
    "ownerId": "user1234-5678-90ab-cdef-123456789012"b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "ownerUserName": "john_doe"johndoe",
    "paymentMethodType": "CREDIT_CARD",
    "methodDetails": {
      "cardType": "Visa",
      "maskedCardNumber": "**** **** **** 4242"0366",
      "expiry": "12/2029"06/2028",
      "cardholderName": "John Michael Doe"
    },
    "billingAddress": {
      "street": "456123 New AddressMain Street",
      "city": "Dar es Salaam",
      "state": "Dar es Salaam Region"Salaam",
      "postalCode": "12346"12345",
      "country": "Tanzania"
    },
    "metadata": {
      "nickname": "Updated Primary Card"
    },
    "isDefault": true,
    "isActive": true,
    "isVerified": false,
    "createdAt": "2025-10-02T14:30:45"15T09:20:15",
    "updatedAt": "2025-10-02T14:50: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-02T14:50: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-02T14:50: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 ~~deletes~~delete a payment ~~method.~~method ~~This~~from ~~action~~the ~~cannot be undone.~~system

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

Access Level: 🔒 Protected (Requires ~~Authentication~~Bearer ~~and~~Token, ~~Ownership)~~Owner only)

Authentication: Bearer Token ~~required in Authorization header~~

Request Headers:

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

Path Parameters:

Parameter	Type	Required	Description	Validation
paymentMethodId	~~string (UUID)~~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-02T14:55: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-02T14:55: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: ~~Sets~~Set a specific payment method as the default for ~~transactions.~~the ~~Automatically~~authenticated ~~unsets any existing default payment method.~~user

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

Access Level: 🔒 Protected (Requires ~~Authentication~~Bearer ~~and~~Token, ~~Ownership)~~Owner only)

Authentication: Bearer Token ~~required in Authorization header~~

Request Headers:

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

Path Parameters:

Parameter	Type	Required	Description	Validation
paymentMethodId	~~string (UUID)~~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-02T15:00:27T10:30:45",
  "data": {
    "paymentMethodId": "pm123456-7890-abcd-ef12-345678901234"b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "ownerId": "user1234-5678-90ab-cdef-123456789012"b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "ownerUserName": "john_doe"johndoe",
    "paymentMethodType": "MNO_PAYMENT",
    "methodDetails": {
      "maskedPhoneNumber": "+255****5678",
      "mccMnc": "640-02"
    },
    "billingAddress": null,
    "metadata": {
      "provider": "M-Pesa"PESA"
    },
    "isDefault": true,
    "isActive": true,
    "isVerified": true,
    "createdAt": "2025-10-01T10:20:20T08:15:30",
    "updatedAt": "2025-10-02T15:00: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-02T15:00: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-02T15:00: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 PaymentMobile MethodsNetwork in Tanzania

~~MNO_PAYMENT~~Operators (~~Mobile Money)~~

Tanzania)

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

~~CREDIT_CARD / DEBIT_CARD~~

~~Visa~~

~~Mastercard~~

~~American Express~~

~~Local bank cards~~

~~BANK_TRANSFER~~

Supported Banks:
Banks (Tanzania)

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

~~Other~~

Data Methods:
Masking Rules

~~PAYPAL - International payments~~

~~CRYPTOCURRENCY - Bitcoin, Ethereum, etc.~~

~~GIFT_CARD - Store gift cards~~

~~CASH_ON_DELIVERY - Pay on delivery~~

~~WALLET - Internal wallet system~~

~~MOBILE_PAYMENT - Google Pay, Apple Pay, etc.~~

Data Masking

~~All sensitive data is automatically masked in API responses for security:~~

Numbers:Shows1234") Numbers:Shows1234") Numbers:Masks5678")

Wallet

Addresses:firstandfNa")

PINs:

Completelymasked(e.g.,")

~~Data Type~~	~~Original~~	~~Masked~~
Card ~~Number~~	~~4242424242424242~~	only last 4 digits (e.g., "** ** ~~4242~~
Account ~~Number~~	~~1234567890~~	only last 4 digits (e.g., "****~~7890~~
Phone ~~Number~~	~~+255712345678~~	middle digits (e.g., "+255****~~5678~~
~~Crypto~~Shows ~~Wallet~~	~~1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa~~	last 4 characters (e.g., "1A1z...~~fNa~~
~~PIN~~	~~1234~~	"****

Validation Rules

CardSecurity NumbersNotes

~~Must~~Sensitive data (card numbers, account numbers, PINs) should be ~~13-19~~tokenized ~~digits~~before storage
NoAll ~~spaces~~responses mask sensitive information

Duplicate detection prevents storing multiple identical payment methods

Only payment method owners can view, update, or ~~dashes~~delete their payment methods
~~Pattern:~~Setting ^[0-9]{13,19}$a payment method as default requires it to be active

ExpiryBusiness DatesRules

~~Format:~~Only ~~MM/YY~~one orpayment ~~MM/YYYY~~method can be default at a time
~~Pattern:~~Setting ^(0[1-9]|1[0-2])/[0-9]{2,4}$

new

Phonedefault Numbersautomatically (Tanzania)

unsets

the

~~Format:~~previous ~~+255XXXXXXXXX~~default
~~Pattern:~~Inactive ^\\+[1-9]\\d{8,14}$

payment

methods

Email Addresses

~~Must~~cannot be ~~valid~~set ~~email~~as ~~format~~default
~~Used~~Payment ~~for~~methods ~~PayPal~~

Currency Codes

~~Must~~can be ~~3-letter~~created ~~ISO~~without ~~code~~verification (isVerified: false)
~~Pattern:~~Partial ^[A-Z]{3}$updates are supported - only provided fields are updated
~~Example:~~Delete ~~TZS,~~operations ~~USD,~~are ~~EUR~~permanent (hard delete)

Duplicate Detection

~~The system automatically prevents duplicate payment methods:~~

~~Cards~~~~: Checks last 4 digits~~

~~Mobile Money~~~~: Checks phone number~~

~~Bank Accounts~~~~: Checks account number~~

~~PayPal~~~~: Checks email address~~

~~Crypto~~~~: Checks wallet address~~

~~Note~~~~: Gift cards and cash on delivery can have multiple instances.~~

Quick Reference Guide

Endpoint Summary

~~Endpoint~~	~~Method~~	~~Purpose~~
`/payment-methods`	~~POST~~	~~Create payment method~~
`/payment-methods/{id}`	~~GET~~	~~Get payment method details~~
`/payment-methods/my-payment-methods`	~~GET~~	~~List all payment methods~~
`/payment-methods/{id}`	~~PUT~~	~~Update payment method~~
`/payment-methods/{id}`	~~DELETE~~	~~Delete payment method~~
`/payment-methods/{id}/set-default`	~~PATCH~~	~~Set as default~~

Common HTTP Status Codes

200 OK~~: Successful operation~~

400 Bad Request~~: Validation error or duplicate~~

401 Unauthorized~~: Authentication required~~

404 Not Found~~: Payment method not found~~

422 Unprocessable Entity~~: Field validation errors~~

Payment Method StatusType Examples

Credit/Debit Card Example

{
  Active"paymentMethodType": Can"CREDIT_CARD",
  be used for transactions

Inactive"methodDetails": Cannot{
    be used for transactions

Pending"cardType": Awaiting"Visa",
    verification
"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"
  }
}

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 PaymentMobile MethodsNetwork in Tanzania

Supported Banks:Banks (Tanzania)

Data Methods:Masking Rules

Data Masking

Validation Rules

CardSecurity NumbersNotes

ExpiryBusiness DatesRules

Phonedefault Numbersautomatically (Tanzania)

Email Addresses

Currency Codes

Duplicate Detection

Quick Reference Guide

Endpoint Summary

Common HTTP Status Codes

Payment Method StatusType 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

Supported Banks:
Banks (Tanzania)

Data Methods:
Masking Rules