Nakit FOP (AKA Reference Number API) kılavuzu

Aşağıda dikkate alınması gereken bazı önemli kullanım alanlarının yanı sıra nakit ödeme şeklinizi uygulamak için gereken yönergeler ve API'ler yer almaktadır.

Kullanım alanları

Reference Number API'nin kullanıldığı çeşitli durumlar vardır. Bu kılavuzda iki kullanım alanı ele alınacak ve bunların uygulanmasında size yol gösterilecektir.

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

Nakit

Kullanıcı, Google'dan ürün satın almak için fiziksel bir konumda (ör. market) nakit ödeme yapabilir. Kullanıcı, işlemi tanımlamak için mağazaya gidip ödeme yapabileceği bir referans numarası oluşturur. Buna ek olarak Google, kullanıcıya satın alma işleminin nasıl tamamlanacağıyla ilgili talimatlar gösterir. İdeal olarak, kullanıcı satın alma işlemini tamamlar tamamlamaz entegrasyon uzmanı, Google'ın ürünü teslim edebilmesi için Google'ı bilgilendirir.

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

Google'ın sağlamak 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 bilgisi gönderilmesini bekler. ReferenceNumberÜcretliBildirim gönderildikten sonra işlem, entegrasyon entegratör tarafından geri alınamaz.

VAN (Sanal Hesap Numarası)

Bir kullanıcı, banka hesabıyla para ödemesi yapabilir. Google, bu numarayı ve talimatları kullanıcıya sunarak entegratörden bir Sanal Hesap Numarası ister. Kullanıcı, bu numarayı kopyalar ve aktarılacak tutara ek olarak bankacılık uygulamasına girer.

Entegratörün, aktarılan tutarın ReferenceNumberGeneration istek tutarıyla eşleştiğini doğrulaması, ardından referans numarası için ödeme yapıldığını Google'a bildirmesi gerekir.

Google, ReferenceNumberPaidNotification bilgisini aldıktan sonra ürünü teslim eder. İşlem entegrasyon uzmanı 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.

İdemli davranışı izleyin

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

Neden önemlidir?

Google, bizim tarafımızdaki eyaletin tedarikçi tarafındaki durumla aynı olduğundan emin olmak için bazı istekleri tekrar deneyebilir. Sisteminizin bunun başka bir işlem olduğunu düşünmemesi gerekir. Bu nedenle aciliyet, çok önemlidir. Bu, bir entegrasyon uzmanının daha önce başarıyla işlenmiş bir şeyi yeniden işlememesi gerektiği anlamına gelir. Böyle bir durumda, önceki yanıt gönderilmelidir.

Idempotency nasıl uygulanır?

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

Önceki yanıtınız hata ise (400 veya 500 vb.) bu isteği yeni bir istek olarak işlemeli ve tekrar kontrol etmelisiniz. Sunucunuz ilk kez kapalıysa ve yeniden denerseniz isteğin başarıyla işlenmesi için bir şans daha vermiş olursunuz.

Daha fazla bilgi edinmek için bu ayrıntılı kılavuza göz atın.

Ödeme Entegratör Hesap Kimliği'ni (PIAID) kullanma

Google ile entegrasyonlar, Google'ın farklı ticari kuruluşlarıyla entegrasyon gerektirebilir. Örneğin, Google Play bir tüzel kişi, başka bir varlık YouTube, diğeri ise Google Ads'dir. Bunlarda, bu yapılandırmaların her birini temsil eden farklı satıcı hesapları yer alır.

Google, Google'daki her tüzel kişinin her satıcı hesabıyla eşleme işlemi için Google, Ödeme Entegratörü Hesap Kimlikleri (PIAID'ler) sağlar. Nakit FOP API'sinin bir örneği için generateReferenceNumber bölümüne göz atın. Aşağıda, bu eşlemenin kullanıldığı bir örnek verilmiştir.

Google, Google'daki her tüzel kişinin her satıcı hesabıyla eşleme işlemi için Google, Ödeme Entegratörü Hesap Kimlikleri (PIAID'ler) sağlar. Nakit FOP API'sinin kullanıldığı bir örnek için generateReferenceNumber bölümüne bakın. Aşağıda, bu eşlemenin kullanıldığı bir örnek verilmiştir.


{
  "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şiniz ve satıcı hesabınız tarafından sağlanan paymentIntegratorAccountId değeridir.

Entegratörün, hizmet verilen her ülkeye göre farklı hesapları da olabilir. Bunun nedeni, çeşitli vergi yasaları ve ülkeler arasındaki 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 işler.

Havale ve ödeme işlemlerini aşağıdaki API'ler yönetir.

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 numaralı telefonu arar. İşlemi veya hesabı tanımlayan bir referans numarasıyla yanıt vermeniz beklenir. Beklenen gecikme: < 3 saniye.

Nakit işlemler için 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 kullanıcının bu referansa ödeme yapmasını engellemeyi tercih edebilir. Süresi dolan bir promosyonu örnek olarak kullanabilirsiniz. Bu isteği başarıyla yanıtladığınızda, referans numarasının ödenemediğinden emin olmanız gerekir.

Kullanıcı ödeme işlemini zaten başlattıysa (örneğin, satış noktasından bir referans numarası arama işlemi), sunucunuz istek gövdesinde bir HTTP 423 yanıtı ve ErrorResponse ile USER_ACTION_IN_PROGRESS durumuyla 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 edildikten ve işlem tamamlandıktan sonra, hizmetinizin işlemin tamamlandığına dair Google'ı bilgilendirmesi ve ürünü kullanıcıya teslim etmesi gerekir. Bu bildirim Google'a ulaştıktan sonra Google, işlemin tamamlanmış olmasını ve ayırtılamaz durumda 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şlemlerini uygulama

Belirli bir FOP için API'leri entegre ettikten sonra havale yapmaya hazırsınız demektir. Havale, tüm ödeme şekillerinde aynı şekilde çalışır.

remittanceStatementNotification

Google, bir işlemden iki gün sonra, o gün kaydettiği işlemlerin özetini içeren bir remittanceStatementNotification gönderir. Bir işlemden iki gün sonra örnek bir bildirim şu şekilde görünür:

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

JSON isteği


{
  "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 ödemesi gereken net tutarı (mikro cinsinden) görebilirsiniz. Ayrıca bu mesajda tarih ve para birimi türü de gösterilir. Faturalandırma dönemi, sırasıyla en erken ve en son işlem gününün 00:00:00.000 ve 23:59:59.999 saatlerini temsil eder.

Mutabakat (remittanceStatementDetails)

Entegratör, mutabakat için remittanceStatementNotification etkinliğine dahil edilen etkinliklerin listesini almak üzere remittanceStatementDetails etkinliğini çağırır.

Google, remittanceStatementDetails isteğine sayfalara ayrılmış bir etkinlik listesi ile yanıt verir. Toplam işlem sayısı 1.000'den fazlaysa remittanceStatementDetails birden fazla kez çağrılmalıdır. İsteklerin sırayla yapılması gerekmez ve paralelleştirilebilir.

İstek URL'si

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

Örnek istek içeriği

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

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

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

Daha fazla bilgi için remittanceStatementDetails sayfasına bakın.

acceptRemittanceStatement ve acceptRemittanceStatementWithModifications

Entegratörler bu etkinlikleri kaydettikleri etkinliklerle karşılaştırmalıdır. Herhangi bir işlem eşleşmezse 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 ücretine vergiler dahil değilse acceptRemittanceStatement numaralı telefonu arayın. Vergiler dahilse acceptRemittanceStatementWithModifications numaralı telefonu arayın.

Ücretlerde vergi olmadığında acceptRemittanceStatement yöntemi kullanılır.

Vergi eklenecekse acceptRemittanceStatementWithModifications işlevini çağırın ve 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ıyla tamamlandıktan 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 içeriği

{
  "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"
}