Payment Details

Create and manage reusable payment details for your business. Payment details specify how customers can pay your invoices — bank transfer, mobile money, cash, credit card, or other methods. Attach payment details to invoices so customers know where and how to send payment. This page also covers bank account lookup and verification.

Endpoints

Payment Details

Method	Endpoint	Description
POST	`/v1/payment-details`	Create a payment detail
GET	`/v1/payment-details`	List payment details
GET	`/v1/payment-details/{id}`	Get payment detail
PATCH	`/v1/payment-details/{id}`	Update a payment detail
DELETE	`/v1/payment-details/{id}`	Delete a payment detail

Bank Verification

Method	Endpoint	Description
GET	`/v1/banks/list`	List supported banks
POST	`/v1/banks/verify-account`	Verify a bank account number

🔑
All endpoints on this page require authentication. See Authentication for details.

Payment Types

Each payment detail has a type that determines what fields are relevant.

Type	Description	Key Fields
`BANK_TRANSFER`	Nigerian bank account for direct transfers	`bankName`, `accountNumber`, `accountName`
`MOBILE_MONEY`	Mobile money wallet	`provider`, `mobileNumber`
`CASH`	Cash payment on delivery or pickup	`instructions`
`CREDIT_CARD`	Card payment via a payment processor	`provider`, `instructions`
`OTHER`	Any other payment method	`instructions`

Create a Payment Detail

Add a new payment method to your business. You can mark one payment detail as the default — it will be automatically attached to new invoices.

curl -X POST https://e-invoicing.earnipay.com/v1/payment-details \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "businessId": "biz_xyz789",
    "type": "BANK_TRANSFER",
    "bankName": "First Bank of Nigeria",
    "accountNumber": "3012345678",
    "accountName": "Okafor Trading International Ltd",
    "isDefault": true
  }'

{
  "statusCode": 201,
  "message": "Payment detail created successfully.",
  "data": {
    "id": "pay_abc123",
    "businessId": "biz_xyz789",
    "type": "BANK_TRANSFER",
    "bankName": "First Bank of Nigeria",
    "accountNumber": "3012345678",
    "accountName": "Okafor Trading International Ltd",
    "isDefault": true,
    "createdAt": "2026-03-13T13:00:00.000Z",
    "updatedAt": "2026-03-13T13:00:00.000Z"
  }
}

Parameters

Parameter	Type	Required	Description
`businessId`	string	Yes	ID of the business this payment detail belongs to
`type`	string	Yes	One of: `BANK_TRANSFER`, `MOBILE_MONEY`, `CASH`, `CREDIT_CARD`, `OTHER`
`bankName`	string	No	Bank name (for `BANK_TRANSFER`). Use List Banks to get valid names
`accountNumber`	string	No	Bank account number (for `BANK_TRANSFER`). Use Verify Account to validate
`accountName`	string	No	Account holder name
`provider`	string	No	Payment provider name (for `MOBILE_MONEY`, `CREDIT_CARD`)
`mobileNumber`	string	No	Mobile wallet number (for `MOBILE_MONEY`)
`instructions`	string	No	Payment instructions for the customer
`isDefault`	boolean	No	Set as the default payment method for this business (default: `false`)

💡
Setting isDefault: true automatically removes the default flag from any existing default payment detail for the same business. Only one payment detail can be the default at a time.

List Payment Details

Retrieve all payment details for a business.

curl "https://e-invoicing.earnipay.com/v1/payment-details?businessId=biz_xyz789" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Parameter	Type	Required	Description
`businessId`	string	Yes	Filter by business ID

{
  "statusCode": 200,
  "message": "Payment details retrieved successfully.",
  "data": [
    {
      "id": "pay_abc123",
      "businessId": "biz_xyz789",
      "type": "BANK_TRANSFER",
      "bankName": "First Bank of Nigeria",
      "accountNumber": "3012345678",
      "accountName": "Okafor Trading International Ltd",
      "isDefault": true,
      "createdAt": "2026-03-13T13:00:00.000Z"
    },
    {
      "id": "pay_def456",
      "businessId": "biz_xyz789",
      "type": "MOBILE_MONEY",
      "provider": "OPay",
      "mobileNumber": "+2348012345678",
      "accountName": "Okafor Trading International Ltd",
      "isDefault": false,
      "createdAt": "2026-03-13T13:10:00.000Z"
    },
    {
      "id": "pay_ghi789",
      "businessId": "biz_xyz789",
      "type": "CASH",
      "instructions": "Pay in cash at our Lagos office: 15 Marina Road, Lagos Island.",
      "isDefault": false,
      "createdAt": "2026-03-13T13:20:00.000Z"
    }
  ]
}

Get Payment Detail

Retrieve a specific payment detail by ID.

curl https://e-invoicing.earnipay.com/v1/payment-details/pay_abc123 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "statusCode": 200,
  "message": "Payment detail retrieved successfully.",
  "data": {
    "id": "pay_abc123",
    "businessId": "biz_xyz789",
    "type": "BANK_TRANSFER",
    "bankName": "First Bank of Nigeria",
    "accountNumber": "3012345678",
    "accountName": "Okafor Trading International Ltd",
    "isDefault": true,
    "createdAt": "2026-03-13T13:00:00.000Z",
    "updatedAt": "2026-03-13T13:00:00.000Z"
  }
}

Update a Payment Detail

Update one or more fields on an existing payment detail. Send only the fields you want to change.

curl -X PATCH https://e-invoicing.earnipay.com/v1/payment-details/pay_abc123 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "accountNumber": "3098765432",
    "instructions": "Please include your invoice number as the transfer reference."
  }'

{
  "statusCode": 200,
  "message": "Payment detail updated successfully.",
  "data": {
    "id": "pay_abc123",
    "businessId": "biz_xyz789",
    "type": "BANK_TRANSFER",
    "bankName": "First Bank of Nigeria",
    "accountNumber": "3098765432",
    "accountName": "Okafor Trading International Ltd",
    "instructions": "Please include your invoice number as the transfer reference.",
    "isDefault": true,
    "createdAt": "2026-03-13T13:00:00.000Z",
    "updatedAt": "2026-03-13T17:00:00.000Z"
  }
}

Delete a Payment Detail

Remove a payment detail. If you delete the default payment detail, no payment method will be marked as default until you set a new one.

curl -X DELETE https://e-invoicing.earnipay.com/v1/payment-details/pay_ghi789 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "statusCode": 200,
  "message": "Payment detail deleted successfully."
}

⚠️
Deleting a payment detail does not affect existing invoices that reference it. The payment information is captured on the invoice at creation time.

List Supported Banks

Retrieve the list of Nigerian banks supported on the platform. Use this to populate a bank selection dropdown or validate bank names before creating a BANK_TRANSFER payment detail.

curl https://e-invoicing.earnipay.com/v1/banks/list \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

{
  "statusCode": 200,
  "message": "Banks retrieved successfully.",
  "data": [
    {
      "name": "Access Bank",
      "code": "044"
    },
    {
      "name": "First Bank of Nigeria",
      "code": "011"
    },
    {
      "name": "Guaranty Trust Bank",
      "code": "058"
    },
    {
      "name": "United Bank for Africa",
      "code": "033"
    },
    {
      "name": "Zenith Bank",
      "code": "057"
    }
  ]
}

Use the code field when verifying bank accounts.

Verify Bank Account

Verify a bank account number and retrieve the account holder's name. Use this before creating a BANK_TRANSFER payment detail to confirm the account number is valid and matches the expected business or individual.

curl -X POST https://e-invoicing.earnipay.com/v1/banks/verify-account \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "bankCode": "011",
    "accountNumber": "3012345678"
  }'

Parameter	Type	Required	Description
`bankCode`	string	Yes	Bank code from List Banks
`accountNumber`	string	Yes	10-digit NUBAN account number

{
  "statusCode": 200,
  "message": "Account verified successfully.",
  "data": {
    "accountNumber": "3012345678",
    "accountName": "OKAFOR TRADING INTERNATIONAL LTD",
    "bankCode": "011",
    "bankName": "First Bank of Nigeria"
  }
}

💡
Use the returned accountName to auto-fill the accountName field when creating a bank transfer payment detail. This ensures the name on the invoice matches the bank's records.

Recommended Flow for Bank Transfer Setup

List banks — GET /v1/banks/list → let the user select their bank
Verify account — POST /v1/banks/verify-account with the bank code and account number
Create payment detail — POST /v1/payment-details with the verified bankName, accountNumber, and accountName

Error Handling

Status Code	Error	Description
`400`	Bad Request	Missing required fields, invalid payment type, or bank account verification failed
`401`	Unauthorized	Missing or expired access token
`403`	Forbidden	You don't have permission for this business
`404`	Not Found	Payment detail ID doesn't exist

{
  "statusCode": 400,
  "message": "type must be one of: BANK_TRANSFER, MOBILE_MONEY, CASH, CREDIT_CARD, OTHER.",
  "error": "Bad Request"
}