Payment Intents

Payment intents let a merchant request funds from a consumer who uses FiatsendOne. The consumer approves or rejects in the app (PIN); your backend tracks status via the Partner API or webhooks.

Typical flow:

Merchant POST /payment-intents  →  Consumer sees pending request in FiatsendOne  →  Approve/Reject  →  Webhook + GET status

Create a payment intent

POST /v1/payment-intents

Field	Required	Description
amount	Yes	Positive amount string
currency	Yes	GHS, USDC, or USDT
consumer_phone	Yes	Consumer's phone in E.164 (+233...)
merchant_reference	Yes	Your idempotency key (unique per intent)
terminal_id	No	Merchant terminal identifier
description	No	Shown to consumer
metadata	No	Custom key-value data

curl -X POST https://sandbox.fiatsend.com/v1/payment-intents \
  -H "Authorization: Bearer $FIATSEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "120.00",
    "currency": "GHS",
    "consumer_phone": "+233501234567",
    "merchant_reference": "order-8842",
    "terminal_id": "FS-TERMINAL-01",
    "description": "Checkout #8842"
  }'

HTTP status	Meaning
201	New intent created
200	Same merchant_reference — existing intent returned

New intents start in pending_approval and expire after a short TTL (default ~90 seconds) unless approved.

Status values

Status	Meaning
pending_approval	Waiting for consumer action in FiatsendOne
approved	Consumer approved (may proceed to settlement)
completed	Fully settled
rejected	Consumer declined
cancelled	Merchant cancelled via API
expired	Approval window elapsed
failed	Processing failed

Merchant operations

Method	Path	Description
GET	/payment-intents/{id}	Fetch current status
POST	/payment-intents/{id}/cancel	Cancel while pending_approval

Consumer approve/reject is handled inside FiatsendOne (not via Partner API keys on the consumer device).

Webhook events

Register events such as:

• payment_intent.pending_approval
• payment_intent.approved
• payment_intent.completed
• payment_intent.rejected
• payment_intent.cancelled
• payment_intent.expired
• payment_intent.failed

See Webhooks.

Prerequisites

• Consumer must have a FiatsendOne account matching consumer_phone.
• For end-to-end testing, configure Fiatsend app ↔ Partner API internal settings (contact partners@fiatsend.com for integration support).

Related

• Withdrawals — push GHS to any MoMo number without in-app approval
• Fiatsend Console