Fiyat Servisi

Dinamik Tutarlı Tag-QR'da ödeme yapılacak tutarı, Macellan SuperApp aşağıda anlatıldığı gibi sizin hazırladığınız servise sorar ve dönen fiyata göre işlem yapar.

Macellan SuperApp Paneli üzerinden Tag-QR oluştururken fiyat tipini Dinamik seçip, hazırladığınız servisin URL adresini buraya yazabilirsiniz.

Örnek Form

Formda yazılı olan https://tag-qr.altpay.dev/get-price değerini kendi hazırladığınız URL ile değiştirmelisiniz.

Adresi yazdığınız inputun yanındaki check işaretini tıklayarak servisin doğru çalışıp çalışmadığını test edebilirsiniz.

Kullanıcı Tag-QR'ı okuttuğunda Macellan SuperApp sizin hazırladığınız servise aşağıdaki değerlerle POST sorgusu gönderir. İsteğin Macellan SuperApp'den geldiğini doğrulayabilmek için Hash Doğrulaması yapabilirsiniz.

{
  "ref_code": "0757249206",
  "user_id": "c6e87629-725c-4a1d-bbfc-ebc21cd32ae3",
  "user_phone": "905555555555",
  "order_id": "1897607390",
  "hash": "2228d897082824ca0c385755a30af6d8a692be8e"
}

Değer	Tip	Açıklama
`ref_code`	`string`	Müşteri tarafından mobil uygulamadan okutulan Tag-QR'ın referans kodu.
`user_id`	`string`	İşlem yapan müşterinin tekil kullanıcı ID'si.
`user_phone`	`string`	İşlem yapan müşterinin tekil kullanıcı telefon numarası.
`order_id`	`string`	Macellan SuperApp'in ödemeye atadığı sipariş numarası.
`hash`	`string`	Hash doğrulamasında kullanılacak değer.

Tekil kullanıcı telefon numarası firmanın ORTAK VERİ SORUMLUSU olduğunu kabul etmesi durumunda yukarıda yer olan örnekteki gibi gönderilmektedir. Aksi halde telefon numarası KVKK mevzuatı gereği maskelenmiş olarak gönderilmektedir ve kullanıcı telefon numarası tekil bir değer olarak kabul edilmemelidir.

Sonuç

Gönderilen parametreleri kullanarak tutarı belirleyip yanıt verebilir veya işlemi durdurabilirsiniz. Macellan SuperApp yanıtı JSON olarak aşağıdaki değerleri bekler.

Macellan SuperApp response status kodu 200 harici tüm durumları hata olarak kabul eder.

{
  "price": 1.12
}

Değer	Tip	Açıklama
`price`	`float`	İşlem sonunda kullanıcının bakiyesinden düşülecek tutar.

Hata Durumu

Eğer servisten hata ile dönmeniz gerekiyorsa, response status 400 göndererek ödemeyi durdurabilirsiniz.

Hata durumunda response aşağıdaki gibi olabilir.

Çıktıda user_message ve message alanları zorunlu değildir. Boş geçebilir veya objeyi çıktıya hiç yazmayabilirsiniz. Kullanıcıya mesaj göstermek istiyorsanız kullanabilirsiniz.

{
  "message": "Fail",
  "user_message": "Lütfen önce bilet alınız."
}

Değer	Tip	Açıklama
`message`	`string`	Macellan SuperApp Backend'ine göndereceğiniz mesaj.
`user_message`	`string`	Mobil uygulamada kullanıcıya göstereceğiniz mesaj.

Hash Doğrulama

Hash doğrulamanın amacı gelen isteğin Macellan SuperApp tarafından gönderildiğine emin olmaktır.

Doğrulama, istek ile beraber gelen değerleri aşağıdaki sıra ile birleştirilip sonucun sha1 hashi alınarak yapılır.

salt değişkeni Macellan SuperApp panelinden Tag-QR oluşturulurken formdaki Salt Key değeridir.

Eğer hash değeri doğru değilse response status 403 ile yanıt verebilirsiniz.

ref_code + user_id + order_id + salt

Hash Doğrulama Örnek

package main

import (
	"crypto/sha1"
	"encoding/hex"
	"strings"
)

type PriceRequest struct {
	RefCode   string `json:"ref_code"`
	Hash      string `json:"hash"`
	UserId    string `json:"user_id"`
	UserPhone string `json:"user_phone"`
	OrderId   string `json:"order_id"`
}

func hashValidator(request *PriceRequest) bool {
    sb := []string{
		request.RefCode,
		request.UserId,
		request.OrderId,
		os.Getenv("SALT"),
	}

	s := strings.Join(sb, "")

	hasher := sha1.New()
	hasher.Write([]byte(s))

	cHash := hex.EncodeToString(hasher.Sum(nil))

    return request.Hash == cHash
}

function hashValidator(): bool
{
    $request = json_decode(file_get_contents('php://input'), true);
    $salt = 'test';

    $cHash = sha1(sprintf(
            '%s%s%s%s',
            $request['ref_code'],
            $request['user_id'],
            $request['order_id'],
            $salt,
        ));

    return $request['hash'] === $cHash;
}

import { createHash } from "crypto";

interface priceRequest {
    ref_code: string;
    user_id: string;
    user_phone: string;
    order_id: string;
    hash: string;
}

function hashValidator(request: priceRequest): boolean
{
    const string: Array<string> = [
        request.ref_code,
        request.user_id,
        request.order_id,
        process.env.salt,
    ]

    const cHash: string = createHash('sha1').update(string.join('')).digest('hex')

    return request.hash == cHash
}

Akış

İstek

Sonuç

Hata Durumu

Hash Doğrulama

Hash Doğrulama Örnek

Bu sayfada