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

# Create Collection

Creates a new integrated collection. This endpoint allows you to:

* Create a payment collection linked to an external payment provider
* Automatically create or find contacts based on customer information
* Generate payment options (payment links, virtual accounts, etc.)
* Configure automated follow-up messages
* Track payment metadata and events

## Request Body

<ParamField body="type" type="string" default="integrated">
  Collection type. Currently only "integrated" is supported for public API
</ParamField>

<ParamField body="reference" type="string" required>
  Unique identifier from your payment provider (e.g., Paystack transaction ID)
</ParamField>

<ParamField body="amount" type="object" required>
  Payment amount object
</ParamField>

<ParamField body="amount.value" type="number" required>
  Payment amount as a number
</ParamField>

<ParamField body="amount.currency" type="string" required>
  ISO currency code (e.g., "NGN", "USD", "GHS")
</ParamField>

<ParamField body="contact" type="object" required>
  Customer information. Contact will be auto-created if not exists, or found by
  phone/email if already exists
</ParamField>

<ParamField body="contact.firstName" type="string" required>
  Customer's first name
</ParamField>

<ParamField body="contact.lastName" type="string" required>
  Customer's last name
</ParamField>

<ParamField body="contact.phone" type="string" required>
  Customer's phone number (E.164 format recommended)
</ParamField>

<ParamField body="contact.email" type="string" required>
  Customer's email address
</ParamField>

<ParamField body="metadata" type="array | object">
  Metadata can be an array or object in any format. **Must include a
  `description` field** when metadata is provided.
</ParamField>

<ParamField body="expiresIn" type="number" default="1440">
  Collection expiration time in minutes (default: 1440 = 24 hours)
</ParamField>

<ParamField body="payable" type="object">
  Payment options configuration
</ParamField>

<ParamField body="payable.enabled" type="boolean" default="false">
  Whether to generate payment options
</ParamField>

<ParamField body="payable.methods" type="array">
  Array of payment methods to generate when enabled: - `payment_link`: Generates
  a payment link URL - `virtual_account`: Creates a dedicated virtual bank
  account - `mobile_money`: Generates mobile money payment instructions -
  `card`: Card payment option - `bank_transfer`: Bank transfer instructions
</ParamField>

<ParamField body="provider" type="string">
  Slug of the payment provider (must exist in your providers list)
</ParamField>

<ParamField body="followUp" type="object">
  Follow-up configuration
</ParamField>

<ParamField body="followUp.enabled" type="boolean">
  Whether to enable automated follow-up messages
</ParamField>

<ParamField body="followUp.startAfter" type="number">
  Minutes to wait before sending first follow-up
</ParamField>

<ParamField body="followUp.cadence" type="string">
  Follow-up frequency. Options: `every_5m`, `every_10m`, `every_15m`,
  `every_30m`, `every_1h`, `every_2h`, `every_4h`, `every_6h`, `every_12h`,
  `daily`
</ParamField>

<ParamField body="followUp.channels" type="array">
  Array of communication channels. Options: `whatsapp`, `sms`, `email`
</ParamField>

<ParamField body="followUp.tone" type="string">
  Message tone. Options: `gentle`, `professional`, `urgent`
</ParamField>

## Example Request

```json theme={null}
{
  "type": "integrated",
  "reference": "PSK_txn_8a7f34",
  "amount": {
    "value": 45000,
    "currency": "NGN"
  },
  "contact": {
    "firstName": "Amina",
    "lastName": "Lawal",
    "phone": "+2348012345678",
    "email": "amina@example.com"
  },
  "metadata": [
    {
      "name": "Standard Membership",
      "amount": {
        "value": 15000,
        "currency": "NGN"
      },
      "description": "January plan renewal",
      "quantity": 1
    }
  ],
  "expiresIn": 1440,
  "payable": {
    "enabled": true,
    "methods": ["payment_link", "virtual_account", "mobile_money"]
  },
  "provider": "paystack",
  "followUp": {
    "enabled": true,
    "startAfter": 20,
    "cadence": "every_10m",
    "channels": ["whatsapp", "sms"],
    "tone": "gentle"
  }
}
```

## Response

<ResponseField name="status" type="string">
  Response status ("success")
</ResponseField>

<ResponseField name="message" type="string">
  Success message
</ResponseField>

<ResponseField name="data" type="object">
  Collection object
</ResponseField>

<ResponseField name="data.id" type="string">
  Collection ID
</ResponseField>

<ResponseField name="data.type" type="string">
  Collection type
</ResponseField>

<ResponseField name="data.contact" type="object">
  Contact information
</ResponseField>

<ResponseField name="data.reference" type="string">
  External payment reference
</ResponseField>

<ResponseField name="data.amount" type="object">
  Payment amount
</ResponseField>

<ResponseField name="data.status" type="string">
  Collection status (pending, completed, expired, overdue, cancelled)
</ResponseField>

<ResponseField name="data.payable" type="object">
  Payment options (if enabled)
</ResponseField>

<ResponseField name="data.payable.options" type="array">
  Array of generated payment options
</ResponseField>

<ResponseField name="data.events" type="array">
  Array of collection events
</ResponseField>

<ResponseField name="data.createdAt" type="string">
  ISO 8601 timestamp
</ResponseField>

<ResponseField name="data.updatedAt" type="string">
  ISO 8601 timestamp
</ResponseField>

<ResponseField name="data.completedAt" type="string">
  ISO 8601 timestamp (null if not completed)
</ResponseField>

## Example Response

```json theme={null}
{
  "status": "success",
  "message": "Collection created successfully",
  "data": {
    "id": "pay_9fmz6170pzaih14pmyl0a49o1l",
    "type": "integrated",
    "contact": {
      "id": "contact_gj7iyx04gs7hticrite6m6qdhc",
      "firstName": "Amina",
      "lastName": "Lawal",
      "phone": "+2348012345678",
      "email": "amina@example.com"
    },
    "reference": "PSK_txn_8a7f34",
    "amount": {
      "value": 45000,
      "currency": "NGN"
    },
    "status": "pending",
    "expiresIn": 1440,
    "payable": {
      "enabled": true,
      "methods": ["payment_link", "virtual_account"],
      "options": [
        {
          "method": "payment_link",
          "link": "https://mitu.ai/pay/PSK_txn_8a7f34",
          "expiresAt": "2025-11-14T17:46:07.000Z"
        },
        {
          "method": "virtual_account",
          "bankName": "MituFi Bank",
          "accountNumber": "0123456789",
          "accountName": "Amina Lawal",
          "expiresAt": "2025-11-14T17:46:07.000Z"
        }
      ]
    },
    "followUp": {
      "enabled": true,
      "startAfter": 20,
      "cadence": "every_10m",
      "channels": ["whatsapp", "sms"],
      "tone": "gentle"
    },
    "metadata": [
      {
        "name": "Standard Membership",
        "amount": {
          "value": 15000,
          "currency": "NGN"
        },
        "description": "January plan renewal",
        "quantity": 1
      }
    ],
    "events": [
      {
        "id": "evt_5kk2yo9288or4ne0tvoef09303",
        "type": "collection.created",
        "timestamp": "2025-11-12T17:46:07.000Z"
      }
    ],
    "createdAt": "2025-11-12T17:46:07.000Z",
    "updatedAt": "2025-11-12T17:46:07.000Z",
    "completedAt": null
  }
}
```

## Notes

* If `followUp` is not provided, AI will intelligently determine the best follow-up strategy based on the collection context
* Contact is automatically created or found based on phone/email
* Payment options are only generated if `payable.enabled` is true
* The reference must be unique within your account
* `metadata` can be an array or object in any format, but must include a `description` field when provided