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

# Create Transfer

> POST /api/v1/transfers - Send money to a bank account

Initiate a money transfer to any Nigerian bank account.

## Endpoint

```
POST /api/v1/transfers
```

## Request Body

<ParamField body="amount_minor" type="number" required>
  Amount in kobo (e.g., 10000 = ₦100.00)
</ParamField>

<ParamField body="recipient_account" type="string" required>
  Recipient account number (10 digits)
</ParamField>

<ParamField body="recipient_bank_code" type="string" required>
  Recipient bank code (e.g., `058` for GTBank)
</ParamField>

<ParamField body="narration" type="string" required>
  Transfer description (max 100 characters)
</ParamField>

<ParamField body="reference" type="string">
  Unique reference for this transfer (auto-generated if not provided)
</ParamField>

<ParamField body="currency" type="string" default="NGN">
  Currency code (currently only NGN supported)
</ParamField>

<ParamField body="metadata" type="object">
  Additional data to store with the transfer
</ParamField>

## Response

<ResponseField name="id" type="string">
  Unique transfer ID
</ResponseField>

<ResponseField name="amount_minor" type="number">
  Transfer amount in kobo
</ResponseField>

<ResponseField name="fee_minor" type="number">
  Transaction fee in kobo
</ResponseField>

<ResponseField name="total_minor" type="number">
  Total amount debited (amount + fee)
</ResponseField>

<ResponseField name="recipient_account" type="string">
  Recipient account number
</ResponseField>

<ResponseField name="recipient_name" type="string">
  Recipient account name
</ResponseField>

<ResponseField name="recipient_bank" type="string">
  Recipient bank name
</ResponseField>

<ResponseField name="status" type="string">
  Transfer status (`pending`, `processing`, `completed`, `failed`)
</ResponseField>

<ResponseField name="reference" type="string">
  Unique reference
</ResponseField>

<ResponseField name="narration" type="string">
  Transfer description
</ResponseField>

<ResponseField name="session_id" type="string">
  Provider session ID
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp
</ResponseField>

## Example Request

<CodeGroup>
  ```javascript JavaScript theme={null}
  const transfer = await client.transfers.create({
    amountMinor: 50000, // ₦500.00
    recipient_account: '0123456789',
    recipient_bank_code: '058',
    narration: 'Payment for services',
    reference: 'TRF_' + Date.now(),
    metadata: {
      customer_id: 'cus_123',
      invoice_id: 'INV_456'
    }
  });

  console.log(`Transfer ID: ${transfer.id}`);
  console.log(`Status: ${transfer.status}`);
  ```

  ```python Python theme={null}
  transfer = client.transfers.create(
      amount_minor=50000,  # ₦500.00
      recipient_account='0123456789',
      recipient_bank_code='058',
      narration='Payment for services',
      reference=f'TRF_{int(time.time())}',
      metadata={
          'customer_id': 'cus_123',
          'invoice_id': 'INV_456'
      }
  )

  print(f"Transfer ID: {transfer.id}")
  print(f"Status: {transfer.status}")
  ```

  ```php PHP theme={null}
  $transfer = $client->transfers->create([
      'amount_minor' => 50000, // ₦500.00
      'recipient_account' => '0123456789',
      'recipient_bank_code' => '058',
      'narration' => 'Payment for services',
      'reference' => 'TRF_' . time(),
      'metadata' => [
          'customer_id' => 'cus_123',
          'invoice_id' => 'INV_456'
      ]
  ]);

  echo "Transfer ID: {$transfer->id}\n";
  echo "Status: {$transfer->status}";
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.usezentra.com/api/v1/transfers \
    -H "Authorization: Bearer YOUR_SECRET_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "amount_minor": 50000,
      "recipient_account": "0123456789",
      "recipient_bank_code": "058",
      "narration": "Payment for services",
      "reference": "TRF_1234567890",
      "metadata": {
        "customer_id": "cus_123",
        "invoice_id": "INV_456"
      }
    }'
  ```
</CodeGroup>

## Example Response

```json theme={null}
{
  "success": true,
  "data": {
    "id": "trn_abc123xyz",
    "amount_minor": 50000,
    "fee_minor": 50,
    "total_minor": 50050,
    "recipient_account": "0123456789",
    "recipient_name": "John Doe",
    "recipient_bank": "Guaranty Trust Bank",
    "recipient_bank_code": "058",
    "status": "pending",
    "reference": "TRF_1234567890",
    "narration": "Payment for services",
    "session_id": "SES_xyz789",
    "currency": "NGN",
    "metadata": {
      "customer_id": "cus_123",
      "invoice_id": "INV_456"
    },
    "created_at": "2024-01-15T10:30:00Z"
  }
}
```

## Transfer Fees

| Amount Range     | Fee |
| ---------------- | --- |
| ₦0 - ₦5,000      | ₦10 |
| ₦5,001 - ₦50,000 | ₦25 |
| Above ₦50,000    | ₦50 |

<Info>
  Fees are automatically deducted from your wallet balance.
</Info>

## Processing Time

* **Instant**: Most transfers complete within seconds
* **Same Day**: Some banks may take up to 24 hours
* **Webhook**: You'll receive a webhook when the transfer completes

## Error Responses

<ResponseExample>
  ```json Insufficient Balance theme={null}
  {
    "success": false,
    "error": {
      "code": "insufficient_balance",
      "message": "Wallet balance insufficient",
      "status": 422,
      "details": {
        "required": 50050,
        "available": 30000
      }
    }
  }
  ```

  ```json Invalid Account theme={null}
  {
    "success": false,
    "error": {
      "code": "invalid_account",
      "message": "Recipient account not found",
      "status": 422
    }
  }
  ```

  ```json Daily Limit Exceeded theme={null}
  {
    "success": false,
    "error": {
      "code": "limit_exceeded",
      "message": "Daily transfer limit exceeded",
      "status": 422,
      "details": {
        "limit": 1000000,
        "used": 950000
      }
    }
  }
  ```
</ResponseExample>

## Idempotency

Use the `reference` parameter to prevent duplicate transfers:

```javascript theme={null}
// This will only create one transfer, even if called multiple times
const transfer = await client.transfers.create({
  amountMinor: 50000,
  destinationAccountNumber: '0123456789',
  destinationBankCode: '058',
  narration: 'Payment',
  reference: 'UNIQUE_REF_123' // Use same reference
});
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Get Transfer" icon="eye" href="/api-reference/transfers/get">
    Check transfer status
  </Card>

  <Card title="List Transfers" icon="list" href="/api-reference/transfers/list">
    View all transfers
  </Card>

  <Card title="Resolve Account" icon="magnifying-glass" href="/api-reference/transfers/resolve-account">
    Verify account before sending
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api-reference/webhooks/overview">
    Handle transfer events
  </Card>
</CardGroup>