Nakit FOP (AKA Reference Number API) kılavuzu

Aşağıda, dikkate alınması gereken bazı önemli kullanım alanları ve nakit ödeme şeklinizi uygulamak için gereken yönergeler ve API'ler verilmiştir.

Kullanım alanları

Reference Number API'nin çeşitli kullanım şekilleri vardır. Bu kılavuzda iki kullanım alanı ele alınmakta ve bunların uygulanmasında size yol gösterilmektedir.

  • Nakit: Kullanıcı, fiziksel bir konumda nakit ödeme yapar.
  • VAN - Kullanıcı, bir Sanal Hesap Numarası'na para aktarır.

Nakit

Kullanıcılar fiziksel bir konumda (ör. market) nakit ödeme yaparak Google'dan bir ürün satın alabilir. Kullanıcı, işlemi tanımlamak için mağazaya gidip ödeme yapması için bir referans numarası oluşturur. Ayrıca Google, kullanıcıya satın alma işleminin nasıl tamamlanacağına dair talimatlar gösterir. İdeal olarak, kullanıcı satın alma işlemini tamamlar tamamlamaz entegratör Google'ı bilgilendirir ve Google'ın ürünü teslim edebilmesi sağlanır.

Google'daki irtibat kişiniz, tipik ödeme talimatlarınızın bir örneğini isteyecektir. Mesajınızı optimize etmek ve hassaslaştırmak için Google temsilcinizle birlikte çalışırsınız.

Google'ın sunmak istediği kullanıcı deneyimi, müşteri siparişinin mağazadan ayrılırken teslim edilmesidir. Google, müşterinin referans numarasını ödemesinden sonra üç dakika içinde Google'a ReferenceNumberPaidNotification bildiriminin gönderilmesini bekler. ReferenceNumberÜcretliBildirim gönderildikten sonra, işlem entegratör tarafından geri alınamaz.

VAN (Sanal Hesap Numarası)

Kullanıcı, banka hesabıyla bir ürün için ödeme yapabilir. Google, entegratörden bir Sanal Hesap Numarası talep ederek numarayı ve talimatları kullanıcıya sunar. Ardından kullanıcı, numarayı kopyalar ve transfer edilecek tutarla birlikte banka başvurusuna girer.

Entegratörün, aktarılan tutarın referenceNumberGeneration istek tutarıyla eşleştiğini doğrulaması, ardından referans numarasının ödendiğini Google'a bildirmesi gerekir.

Google, ReferenceNumberPaidNotification'i aldıktan sonra ürünü teslim eder ve işlem entegratör tarafından geri alınamaz.

Sunucularınız ile Google'ın sunucuları arasında ileti gönderme

Sunucularınız ile Google'ın sunucuları arasında (veya tam tersi) ileti gönderirken lütfen bu işlemi bu yönergelere uygun şekilde yapın.

Gelen istek - DecryptWithVendorPrivateKey(Base64UrlDecode(request))

Giden yanıt - Base64UrlEncode(EncryptWithGooglePublicKey(request))

Google isteği - Base64UrlEncode(EncryptWithGooglePublicKey(request))

Google yanıtı - DecryptWithVendorPrivateKey(Base64UrlDecode(request))

İstek ve yanıtların işlenmesini gösteren bir PGP kitaplığı ve java'daki örnek burada verilmiştir.

Eş anlamlı davranışı izle

Aciliyet, başarıyla işlenmiş herhangi bir isteği (ödeme gibi) yeniden işlemeyi denememeniz gerektiği anlamına gelir. Bunun yerine, başarılı işleme için yanıt raporlanmalıdır.

Neden önemlidir?

Google, bizim tarafımızdaki eyaletin tedarikçi tarafındaki eyaletle aynı olduğundan emin olmak için bazı talepleri yeniden deneyebilir. Sisteminiz bunun başka bir işlem olduğunu düşünmemelidir. Bu nedenle, eşitsizlik çok önemlidir. Bu, entegratörün zaten başarıyla işlenmiş bir öğeyi yeniden işlememesi gerektiği anlamına gelir. Bu durumda, bunun yerine önceki yanıt gönderilmelidir.

Boşta kalma nasıl uygulanır?

Google bir yeniden deneme gönderirse istek kimliği aynı olur, içerik aynı olur ancak zaman damgası farklı olur. Daha önce gönderdiğiniz yanıtla yanıt verin. İlk yanıtınız 200 (Başarılı) ise Google aynı yanıtı farklı bir zaman damgasıyla bekler.

Önceki yanıtınız bir hataysa (400 veya 500 vb.) bu isteği yeni bir istek olarak işleme alıp tekrar kontrol etmeniz gerekir. Bu, sunucunuz ilk kez çöktüğünde ve yeniden denemeniz, isteğin başarılı bir şekilde işlenmesi için bir şans daha vermesi açısından yararlıdır.

Daha fazla bilgi edinmek için bu ayrıntılı kılavuza bakın.

Ödeme Entegratörü Hesap Kimliğini (PIAID) kullanın

Google ile entegrasyon için Google'ın farklı tüzel kişilikleriyle entegrasyon gerekebilir. Örneğin, Google Play bir tüzel kişidir, başka bir YouTube kuruluşudur ve başka bir tüzel kişi de Google Ads'dir. Bunlar, bu yapılandırmaların her birini temsil edecek farklı satıcı hesaplarını içerir.

Google, Google'daki her varlıktan her bir satıcı hesabına eşleme için Ödeme Entegratörü Hesap Kimlikleri (PIAID'ler) sağlar. Nakit FOP API örneği için generateReferenceNumber bölümüne bakın. Bu eşlemenin kullanıldığı bir örneği burada bulabilirsiniz.

Google, Google'daki her varlıktan her bir satıcı hesabına eşleme için Ödeme Entegratörü Hesap Kimlikleri (PIAID'ler) sağlar. Nakit FOP API'sinin kullanımıyla ilgili bir örnek için generateReferenceNumber öğesine bakın. Bu eşlemenin kullanıldığı bir örneği burada bulabilirsiniz.


{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ",
    "requestTimestamp": "1502220196077"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA_USD",
  "transactionDescription": "Google - Music",
  "currencyCode": "USD",
  "amount": "2000000"
}

Vurgulanan bölüme dikkat edin. Burada gereken iki değer, Google'daki irtibat kişinizin sağladığı paymentIntegratorAccountId ve satıcı hesabınızdır.

Entegratörün, hizmet verilen her ülkeye göre farklı hesapları da olabilir. Bunun nedeni, çeşitli vergi yasaları ve ülkeden ülkeye değişen diğer farklılıklar olabilir. Bu durumda, her ülke için başka bir PIAID oluşturulabilir.

Entegre edilecek API'ler

Aşağıdaki API'ler, referans numarası oluşturma ve ödeme bildirimlerini ele alır.

Aşağıdaki API'ler, havale ve ödeme işlemlerini gerçekleştirir.

Referans numaraları oluşturmak ve Google ile anlaşmak için yukarıdaki API'lerin tümünü entegre etmeniz gerekir.

Referans numarası oluştur

Bir satın alma işlemi başlattığınızda Google, GenerateReferenceNumber'ı çağırır. Bu e-postayı yanıtlayarak işlemi veya hesabı tanımlayan bir referans numarası iletmenizi bekleriz. Beklenen gecikme 3 saniyeden azdır.

Nakit işlemlerde referans numarası en fazla 12 karakter uzunluğunda olabilir.

URL: POST https://[your basepath]/v1/generateReferenceNumber

JSON isteğinde bulun

{
"requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "cf9fde73-3735-4463-8e6e-c999fda35af6",
    "requestTimestamp": "1561678470395"
  },
  "paymentIntegratorAccountId": "Sample_Cash_Vendor_282",
  "transactionDescription": "Google Play - Tester",
  "currencyCode": "USD",
  "amount": "10000000"
}

Yanıt JSON

{
  "responseHeader": {
    "responseTimestamp": "1561678947659"
  },
  "result": "SUCCESS",
  "referenceNumber": "38a41c05-ba7b-4040-a909-4331d0b9ce46"
}

Örnek Java

`String generateReferenceNumberJson = Utils.decryptAndDecode(encodedEncryptedGenerateReferenceNumberRequest);`

GenerateReferenceNumberRequest request = gson.fromJson(generateReferenceNumberJson, GenerateReferenceNumberRequest.class);

Referans numarasını iptal et

Google, bir referans numarasını iptal etmeyi ve bunun için kullanıcının ödemeyi yapmasını engellemeyi seçebilir. Kullanım süresi sona eren bir promosyon buna örnek olarak gösterilebilir. Bu talebi başarılı bir şekilde yanıtladıktan sonra, referans numarasının ödenemeyeceğinden emin olmanız gerekir.

Kullanıcı ödeme işlemini zaten başlattıysa (örneğin, satış noktasından referans numarası aradıysa) sunucunuz bir HTTP 423 yanıtı ve istek gövdesinde USER_ACTION_IN_PROGRESS durumu ile ErrorResponse ile yanıt vermelidir.

URL: POST https://[your basepath]/v1/cancelReferenceNumber

JSON isteğinde bulun

{
"requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "51e00f16-36ba-4490-b228-0a670d202206",
    "requestTimestamp": "1561678947926"
  },
  "paymentIntegratorAccountId": "Sample_Cash_Vendor_282",
  "referenceNumber": "38a41c05-ba7b-4040-a909-4331d0b9ce46"
}

Yanıt JSON

{
  "responseHeader": {
    "responseTimestamp": "1561680406459"
  },
  "result": "SUCCESS"
}

referenceNumberPaidNotification

Ödeme kabul edilip işlem tamamlandıktan sonra hizmetinizin Google'a işlemin tamamlandığını bildirmesi ve ürünü kullanıcıya teslim etmesi gerekir. Google bu bildirimi aldıktan sonra, işlemin kesinleşmesini ve rezerve edilemez olmasını bekler.

referenceNumberPaidNotification uç nokta URL'si:


POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/referenceNumberPaidNotification/[PIAID]

JSON isteğinde bulun

{
 "requestHeader": {
    "requestTimestamp": "1561748625577",
    "requestId": "ae8e310a-92de-436a-a32c-0bd753ae4e4b",
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    }
  },
  "paymentIntegratorTransactionId": "cf9fde73-3735-4463-8e6e-c999fda35af6",
  "referenceNumber": "e4e15b5d-8154-4068-b6eb-560e2a65ac48",
  "paymentLocation": {
    "brandName": "TestMart",
    "locationId": "1234"
  },
   "paymentIntegratorAccountId": "Sample_Cash_Vendor_282",
  "paymentTimestamp": "1561748625577"
}

Yanıt JSON

{
  "responseHeader": {
    "responseTimestamp": "1561748642600"
  },
  "result": "SUCCESS"
}

Havale işlemi

Ödeme şekliniz için API'leri entegre ettikten sonra havaleye hazırsınız demektir. Havale, tüm ödeme şekillerinde aynı şekilde işler.

remittanceStatementNotification

Bir işlemden iki gün sonra Google, Google'ın o gün kaydettiği işlemlerin özetini içeren bir remittanceStatementNotification gönderir. Bir işlemden iki gün sonra aşağıdaki örnek bir bildirim gösterilir:

POST https://www.integratordomain.com/v1/remittanceStatementNotification

JSON isteğinde bulun


{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "0123434-statement-abc",
    "requestTimestamp": "1502632800000"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA_USD",
  "remittanceStatementSummary": {
    "statementDate": "1502607600000",
    "billingPeriod": {
      "startDate": "1502434800000",
      "endDate": "1502521199000",
    },
    "dateDue": "1503212400000",
    "currencyCode": "INR",
    "totalDueByIntegrator": "1076000000",
  }
}

totalDueByIntegrator eşlemesine dikkat edin. Bu satırda Entegratörün borçlu olduğu net tutarı (mikro cinsinden) görebilirsiniz. Ayrıca, bu mesajda para biriminin tarihi ve türü görünür. Fatura dönemi, sırasıyla en erken ve en son işlem günlerinin 00:00:00.000 ve 23:59:59.999'unu temsil eder.

Mutabakat (remittanceStatementDetails)

Mutabakat için entegratör, remittanceStatementBildirim'e dahil edilen etkinliklerin listesini almak için remittanceStatementDetails'i çağırır.

Google, remittanceStatementDetails isteğini sayfalara ayrılmış bir etkinlik listesiyle yanıtlar. Toplam işlem sayısı 1.000'den fazlaysa remittanceStatementDetails birden çok kez çağrılmalıdır. İsteklerin sırayla yapılması gerekmez ve paralel yapılabilir.

İstek URL'si

POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/remittanceStatementDetails

Örnek istek gövdesi

{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "statement_detail_request_139932019",
    "requestTimestamp": "1502551332087"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA_USD",
  "statementId": "0123434-statement-abc",
  "numberOfEvents": 4
}

Aşağıda, iki yakalama etkinliğini (işlemleri) açıklayan daha büyük bir yanıtın kısa snippet'i verilmiştir.

"captureEvents": [ {
    {
      "eventRequestId": "bWVyY2hhbnQgdHJhbnNhY3Rpb24gaWQ",
      "paymentIntegratorEventId": "ioj32SOIjf23oijSDfoij",
      "eventCharge": "700000000",
      "eventFee": "-28000000"
    },
    {
      "eventRequestId": "Ggghvh78200PQ3Yrpb",
      "paymentIntegratorEventId": "iasdf23dSdfijSDfoij",
      "eventCharge": "800000000",
      "eventFee": "-32000000"
    }
  }

Daha fazla bilgi edinmek için remittanceStatementDetails adresini ziyaret edin.

acceptRemittanceStatement ve acceptRemittanceStatementWithModifications

Entegratörler bu etkinlikleri, kaydettikleri etkinliklerle karşılaştırmalıdır. Eşleşmeyen işlemler veya eksik işlemler varsa daha ayrıntılı inceleme için Google ile iletişime geçin. Tüm işlemler eşleşiyorsa ve işlem ücreti vergiler içermiyorsa acceptRemittanceStatement numaralı telefonu arayın. Vergiler dahilse acceptRemittanceStatementWithModifications numaralı telefonu arayın.

Ücretlere vergi alınmadığında acceptRemittanceStatement yöntemi kullanılır.

Vergi dahil edilecekse acceptRemittanceStatementWithModifications numaralı telefonu arayıp vergi oranını tanımlayın. Vergi oranınız değişirse bu bilgiyi güncellediğinizden emin olun. acceptRemittanceStatement işlemi başarılı olduktan sonra, Google hesabına banka havalenizi başlatın.

acceptRemittanceStatement için istek URL'si

POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/acceptRemittanceStatement

Örnek istek gövdesi

{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "0123434-abc",
    "requestTimestamp": "1502545413098"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA_USD",
  "statementId": "0123434-statement-abc"
}

Örnek yanıt

{
  "responseHeader": {
    "responseTimestamp": "1519996752221"
  }
  "acceptRemittanceStatementResultCode": "SUCCESS"
}

acceptRemittanceStatementWithModifications için istek URL'si

POST https://billpaynotification.googleapis.com/secure-serving/gsp/v1/acceptRemittanceStatementWithModifications

Örnek istek gövdesi

{
  "requestHeader": {
    "protocolVersion": {
      "major": 1,
      "minor": 0,
      "revision": 0
    },
    "requestId": "0123434-abc",
    "requestTimestamp": "1502545413098"
  },
  "paymentIntegratorAccountId": "InvisiCashUSA_USD",
  "statementId": "0123434-statement-abc"
  "feeToVatModification": {
    "vatToFeeRatioInMicros": "150000"
  }
}

Örnek yanıt

{
  "responseHeader": {
    "responseTimestamp": "1519996752221"
  }
  "acceptRemittanceStatementWithModificationsResultCode": "SUCCESS"
}