> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usebila.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Collections

> Accept payments from customers via mobile money

Accept mobile money payments from customers for goods, subscriptions, bills, or donations.

## Endpoints

| Endpoint                               | Method | Description                        |
| -------------------------------------- | ------ | ---------------------------------- |
| `/bila/collections`                    | GET    | List all collections               |
| `/bila/collections/{id}`               | GET    | Get a single collection by ID      |
| `/bila/collections/status/{reference}` | GET    | Get collection by your reference   |
| `/bila/collections/mobile-money`       | POST   | Initiate a mobile money collection |

## Collection Object

```json theme={null}
{
  "id": "col-001",
  "reference": "order-12345",
  "status": "successful",
  "amount": 100.00,
  "currency": "ZMW",
  "narration": "Payment for Order #12345",
  "customer": {
    "phone": "0977123456",
    "name": "JOHN DOE",
    "operator": "airtel"
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "completedAt": "2024-01-15T10:31:00Z"
}
```

## Collection Statuses

| Status       | Description                                    |
| ------------ | ---------------------------------------------- |
| `pending`    | Waiting for customer to approve on their phone |
| `successful` | Payment completed successfully                 |
| `failed`     | Payment failed or was declined                 |

## How It Works

1. You initiate a collection request
2. Customer receives a prompt on their phone
3. Customer enters their PIN to approve
4. Funds are credited to your wallet
5. You receive a webhook notification (optional)

```mermaid theme={null}
sequenceDiagram
    participant M as Your App
    participant B as Bila API
    participant C as Customer Phone
    
    M->>B: POST /collections/mobile-money
    B->>C: Send payment prompt
    C->>C: Customer enters PIN
    C->>B: Payment approved
    B->>M: Collection successful
```

## Initiate Collection

```bash theme={null}
curl -X POST "https://api.usebila.com/api/v1/bila/collections/mobile-money" \
  -H "x-api-key: sk_test_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100,
    "reference": "order-12345",
    "phone": "0977123456",
    "operator": "airtel",
    "country": "zm",
    "walletId": "your-wallet-id",
    "customerName": "John Doe",
    "narration": "Payment for Order #12345"
  }'
```

## Fee Bearer

You can specify who pays the transaction fee:

| Bearer     | Description                                        |
| ---------- | -------------------------------------------------- |
| `customer` | Fee is added to the amount (customer pays more)    |
| `merchant` | Fee is deducted from the amount (you receive less) |

```json theme={null}
{
  "amount": 100,
  "bearer": "customer",
  // ... other fields
}
```

## Check Collection Status

```bash theme={null}
curl -X GET "https://api.usebila.com/api/v1/bila/collections/status/order-12345" \
  -H "x-api-key: sk_test_your_api_key"
```

## Best Practices

<AccordionGroup>
  <Accordion title="Use unique references">
    Use your order ID or invoice number as the reference for easy reconciliation.
  </Accordion>

  <Accordion title="Handle pending status">
    Collections may stay pending while waiting for customer approval. Poll the status or use webhooks.
  </Accordion>

  <Accordion title="Show clear descriptions">
    Use descriptive narrations so customers know what they're paying for.
  </Accordion>
</AccordionGroup>

<a href="/docs/api-reference" style={{ textDecoration: 'none', borderBottom: 'none', display: 'block' }}>
  <div
    style={{
  borderRadius: '16px',
  padding: '32px',
  height: '120px',
  display: 'flex',
  flexDirection: 'column',
  justifyContent: 'flex-end',
  border: '0.5px solid #f16101',
  cursor: 'pointer',
  transition: 'all 0.15s ease-in-out',
  boxShadow: '0 4px 14px 0 rgba(241, 97, 1, 0.1)',
}}
    onMouseEnter={e => {
  e.currentTarget.style.background = 'rgba(241, 97, 1, 0.05)';
  e.currentTarget.style.boxShadow = '0 6px 20px 0 rgba(241, 97, 1, 0.2)';
  e.currentTarget.style.transform = 'translateY(-2px)';
}}
    onMouseLeave={e => {
  e.currentTarget.style.background = 'transparent';
  e.currentTarget.style.boxShadow = '0 4px 14px 0 rgba(241, 97, 1, 0.1)';
  e.currentTarget.style.transform = 'none';
}}
  >
    <div style={{ fontSize: '24px', marginBottom: '8px' }}>⟡</div>
    <div style={{ fontWeight: '500', fontSize: '16px' }}>API Reference</div>
    <div style={{ opacity: 0.6, fontSize: '13px', marginTop: '4px' }}>Explore the complete API reference</div>
  </div>
</a>