Skip to main content

Payment Methods

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

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

Short Description: The Payment Methods API enables users to manage their payment methods for transactions. Supports multiple payment types including credit/debit cards, mobile money (M-Pesa, Airtel Money, Tigo Pesa), bank transfers, PayPal, cryptocurrency wallets, gift cards, and cash on delivery. Features include setting default payment methods, masking sensitive data, and validation to prevent duplicate entries.

Hints:

  • Sensitive data (card numbers, account numbers, PINs) are automatically masked in responses
  • Only one payment method can be set as default at a time
  • Duplicate payment methods 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

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:30:45",
  "data": {
    // Actual response data goes here
  }
}

Error Response Structure

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Error description",
  "action_time": "2025-10-02T10: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

  • 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)

Endpoints

1. Create Payment Method

Purpose: Creates a new payment method for the authenticated user. Validates details based on payment type and prevents duplicate entries.

Endpoint: POST {base_url}/payment-methods

Access Level: 🔒 Protected (Requires Authentication)

Authentication: Bearer Token required in Authorization header

Request Headers:

Header Type Required Description
Authorization string Yes Bearer token for authenticated user
Content-Type string Yes Must be application/json

Request JSON Sample (Credit Card):

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

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

{
  "paymentMethodType": "MNO_PAYMENT",
  "methodDetails": {
    "phoneNumber": "+255712345678",
    "mccMnc": "640-02"
  },
  "billingAddress": null,
  "metadata": {
    "provider": "M-Pesa"
  },
  "isDefault": false
}

Request Body Parameters:

Parameter Type Required Description Validation
paymentMethodType string Yes Type of payment method enum: CREDIT_CARD, DEBIT_CARD, PAYPAL, BANK_TRANSFER, CRYPTOCURRENCY, MOBILE_PAYMENT, MNO_PAYMENT, WALLET, GIFT_CARD, CASH_ON_DELIVERY
methodDetails object Yes Payment method specific details Varies by payment type
billingAddress object No Billing address for payment method Required for cards and bank transfers
metadata object No Additional custom data Key-value pairs
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:30:45",
  "data": {
    "paymentMethodId": "pm123456-7890-abcd-ef12-345678901234",
    "ownerId": "user1234-5678-90ab-cdef-123456789012",
    "ownerUserName": "john_doe",
    "paymentMethodType": "CREDIT_CARD",
    "methodDetails": {
      "cardType": "Visa",
      "maskedCardNumber": "**** **** **** 4242",
      "expiry": "12/2028",
      "cardholderName": "John Doe"
    },
    "billingAddress": {
      "street": "123 Main Street",
      "city": "Dar es Salaam",
      "state": "Dar es Salaam Region",
      "postalCode": "12345",
      "country": "Tanzania"
    },
    "metadata": {
      "nickname": "My Primary Card"
    },
    "isDefault": true,
    "isActive": true,
    "isVerified": false,
    "createdAt": "2025-10-02T14:30:45",
    "updatedAt": "2025-10-02T14:30:45"
  }
}

Success Response Fields:

Field Description
paymentMethodId Unique identifier for the payment method
ownerId User ID who owns this payment method
ownerUserName Username of the owner
paymentMethodType Type of payment method
methodDetails Payment method details with sensitive data masked
methodDetails.maskedCardNumber Card number with only last 4 digits visible
methodDetails.maskedAccountNumber Account number with only last 4 digits visible
methodDetails.maskedPhoneNumber Phone number with middle digits masked
methodDetails.maskedWalletAddress Crypto wallet with middle section masked
methodDetails.maskedPin PIN completely masked as ****
billingAddress Billing address if provided
metadata Custom metadata
isDefault Whether this is the default payment method
isActive Whether the payment method is active
isVerified Whether the payment method is verified
createdAt Creation timestamp
updatedAt Last update timestamp

Error Response Examples:

Bad Request - Missing Required Fields (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Card number is required",
  "action_time": "2025-10-02T14: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:30:45",
  "data": "Payment method with similar details already exists for your account"
}

Validation Error (422):

{
  "success": false,
  "httpStatus": "UNPROCESSABLE_ENTITY",
  "message": "Validation failed",
  "action_time": "2025-10-02T14:30:45",
  "data": {
    "methodDetails.cardNumber": "Invalid card number",
    "methodDetails.expiry": "Invalid expiry format (MM/YY)",
    "billingAddress.street": "Street is required"
  }
}

2. Get Payment Method by ID

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

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

Access Level: 🔒 Protected (Requires Authentication and Ownership)

Authentication: Bearer Token required in Authorization header

Request Headers:

Header Type Required Description
Authorization string Yes Bearer token for authenticated user

Path Parameters:

Parameter Type Required Description Validation
paymentMethodId string (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:45",
  "data": {
    "paymentMethodId": "pm123456-7890-abcd-ef12-345678901234",
    "ownerId": "user1234-5678-90ab-cdef-123456789012",
    "ownerUserName": "john_doe",
    "paymentMethodType": "MNO_PAYMENT",
    "methodDetails": {
      "maskedPhoneNumber": "+255****5678",
      "mccMnc": "640-02"
    },
    "billingAddress": null,
    "metadata": {
      "provider": "M-Pesa"
    },
    "isDefault": true,
    "isActive": true,
    "isVerified": true,
    "createdAt": "2025-10-01T10:20:30",
    "updatedAt": "2025-10-02T14:35:45"
  }
}

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:45",
  "data": "Payment method not found, or you do not have access to it"
}

3. Get My Payment Methods

Purpose: Retrieves all payment methods belonging to the authenticated user with summary information and statistics.

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

Access Level: 🔒 Protected (Requires Authentication)

Authentication: Bearer Token required in Authorization header

Request Headers:

Header Type Required Description
Authorization string Yes Bearer token for authenticated user

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Payment methods retrieved successfully",
  "action_time": "2025-10-02T14:40:45",
  "data": {
    "paymentMethods": [
      {
        "paymentMethodId": "pm123456-7890-abcd-ef12-345678901234",
        "paymentMethodType": "MNO_PAYMENT",
        "displayName": "M-Pesa +255****5678",
        "isDefault": true,
        "isActive": true,
        "isVerified": true,
        "createdAt": "2025-10-01T10:20:30",
        "details": {
          "maskedPhoneNumber": "+255****5678",
          "status": "Active"
        }
      },
      {
        "paymentMethodId": "pm234567-8901-bcde-f123-456789012345",
        "paymentMethodType": "CREDIT_CARD",
        "displayName": "Visa ****4242",
        "isDefault": false,
        "isActive": true,
        "isVerified": false,
        "createdAt": "2025-10-02T14:30:45",
        "details": {
          "cardType": "Visa",
          "lastFourDigits": "4242",
          "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-7890-abcd-ef12-345678901234",
      "paymentMethodType": "MNO_PAYMENT",
      "displayName": "M-Pesa +255****5678",
      "isDefault": true,
      "isActive": true,
      "isVerified": true,
      "createdAt": "2025-10-01T10:20:30",
      "details": {
        "maskedPhoneNumber": "+255****5678",
        "status": "Active"
      }
    }
  }
}

Success Response Fields:

Field Description
paymentMethods Array of all payment methods
paymentMethods[].paymentMethodId Unique identifier
paymentMethods[].paymentMethodType Type of payment method
paymentMethods[].displayName Human-readable display name (e.g., "Visa ****1234")
paymentMethods[].isDefault Whether this is the default method
paymentMethods[].isActive Whether the method is active
paymentMethods[].isVerified Whether the method is verified
paymentMethods[].details Summary details for list display
paymentMethods[].details.status Status text: "Active", "Inactive", or "Pending"
totalCount Total number of payment methods
activeCount Number of active payment methods
defaultPaymentMethod The default payment method (null if none set)

4. Update Payment Method

Purpose: Updates an existing payment method. Can update method details, billing address, metadata, or default status.

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

Access Level: 🔒 Protected (Requires Authentication and Ownership)

Authentication: Bearer Token required in Authorization header

Request Headers:

Header Type Required Description
Authorization string Yes Bearer token for authenticated user
Content-Type string Yes Must be application/json

Path Parameters:

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

Request JSON Sample:

{
  "paymentMethodType": "CREDIT_CARD",
  "methodDetails": {
    "expiry": "12/2029",
    "cardholderName": "John Michael Doe"
  },
  "billingAddress": {
    "street": "456 New Address Street",
    "city": "Dar es Salaam",
    "state": "Dar es Salaam Region",
    "postalCode": "12346",
    "country": "Tanzania"
  },
  "metadata": {
    "nickname": "Updated Primary Card"
  },
  "isDefault": true
}

Request Body Parameters:

Parameter Type Required Description Validation
paymentMethodType string Yes Type of payment method (must match existing) Same validation as create
methodDetails object Yes Updated payment method details Only provided fields are updated
billingAddress object No Updated billing address Partial updates supported
metadata object No Updated metadata Replaces existing metadata
isDefault boolean No Update default status If true, unsets other defaults

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Payment method updated successfully",
  "action_time": "2025-10-02T14:50:45",
  "data": {
    "paymentMethodId": "pm123456-7890-abcd-ef12-345678901234",
    "ownerId": "user1234-5678-90ab-cdef-123456789012",
    "ownerUserName": "john_doe",
    "paymentMethodType": "CREDIT_CARD",
    "methodDetails": {
      "cardType": "Visa",
      "maskedCardNumber": "**** **** **** 4242",
      "expiry": "12/2029",
      "cardholderName": "John Michael Doe"
    },
    "billingAddress": {
      "street": "456 New Address Street",
      "city": "Dar es Salaam",
      "state": "Dar es Salaam Region",
      "postalCode": "12346",
      "country": "Tanzania"
    },
    "metadata": {
      "nickname": "Updated Primary Card"
    },
    "isDefault": true,
    "isActive": true,
    "isVerified": false,
    "createdAt": "2025-10-02T14:30:45",
    "updatedAt": "2025-10-02T14:50:45"
  }
}

Error Response Examples:

Not Found (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Payment method not found",
  "action_time": "2025-10-02T14:50: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:45",
  "data": "This payment method already exists for your account"
}

5. Delete Payment Method

Purpose: Permanently deletes a payment method. This action cannot be undone.

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

Access Level: 🔒 Protected (Requires Authentication and Ownership)

Authentication: Bearer Token required in Authorization header

Request Headers:

Header Type Required Description
Authorization string Yes Bearer token for authenticated user

Path Parameters:

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

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Payment method deleted successfully",
  "action_time": "2025-10-02T14:55:45",
  "data": null
}

Error Response Examples:

Not Found (404):

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "Payment method not found",
  "action_time": "2025-10-02T14:55:45",
  "data": "Payment method not found"
}

6. Set Payment Method as Default

Purpose: Sets a payment method as the default for transactions. Automatically unsets any existing default payment method.

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

Access Level: 🔒 Protected (Requires Authentication and Ownership)

Authentication: Bearer Token required in Authorization header

Request Headers:

Header Type Required Description
Authorization string Yes Bearer token for authenticated user

Path Parameters:

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

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Payment method set as default successfully",
  "action_time": "2025-10-02T15:00:45",
  "data": {
    "paymentMethodId": "pm123456-7890-abcd-ef12-345678901234",
    "ownerId": "user1234-5678-90ab-cdef-123456789012",
    "ownerUserName": "john_doe",
    "paymentMethodType": "MNO_PAYMENT",
    "methodDetails": {
      "maskedPhoneNumber": "+255****5678",
      "mccMnc": "640-02"
    },
    "billingAddress": null,
    "metadata": {
      "provider": "M-Pesa"
    },
    "isDefault": true,
    "isActive": true,
    "isVerified": true,
    "createdAt": "2025-10-01T10:20:30",
    "updatedAt": "2025-10-02T15:00:45"
  }
}

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: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:45",
  "data": "Payment method not found"
}

Payment Method Types

Supported Payment Methods in Tanzania

MNO_PAYMENT (Mobile Money)

  • 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:

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

Other Methods:

  • 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:

Data Type Original Masked
Card Number 4242424242424242 **** **** **** 4242
Account Number 1234567890 ****7890
Phone Number +255712345678 +255****5678
Crypto Wallet 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa 1A1z...fNa
PIN 1234 ****

Validation Rules

Card Numbers

  • Must be 13-19 digits
  • No spaces or dashes
  • Pattern: ^[0-9]{13,19}$

Expiry Dates

  • Format: MM/YY or MM/YYYY
  • Pattern: ^(0[1-9]|1[0-2])/[0-9]{2,4}$

Phone Numbers (Tanzania)

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

Email Addresses

  • Must be valid email format
  • Used for PayPal

Currency Codes

  • Must be 3-letter ISO code
  • Pattern: ^[A-Z]{3}$
  • Example: TZS, USD, EUR

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 Status

  • Active: Can be used for transactions
  • Inactive: Cannot be used for transactions
  • Pending: Awaiting verification
Back to top