Skip to main content
POST
Initiate a Direct Payment Request
Direct pay is disabled by default on live environment; Follow the steps in the Activate Direct pay on your Live Fapshi API guide to enable direct pay in live mode.

Endpoint

POST /direct-pay Send a payment request directly to a user’s mobile device. You are responsible for building your own checkout and verifying payment status.
Direct payment transactions cannot and do not expire. Consequently, their final state is either SUCCESSFUL or FAILED.
Handle this endpoint with care; misuse can result in account suspension.
Direct Pay is not available to payment aggregators (platforms that provide checkout to multiple merchants). Activation in live mode is reviewed per use case.
No idempotency. Fapshi does not support idempotency keys and does not enforce uniqueness of externalId. Sending the same request twice creates two transactions and sends two payment prompts to the customer. If a request times out or its response is lost, do not resend it blindly; first look it up with GET /transaction/{userId}. See Transaction Handling.

Parameters

Response

  • 200 OK with JSON body containing:
    • message: success message
    • transId: transaction ID to track payment status
    • dateInitiated: date when the payment was initiated
  • Errors return 4XX with failure message.
A 200 response means the payment prompt was sent, not that the customer has paid. Track the final status with webhooks or GET /payment-status/{transId}. If the status is FAILED, the reason (insufficient funds, declined, ignored prompt, etc.) is not provided; see Failed Transactions.

Authorizations

apiuser
string
header
required
apikey
string
header
required

Body

application/json
amount
integer
required

Amount to be paid (minimum 100 XAF).

Required range: x >= 100
phone
string
required

Phone number where payment request is sent.

medium
enum<string>

Payment medium (optional).

Available options:
mobile money,
orange money
name
string

Name of the payer (optional).

email
string<email>

Email of the payer for receipts (optional).

userId
string

Internal user ID (optional).

Pattern: ^[a-zA-Z0-9\-_]{1,100}$
externalId
string

Transaction/order ID for reconciliation (optional). Not required to be unique: Fapshi does not deduplicate requests, so a repeated request creates a new transaction.

Pattern: ^[a-zA-Z0-9\-_]{1,100}$
message
string

Reason for payment (optional).

Response

Accepted

message
string

Success message

transId
string

Transaction ID for the payment.

dateInitiated
string<date>

Date when the payment was initiated.