Skip to main content

​
Endpoint

POST /wallets/{id}/payment-method

​
Description

Use this endpoint to add a payment method to a wallet that has already been created. Once a payment method is added, the wallet can be funded or used for payouts through the specified channel.

​
Path Parameters

ParameterTypeRequiredDescription
idstring (UUID)YesThe unique identifier of the wallet

​
Request Body

{
  "type": "bank_account"
}

​
Request Fields

FieldTypeRequiredDescription
typestringYesThe type of payment method to add

​
Supported Payment Method Types

TypeDescription
bank_accountLinks a bank account to the wallet for funding or payouts
Additional payment method types may be supported depending on your integration and region.

​
Response

​
Success Response (200 OK)

{
  "data": {
    "id": "3d2e3f3e-3b3c-4907-a4fd-e241203440d7",
    "status": "active",
    "payment_methods": [
      {
        "account_name": "Prosacco Erdman",
        "account_number": "3515200757",
        "account_type": "savings",
        "address": null,
        "bank_address": "9896 Bulah Roads, Suite 256, North Carolina, Kansas, 09819, US",
        "bank_code": "035",
        "bank_name": "Wema Bank"
      }
    ],

    "balance": {
      "amount": 0,
      "currency": "NGN"
    }
  }
}

​
Response Fields

FieldTypeDescription
idstringThe wallet ID
statusstringCurrent wallet status (active, inactive, etc.)
payment_methodsarrayList of payment methods linked to the wallet
balance.amountnumberWallet balance amount
balance.currencystringWallet currency
The payment_methods array may initially be empty if additional verification or setup is required before activation.

​
Example cURL Request

curl -X POST https://api.yourdomain.com/wallets/{id}/payment-method \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "bank_account"
  }'

​
Common Errors

Status CodeReason
400Invalid request body
401Unauthorized request
404Wallet not found
422Unsupported or invalid payment method type

​
Notes & Best Practices

  • Ensure the wallet exists and is active before adding a payment method.
  • Some payment methods may require additional verification steps before they become usable.
  • Always store and reference the wallet ID securely.
  • Use sandbox mode to test payment method creation before moving to production.

​
Next Steps

After successfully adding a payment method, you can:
  • Fund the wallet
  • Initiate payouts
  • Retrieve wallet details
  • Monitor wallet activity via webhooks