​

Payments

​

Transaction states

AWAITING_ACCEPTANCE -> COMPLETED
AWAITING_ACCEPTANCE -> REJECTED
AWAITING_ACCEPTANCE -> EXPIRED

​

Initiate a payment

curl -X POST https://staging-switch.yourflexpay.com/api/v1/transactions \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: txn-001' \
  -d '{
	"senderTag": "alice@walletapp",
	"receiverTag": "bob@shopapp",
	"amount": 500,
	"currency": "NGN",
	"callbackUrl": "https://wallet-app.example.com/switch/callback"
  }'

​

Best practices

• Prefer qualified paytag addresses such as alice@walletapp.
• Always send an Idempotency-Key for retriable requests.
• Expect an asynchronous webhook to the receiving application.
• Do not treat initiation as settlement; settlement happens after acceptance.

​

Accept a transaction

• marks the transaction as COMPLETED
• debits the sender wallet
• credits the receiver wallet
• writes immutable ledger entries
• sends the sender callback asynchronously

​

Reject a transaction

​

Expiry behavior

​

Settlement finality

​

Related topics

• Webhooks
• Errors