Overview

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

When To Use Direct Charge

Backend-Driven Flows

Best for server-to-server payment initiation where you control the full transaction lifecycle.

Provider-Specific Inputs

Use when payment requires provider-specific fields like network or customer OTP codes.

Recurring / Embedded UX

Useful for tightly integrated experiences where redirect checkout is not preferred.

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

Pick provider slug

Select a valid provider from Supported Providers.

Fetch provider properties (optional)

For providers like Bank Transfer(bank-transfer-nigeria), fetch required properties (for example network values) before charging.

Send direct charge request

Call the direct-charge endpoint with provider, amount, and customerInput.

Handle action + confirm final status

Use response action (processing, redirect, bankTransfer) and finalize based on webhook/verification.

Fetch Provider Properties (Optional)

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:

{
  "data": {
    "networks": [
      { "name": "Airtel", "value": "airtel" },
      { "name": "MTN MoMo", "value": "mtn-momo" }
    ]
  }
}

Direct Charge Request

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:

{
  "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

processing

Customer/provider interaction is in progress (for example USSD/STK authorization pending). Keep payment state pending and wait for webhook/verification final status.

redirect

Redirect customer to provider URL (usually at data.data.link). Do not treat redirect completion alone as payment success.

bankTransfer

Display returned bank transfer instructions (account name/number, amount, expiry). Wait for webhook/verification before marking success.

Amount Rule (Important)

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

100.00 NGN -> 10000
2500.75 NGN -> 250075

See Amount Specification.

Final Status Confirmation

For order fulfillment, rely on:

Webhooks for async payment updates.
GET /payments/v1/payments/verify/{reference} for backend verification.

Processing Flows

Understand processing, redirect, bankTransfer, and pre-OTP patterns.

Example Payloads

Copy provider-specific request examples.

Supported Providers

Provider slugs, limits, and country coverage.

Getting Started

Core Concepts

Providers & Coverage

Development

Collect Payment

Disbursements

When To Use Direct Charge

Backend-Driven Flows

Provider-Specific Inputs

Recurring / Embedded UX

Endpoints

Integration Steps

Fetch Provider Properties (Optional)

Direct Charge Request

Request Fields

Action Types and Handling

Amount Rule (Important)

Final Status Confirmation

Processing Flows

Example Payloads

Supported Providers

​When To Use Direct Charge

Backend-Driven Flows

Provider-Specific Inputs

Recurring / Embedded UX

​Endpoints

​Integration Steps

​Fetch Provider Properties (Optional)

​Direct Charge Request

​Request Fields

​Action Types and Handling

​Amount Rule (Important)

​Final Status Confirmation

​Related Docs

Processing Flows

Example Payloads

Supported Providers

When To Use Direct Charge

Endpoints

Integration Steps

Fetch Provider Properties (Optional)

Direct Charge Request

Request Fields

Action Types and Handling

Amount Rule (Important)

Final Status Confirmation

Related Docs