Collection API

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

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

Short Description: The ~~Payment Methods~~Collection API ~~enables~~handles wallet top-up flows for NextGate users. It allows users to ~~manage~~deposit money into their ~~payment~~NextGate ~~instruments~~wallet ~~including credit/debit cards,~~via mobile money (~~M-Pesa,~~USSD ~~Airtel~~push) ~~Money),~~or ~~bank transfers, PayPal, cryptocurrencies, wallets, gift cards, and cash on delivery options. This API provides secure storage, retrieval, updating, and deletion of~~card payment ~~methods~~through ~~with~~Selcom. ~~built-in~~All ~~validation~~subsequent ~~and~~platform ~~duplicate~~payments ~~detection.~~(events, products) are made from the wallet balance.

Hints:

~~All~~Always ~~endpoints~~provide ~~require~~a ~~authentication~~unique ~~via~~idempotencyKey ~~Bearer~~per ~~token~~request into prevent duplicate charges

For USSD channels the ~~Authorization~~user ~~header~~receives a PIN prompt on their phone — poll /status/{id} to track completion
~~Sensitive~~For ~~data~~CARD ~~(card~~channel ~~numbers,~~the ~~account~~response ~~numbers,~~contains ~~PINs)~~a ~~are~~paymentUrl — redirect the user to complete payment

Selcom webhooks automatically ~~tokenized and masked in responses~~

~~Only one payment method can be set as default at a time; setting a new default automatically unsets~~credit the ~~previous~~wallet ~~one~~

~~Payment~~confirmation ~~methods~~— ~~support~~no ~~soft~~manual ~~verification~~step ~~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~~needed

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

Error Response Structure

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

Standard Response Fields

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

HTTPFlow Method Badge StandardsDiagram

~~For~~

User
 better|
 visual|--- clarity,POST all endpoints use colored badges for HTTP methods with the following standard colors:


GET/collection/initiate --------> GETCollectionController
 |       (channel, amount, msisdn)                |
 |                                       Validate request
 |                                       Check idempotency
 |                                       Save CollectionRequest (PENDING)
 |                                                |
 |                               .----------------.
 |                               |                |
 |                            USSD             CARD
 |                               |                |
 |                        Push USSD to      Create Selcom
 |                        Selcom API        Checkout Order
 |                               |                |
 |                        Status: AWAITING  Status: AWAITING
 |                        CUSTOMER_ACTION   CUSTOMER_ACTION
 |                               |                |
 |<-- Response (requestId) ------'----------------'
 Green|
 |   [USSD: User enters PIN on phone]
 |   [CARD: User pays on paymentUrl ]
 |
 |                   Selcom Webhook ---------> /api/selcom/webhook
 |                   (Safe,payment read-onlyconfirmed)               operations)
|
 POST|                                           creditWallet()
 |                                           Status: COMPLETED
 |
 |--- GET /collection/status/{id} -------> POSTStatus: COMPLETED
 |<-- Blue{ (Createstatus, newtransactionRef, 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

~~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~~

~~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~~

~~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~~

~~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~~

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

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

~~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~~

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

~~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. CreateInitiate Payment MethodCollection
Purpose: CreateInitiates a newwallet paymenttop-up methodrequest forvia themobile authenticatedmoney user(USSD) withor supportcard for multiple payment typespayment.
Endpoint: POST {base_url}/payment-methodscollection/initiate
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 (RequiresAuthorization: Bearer Token, Owner only)

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

~~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~~

~~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~~

Authentication: Bearer Token<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~~JWT 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 +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~~	~~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~~json

Request JSON Sample ~~- Update Card Expiry~~(USSD):

{
  "paymentMethodType"channel": "CREDIT_CARD"MPESA",
  "methodDetails"amount": {50000,
  "expiry"msisdn": "06/2028"255712345678",
  }"idempotencyKey": "usr-123-topup-1741234567"
}

Request JSON Sample ~~- Update Mobile Money Number~~(CARD):

{
  "paymentMethodType"channel": "MNO_PAYMENT"CARD",
  "methodDetails"amount": {50000,
  "phoneNumber"idempotencyKey": "+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": trueusr-123-topup-1741234568"
}

Request Body Parameters:

uniqueper

Parameter	Type	Required	Description	Validation
~~paymentMethodType~~`channel`	string ~~(enum)~~	NoYes	~~Type~~Payment ~~of payment method~~channel	~~Must~~enum: ~~match~~`MPESA`, ~~existing~~`AIRTEL`, ~~type~~`TIGO`, or`HALOPESA`, be`SELCOM_PESA`, ~~a valid payment type~~`CARD`
~~methodDetails~~`amount`	~~object~~number	NoYes	~~Payment method details~~Amount to ~~update~~top up in TZS	~~Only~~Min: ~~provided fields will be updated~~1000
~~billingAddress~~`msisdn`	~~object~~string	NoConditional	~~Billing~~Mobile ~~address~~phone ~~to update~~number	~~Partial~~Required ~~updates~~for ~~supported~~all channels except CARD. Format: `255XXXXXXXXX` (12 digits)
~~metadata~~`idempotencyKey`	~~object~~string	NoYes	~~Metadata~~Unique key to ~~update~~prevent duplicate requests	~~Replaces~~Max ~~existing~~200 ~~metadata~~chars, ~~completely~~
~~isDefault~~	~~boolean~~	No	~~Update default status~~	~~Setting to true unsets other defaults~~request

~~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 (USSD):

{
  "success": true,
  "httpStatus": "OK",
  "message": "PaymentCollection method updatedinitiated successfully",
  "action_time": "2025-10-27T10:2026-03-06T10:30:45",
  "data": {
    "paymentMethodId"collectionRequestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "ownerId"channel": "b2c3d4e5-f6a7-8901-bcde-f12345678901"MPESA",
    "ownerUserName"amount": 50000,
    "currency": "johndoe"TZS",
    "paymentMethodType"status": "CREDIT_CARD"AWAITING_CUSTOMER_ACTION",
    "methodDetails"msisdnDisplay": "2557****678",
    "paymentUrl": null,
    "message": "Please enter your PIN on your phone to complete payment."
  }
}

Success Response JSON Sample (CARD):

{
  "success": true,
  "httpStatus": "OK",
  "message": "Collection initiated successfully",
  "action_time": "2026-03-06T10:30:45",
  "data": {
    "cardType"collectionRequestId": "Visa"a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "maskedCardNumber"channel": "**** **** **** 0366"CARD",
    "expiry"amount": 50000,
    "currency": "06/2028"TZS",
    "cardholderName"status": "John Doe"
    }AWAITING_CUSTOMER_ACTION",
    "billingAddress"msisdnDisplay": {null,
    "street"paymentUrl": "123 Main Street"https://checkout.selcom.net/pay/abc123",
    "city"message": "DarRedirect esuser Salaam",to payment URL."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~~`collectionRequestId`	~~Unique~~UUID ~~identifier~~— ofuse ~~the~~this ~~updated~~to ~~payment~~poll ~~method~~`/status/{id}`
~~ownerId~~`channel`	~~User~~Channel ~~account~~used ~~ID who owns~~for this ~~payment method~~collection
~~ownerUserName~~`amount`	~~Username~~Amount ofin ~~the payment method owner~~TZS
~~paymentMethodType~~`currency`	~~Type~~Always ~~of payment method~~`TZS`
~~methodDetails~~`status`	~~Updated~~Current ~~payment-specific~~status ~~details~~— ~~with~~see ~~sensitive~~status ~~data~~table ~~masked~~below
~~billingAddress~~`msisdnDisplay`	~~Updated~~Masked ~~billing~~phone ~~address~~number ife.g. ~~modified~~`2557****678`
~~metadata~~`paymentUrl`	~~Updated~~Card ~~metadata~~payment ifURL ~~modified~~— redirect user here (null for USSD)
~~isDefault~~`message`	~~Updated~~Human-readable ~~default~~instruction ~~status~~for the user

Collection Status Values:

Status	Description
`PENDING`	Request created, not yet sent to Selcom
~~isActive~~`AWAITING_CUSTOMER_ACTION`	~~Current~~Sent ~~active~~to ~~status~~Selcom, waiting for user PIN or card payment
~~isVerified~~`COMPLETED`	~~Current~~Payment ~~verification~~confirmed, ~~status~~wallet credited
~~createdAt~~`FAILED`	~~Original~~Payment ~~creation~~failed ~~timestamp~~or rejected
~~updatedAt~~`EXPIRED`	~~Timestamp~~Request ofexpired ~~this~~before ~~update~~user acted (30 min window)

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~~Responses:

~~Not~~Missing ~~Found~~phone ~~(404):~~

for

{
  "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~~USSD (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "ThisPhone paymentnumber methodis already existsrequired for yourMPESA account"payments.",
  "action_time": "2025-10-27T10:2026-03-06T10:30:45",
  "data": "ThisPhone paymentnumber methodis already existsrequired for yourMPESA account"payments."
}

~~Validation~~Invalid ~~Error~~phone format (~~422)~~400):

{
  "success": false,
  "httpStatus": "UNPROCESSABLE_ENTITY"BAD_REQUEST",
  "message": "ValidationInvalid failed"phone number format.",
  "action_time": "2025-10-27T10:2026-03-06T10:30:45",
  "data": {
    "phoneNumber": "Invalid phone number"number format."
}

Selcom rejection (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "expiry"message": "InvalidPayment expiryinitiation formatfailed: (MM/YY)Subscriber not found",
  "action_time": }"2026-03-06T10:30:45",
  "data": "Payment initiation failed: Subscriber not found"
}

5.2. DeleteGet PaymentCollection MethodStatus

Purpose: ~~Permanently~~Returns ~~delete~~the current status of a ~~payment~~collection ~~method~~request. ~~from~~Poll this after initiating to know when the ~~system~~wallet has been credited.

Endpoint: ~~DELETE~~GET /collection/status/{base_url}/payment-methods/{paymentMethodId}collectionRequestId}

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

Authentication: Authorization: Bearer Token<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~~`collectionRequestId`	UUID	Yes	~~Unique~~ID ~~identifier~~returned offrom ~~the payment method to delete~~	~~Valid UUID format~~`/initiate`

Success Response JSON Sample:

{
  "success": true,
  "httpStatus": "OK",
  "message": "PaymentCollection methodstatus deleted successfully"retrieved",
  "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:2026-03-06T10:30:45",
  "data": {
    "paymentMethodId"collectionRequestId": "b2c3d4e5-f6a7-8901-bcde-f12345678901"a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "ownerId"channel": "b2c3d4e5-f6a7-8901-bcde-f12345678901"MPESA",
    "ownerUserName"amount": 50000,
    "currency": "johndoe"TZS",
    "paymentMethodType"status": "MNO_PAYMENT"COMPLETED",
    "methodDetails": {
      "maskedPhoneNumber"msisdnDisplay": "+255*2557****5678"678",
    "mccMnc"failureReason": null,
    "transactionRef": "M-PESA"
    }NXT-TXN-20260306-ABCD1234",
    "isDefault": true,
    "isActive": true,
    "isVerified": true,
    "createdAt": "2025-10-20T08:15:30"2026-03-06T10:30:00",
    "updatedAt"completedAt": "2025-10-27T10:30:2026-03-06T10:31:45"
  }
}

Success Response Fields:

~~timestamp~~

Field	Description
~~paymentMethodId~~`collectionRequestId`	~~Unique identifier~~UUID of ~~the~~this ~~payment~~collection ~~method now set as default~~request
~~isDefault~~`channel`	~~Now~~Channel ~~set to true~~used
~~updatedAt~~`amount`	~~Updated~~Amount toin ~~current~~TZS
`currency`	Always `TZS`
`status`	Current status — see status table above
`msisdnDisplay`	Masked phone number
`failureReason`	Populated if status is `FAILED`
`transactionRef`	Wallet transaction reference — available when `COMPLETED`
`createdAt`	When the request was created
`completedAt`	When the wallet was credited — null if not yet completed

~~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~~Responses:

~~Bad~~Not ~~Request~~found -or ~~Inactive~~not ~~Payment~~owned ~~Method~~by user (400):

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "CannotCollection 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 methodrequest not found",
  "action_time": "2025-10-27T10:2026-03-06T10:30:45",
  "data": "PaymentCollection methodrequest 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~~ ~~BadgeCodeTemplates~~

~~GET~~

~~Badge:~~

~~style="background-color:logicviolation~~

~~Unauthorized~~:

403

Forbidden:~~Insufficient~~

Method Endpoint Description

Method	Endpoint	Description
POST	`<span/collection/initiate`	Start ~~#28a745;~~a ~~color:~~top-up ~~white;~~via ~~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,~~USSD or ~~business~~card
GET	`401/collection/status/{id}`	Check ~~Authentication~~top-up ~~required/failed~~status

POST

<span/collection/initiate

Start ~~#28a745;~~a ~~color:~~top-up ~~white;~~via ~~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,~~USSD or ~~business~~card

GET 401/collection/status/{id} Check ~~Authentication~~top-up ~~required/failed~~status

~~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"
  }
}