Pikaopas

Jokainen FeitPayn API-avain on live-avain ja jokainen maksu on todellinen. Voit rekisteröityä, määrittää organisaatiosi ja lähettää yrityksesi tunnistamistiedot heti. Live-API-avaimet, maksuaikomukset, kassaistunnot ja nostot ovat käytettävissä, kun tilisi on aktivoitu: live-maksut otetaan käyttöön, kun tilisi on vahvistettu ja hyväksytty.

Esimerkeissä käytetään paikkamerkkejä kuten gp_live_YOUR_KEY ja store_YOUR_STORE_ID — älä koskaan liitä oikeita salaisuuksia koodiin.

Maksut edellyttävät aktivoitua tiliä

Vaiheet 4–9 toimivat vasta, kun tilisi on aktivoitu. Siihen asti rajapinta vastaa feature_unavailable_error -virheellä — esimerkiksi live_keys_disabled, jos yrität luoda live-avaimen. Jokainen maksu on todellinen ensimmäisestä alkaen, joten aloita pienellä summalla.

1. Luo tili. Rekisteröidy osoitteessa https://app.feitpay.com/auth/sign-up ja vahvista sähköpostisi; luo sen jälkeen organisaatio ja kauppa. Käyttöönoton tarkistuslista kertoo tarkasti, mikä estää seuraavan vaiheen.

2. Lähetä yrityksesi tunnistamistiedot. Täytä kohdassa Organisaatio → Vaatimustenmukaisuus kauppiashakemus (KYB) ja lähetä se. FeitPayn ylläpitäjät tarkastavat sen käsin; lähettäminen ei ole hyväksyntä, eikä mitään hyväksytä automaattisesti.

3. Odota aktivointia. FeitPay aktivoi tilisi live-maksuille, kun tunnistamisesi on hyväksytty ja muut live-maksujen edellytykset täyttyvät (katso Sääntelytilanne). Käyttöönoton tarkistuslista merkitsee live-tilan vaiheen valmiiksi, kun tilisi on aktivoitu.

4. Luo live-API-avain kohdassa Integrointi → API-avaimet oikeuksilla payments:write ja payments:read. Salaisuus (gp_live_…) näytetään vain kerran LIVE · tilin aktivoinnin jälkeen. Säilytä se palvelimellasi.

5. Rekisteröi webhook-päätepiste kohdassa Integrointi → Webhookit tai rajapinnan kautta. Tallenna allekirjoitussalaisuus whsec_…; se näytetään vain kerran. Rekisteröi päätepiste vaiheen 3 jälkeen: päätepisteet kuuluvat yhteen ympäristöön, ja live-tapahtumat toimitetaan vain live-tilassa rekisteröityihin päätepisteisiin.

6. Luo maksuaikomus.

   POST/v1/payment-intentslive · tilin aktivoinnin jälkeen
   curl

   curl -X POST https://api.feitpay.com/v1/payment-intents \
     -H "Authorization: Bearer gp_live_YOUR_KEY" \
     -H "Idempotency-Key: order-123" \
     -H "Content-Type: application/json" \
     -d '{
       "store_id": "store_YOUR_STORE_ID",
       "amount": "59.90",
       "currency": "EUR",
       "merchant_order_id": "order-123",
       "return_url": "https://merchant.example/thank-you"
     }'

   TypeScript

   import { FeitPay } from '@feitpay/sdk';
   
   const gp = new FeitPay({ apiKey: process.env.FEITPAY_API_KEY!, baseUrl: 'https://api.feitpay.com' });
   
   const intent = await gp.paymentIntents.create(
     {
       store_id: 'store_YOUR_STORE_ID',
       amount: '59.90',
       currency: 'EUR',
       merchant_order_id: 'order-123',
       return_url: 'https://merchant.example/thank-you',
     },
     { idempotencyKey: 'order-123' },
   );
   console.log(intent.status, intent.checkout_url);

   Go

   client, err := feitpay.New(os.Getenv("FEITPAY_API_KEY"), feitpay.WithBaseURL("https://api.feitpay.com"))
   if err != nil {
     log.Fatal(err)
   }
   intent, err := client.PaymentIntents.Create(ctx, &feitpay.PaymentIntentCreateParams{
     StoreID:         "store_YOUR_STORE_ID",
     Amount:          "59.90",
     Currency:        "EUR",
     MerchantOrderID: "order-123",
     ReturnURL:       "https://merchant.example/thank-you",
     IdempotencyKey:  "order-123",
   })

   Python

   import os
   from feitpay import FeitPay
   
   gp = FeitPay(api_key=os.environ["FEITPAY_API_KEY"], base_url="https://api.feitpay.com")
   intent = gp.payment_intents.create(
       store_id="store_YOUR_STORE_ID",
       amount="59.90",
       currency="EUR",
       merchant_order_id="order-123",
       return_url="https://merchant.example/thank-you",
       idempotency_key="order-123",
   )
   print(intent["status"], intent["checkout_url"])

   Vastaus on payment_intent, jonka status on "created" ja livemode on true ja jolla on expires_at, isännöity checkout_url osoitteessa https://checkout.feitpay.com sekä processor-objekti (name: "bitcart", custodial: true). Saman pyynnön toistaminen samalla Idempotency-Key-arvolla palauttaa saman aikomuksen. Jätä allowed_networks pois: live-maksut tarjoavat kaikki alustan hyväksymät varat, ja kenttä torjutaan koodilla allowed_networks_unsupported.

7. Asiakas maksaa isännöidyssä kassassa. Ohjaa asiakas checkout_url-osoitteeseen. Kassa avaa laskun alustan Bitcart-tilillä ja näyttää jokaiselle hyväksytylle varalle osoitteen, Bitcartin vaihtokurssilla lasketun tarkan summan ja QR-koodin. Asiakas maksaa FeitPayn lompakkoon; summa hyvitetään säilytyksessä olevaan saldoosi, kun maksu on valmis.

8. Seuraa tilakonetta. Aikomus etenee awaiting_payment → detected → confirming → confirmed, kun Bitcart ilmoittaa laskun maksetuksi, vahvistetuksi ja valmiiksi. Kassa, hallintapaneeli ja webhook-päätepisteesi näkevät samat tilat.

9. Todenna webhook ja toimita tilaus. Päätepisteesi vastaanottaa payment.confirmed-tapahtuman. Todenna allekirjoitus raa’an rungon yli (katso Webhook-allekirjoitusten todentaminen), ohita kaksoiskappaleet event_id:n perusteella ja toimita vain, kun data.fulfillable on true — tarkista vielä GET /v1/payment-intents/{id} ennen peruuttamatonta toimenpidettä.

Saldon nostaminen

Vahvistetut maksut hyvitetään säilytyksessä olevaan saldoosi (GET /v1/balances). Nostaaksesi lisää osoite kohdassa Talous → Nostot → Nosto-osoitteet (käytettävissä odotusajan jälkeen), pyydä nosto ja anna toisen organisaatiosi jäsenen hyväksyä se (oletuksena käytössä). FeitPayn ylläpitäjä tarkastaa jokaisen noston ennen kuin alustan kuuma lompakko lähettää sen. Nostot otetaan käyttöön erikseen live-maksuista; siihen asti nostopyyntö torjutaan koodilla payouts_unavailable.

Aja esimerkit

Repositoriossa on ajettavat vastaanottimet, jotka todentavat allekirjoitukset ja käsittelevät jokaisen tapahtuman vain kerran:

Esimerkki	Portti	Käynnistys
examples/node-saas	4400	FEITPAY_WEBHOOK_SECRET=whsec_… pnpm --filter @feitpay/example-node-saas start
examples/go-webhook	4401	cd examples/go-webhook && FEITPAY_WEBHOOK_SECRET=whsec_… go run .
examples/python-shop	4402	FEITPAY_WEBHOOK_SECRET=whsec_… python examples/python-shop/shop.py

Seuraavaksi

• Tutustu jokaiseen tilaan tilakoneessa.
• Katso, mitä asiakas näkee isännöidyssä kassassa.
• Lue tietoturvamalli ennen kuin suunnittelet integraatiosi.
• Lue sääntelytilanne ymmärtääksesi, mitä tilin aktivointi edellyttää.