Initiate

Genel Bakış

ClearTX sisteminde yeni bir işlem başlatır. Bu endpoint, travel rule uyumluluğunda farklı kullanım senaryoları için tasarlanmış üç farklı protokolü destekler: MAIN, BASIC ve NOTIFY.

İşlem durumlarının tümü ve geçişleri için Transactions sayfasına bakın.

Endpoint

POST /v1/transactions/initiate

İstek Gövdesi

Parametreler

Parameter	Tür	Gerekli	Açıklama
transactionAsset	string	Evet	Varlık tanımlayıcısı (ör. "ETH-USDT", "BTC-BTC")
transactionAssetDecimals	integer	Evet	Ondalık basamak sayısı (Bkz. Notlar)
transactionAmount	string	Evet	String olarak transaction tutarı
protocol	string	Evet	Protokol tipi: "MAIN", "BASIC" veya "NOTIFY"
beneficiaryVASPid	string	MAIN/BASIC: Hayır / NOTIFY: Evet	Beneficiary KVHS'ın UUID'si
beneficiaryVASPdid	string	MAIN/BASIC: Evet / NOTIFY: Hayır	Beneficiary KVHS'ın DID'i
transactionBlockchainInfo	object	Evet	Blockchain işlem detayları
transactionBlockchainInfo.origin	string	Opsiyonel	Origin blockchain adresi
transactionBlockchainInfo.destination	string	Evet	Destination blockchain adresi
transactionBlockchainInfo.txHash	string	Opsiyonel	İşlemin blockchain hash'i (broadcast sonrasında sağlanabilir)
notificationEmail	string	NOTIFY: Evet / Diğerleri: Kullanılmaz	Bildirim e-postası (sadece NOTIFY)
pii	object	Evet	Kişisel Tanımlanabilir Bilgi, zorunluluğu protokole bağlıdır

JSON Şeması

{
  "transactionAsset": "string",
  "transactionAssetDecimals": "integer (gönderilmezse 0 kabul edilir)",
  "transactionAmount": "string (zorunlu)",
  "protocol": "MAIN | BASIC | NOTIFY",
  "beneficiaryVASPid": "string (NOTIFY akışında zorunlu)",
  "beneficiaryVASPdid": "string (MAIN/BASIC akışlarında zorunlu)",
  "transactionBlockchainInfo": {
    "origin": "string",
    "destination": "string (zorunlu)",
    "txHash": "string"
  },
  "notificationEmail": "string (sadece NOTIFY)",
  "pii": {
    "originator": {
      "accountNumber": ["string"],
      "originatorPersons": [
        {
          "naturalPerson": {
            "name": [
              {
                "nameIdentifier": [
                  {
                    "primaryIdentifier": "string (soyad)",
                    "secondaryIdentifier": "string (ad)"
                  }
                ]
              }
            ],
            "geographicAddress": [
              {
                "addressType": "string",
                "streetName": "string",
                "townName": "string",
                "country": "string",
                "buildingNumber": "string",
                "postCode": "string"
              }
            ],
            "nationalIdentification": {
              "countryOfIssue": "string",
              "nationalIdentifier": "string",
              "nationalIdentifierType": "string"
            },
            "dateAndPlaceOfBirth": {
              "dateOfBirth": "string",
              "placeOfBirth": "string"
            }
          }
        }
      ]
    },
    "beneficiary": {
      "accountNumber": ["string"],
      "beneficiaryPersons": [
        {
          "naturalPerson": {
            "name": [
              {
                "nameIdentifier": [
                  {
                    "primaryIdentifier": "string (soyad)",
                    "secondaryIdentifier": "string (ad)"
                  }
                ]
              }
            ],
            "geographicAddress": [
              {
                "addressType": "string",
                "streetName": "string",
                "townName": "string",
                "country": "string",
                "buildingNumber": "string",
                "postCode": "string"
              }
            ],
            "nationalIdentification": {
              "countryOfIssue": "string",
              "nationalIdentifier": "string",
              "nationalIdentifierType": "string"
            }
          }
        }
      ]
    }
  }
}

PII Detayları

Tüzel kişi (legalPerson) örnekleri ve tüm alan açıklamaları için PII Dokümantasyonu sayfasına bakın.

Protokol Semantikleri

MAIN

• Yalnızca temel işlem/varlık bilgileri (destination, miktar vb.) başlatmada paylaşılır.
• pii verisi sadece CONFIRM sonrasında beneficiary'ye iletilir.
• Başlatmada PII bilgisi saklanır ancak karşıya iletilmez; CONFIRM ile paylaşılır.
• beneficiaryVASPdid gönderilmesi zorunludur.

BASIC

• Tüm pii verisi başlatmada beneficiary'ye iletilir.
• beneficiaryVASPdid gönderilmesi zorunludur.

NOTIFY

• Sisteme kayıtlı olmayan borsayı bilgilendirme için; emir NOTIFY e-posta adresine bildirilir.
• notificationEmail zorunludur.
• txHash isteğe bağlıdır; ClearTX veya originator broadcast sonrasında webhook ile paylaşabilir.
• beneficiaryVASPid zorunlu, beneficiaryVASPdid isteğe bağlıdır.
• pii zorunlu.
• NOTIFY'de beneficiary'nin sisteme kayıtlı olmaması mümkündür.

Protokol Türleri

MAIN Protokolü

MAIN protokolü, beneficiary borsayı gelen bir işlem hakkında bilgilendirir. Başlangıçta yalnızca blockchain destination adresi paylaşılır; diğer tüm bilgiler onay sonrası paylaşılır.

Kullanım Senaryosu: Onay akışına sahip standart travel rule uyumluluğu.

BASIC Protokolü

BASIC protokolü, onay gerektirmeden tüm işlem bilgilerini doğrudan beneficiary borsaya gönderir.

Kullanım Senaryosu: Onay gerekmeyen durumlarda doğrudan bilgi paylaşımı.

NOTIFY Protokolü

NOTIFY protokolü, ClearTX kullanmayan borsalara blockchain işlemleri hakkında e-posta bildirimleri gönderir.

Kullanım Senaryosu: İşlemler hakkında ClearTX dışındaki borsaları bilgilendirme.

bilgi

NOTIFY protokolünde notificationEmail alanı zorunludur. Beneficiary kimlik alanları içerisinde beneficiaryVASPid zorunludur ve beneficiaryVASPdid opsiyoneldir.

İstek Örnekleri

MAIN Protokol Örneği

{
  "protocol": "MAIN",
  "transactionAsset": "BTC-BTC",
  "transactionAssetDecimals": 8,
  "transactionAmount": "0.0032",
  "beneficiaryVASPid": "ce422f07-d7ac-4da1-b808-03918d4603c8",
  "beneficiaryVASPdid": "did:web:beneficiary.example",
  "transactionBlockchainInfo": {
    "origin": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
    "destination": "1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2"
  },
  "pii": {
    "originator": {
      "accountNumber": ["ACC-ORIG-001"],
      "originatorPersons": [
        {
          "naturalPerson": {
            "name": [
              {
                "nameIdentifier": [
                  {
                    "primaryIdentifier": "Alice",
                    "secondaryIdentifier": "Johnson"
                  }
                ]
              }
            ],
            "geographicAddress": [
              {
                "addressType": "HOME",
                "streetName": "Oak Avenue",
                "townName": "Los Angeles",
                "country": "US",
                "buildingNumber": "456",
                "postCode": "90210"
              }
            ],
            "nationalIdentification": {
              "countryOfIssue": "US",
              "nationalIdentifier": "987-65-4321",
              "nationalIdentificationType": "SSN"
            }
          }
        }
      ]
    },
    "beneficiary": {
      "accountNumber": ["ACC-BEN-001"],
      "beneficiaryPersons": [
        {
          "naturalPerson": {
            "name": [
              {
                "nameIdentifier": [
                  {
                    "primaryIdentifier": "Bob",
                    "secondaryIdentifier": "Wilson"
                  }
                ]
              }
            ],
            "geographicAddress": [
              {
                "addressType": "HOME",
                "streetName": "King Street",
                "townName": "London",
                "country": "GB",
                "buildingNumber": "12",
                "postCode": "SW1A 1AA"
              }
            ],
            "nationalIdentification": {
              "countryOfIssue": "GB",
              "nationalIdentifier": "AB123456C",
              "nationalIdentificationType": "NINO"
            }
          }
        }
      ]
    }
  }
}

BASIC Protokol Örneği

{
  "transactionAsset": "ETH-USDT",
  "transactionAssetDecimals": 6,
  "transactionAmount": "100.000000",
  "beneficiaryVASPid": "ce422f07-d7ac-4da1-b808-03918d4603c8",
  "beneficiaryVASPdid": "did:web:beneficiary.example",
  "transactionBlockchainInfo": {
    "origin": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
    "destination": "0x8ba1f109551bD432803012645546eaCe3bDd2fF3"
  },
  "protocol": "BASIC",
  "pii": {
    "originator": {
      "accountNumber": ["ACC-ORIG-001"],
      "originatorPersons": [
        {
          "naturalPerson": {
            "name": [
              {
                "nameIdentifier": [
                  {
                    "primaryIdentifier": "Alice",
                    "secondaryIdentifier": "Johnson"
                  }
                ]
              }
            ],
            "geographicAddress": [
              {
                "addressType": "HOME",
                "streetName": "Oak Avenue",
                "townName": "Los Angeles",
                "country": "US",
                "buildingNumber": "456",
                "postCode": "90210"
              }
            ],
            "nationalIdentification": {
              "countryOfIssue": "US",
              "nationalIdentifier": "987-65-4321",
              "nationalIdentificationType": "SSN"
            }
          }
        }
      ]
    },
    "beneficiary": {
      "accountNumber": ["ACC-BEN-001"],
      "beneficiaryPersons": [
        {
          "naturalPerson": {
            "name": [
              {
                "nameIdentifier": [
                  {
                    "primaryIdentifier": "Bob",
                    "secondaryIdentifier": "Wilson"
                  }
                ]
              }
            ],
            "geographicAddress": [
              {
                "addressType": "HOME",
                "streetName": "King Street",
                "townName": "London",
                "country": "GB",
                "buildingNumber": "12",
                "postCode": "SW1A 1AA"
              }
            ],
            "nationalIdentification": {
              "countryOfIssue": "GB",
              "nationalIdentifier": "AB123456C",
              "nationalIdentificationType": "NINO"
            }
          }
        }
      ]
    }
  }
}

NOTIFY Protokol Örneği

{
  "transactionAsset": "BTC-BTC",
  "transactionAssetDecimals": 8,
  "transactionAmount": "0.1",
  "beneficiaryVASPid": "ce422f07-d7ac-4da1-b808-03918d4603c8",
  "transactionBlockchainInfo": {
    "origin": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
    "destination": "1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2"
  },
  "protocol": "NOTIFY",
  "notificationEmail": "[email protected]",
  "pii": {
    "originator": {
      "originatorPersons": [
        {
          "naturalPerson": {
            "name": [
              {
                "nameIdentifier": [
                  {
                    "primaryIdentifier": "Charlie",
                    "secondaryIdentifier": "Brown"
                  }
                ]
              }
            ],
            "geographicAddress": [
              {
                "addressType": "HOME",
                "streetName": "Pine Street",
                "townName": "Chicago",
                "country": "US",
                "buildingNumber": "789",
                "postCode": "60601"
              }
            ],
            "nationalIdentification": {
              "countryOfIssue": "US",
              "nationalIdentifier": "111-22-3333",
              "nationalIdentificationType": "SSN"
            }
          }
        }
      ]
    },
    "beneficiary": {
      "beneficiaryPersons": [
        {
          "naturalPerson": {
            "name": [
              {
                "nameIdentifier": [
                  {
                    "primaryIdentifier": "Diana",
                    "secondaryIdentifier": "Prince"
                  }
                ]
              }
            ],
            "geographicAddress": null,
            "nationalIdentification": {
              "countryOfIssue": "AU",
              "nationalIdentifier": "123456789",
              "nationalIdentificationType": "TFN"
            }
          }
        }
      ]
    }
  }
}

Yanıt

Başarılı Yanıt (200 OK)

Örnek Yanıt

{
  "transactionRef": "6f61b14a-60ec-4569-8ba9-b675dae62159",
  "status": "NEW",
  "protocol": "MAIN",
  "transactionAsset": "BTC-BTC",
  "transactionAmount": "0.0032",
  "beneficiaryVASPid": "ce422f07-d7ac-4da1-b808-03918d4603c8",
  "beneficiaryVASPdid": "did:web:example.com",
  "destination": "1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2"
}

Yanıt Alanları

Alan	Tür	Açıklama
transactionRef	string	Benzersiz transaction referans ID
status	string	Transaction durumu (NEW, UNTRACKED vb.)
protocol	string	İşlem için kullanılan protokol
transactionAsset	string	Varlık tanımlayıcısı
transactionAmount	string	Transaction tutarı
beneficiaryVASPid	string	Beneficiary KVHS ID
beneficiaryVASPdid	string	Beneficiary KVHS DID
destination	string	Destination blockchain adresi

Notlar

• txHash alanı NOTIFY protokolü için zorunludur.
• notificationEmail alanı yalnızca NOTIFY protokolü için zorunludur.
• PII veri yapısı, travel rule uyumluluk standartlarını takip eder.
• Tüm para tutarları, hassasiyet sorunlarını önlemek için string olarak gönderilmelidir.
• transactionAssetDecimals alanı, tutarın nasıl yorumlanacağını belirler (varlık için geçerli ondalık sayısı kullanılmalıdır).