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

# Overview

> Charge customers directly from your backend using provider slugs and customer input without creating a hosted checkout session.

Direct Charge allows your backend to initiate payment directly with a provider, without first creating a checkout URL.

## When To Use Direct Charge

<CardGroup cols={3}>
  <Card title="Backend-Driven Flows" icon="server">
    Best for server-to-server payment initiation where you control the full transaction lifecycle.
  </Card>

  <Card title="Provider-Specific Inputs" icon="sliders">
    Use when payment requires provider-specific fields like `network` or customer OTP codes.
  </Card>

  <Card title="Recurring / Embedded UX" icon="repeat">
    Useful for tightly integrated experiences where redirect checkout is not preferred.
  </Card>
</CardGroup>

## Endpoints

| Method | Endpoint                                                    | Purpose                                                          |
| ------ | ----------------------------------------------------------- | ---------------------------------------------------------------- |
| `GET`  | `/payments/v1/payments/direct-charge/{provider}/properties` | Fetch provider-specific properties (optional for some providers) |
| `POST` | `/payments/v1/payments/direct-charge`                       | Initiate direct charge                                           |
| `GET`  | `/payments/v1/payments/verify/{reference}`                  | Verify final transaction status                                  |

## Integration Steps

<Steps>
  <Step title="Pick provider slug">
    Select a valid provider from [Supported Providers](/en/guides/introductions/supported-providers).
  </Step>

  <Step title="Fetch provider properties (optional)">
    For providers like Bank Transfer(bank-transfer-nigeria), fetch required properties (for example network values) before charging.
  </Step>

  <Step title="Send direct charge request">
    Call the direct-charge endpoint with `provider`, `amount`, and `customerInput`.
  </Step>

  <Step title="Handle action + confirm final status">
    Use response action (`processing`, `redirect`, `bankTransfer`) and finalize based on webhook/verification.
  </Step>
</Steps>

## Fetch Provider Properties (Optional)

```bash theme={null}
curl --location 'https://sandbox-api.payfonte.com/payments/v1/payments/direct-charge/{provider}/properties' \
  --header 'client-id: <client-id>' \
  --header 'client-secret: <client-secret>'
```

Example response:

```json theme={null}
{
  "data": {
    "networks": [
      { "name": "Airtel", "value": "airtel" },
      { "name": "MTN MoMo", "value": "mtn-momo" }
    ]
  }
}
```

## Direct Charge Request

```bash theme={null}
curl --location 'https://sandbox-api.payfonte.com/payments/v1/payments/direct-charge' \
  --header 'client-id: <client-id>' \
  --header 'client-secret: <client-secret>' \
  --header 'Content-Type: application/json' \
  --data '{
    "reference": "ORDER-1001",
    "amount": 10000,
    "provider": "mtn-momo-ivory-coast",
    "webhook": "https://yourapp.com/webhooks/payfonte",
    "narration": "Order payment",
    "customerInput": {
      "phoneNumber": "2250512345678"
    }
  }'
```

Sample response:

```json theme={null}
{
  "data": {
    "action": "processing",
    "sessionId": "1031-4120-a98f-9357692945",
    "provider": "mtn-momo-ivory-coast",
    "channel": "mobile-money",
    "reference": "ORDER-1001",
    "amount": 10000,
    "status": "pending",
    "statusDescription": "Awaiting Provider's Feedback"
  },
  "statusCode": 201
}
```

## Request Fields

| Field           | Type    | Required    | Description                                          |
| --------------- | ------- | ----------- | ---------------------------------------------------- |
| `provider`      | string  | Yes         | Provider slug (for example `mtn-momo-ivory-coast`)   |
| `amount`        | integer | Yes         | Amount in minor units (no decimals)                  |
| `customerInput` | object  | Yes         | Provider/customer fields (for example `phoneNumber`) |
| `reference`     | string  | Recommended | Unique merchant reference                            |
| `webhook`       | string  | No          | Override webhook for this transaction                |
| `narration`     | string  | No          | Transaction description                              |
| `metadata`      | object  | No          | Custom metadata returned downstream                  |

## Action Types and Handling

<AccordionGroup>
  <Accordion title="processing" icon="clock" defaultOpen>
    Customer/provider interaction is in progress (for example USSD/STK authorization pending).
    Keep payment state pending and wait for webhook/verification final status.
  </Accordion>

  <Accordion title="redirect" icon="arrow-up-right-from-square">
    Redirect customer to provider URL (usually at `data.data.link`).
    Do not treat redirect completion alone as payment success.
  </Accordion>

  <Accordion title="bankTransfer" icon="building">
    Display returned bank transfer instructions (account name/number, amount, expiry).
    Wait for webhook/verification before marking success.
  </Accordion>
</AccordionGroup>

## Amount Rule (Important)

<Warning>
  Payfonte does not support decimal amounts in API requests. Send integer minor-unit values only.
</Warning>

* `100.00 NGN` -> `10000`
* `2500.75 NGN` -> `250075`

See [Amount Specification](/en/guides/introductions/amount-specification).

## Final Status Confirmation

For order fulfillment, rely on:

1. [Webhooks](/en/guides/collections/webhook) for async payment updates.
2. `GET /payments/v1/payments/verify/{reference}` for backend verification.

## Related Docs

<CardGroup cols={3}>
  <Card title="Processing Flows" icon="bolt" href="/en/guides/collections/direct-charge/response-types">
    Understand `processing`, `redirect`, `bankTransfer`, and pre-OTP patterns.
  </Card>

  <Card title="Example Payloads" icon="code" href="/en/guides/collections/direct-charge/examples">
    Copy provider-specific request examples.
  </Card>

  <Card title="Supported Providers" icon="globe-africa" href="/en/guides/introductions/supported-providers">
    Provider slugs, limits, and country coverage.
  </Card>
</CardGroup>