E-commerce & Marketplaces

✅ What you can build

Accept payment from buyers in their own local currency — M-Pesa, PIX, GCash, SEPA, cards and 150+ more — hold the funds, then pay your sellers out in their currency. TransFi handles the local rails, conversion and compliance.

📘 Is this you?

• You run an online store selling to customers in several countries
• You run a marketplace where buyers pay you and you owe money to sellers
• You run a platform taking payment for services delivered by someone else

How money moves for your business

A buyer pays in their local currency. The funds land in your TransFi account, where you can hold them across currencies. When it is time to settle with a seller, you pay out from that balance — either individually as orders complete, or in a batch on your own cycle.

Buyer → your account → your seller

Flows you'll use

→ Every flow number refers to one of the thirteen on the Flow Guides page.

Your integration, end to end

1. Create the buyer as a user — POST /v3/users/individual
2. Create the payin order — POST /v3/orders with orderType: "payin", receive a payUrl
3. Send the buyer to the payment page — they pay with their local method
4. Handle the success webhook — release the goods or service
5. Register your sellers as recipients — POST /v3/recipients/individual or /business
6. Pay the seller — POST /v3/orders with orderType: "payout"

Sample call sequence

# 1 — Create the buyer
curl -X POST 'https://sandbox-api.transfi.com/v3/users/individual' \
  -H 'Authorization: Basic YOUR_BASE64_CREDENTIALS' \
  -H 'mid: YOUR_MID' \
  -H 'Content-Type: application/json' \
  -d '{
    "firstName": "Asha", "lastName": "Kamau",
    "email": "[email protected]",
    "phone": "0712345678", "phoneCode": "+254", "country": "KE"
  }'
# -> { "data": { "userId": "UX-250930062608488" } }

# 2 — Collect from the buyer
curl -X POST 'https://sandbox-api.transfi.com/v3/orders' \
  -H 'Authorization: Basic YOUR_BASE64_CREDENTIALS' \
  -H 'mid: YOUR_MID' \
  -H 'Content-Type: application/json' \
  -d '{
    "userId": "UX-250930062608488",
    "orderType": "payin",
    "purposeCode": "company_expenses",
    "partnerId": "order-1001",
    "source": { "currency": "KES", "amount": "5000",
                "paymentType": "mobile_money", "paymentCode": "MPESA" },
    "destination": { "currency": "USDT" }
  }'
# -> { "data": { "orderId": "OR-...", "payUrl": "https://..." } }

# 3 — Pay the seller once funds have settled
curl -X POST 'https://sandbox-api.transfi.com/v3/orders' \
  -H 'Authorization: Basic YOUR_BASE64_CREDENTIALS' \
  -H 'mid: YOUR_MID' \
  -H 'Content-Type: application/json' \
  -d '{
    "userId": "UX-SELLER-ID",
    "orderType": "payout",
    "purposeCode": "company_expenses",
    "partnerId": "payout-2001",
    "source": { "currency": "USDT" },
    "destination": { "currency": "PHP", "amount": "10000",
                     "paymentType": "bank_transfer" }
  }'

Set up first

• Get your credentials — including the mid header required on every call
• Configure webhooks — this is how you learn a payment succeeded
• Top up your balance — payouts draw from it, so fund it before settling with sellers

Good to know for your industry

• Let the buyer choose. Omit paymentCode and the hosted page shows every method enabled for that currency and payment type. Fetch options from List Payment Methods.
• Amount mismatches. Because a cart has a fixed price, a difference between expected and received amount needs handling in your reconciliation.
• Refunds follow a separate process — see Processing Refunds.

Go-live checklist

• Webhook endpoint live, signature verification tested
• Business verification (KYB) complete
• Sellers registered as recipients
• Balance funded for your first settlement run
• Base URL switched to https://api.transfi.com

APIs you'll use