Bu sayfada
Hızlı Başlangıç
Proje oluşturun, Sandbox'ta faturayı ve imzalı webhook'u test edin, ardından canlı kimlik bilgileri üretip ilk gerçek ana ağ ödemesini alın.
Hesap oluşturun
paymos.io üzerinden e-posta sihirli bağlantısıyla (veya Google / passkey ile) giriş yapın — parola belirlemeniz gerekmez.
Proje oluşturun
Panel → Projeler → Yeni proje sayfasını açın, projeye bir ad verin ve müşterilerinizin kullanacağı varlık-ağ çiftlerini etkinleştirin.
Test API anahtarlarınızı alın
Panel → Geliştirici → API Anahtarları bölümüne gidin ve bir test anahtarı çifti üretin:
- —Payment Key (
pk_test_…) — test faturaları oluşturmak ve fatura durumunu okumak için kullanılır - —API Secret (
sk_test_…) — HMAC-SHA256 istek imzasını hesaplamak için kullanılır (aşağıdaki uyarıya bakın)
API Secret sunucunuzdan asla çıkmaz. Başlıklarda, sorgu dizgelerinde veya istemci kodunda asla göndermeyin. Asla git'e commit etmeyin — sızarsa derhal rotasyona sokun.
Test webhook uç noktası kaydedin
Sunucunuzun webhook işleyicisini bir HTTPS adresinde yayına alın, ardından Sandbox'ta Panel → Geliştirici → Webhook'lar sayfasını açıp uç noktayı oluşturun: HTTPS geri çağırma adresini girin, Invoice kategorisini ve projenizi seçin. Yalnızca bir kez gösterilen whsec_test_… sırrını sunucunuza kopyalayın; API anahtarı çiftinden ayrıdır ve test webhook teslimatlarını imzalar.
Test faturası oluşturun
Aşağıdaki resmî sunucu SDK'larından birini kullanın. SDK isteği serileştirir, tam HMAC imzasını oluşturur, zaman damgası başlıklarını ayarlar, güvenli yeniden denemeler uygular ve tiplenmiş yanıt döndürür. Manuel imzalama ayrıca Kimlik Doğrulama sayfasında belgelenmiştir.
API_KEY_ID="pk_live_xxxxxxxxxxxx"
API_SECRET="sk_live_xxxxxxxxxxxx"
BODY='{"project_id":"prj_xxxxxxxxxxxx","amount":"100.00","currency":"USD","external_order_id":"order-123","client_id":"customer-456"}'
TS=$(date +%s)
BODY_HASH=$(printf '%s' "$BODY" | openssl dgst -sha256 -hex | sed 's/^.* //')
SIGNATURE=$(printf '%s\n%s\n%s\n%s\n%s' "$TS" POST /v1/invoices '' "$BODY_HASH" \
| openssl dgst -sha256 -hmac "$API_SECRET" -binary | base64)
curl -sS https://api.paymos.io/v1/invoices \
-H "Authorization: HMAC-SHA256 $API_KEY_ID:$SIGNATURE" \
-H "X-Request-Timestamp: $TS" \
-H "Content-Type: application/json" \
-d "$BODY"
import { Paymos, externalOrderId } from '@paymos/sdk';
const paymos = new Paymos({
apiKey: process.env.PAYMOS_API_KEY,
apiSecret: process.env.PAYMOS_API_SECRET,
});
const invoice = await paymos.invoices.create({
projectId: 'prj_xxxxxxxxxxxx',
amount: '100.00',
currency: 'USD',
externalOrderId: externalOrderId('order'),
clientId: 'customer-456',
});
console.log(invoice.invoiceId, invoice.paymentUrl);
import os
from paymos import Paymos
paymos = Paymos(
api_key=os.environ["PAYMOS_API_KEY"],
api_secret=os.environ["PAYMOS_API_SECRET"],
)
invoice = paymos.invoices.create(
project_id="prj_xxxxxxxxxxxx",
amount="100.00",
currency="USD",
external_order_id="order-123",
client_id="customer-456",
)
print(invoice["invoice_id"], invoice["payment_url"])
<?php
use Paymos\Client;
use Paymos\ClientConfig;
use Paymos\IdempotencyKey;
$paymos = new Client(new ClientConfig(
getenv('PAYMOS_API_KEY'),
getenv('PAYMOS_API_SECRET')
));
$invoice = $paymos->invoices()->create(array(
'project_id' => 'prj_xxxxxxxxxxxx',
'amount' => '100.00',
'currency' => 'USD',
'external_order_id' => IdempotencyKey::externalOrderId('order'),
'client_id' => 'customer-456',
));
echo $invoice['invoice_id'] . ' ' . $invoice['payment_url'];
package main
import (
"context"
"fmt"
"os"
paymos "github.com/Paymos-labs/go-sdk/v2"
)
func main() {
client, err := paymos.NewClient(os.Getenv("PAYMOS_API_KEY"), os.Getenv("PAYMOS_API_SECRET"))
if err != nil {
panic(err)
}
invoice, err := client.Invoices.Create(context.Background(), paymos.CreateInvoiceParams{
ProjectID: "prj_xxxxxxxxxxxx",
Amount: "100.00",
Currency: "USD",
ExternalOrderID: "order-123",
ClientID: stringPointer("customer-456"),
})
if err != nil {
panic(err)
}
fmt.Println(invoice.InvoiceID, invoice.PaymentURL)
}
func stringPointer(value string) *string { return &value }
using Paymos;
using var paymos = new PaymosClient(
Environment.GetEnvironmentVariable("PAYMOS_API_KEY")!,
Environment.GetEnvironmentVariable("PAYMOS_API_SECRET")!);
var invoice = await paymos.Invoices.CreateAsync(new CreateInvoiceRequest(
ProjectId: "prj_xxxxxxxxxxxx",
Amount: "100.00",
Currency: "USD",
ExternalOrderId: "order-123",
ClientId: "customer-456"));
Console.WriteLine($"{invoice.InvoiceId} {invoice.PaymentUrl}");
import io.paymos.CreateInvoiceRequest;
import io.paymos.Invoice;
import io.paymos.PaymosClient;
PaymosClient paymos = new PaymosClient(
System.getenv("PAYMOS_API_KEY"),
System.getenv("PAYMOS_API_SECRET"));
Invoice invoice = paymos.invoices.create(
CreateInvoiceRequest.builder()
.projectId("prj_xxxxxxxxxxxx")
.amount("100.00")
.currency("USD")
.externalOrderId("order-123")
.clientId("customer-456")
.build());
System.out.println(invoice.invoiceId() + " " + invoice.paymentUrl());
require 'paymos'
paymos = Paymos::Client.new(
api_key: ENV.fetch('PAYMOS_API_KEY'),
api_secret: ENV.fetch('PAYMOS_API_SECRET')
)
invoice = paymos.invoices.create(
project_id: 'prj_xxxxxxxxxxxx',
amount: '100.00',
currency: 'USD',
external_order_id: 'order-123',
client_id: 'customer-456'
)
puts "#{invoice.invoice_id} #{invoice.payment_url}"
use paymos::{CreateInvoiceRequest, PaymosClient};
let paymos = PaymosClient::new(
std::env::var("PAYMOS_API_KEY")?,
std::env::var("PAYMOS_API_SECRET")?,
)?;
let invoice = paymos
.invoices()
.create(&CreateInvoiceRequest {
project_id: "prj_xxxxxxxxxxxx".to_owned(),
amount: "100.00".to_owned(),
currency: "USD".to_owned(),
external_order_id: "order-123".to_owned(),
network: None,
allow_multiple_payments: None,
customer_fee_percent: None,
client_id: Some("customer-456".to_owned()),
})
.await?;
println!("{} {}", invoice.invoice_id, invoice.payment_url);
Ödeme sayfasını açın
Yanıt bir payment_url içerir. Müşterinizi oraya yönlendirin veya aynı URL'yi ?embed=true ile gömün:
{
"invoice_id": "inv_5CcyDYmMUGtzYL10q0Iimr",
"project_id": "prj_xFukZuAJZR06pLVBh3uwzv",
"status": "awaiting_client",
"is_final": false,
"is_test": true,
"payment_url": "https://checkout.paymos.io/invoice/inv_5CcyDYmMUGtzYL10q0Iimr",
"order": {
"external_id": "order-123",
"client_id": "customer-456",
"amount": "100.00",
"currency": "USD"
},
"created_at": 1743594000,
"updated_at": 1743594000,
"expires_at": 1743597600
}
Müşteri; cüzdan adresi, QR kodu ve geri sayım içeren bir ödeme sayfası görür. Projede etkin olan herhangi bir varlık + ağ ile ödeyebilir — bkz. Desteklenen Para Birimleri.
Projenin kanalı Telegram botu ise bu bağlantı müşteriyi Paymos botuna götürür. Ödeyen kişi varlığı ve ağı orada seçer, adresi ve QR kodunu alır, durumu Telegram'dan çıkmadan izler; Paymos hesabına da gerek kalmaz.
Yönlendirme modu, iframe gömme modu ve tarayıcı olayları için bkz. Barındırılan Ödeme Sayfası.
Webhook'u işleyin
Ödeme onaylandığında Paymos, kayıtlı webhook URL'nize bir POST gönderir:
{
"event_id": "evt_J7EEYeL9pZJukfj2c5OQ44",
"event_type": "invoice.paid",
"version": 1,
"occurred_at": 1739281200,
"data": {
"invoice_id": "inv_5CcyDYmMUGtzYL10q0Iimr",
"project_id": "prj_xFukZuAJZR06pLVBh3uwzv",
"status": "paid",
"is_final": true,
"is_test": false,
"payment_url": "https://checkout.paymos.io/invoice/inv_5CcyDYmMUGtzYL10q0Iimr",
"order": {
"external_id": "order-12345",
"client_id": "customer-67890",
"amount": "100.00",
"currency": "USD"
},
"payment": {
"currency": "USDT",
"network": "TRC20",
"chain_id": 728126428,
"contract_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
"expected": "50.00",
"address": "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
"exchange_rate": "2.00",
"paid": "50.00",
"remaining": "0",
"fee": "0.50",
"net": "49.50",
"transfers": [
{
"tx_hash": "abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
"amount": "50.00",
"status": "confirmed",
"created_at": 1739281020,
"confirmed_at": 1739281200,
"required_confirmations": 19,
"estimated_confirmation_at": 1739281080,
"explorer_url": "https://tronscan.org/#/transaction/abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890"
}
]
},
"expires_at": 1739284200,
"completed_at": 1739281200,
"created_at": 1739277600,
"updated_at": 1739281200
}
}
X-Webhook-Signature başlığını doğrulayın ve siparişi teslim edin.
Siparişi asla bir tarayıcı olayından (paymos:succeeded veya iframe postMessage) teslim etmeyin. Yetkili olan yalnızca imzalı sunucu taraflı webhook'tur — tarayıcı sinyalleri taklit edilebilir.
import { WebhookVerifier } from '@paymos/sdk';
const verifier = new WebhookVerifier(process.env.PAYMOS_WEBHOOK_SECRET);
// Keep the body as a Buffer until verification succeeds.
const event = verifier.constructEvent(signatureHeader, rawBody);
console.log(event.eventId, event.eventType, event.data);
import os
from paymos import WebhookVerifier
verifier = WebhookVerifier(os.environ["PAYMOS_WEBHOOK_SECRET"])
# Keep raw_body as bytes until verification succeeds.
event = verifier.construct_event(signature_header, raw_body)
print(event["event_id"], event["event_type"], event["data"])
<?php
use Paymos\Webhook\WebhookEvent;
use Paymos\Webhook\WebhookVerifier;
$verifier = new WebhookVerifier(getenv('PAYMOS_WEBHOOK_SECRET'));
// Keep $rawBody unchanged until verification succeeds.
$payload = $verifier->decodeVerifiedPayload($signatureHeader, $rawBody);
$event = new WebhookEvent($payload);
echo $event->id() . ' ' . $event->type();
package main
import (
"fmt"
"os"
"time"
paymos "github.com/Paymos-labs/go-sdk/v2"
)
type invoiceEventData struct {
InvoiceID string `json:"invoice_id"`
}
func handleWebhook(signatureHeader string, rawBody []byte) error {
verifier, err := paymos.NewWebhookVerifier(os.Getenv("PAYMOS_WEBHOOK_SECRET"), 5*time.Minute)
if err != nil {
return err
}
var event paymos.WebhookEvent[invoiceEventData]
if err := verifier.ConstructEvent(signatureHeader, rawBody, time.Now(), &event); err != nil {
return err
}
fmt.Println(event.EventID, event.EventType, event.Data.InvoiceID)
return nil
}
using Paymos;
var verifier = new WebhookVerifier(
Environment.GetEnvironmentVariable("PAYMOS_WEBHOOK_SECRET")!);
// Keep rawBody as ReadOnlySpan<byte> until verification succeeds.
var webhook = verifier.ConstructEvent<InvoiceEventData>(signatureHeader, rawBody);
Console.WriteLine($"{webhook.EventId} {webhook.EventType} {webhook.Data.InvoiceId}");
public sealed record InvoiceEventData(string InvoiceId);
import com.fasterxml.jackson.databind.JsonNode;
import io.paymos.WebhookEvent;
import io.paymos.WebhookVerifier;
import java.time.Instant;
WebhookVerifier verifier = new WebhookVerifier(System.getenv("PAYMOS_WEBHOOK_SECRET"));
// Keep rawBody as byte[] until verification succeeds.
WebhookEvent<JsonNode> event =
verifier.constructEvent(signatureHeader, rawBody, Instant.now());
System.out.println(event.eventId() + " " + event.eventType() + " " + event.data());
require 'paymos'
verifier = Paymos::WebhookVerifier.new(ENV.fetch('PAYMOS_WEBHOOK_SECRET'))
# Keep raw_body as the original String until verification succeeds.
event = verifier.construct_event(signature_header, raw_body)
puts "#{event.event_id} #{event.event_type} #{event.data}"
use paymos::{Invoice, WebhookEvent, WebhookVerifier};
let verifier = WebhookVerifier::new(std::env::var("PAYMOS_WEBHOOK_SECRET")?)?;
// Keep raw_body as &[u8] until verification succeeds.
let event: WebhookEvent<Invoice> = verifier.construct_event(signature_header, raw_body)?;
println!("{} {} {}", event.event_id, event.event_type, event.data.invoice_id);
Test ödemesini simüle edin
Test faturasını ödendi olarak işaretlemek için ödeme simülatörünü kullanın. Test faturasına gerçek varlık göndermeyin. Kayıtlı uç noktanızın imzalı olayı aldığını ve sunucunuzun siparişi teslim etmeden önce olayı whsec_test_… ile doğruladığını görün.
Production'a geçin
Sandbox isteği ve imzalı webhook çalıştıktan sonra panelde Production'a geçin. Manuel onay adımı yoktur. Ortamı değiştirmek anahtar üretmez: Panel → Geliştirici → API Anahtarları bölümünü açın ve ayrı canlı kimlik bilgileri oluşturun (pk_live_… ve sk_live_…). Canlı webhook uç noktasını ayrıca kaydedin, whsec_live_… sırrını test sırrından ayrı saklayın.
İlk gerçek ana ağ ödemenizi alın
Fatura isteğini canlı kimlik bilgileriyle tekrarlayın, dönen payment_url adresini (projenin kanalına göre ödeme sayfası ya da Paymos botu) açın ve etkin bir ana ağ üzerinden desteklenen bir varlık gönderin. Paymos transferi algılar ve gereken onaylardan sonra imzalı canlı webhook'u gönderir.
Kayıttan ilk gerçek ana ağ ödemesine kadar olağan yol yaklaşık 10 dakika sürer. Bu bir devreye alma ölçütüdür, SLA değil: onay süresi ağa, tutara ve o anki blokzincir koşullarına bağlıdır.
Sonraki adımlar
- —API Anahtarları — kimlik türleri, kapsam, yaşam döngüsü
- —Sunucu SDK'ları — sekiz dil ekosistemi için resmî istemciler
- —Barındırılan Ödeme Sayfası — yönlendirme ve iframe gömme seçenekleri
- —Test — sandbox'ta nasıl test edilir
- —Webhook'lar — imza doğrulama ve yeniden deneme politikası