Guthaben an Standorten mit Geschäfts- und Verkaufsräumen erhalten


Guthaben an Standorten mit Geschäfts- und Verkaufsräumen erhalten

Stellen Sie sicher, dass Sie Ihr Amazon Incentives-API-Konto einrichten, bevor Sie mit der Integration beginnen. Schritte zum Onboarding bei Amazon "Vor Ort aufladen"


Amazon Balance Load (ABL) besteht aus einer Reihe von Systemen, mit denen Sie Guthaben direkt auf den Amazon-Geschenkgutschein-Saldo eines Kunden laden können, solange sich der Kunde als aktiver Amazon-Kunde ausweisen kann.

Amazon Balance Load (ABL) besteht aus einer Reihe von Systemen, mit denen Sie Guthaben direkt auf den Amazon-Geschenkgutschein-Saldo eines Kunden laden können, solange sich der Kunde als aktiver Amazon-Kunde ausweisen kann. Amazon "Vor Ort aufladen" verwendet den Amazon Balance Load-Service, damit ein Kunde in einem realen Einzelhandelsgeschäft (mit Geschäfts- und Verkaufsräumen) in Ihrem Netzwerk Guthaben auf sein Amazon-Geschenkgutschein-Saldo laden kann, indem er einen Barcode oder eine Mobiltelefonnummer zur Identifizierung des Amazon-Kundenkontos bereitstellt. Wenn kein aktives Amazon-Konto gefunden werden kann, kann ein Kunde einen Amazon-Einlösungscode für Geschenkgutscheine auf einer gedruckten Quittung erhalten, die er später einlösen kann, wenn Ihre Implementierung dies zulässt.

Integration in Amazon Balance Load

Sie können synchrone Anforderungen an diese Vorgangsendpunkte stellen, indem Sie die Höhe des Guthabens angeben, die sie laden möchten. Vorgänge reagieren auf jede Anforderung mit einem Status, der den Erfolg oder Fehler des Vorgangs angibt.

Diese APIs stehen Partnern zur Verfügung, die eine vertragliche Vereinbarung mit Amazon abschließen, um eine Lösung (in der Regel ein Point of Sale-System) zu erstellen, mit der Gelder in den Geschenkgutscheinsaldo eines Amazon-Kunden geladen werden können.

Amazon "Vor Ort aufladen"

Land Servicename
Vereinigte Staaten von Amerika, Mexiko, Japan, Kanada Amazon Cash
Großbritannien, Vereinigte Arabische Emirate Top up in store
Italien Ricarica in cassa
Frankreich Recharge près de chez vous
Spanien Recargas en tienda
Deutschland Vor Ort aufladen

Mit dem "Vor Ort aufladen"-Service (Name kann je nach Land unterschiedlich sein) können Amazon-Kunden Guthaben auf ihren Amazon-Geschenkgutschein-Saldo laden oder einen Einlösungscode für Geschenkgutscheine in Echtzeit von einem Standorte mit Geschäfts- und Verkaufsräumen erhalten. Diese Transaktion wird im Netzwerk von Standorten mit Geschäfts- und Verkaufsräumen des Vertriebspartners initiiert, die die Ladeanforderungen verarbeiten und diese Transaktionen direkt an Amazon weiterleiten.

Einem Kunden stehen zwei Methoden zur Verfügung, um sein Amazon-Konto am Standort mit Geschäfts- und Verkaufsräumen eines Partners darzustellen:

  1. Anzeigen eines von Amazon generierten personalisierten Barcodes, der mit dem Amazon-Konto des Kunden verknüpft ist (Kunden erhalten ihren Barcode für Amazon "Vor Ort aufladen" über die Amazon-App oder die Amazon-Website), oder
  2. Eingeben/Bereitstellen der Telefonnummer, die mit seinem Amazon-Konto verknüpft ist, an der Verkaufsstelle.

Hinweis: Die Unterstützung für Konto-Identifizierungsformate und andere Details kann je nach Land variieren.

Zusätzlich zur Identifizierungsmethode des Kunden (z. B. Barcode oder Telefonnummer) teilt der Kunde dem Filialpartner den Guthabenbetrag mit, den er auf sein Konto laden möchte (mindestens 5 USD und maximal 500 USD pro Aufladung in den USA). Diese Informationen werden kompiliert und dann an Amazon übermittelt, die anschließend mit einer Bestätigung oder Ablehnung der Ladeanforderung antworten. Sie können entweder einen Zweistufen- oder Einstufen-Ladeanforderungsvorgang verwenden, wie unten beschrieben.

Onboarding

Um mit der Integration zu beginnen, lesen Sie die Schritt-für-Schritt-Anleitung in den Schritten zum Onboarding bei Amazon "Vor Ort aufladen".

Wenn Sie angemeldet sind, erhalten Sie eine eindeutige Partner-ID, bei der zwischen Groß- und Kleinschreibung unterschieden wird. Ihr Code enthält diese Kennung in allen Anforderungen an die Incentives-API.

Mindest- und Höchstbetrag pro Transaktion und Land

Land Währung Minimale Transaktion Maximale Transaktion
Kanada CAD 5 C $ 500 C $
Frankreich EUR € 5 € 500
Italien EUR € 5 € 500
Japan JPY ¥ 500 ¥ 49 000
Mexiko MXN $ 100 $ 5 000
Spanien EUR € 5 € 500
Vereinigte Arabische Emirate AED 10 AED 500 AED
Vereinigtes Königreich GBP £ 5 £ 250
Vereinigte Staaten von Amerika USD 5 USD $ 500

Hinweis: Wenn Ihre Integration für ein Land gilt, das nicht aufgeführt ist, wenden Sie sich bitte an Ihren Account Manager, um die Mindest- und Höchstbelastung zu erfahren.

Zweistufiger Saldoerhöhungsvorgang

Der zweistufige Saldoerhöhungsvorgang beinhaltet die Verwendung von zwei APIs: ValidateAccountForAmazonBalanceLoad und LoadAmazonBalance. Der typische Prozess wird im Folgenden beschrieben:

  1. Shop-Kassierer scannen den Barcode von Amazon "Vor Ort aufladen" des Kunden oder gibt die Telefonnummer des Kunden ein und fragt, wie viel Geld der Kunde laden möchte.
  2. Der Kassierer gibt den Betrag in das Kassenterminal ein und bestätigt mit dem Kunden.
  3. Das Kassenterminal sendet eine ValidateAccountForAmazonBalanceLoad-Anforderung an Amazon. Amazon prüft, ob der Kunde berechtigt ist, den angeforderten Betrag in sein Amazon-Also für Geschenkgutscheine zu laden.
  4. Wenn die ValidateAccountForAmazonBalanceLoad-Antwort die Anforderung bestätigt, nimmt der Kassierer Bargeld vom Kunden entgegen. Dann sendet Kassenterminal die LoadAmazonBalance-Anforderung über das Vertriebspartnernetz an Amazon. Amazon empfiehlt keine Aktivierungen vor der Offerte (d. h. Aufruf von LoadAmazonBalance, bevor der Kassierer Geld erhalten hat).
  5. Amazon bearbeitet die Anforderung, überprüft zunächst die Berechtigung des Kunden und lädt, wenn das Amazon-Konto identifiziert werden konnte, das angeforderte Guthaben in den für Amazon-Geschenkgutscheine des Kunden. Eine Bestätigungsantwort wird gesendet. Wenn das Konto nicht berechtigt ist, wird eine Ablehnungsantwort zurückgesendet. Wenn der Kunde die Telefonnummer für den Saldoerhöhungsvorgang angibt und diese Telefonnummer keinem Amazon-Konto zugeordnet werden kann, wird der Vorgang mit einem gültigen Einlösungscode für Geschenkgutscheine antworten. In diesem Fall muss der Einlösungscode auf die Quittung gedruckt und dem Kunden übergeben werden.

Abbildung 1. Prozessdiagramm für Saldoerhöhung in zwei Schritten

Einstufiger Saldoerhöhungsvorgang

Wenn Sie nicht die Möglichkeit haben, eine ValidateAccountForAmazonBalanceLoad-Anforderung zu senden, wie in den obigen zwei Schritten beschrieben, können Sie nur die LoadAmazonBalanceLoad-Anforderung direkt verwenden. Dieser einstufige Saldoerhöhungsvorgang wird hier beschrieben:

  1. Shop-Kassierer scannen den Barcode von Amazon "Vor Ort aufladen" des Kunden oder gibt die Telefonnummer des Kunden ein und fragt, wie viel Geld der Kunde laden möchte.
  2. Der Kassierer gibt den Betrag in das Kassenterminal ein, bestätigt mit dem Kunden und nimmt dann das Geld vom Kunden entgegen.
  3. Das Kassenterminal sendet eine LoadAmazonBalance-Anforderung über Ihr Netzwerk an Amazon.
  4. Zur Bearbeitung der Anforderung prüft Amazon die Berechtigung des Kunden. Wenn Sie berechtigt sind und das Amazon-Konto identifiziert werden kann, lädt Amazon das angeforderte Guthaben in den Geschenkgutscheinsaldo des Kunden. Eine Bestätigungsantwort wird gesendet. Wenn das Konto nicht berechtigt ist, wird eine Ablehnungsantwort zurückgesendet. Wenn der Kunde eine Telefonnummer angibt, diese Telefonnummer jedoch keinem Amazon-Konto zugeordnet werden kann, antwortet der Vorgang mit einem gültigen Einlösungscode für Geschenkgutscheine. In diesem Fall muss der Einlösungscode auf der Quittung ausgedruckt und dem Kunden übergeben werden.

Abbildung 2. Prozessdiagramm für Saldoerhöhung in Shops in einem Schritt

Vorgänge mit Beispielen

API Beschreibung
ValidateAccountForAmazonBalanceLoad Prüft, ob das Amazon-Konto eines Kunden mit LoadAmazonBalance und anderen Schecks verwendet werden kann.
LoadAmazonBalance Lädt Guthaben in den Amazon-Geschenkgutscheinsaldo eines Kunden. Wenn das Amazon-Konto nicht abgeglichen werden kann, wird ein Einlösungscode für Geschenkgutscheine ausgegeben, den der Kunde später online einlösen kann.
VoidAmazonBalanceLoad Annulliert eine zuvor erfolgreiche LoadAmazonBalance-Anforderung.

Anforderungsparameter

account

Der account-Parameter identifiziert einen Endkunden als aktiven Amazon-Kunden.

Dies ist eine Verbundstruktur, die aus id und type besteht.

id: Eine eindeutige Kennung, mit der Amazon das Amazon-Konto eines Kunden finden kann (bei Amazon "Vor Ort aufladen" ist die ID entweder eine Barcodenummer oder die Telefonnummer des Kunden).

Vorgänge unterstützen zwei Typwerte:

Wert Beschreibung
1 Barcode
4 Telefonnummer
2, 3 Diese Werte gelten nur für Produkte, die für Amazon "Vor Ort aufladen" nicht relevant sind und nicht verwendet werden sollten.

type: Art der Kontenkennung des Endkunden. Es unterstützt Kundenkennungen wie Barcode, Telefonnummer, E-Mail usw.


partnerId

Der Parameter partnerId ist eine eindeutige Kennung, die Amazon während des Onboarding-Prozesses bereitstellt. Dieser Wert wird vom Amazon Partner-Integrationsmanager zugewiesen und identifiziert einen Vertriebspartner eindeutig. Bei diesem Wert wird zwischen Groß- und Kleinschreibung unterschieden.


loadBalanceRequestId

Ein eindeutiger Bezeichner, den Sie generieren, um eine Anforderung darzustellen. Diesem Wert muss der partnerId-Wert vorangestellt werden. Außerdem muss weniger als 40 Zeichen lang sein.


amount

Der Parameter amount gibt das Guthaben an, die geladen werden muss. Es ist ein Verbundparameter, der aus einem Währungscode und einem Wert besteht.

  • currencyCode: ISO-4217-Währungscode.
  • value: Angeforderter Betrag. Dieses Feld ist eine ganze Zahl (Beispiel: 100,23 bedeutet 10023). In einer Währung, die keine Dezimalzahl unterstützt, ist kein Auffüllen erforderlich. Beispielsweise ist 231 Yen in Japan 231, NICHT 23100.

timestamp

UNIX UTC-Zeitstempel in Millisekunden seit 1/1/1970 00:00 UTC, als Sie die Anforderung initiiert haben.

Beispiel: 2018-08-23T15:34:43+00:00 würde als 1535038483000 dargestellt.


voidIfUsed

Boolescher Wert, der angibt, ob ein LoadAmazonBalance annulliert werden soll, auch wenn der Endkunde das Guthaben bereits (ganz oder teilweise) verwendet hat.

Anwendungsbeispiel: Wenn der Kunde bereits einen Teil seines geladenen Guthabens verwendet hat, aber eine Annullierung beantragt wird, werden wir alle verbleibenden Guthaben vom ursprünglich geladenen Betrag widerrufen.

Für den Anwendungsfall Amazon "Vor Ort aufladen" muss dieser Wert immer wahr sein.


transactionSource

Standortdaten zur Identifizierung des Standorts, an dem die Erhöhung des Amazon-Saldos erzeugt wurde. Dieser Parameter ist für das Amazon "Vor Ort laden"-Produkt erforderlich.

Dieser Parameter ist eine Kombination der folgenden Komponenten:

Komponente Beschreibung
sourceId Bezeichner einer Transaktionsquellentität (Beispiel: Shop-Nummer oder Shop-ID).
institutionId Bezeichner einer übergeordneten Entität einer Transaktionsquelle (Beispiel: Händlernummer). Wenn die übergeordnete Entität nicht vorhanden ist, kopieren Sie sourceId.
sourceDetails Zeichenfolge, um weitere Informationen zur Transaktionsquelle bereitzustellen.

Der sourceDetails-Wert muss den institutionName-Schlüssel mit dem Wert als Name der Quelle enthalten (z. B. Händlername). Weitere Informationen wie Quellstandort, Telefonnummer usw. sollten enthalten sein.

Der Wert institutionName erscheint in der E-Mail über hinzugefügtes Guthaben in diesem Satz: "Ihrem Amazon-Saldo wurde Guthaben bei institutionName hinzugefügt."

Es gibt zwei Möglichkeiten zum Senden von Lagerstandortdaten von Amazon.

  1. Langform – Sie stellen für jede Transaktion spezifische Daten zum Speicherort bereit (müssen sourceId, institutionId und sourceDetails enthalten).
  2. Kurzform – Sie geben nur die sourceId und die institutionId in der API-Anforderung an. Eine separate Standortzuordnungsdatei muss gesendet werden, damit Amazon die Daten analysieren kann.

Anweisungen zur Standortzuordnungsdatei.

Hinweis: Die sourceDetails müssen wie in diesem Beispiel als JSON-Blob formatiert sein:

"transactionSource":{
      "sourceId":"558978547",
      "institutionId":"97263700008",
  "sourceDetails":"{\"institutionName\" : \"Fred Meyer\", \"institutionParentCompany\" : \"Kroger\", \"address1\" : \"2041 148th Ave NE\", \"address2\" : \"\", \"city\" : \"Bellevue\", \"state\" : \"Washington\", \"zip\" : \"98007\", \"phoneNumber\" : \"+14258658560\"}"
   }

Weitere Beispiele für transactionSource finden Sie unter Transaktionsquelle mit Geschäfts- und Verkaufsräumen.

Kontotyp mit Barcode

Voraussetzungen

Zur Integration in das Amazon "Vor Ort aufladen"-Produkt und Unterstützung des Kontotyps 1 (barcodebasiert) muss Ihr Kassensystem über Barcode-Scanner verfügen, die Barcodes auf Mobiltelefonen scannen und 1D-Barcodes im Format Code 128 unterstützen.

Barcode-Format

Amazon verwendet seinen eigenen Produktcode und IIN für die Erstellung des Barcodes. Der Amazon-Strichcode ist 30 Ziffern lang und besteht aus:

  • 11-stellige UPC
  • 13-stellige EAN oder JAN
  • 6-stellige IIN
  • 12-stellige PAN
  • 1-stellige Prüfsumme

Amazon verwendet den LUHN-Algorithmus, um die Prüfsummenziffer zu generieren, und der Algorithmus wird auf die IIN + PAN angewendet.

Hier finden Sie den Produktcode von Amazon (UPC/EAN/JAN) und IIN sowie ein Barcode-Beispiel. Beachten Sie, dass der Produktcode je nach Land unterschiedlich ist.

Produktcode (UPC 11, EAN 13, JAN 13)

Land Beispiel-Produktcode
Vereinigte Staaten von Amerika 85143200701
Kanada 85143200702
Mexiko 85143200703
Vereinigtes Königreich 85143200704
Deutschland 1230000042413
Frankreich 1230000042512
Italien 85143200707
Spanien 1230000042727
Japan 4582274041003
  1. Globale Kennnummer der ausgebenden Einrichtung (IIN): 608574

Abbildung 3.1a Barcode-Beispiel: 30 Ziffern

Abbildung 4.1b Barcode-Beispiel: 32 Ziffern

Kontotyp mit Telefonnummer

Voraussetzungen

Die Telefonnummer ist ein weiterer unterstützter Kontotyp (Typ 4). Zur Integration in das Amazon "Vor Ort aufladen"-Produkt und Unterstützung des Kontotyps für Telefonnummer muss Ihr Kassensystem es einem Betreiber ermöglichen, Telefonnummern einzugeben und eine Quittung mit dynamischem Einlösungscode auszudrucken. In bestimmten Szenarien muss die Amazon "Vor Ort aufladen"-Transaktion einen Papierbeleg zurückgeben, die einen dynamischen Einlösungscode enthält, den der Kunde später online verwenden kann, um sein Konto gutschreiben zu können.

Telefonnummernformat

Die Eingabe der Telefonnummer muss einem der folgenden Formate entsprechen:

Format Beschreibung
E.164-Format E.164 ist der internationale Telefonnummerierungsplan, der sicherstellt, dass jedes Gerät im PSTN (öffentliche Fernsprechvermittlungsnetz) über eine weltweit eindeutige Nummer verfügt.
Lokales Nummernformat Streng numerisch, d. h. es darf keine Bindestriche, Leerzeichen oder Paranthese (-, ' ', oder ()) enthalten. Die Nummer muss eine gültige Ortsnummer sein und die Ortsvorwahl enthalten. Beispiel: In den USA wäre eine gültige lokale Nummer 10 Ziffern lang, also etwa 2066231234.

E.164-Nummern können maximal fünfzehn Ziffern haben und folgendermaßen formatiert sein:

[+] [country code] [subscriber number including area code]   

Beispiel: +14155552671 (US-Nummer), +442071838750 (GB-Nummer).

Wir ziehen es vor, dass Sie uns Telefonnummern im E.164-Format übermitteln.

Hinweis: Derzeit unterstützen wir nur die Verwendung einer lokalen Telefonnummer im entsprechenden Land, in dem die Transaktion stattfindet. Wenn ein Kunde also versucht, eine mexikanische Telefonnummer an einem US-Kiosk/Geschäft zu verwenden, wird die Transaktion an der Kasse abgelehnt.

Beleganforderungen

Die Anforderungen für Belege unterscheiden sich je nach der Fähigkeit des Kassensystems, den Inhalt zu ändern, je nachdem, ob der LoadAmazonBalance-Aufruf zur telefonformfaktorbasierten Erhöhung das Guthaben auf das Konto des Kunden (verifizierte Telefonnummer) angewendet hat oder einen Einlösungscode (nicht überprüfte Telefonnummer) ausgestellt hat.

Szenario Sollte der Einlösungscode auf der Quittung erscheinen? Anweisungstext (wenn Kasse den Quittungstext ändern kann)
Verifizierte Telefonnummer Nein.
(Guthaben wird automatisch auf das Konto des Kunden gutgeschrieben. Die LoadAmazonBalance-Antwort enthält keinen Einlösungscode.)
Guthaben wurde Ihrem Amazon-Saldo hinzugefügt.
Amazon "Vor Ort aufladen"-Transaktionen sind nicht erstattungsfähig, sofern dies nicht gesetzlich vorgeschrieben ist. Bewahren Sie diese Quittung auf, bis Sie die Bestätigung erhalten, dass Ihr Guthaben Ihrem Amazon-Saldo hinzugefügt wurde. Es gelten weitere Einschränkungen. Die vollständigen Geschäftsbedingungen finden Sie unter www.amazon.com/gc-legal.
Nicht überprüfte Telefonnummer Ja.
(LoadAmazonBalance gibt einen Einlösungscode aus)
Einlösungscode: AR7E-VJTKKU-TFJ
Ihre Transaktion ist nicht abgeschlossen. Guthaben wird erst hinzugefügt, wenn Sie zu www.amazon.com/gc/redeem wechseln und den auf dieser Quittung gedruckten Einlösungscode eingeben, um Guthaben zu Ihrem Amazon-Saldo hinzuzufügen.
Amazon "Vor Ort aufladen"-Transaktionen sind nicht erstattungsfähig, sofern dies nicht gesetzlich vorgeschrieben ist. Es gelten weitere Einschränkungen. Die vollständigen Geschäftsbedingungen finden Sie unter www.amazon.com/gc-legal.
Gültiger Barcode Nein.
(Guthaben wird automatisch auf das Konto des Kunden gutgeschrieben. LoadAmazonBalance-Antwort enthält keinen Einlösungscode)
Guthaben wurde Ihrem Amazon-Saldo hinzugefügt.
Ungültiger Barcode Nein.
(Transaktion schlägt fehl. Die LoadAmazonBalance-Antwort enthält keinen Einlösungscode.)
(Es muss keine Quittung gedruckt werden, oder es muss eine Quittung zu einer fehlgeschlagenen Transaktion muss gedruckt werden.)

Standardanleitungstext

Wenn das Kassensystem den Beleginhalt nicht ändern kann, sollte dieser Text erscheinen:

    Halten Sie an dieser Quittung fest, bis Sie die Bestätigung erhalten, dass Ihrem Amazon-Saldo Guthaben hinzugefügt wurde. Wenn das Guthaben nicht automatisch auf Ihr Konto angewendet wurde, können Sie unter www.amazon.de/gc/redeem die Transaktion abschließen. Amazon "Vor Ort aufladen"-Transaktionen sind nicht erstattungsfähig, sofern dies nicht gesetzlich vorgeschrieben ist. Es gelten weitere Einschränkungen. Die vollständigen Geschäftsbedingungen finden Sie unter www.amazon.com/gc-legal.

ValidateAccountForAmazonBalanceLoad

Der Vorgang ValidateAccountForAmazonBalanceLoad überprüft, ob der beabsichtigte Betrag innerhalb des für dieses Land zulässigen Bereichs liegt, und prüft, ob das Amazon-Konto eines Kunden für den Saldoladungsprozess berechtigt ist.

Für den Barcode-Kontotyp überprüft die Berechtigungsprüfung, ob der Barcode mit einem aktiven Amazon-Kundenkonto verknüpft ist, und ist berechtigt, Guthaben in ihrem Amazon-Geschenkgutschein-Guthaben hinzuzufügen.

Für den Telefonnummer-Kontotyp wird überprüft, ob es sich bei der angegebenen Telefonnummer um eine gültige Telefonnummer handelt. Wenn das Telefon als ein Gerät identifiziert werden kann, das mit einem Amazon-Kundenkonto verknüpft ist, validiert dies auch den Status der Kundenberechtigung. Andernfalls lehnt die Validierung die unbekannte Telefonnummer (die nicht mit einem Amazon-Kunden verknüpft ist) NICHT ab und sieht dies als gültiges Konto an. Der Vorgang reagiert in diesem Fall mit einem PARTIAL_SUCCESS. Bei solchen unbekannten Telefonnummern gibt der LoadAmazonBalance-Vorgang einen Einlösungscode für die manuelle Einlösung durch den Kunden zu einem späteren Zeitpunkt zurück.

Hinweis: Dieser Vorgang ist bevorzugt, aber KEINE Voraussetzung, um später einen erfolgreichen LoadAmazonBalance-Vorgang durchzuführen.

Anforderungsparameter

Abbildung 5 Parameter der ValidAccountForAmazonBalance-Anforderung

Erfolgsantwort, Teilerfolgsantwort

Abbildung 6 ValidAccountForAmazonBalanceLoad-Erfolgsantwort

Fehlerantwort

Diese erforderlichen Zeichenfolgen werden in ValidateAccountForAmazonBalanceLoadException angezeigt:

  • errorCode
  • errorType
  • errorMessage
  • status

    Beispiel 1: Anforderungs- und Erfolgsantwort für Barcode-Kontotyp

Anforderung

POST /ValidateAccountForAmazonBalanceLoad HTTP/1.1 accept:application/x-www-form-urlencoded; charset=UTF-8 content-type:application/x-www-form-urlencoded; charset=UTF-8 host:agcod-v2-gamma.amazon.com x-amz-date:20130910T221949Z x-amz-target:com.amazonaws.agcod.AGCODService.ValidateAccountForAmazonBalanceLoad
	Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20130910/uswest-
1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;xamz-date;x-amz-target,
Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790
Payload=

<ValidateAccountForAmazonBalanceLoadRequest>
 	<account>
 	 	<id>851432007016085741001033001453</id>
 	 	<type>1</type>
 	</account>
 	<partnerId>PartnerUS </partnerId>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
    <timestamp>1464933146000</timestamp>
 	<transactionSource>
 	 	<sourceId>12344332</sourceId>
 	 	<institutionId>A1234</institutionId>
             <sourceDetails>
                 {"institutionName":"Walgreens", "Address":"1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101", "Phone":"+12061232333"}
             </sourceDetails>
 	</transactionSource>
</ValidateAccountForAmazonBalanceLoadRequest>

Antwort

<ValidateAccountForAmazonBalanceLoadResponse>
 	<account>
 	 	<id>851432007016085741001033001453</id>
 	 	<type>1</type>
 	</account>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<status>SUCCESS</status>
</ValidateAccountForAmazonBalanceLoadResponse>  

Beispiel 2: Anforderungs- und Erfolgsantwort für ein Konto der Typs "Telefonnummer"

Anforderung

POST /ValidateAccountForAmazonBalanceLoad HTTP/1.1 accept:application/x-www-form-urlencoded; charset=UTF-8 content-type:application/x-www-form-urlencoded; charset=UTF-8 host:agcod-v2-gamma.amazon.com x-amz-date:20130910T221949Z x-amz-target:com.amazonaws.agcod.AGCODService.
ValidateAccountForAmazonBalanceLoad
Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20130910/uswest-
1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;xamz-date;x-amz-target,
Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790 Payload=
<LoadAmazonBalanceRequest>
    <account>
        <id>2061231234</id>
        <type>4</type>
    </account>
    <partnerId>PartnerUS </partnerId>
    <amount>
        <currencyCode>USD</currencyCode>
        <value>4570</value>
    </amount>
    <loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
    <timestamp>1464933146000</timestamp>
    <transactionSource>
        <sourceId>12344332</sourceId>
        <institutionId>A1234</institutionId>
        <sourceDetails>{ "institutionName": "Walgreens",
                         "Address": "1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101",
                         "Phone": "+12061232333"}
        </sourceDetails>
    </transactionSource>
</LoadAmazonBalanceRequest>

Antwort

<ValidateAccountForAmazonBalanceLoadResponse>
 	<account>
 	 	<id>+12061231234</id>
 	 	<type>4</type>
 	</account>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<status>SUCCESS</status>
</ValidateAccountForAmazonBalanceLoadResponse>  

Beispiel 3: Anforderungs- und Partial_Success-Antwort für ein Konto des Typs "Telefonnummer"

Anforderung

POST /ValidateAccountForAmazonBalanceLoad HTTP/1.1 accept:application/x-www-form-urlencoded; charset=UTF-8 content-type:application/x-www-form-urlencoded; charset=UTF-8 host:agcod-v2-gamma.amazon.com x-amz-date:20130910T221949Z x-amz-target:com.amazonaws.agcod.AGCODService.
ValidateAccountForAmazonBalanceLoad
Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20130910/uswest-
1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;xamz-date;x-amz-target,
Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790 Payload=
<ValidateAccountForAmazonBalanceLoadRequest>
 	<account>
 	 	<id>2061231235 </id>
 	 	<type>4</type>
 	</account>
 	<partnerId>PartnerUS </partnerId>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
       <timestamp>1464933146000</timestamp>
 	<transactionSource>
 	 	<sourceId>12344332</sourceId>
	 	 	<institutionId>A1234</institutionId>
             <sourceDetails>
                 {"institutionName":"Walgreens", "Address":"1234 Sample
Ave N, Unit #10, Seattle, WA, US, 98101", "Phone":"+12061232333"}
             </sourceDetails>
 	</transactionSource>
</ValidateAccountForAmazonBalanceLoadRequest>

Antwort

<ValidateAccountForAmazonBalanceLoadResponse>
 	<account>
 	 	<id>+12061231235</id>
 	 	<type>4</type>
 	</account>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<status>PARTIAL_SUCCESS</status>
</ValidateAccountForAmazonBalanceLoadResponse>  

Beispiel 4: Fehlerantwort

Fehlerantwort

<ValidateAccountForAmazonBalanceLoadException>
 	<errorCode>F200</errorCode>
 	<errorType>InvalidRequestInput</errorType>
 	<errorMessage>API request body is null/empty</errorMessage>
 	<status>FAILURE</status>
</ValidateAccountForAmazonBalanceLoadException>  

Beispiel 5: Erneutes Senden der Fehlerantwort

Fehlerantwort

<ValidateAccountForAmazonBalanceLoadException>
 	<errorCode>F400</errorCode>
 	<errorType>SystemTemporarilyUnavailable</errorType>  	<errorMessage>Amazon system is temporarily not available</errorMessage>
 	<status>RESEND</status>
</ValidateAccountForAmazonBalanceLoadException>

Ein F400-Fehler erfordert eine sorgfältige Wiederholungshandhabung, um sicherzustellen, dass keine unbeabsichtigten Auszahlungen auftreten. Siehe Fehlerbehandlung.

Beispiel 6: Vergleich der Antworten (für Barcode- und Telefonnummerntypen)

Antworten für Telefonnummerntyp (Typwert 4), wenn Telefonnummer verifiziert ist

Verifiziertes Telefon (mit Amazon-Konto verknüpftes und verifiziertes Telefon)

<ValidateAccountForAmazonBalanceLoadResponse>
    <account>
        <id>+14252134543</id>
        <type>4</type>
    </account>
    <amount>
        <currencyCode>USD</currencyCode>
        <value>4570</value>
    </amount>
    <status>SUCCESS</status>
</ValidateAccountForAmazonBalanceLoadResponse>

Nicht verifiziertes Telefon (NICHT mit Amazon-Konto verknüpftes/verifiziertes Telefon)

<ValidateAccountForAmazonBalanceLoadResponse>
    <account>
        <id>+14252134543</id>
        <type>4</type>
    </account>
    <amount>
        <currencyCode>USD</currencyCode>
        <value>4570</value>
    </amount>
    <status>SUCCESS</status>
</ValidateAccountForAmazonBalanceLoadResponse>
<ValidateAccountForAmazonBalanceLoadResponse>
    <account>
        <id>+12061231234</id>
        <type>4</type>
    </account>
    <amount>
        <currencyCode>USD</currencyCode>
        <value>4570</value>
    </amount>
    <status>PARTIAL_SUCCESS</status>
</ValidateAccountForAmazonBalanceLoadResponse>

Antworten für Barcode-Typ (Typwert 1)

Gültiger/aktiver Barcode

<ValidateAccountForAmazonBalanceLoadResponse>
    <account>
        <id>851432007016085741001033001453</id>
        <type>1</type>
    </account>
    <amount>
        <currencyCode>USD</currencyCode>
        <value>4570</value>
    </amount>
    <status>SUCCESS</status>
</ValidateAccountForAmazonBalanceLoadResponse>

Ungültiger/inaktiver Barcode

<ValidateAccountForAmazonBalanceLoadException>
    <errorCode>F200</errorCode>
    <errorType>UndefinedAccountId</errorType>
    <errorMessage>AccountId provided in request does not exist in Amazon system</errorMessage>
    <status>FAILURE</status>
</ValidateAccountForAmazonBalanceLoadException>

LoadAmazonBalance

Der LoadAmazonBalance-Vorgang lädt Guthaben auf das Amazon-Geschenkgutscheinsaldo eines Kunden oder gibt einen gültigen Einlösungscode für Geschenkgutscheine zurück (falls die angegebene Telefonnummer nicht verifiziert ist, d. h., die Telefonnummer nicht für ein Amazon-Konto verifiziert). Dieser Vorgang ist idempotent. Wenn also Amazon mehrere LoadAmazonBalance-Anforderungen mit derselben loadBalanceRequestId erhält und alle Parameter (account, partnerId, amount und transactionSource) übereinstimmen, wird dieselbe Antwort vom ersten Aufruf zurückgegeben. Die von Ihnen bereitgestellte loadBalanceRequestId kann maximal 40 Zeichen lang sein und eindeutig sein. Außerdem muss ihr Ihre partnerId vorangestellt sein.

Anforderungsparameter

Abbildung 8 Parameter von LoadBalanceRequest

Erfolgsantwort für Kontotyp mit Barcode

Abbildung 9 LoadBalanceResponse-Erfolg

Erfolgsantwort für Kontotyp mit Telefonnummer

LoadAmazonBalance-Antwortparameter

Parametername Erforderlich Einschränkungen Typ
account Ja Object
loadBalanceRequestId Ja partnerId als Präfix, max. 40 Zeichen String
amount Ja Object
status Ja String
additionalInfo Ja Object

Das Feld additionalInfo ist Text im JSON-Format und enthält Informationen wie den Einlösungscode. Details finden Sie im Beispiel.

Fehlerantwort

LoadAmazonBalanceException enthält 4 Zeichenfolgenparameter:

  • errorCode
  • errorType
  • errorMessage
  • status

Beispiel für LoadAmazonBalance-Fehlerantwort:

<LoadAmazonBalanceException>
 	<errorCode>F100 </errorCode>
 	<errorType>GeneralError</errorType>
 	<errorMessage>Amazon Internal Error</errorMessage>
 	<status>FAILURE</status>
</LoadAmazonBalanceException>

Beispiel 1: LoadAmazonBalance-Anforderungs- und Erfolgsantwort für Konto mit Barcode

Anforderung

POST /LoadAmazonBalance HTTP/1.1
accept:application/x-www-form-urlencoded; charset=UTF-8 content-type:application/x-www-form-urlencoded; charset=UTF-8 host:agcod-v2-gamma.amazon.com x-amz-date:20130910T221949Z
x-amz-target:com.amazonaws.agcod.AGCODService.LoadAmazonBalance
Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20130910/uswest-
1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;xamz-date;x-amz-target,
Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790 Payload=
<LoadAmazonBalanceRequest>
 	<account>
 	 	<id>851432007016085741001033001453</id>
 	 	<type>1</type>
 	</account>
 	<partnerId>PartnerUS </partnerId>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
 	<timestamp>1464933146000</timestamp>
 	<transactionSource>
 	 	<sourceId>12344332</sourceId>
 	 	<institutionId>A1234</institutionId>
 	 	<sourceDetails>{ "institutionName": "Walgreens",
                         "Address": "1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101",
                         "Phone": "+12061232333"}
        </sourceDetails>
 	</transactionSource>
</LoadAmazonBalanceRequest>

Antwort

<LoadAmazonBalanceResponse>
    <account>
        <id>851432007016085741001033001453</id>
        <type>1</type>
    </account>
    <amount>
        <currencyCode>USD</currencyCode>
        <value>4570</value>
    </amount>
    <status>SUCCESS</status>
    <loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
</LoadAmazonBalanceResponse>

Beispiel 2: LoadAmazonBalance-Anforderungs- und Erfolgsantwort (Konto mit Telefonnummer) mit unbekannter Telefonnummer (Einlösungscode muss manuell eingefordert werden)

Anforderung

POST /LoadAmazonBalance HTTP/1.1
accept:application/x-www-form-urlencoded; charset=UTF-8 content-type:application/x-www-form-urlencoded; charset=UTF-8 host:agcod-v2-gamma.amazon.com x-amz-date:20130910T221949Z
x-amz-target:com.amazonaws.agcod.AGCODService.LoadAmazonBalance
Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20130910/uswest-
1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;xamz-date;x-amz-target,
Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790 Payload=
<LoadAmazonBalanceRequest>
 	<account>
 	 	<id>2061231234</id>
 	 	<type>4</type>
 	</account>
 	<partnerId>PartnerUS </partnerId>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
 	<timestamp>1464933146000</timestamp>
 	<transactionSource>
 	 	<sourceId>12344332</sourceId>
 	 	<institutionId>A1234</institutionId>
 	 	<sourceDetails>{ "institutionName": "Walgreens",
                         "Address": "1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101",
                         "Phone": "+12061232333"}
        </sourceDetails>
 	</transactionSource>
</LoadAmazonBalanceRequest>

Erfolgsantwort

<LoadAmazonBalanceResponse>
 	<account>
 	 	<id>+12061231234</id>
 	 	<type>4</type>
 	</account>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<status>SUCCESS</status>
 	<loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
 	<additionalInfo>
{"claimcode":"ABCD-EFGH-JK123"}
</additionalInfo>
</LoadAmazonBalanceResponse>

Fehlerantwort

<LoadAmazonBalanceException>
 	<errorCode>F100 </errorCode>
 	<errorType>GeneralError</errorType>
 	<errorMessage>Amazon Internal Error</errorMessage>
 	<status>FAILURE</status>
</LoadAmazonBalanceException>

Beispiel 3: LoadAmazonBalance-Anforderungs- und Erfolgsantwort (Konto mit Telefonnummer) mit verifizierter Telefonnummer (Guthaben automatisch zugewiesen/eingefordert)

Anforderung

POST /LoadAmazonBalance HTTP/1.1
accept:application/x-www-form-urlencoded; charset=UTF-8 content-type:application/x-www-form-urlencoded; charset=UTF-8 host:agcod-v2-gamma.amazon.com x-amz-date:20130910T221949Z
x-amz-target:com.amazonaws.agcod.AGCODService.LoadAmazonBalance
Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20130910/uswest-
1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;xamz-date;x-amz-target,
Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790 Payload=
<LoadAmazonBalanceRequest>
 	<account>
 	 	<id>2061231234</id>
 	 	<type>4</type>
 	</account>
 	<partnerId>PartnerUS </partnerId>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
 	<timestamp>1464933146000</timestamp>
 	<transactionSource>
 	 	<sourceId>12344332</sourceId>
 	 	<institutionId>A1234</institutionId>
 	 	<sourceDetails>
{"institutionName":"Walgreens", "Address":"1234 Sample Ave N, Unit #10,
Seattle, WA, US, 98101", "Phone":"+12061232333"}
             </sourceDetails>
 	</transactionSource>
</LoadAmazonBalanceRequest>

Antwort

<LoadAmazonBalanceResponse>
 	<account>
 	 	<id>+12061231234</id>
 	 	<type>4</type>
 	</account>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<status>SUCCESS</status>
 	<loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
 	<additionalInfo>{"claimcode":"XXXX-XXXXXX-XXXX"}</additionalInfo>
</LoadAmazonBalanceResponse>

Beispiel für LoadAmazonBalance-Fehlerantwort:

Fehlerantwort

<LoadAmazonBalanceException>
 	<errorCode>F100 </errorCode>
 	<errorType>GeneralError</errorType>
 	<errorMessage>Amazon Internal Error</errorMessage>
 	<status>FAILURE</status>
</LoadAmazonBalanceException>

Beispiel für LoadAmazonBalance-Neusendeantwort:

Fehlerantwort

<LoadAmazonBalanceException>
    <errorCode>F400</errorCode>
    <errorType>SystemTemporarilyUnavailable</errorType>
    <errorMessage>Amazon system is temporarily not available</errorMessage>
    <status>RESEND</status>
</LoadAmazonBalanceException>

Zusätzliche Anforderungen an Standorte mit Geschäfts- und Verkaufsräumen

Jeder Aufruf von LoadAmazonBalance, der an einem Standort mit Geschäfts- und Verkaufsräumen stattfindet, muss Details zu dem Ort enthalten, an dem die Transaktion stattgefunden hat. Anforderungen an diese Endpunkte können ein transactionSource-Objekt enthalten, das den physischen Speicherort des Ereignisses beschreibt.

Hinweis: LoadAmazonBalance, das mit Anmelden und Empfangen verwendet wird, sollte kein transactionSource-Objekt enthalten.

Feld in transactionSource Beschreibung
sourceId Bezeichner einer Transaktionsquellentität (Beispiel: Shop-Nummer oder Shop-ID).
institutionId Bezeichner einer übergeordneten Entität einer Transaktionsquelle (Beispiel: Händlernummer). Wenn die übergeordnete Entität nicht vorhanden ist, kopieren Sie sourceId.
sourceDetails Zeichenfolge, um weitere Informationen zur Transaktionsquelle bereitzustellen. Es muss den institutionName-Schlüssel mit Wert als Name der Quelle enthalten (z. B. Händlername). Weitere Informationen wie Quellstandort, Telefonnummer usw. sollten enthalten sein.
institutionParentCompany Name der Muttergesellschaft für institutionName. Wenn es keine Muttergesellschaft gibt, sollte institutionName wiederholt werden.

Es gibt zwei Möglichkeiten zum Senden von Shopstandortdaten an Amazon:

  1. Langform – Ein Partner stellt für jede Transaktion spezifische Shopstandortdaten bereit (muss sourceId, institutionId und sourceDetails enthalten)
  2. Kurzform – Ein Partner stellt nur die sourceId und institutionId in der API-Anforderung zur Verfügung. Es muss eine separate Standortzuordnungsdatei gesendet werden, die diese Bezeichner physischen Standorten zuordnet. Anweisungen zur Standortzuordnungsdatei finden Sie in dieser Tabelle.

Ein Beispiel der Nutzlast in der "Langform" für die Transaktionsquelle im XML- und JSON-Format ist unten dargestellt. Beachten Sie, dass sourceDetails als JSON-Blob formatiert werden muss. Im JSON-Beispiel verwendet das JSON-Blob den umgekehrten Schrägstrich, um Anführungszeichen zu escapen.

Beispiel für die Langform eines XML-Hauptteils (beachten Sie, dass der sourceDetails-Wert als JSON-Blob formatiert werden muss):

<LoadAmazonBalanceRequest>
 	<account>
 	 	<id>851432007016085741001033001453</id>
 	 	<type>1</type>
 	</account>
 	<partnerId>PartnerUS </partnerId>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
 	<timestamp>1464933146</timestamp>
 	<transactionSource>
 	 	<sourceId>12344332</sourceId>
 	 	<institutionId>A1234</institutionId>
 	 	<sourceDetails>{ "institutionName": "Walgreens",
                         "Address": "1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101",
                         "Phone": "+12061232333"}
        </sourceDetails>
 	</transactionSource>
</LoadAmazonBalanceRequest>

Beispiel für die Kurzform von transactionSource im JSON-Hauptteil:

{
  "loadBalanceRequestId": "Amxx134565",
  "partnerId": "Amxx1",
  "amount": {
    "currencyCode": "USD",
    "value": 1000
  },
  "account": {
    "id": "5551112222",
    "type": "4"
  },
  "timestamp": 1574704599588,
  "transactionSource": {
    "sourceId": "12345",
    "institutionId": "A123"
  },
  "externalReference": "serviceId:123",
  "notificationDetails": {
    "notificationMessage": "Thank you for loading balance at 12345!"
  }
}

VoidAmazonBalanceLoad

Wenn ein Kassenterminal nicht garantieren kann, dass eine Anforderung erfolgreich ausgeführt wurde, z. B. wegen einer fehlenden Nachricht aufgrund von Netzwerkproblemen, muss das Kassenterminal und/oder der Vertriebspartner eine VoidAmazonBalanceLoad-Anforderung ausführen, um sicherzustellen, dass das Guthaben nicht zum Amazon-Geschenkgutschein-Saldo des Kunden hinzugefügt wird. Im Falle eines Fehlers am Kassenterminal gibt der Kassierer immer das Geld an den Endkunden zurück. Daher ist es wichtig, sicherzustellen, dass das Guthaben umgehend aus dem Amazon-Geschenkgutschein-Saldo des Kunden entfernt wird, falls Guthaben erfolgreich hinzugefügt wurde, aber die Bestätigungsnachricht nie vom Kassenterminal erhalten wurde.

Der Vorgang VoidAmazonBalanceLoad annulliert nur innerhalb von 15 Minuten nach der ursprünglichen Anforderung eine erfolgreiche LoadAmazonBalance-Anforderung. Die ursprüngliche loadBalanceRequestId, die verwendet wird, um Guthaben aus einer erfolgreichen LoadAmazonBalance-Anforderung zu laden, ist für den Annullierungsvorgang erforderlich. Die Felder currencyCode, value, sourceId und institutionId müssen mit den entsprechenden Werten übereinstimmen, die in der ursprünglichen LoadAmazonBalance-Anforderung angegeben wurden. Der Annullierungsvorgang ist idempotent.

Anforderungsparameter

Abbildung 12 Diagramm für VoidAmazonBalanceLoad-Anforderung

Erfolgsantwort

Abbildung 13: Diagramm für VoidAmazonBalanceLoad-Erfolgsantwort

Fehlerantwort

Wenn die Annullierungsanforderung fehlschlägt, wird eine VoidAmazonBalanceLoad-Ausnahme mit den folgenden Zeichenfolgenparametern zurückgegeben:

  • errorCode
  • errorType
  • errorMessage
  • status

Beispiel 1: VoidAmazonBalanceLoad-Anforderung und -Erfolgsantwort (Konto mit Barcode):

Anforderung

POST /VoidAmazonBalance HTTP/1.1
accept:application/x-www-form-urlencoded; charset=UTF-8 content-type:application/x-www-form-urlencoded; charset=UTF-8 host:agcod-v2-gamma.amazon.com x-amz-date:20130910T221949Z
x-amz-target:com.amazonaws.agcod.AGCODService.VoidAmazonBalance
Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20130910/uswest-
1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;xamz-date;x-amz-target,
Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790 Payload=
<VoidAmazonBalanceLoadRequest>
 	<account>
 	 	<id>851432007016085741001033001453</id>
 	 	<type>1</type>
 	</account>
	 	<partnerId>PartnerUS </partnerId>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
 	<timestamp>1464933146000</timestamp>
 	<transactionSource>
 	 	<sourceId>12344332</sourceId>
 	 	<institutionId>A1234</institutionId>
 	 	<SourceDetails {"institutionName“ :"Walgreens“,
"Address":"1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101",
"Phone":"+12061232333"}</sourceDetails>
 	</transactionSource>
 	<voidIfUsed>True</voidIfUsed>
</VoidAmazonBalanceLoadRequest>

Antwort

<VoidAmazonBalanceLoadResponse>
 	<account>
 	 	<id>851432007016085741001033001453</id>
 	 	<type>1</type>
 	</account>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<status>SUCCESS</status>
 	<loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
</VoidAmazonBalanceLoadResponse>

Beispiel 2: VoidAmazonBalanceLoad-Anforderung und Erfolgsantwort (Konto mit Telefonnummer):

Anforderung

POST /VoidAmazonBalance HTTP/1.1
accept:application/x-www-form-urlencoded; charset=UTF-8 content-type:application/x-www-form-urlencoded; charset=UTF-8 host:agcod-v2-gamma.amazon.com x-amz-date:20130910T221949Z
x-amz-target:com.amazonaws.agcod.AGCODService.VoidAmazonBalance
Authorization:AWS4-HMAC-SHA256
Credential=AKIAJBYCL67O6NJUNYBQ/20130910/uswest-
1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;xamz-date;x-amz-target,
Signature=6dce900ea3557473ee750dfe11489dc667366ffc8823541fadf13934e5d64790 Payload=
<VoidAmazonBalanceLoadRequest>
    <account>
        <id>7574662233</id>
        <type>4</type>
    </account>
    <partnerId>PartnerUS </partnerId>
    <amount>
        <currencyCode>USD</currencyCode>
        <value>4570</value>
    </amount>
    <loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
    <timestamp>1464933146000</timestamp>
    <transactionSource>
        <sourceId>12344332</sourceId>
        <institutionId>A1234</institutionId>
        <sourceDetails>{"institutionName":"Walgreens",
          "Address":"1234 Sample Ave N, Unit #10, Seattle, WA, US, 98101",
          "Phone":"+12061232333"}</sourceDetails>
    </transactionSource>
    <voidIfUsed>True</voidIfUsed>
</VoidAmazonBalanceLoadRequest>

Antwort

<VoidAmazonBalanceLoadResponse>
 	<account>
 	 	<id>+17574662233</id>
 	 	<type>4</type>
 	</account>
 	<amount>
 	 	<currencyCode>USD</currencyCode>
 	 	<value>4570</value>
 	</amount>
 	<status>SUCCESS</status>
 	<loadBalanceRequestId>PartnerUSrequestId1</loadBalanceRequestId>
</VoidAmazonBalanceLoadResponse>

Beispiel 3: Beispiel für VoidAmazonBalanceLoad-Fehlerantwort:

Fehlerantwort

<VoidAmazonBalanceLoadException>
    <errorCode>F200</errorCode>
    <errorType>LoadBalanceRequestIdDoesNotExist</errorType>
    <errorMessage>Balance Load with provided loadBalanceRequestId does not exist</errorMessage>
    <status>FAILURE</status>
</VoidAmazonBalanceLoadException>

Beispiel 4: Beispiel für VoidAmazonBalanceLoad-Neusendeantwort:

Fehlerantwort

<VoidAmazonBalanceLoadException>
    <errorCode>F400</errorCode>
    <errorType>SystemTemporarilyUnavailable</errorType>
    <errorMessage>Amazon system is temporarily not available</errorMessage>
    <status>RESEND</status>
</VoidAmazonBalanceLoadException>

Testdaten

Damit Tests während der Entwicklung einfacher durchgeführt werden können, haben wir Test-Konten (amazon.com) erstellt. Für die Sandbox- und Produktionsumgebungen stehen separate Konten zur Verfügung. Diese Token finden Sie unter https://s3.amazonaws.com/AGCOD/tech_spec/amazon-test-tokens.txt.

Sehen Sie sich auch Mock-Codes an, mit denen Sie testen können, wie Ihr Code häufige Anforderungsfehler handhabt.

Digitale Signaturen – Signaturvorgang

Jede Anforderung für einen Incentives-API-Vorgang muss mithilfe Ihrer Incentives-API-Sicherheitsanmeldedaten und des Signaturalgorithmus von Signature Version 4 digital signiert werden.

Beispiel für das Signieren von AWS V4

(in Region us-east-1)

Zu signierende Nutzlast:

{
  "account": {
    "id": 0360002414571003423331033001453.
    "type": "1"
  },
  "partnerId": "PartnerUS",
  "amount": {
    "currencyCode": "USD",
    "value": 4570
  },
  "loadBalanceRequestId": "PartnerUSrequestId1",
  "timestamp": 1464933146000,
  "transactionSource": {
    "sourceId": "12344332",
    "institutionId": "A1234",
    "sourceDetails": "{'name': 'Store'}"
  }
}

Nutzlast mit Hash

24921f8ae68d62e1d96fd98e33f28da3e52826f43c5fa0389bfa33817e2711a1

Kanonische Anforderung (Leerzeilen einschließen)

POST
/LoadAmazonBalance
 accept:application/json content-type:application/json host:agcod-v2-gamma.amazon.com x-amz-date:20160708T073147Z
x-amz-target:com.amazonaws.agcod.AGCODService.LoadAmazonBalance

accept;content-type;host;x-amz-date;x-amz-target
24921f8ae68d62e1d96fd98e33f28da3e52826f43c5fa0389bfa33817e2711a1

Kanonische Anforderung mit Hash

a6a2e4283152cbcc7114409dfbc3dda721663f4bb14b6e34f8e1f71c374f9c14

String to sign

AWS4-HMAC-SHA256
20160708T073147Z
20160708/us-east-1/AGCODService/aws4_request
a6a2e4283152cbcc7114409dfbc3dda721663f4bb14b6e34f8e1f71c374f9c14

Abgeleiteter Signaturschlüssel

 780860beb9efce461eaee56c38d7f904cf1b803cd9ea6f2c3402415b92af9453

Signatur

(Ihre Signatur unterscheidet sich, da Sie unterschiedliche AWS-Anmeldedaten haben.)

66bd6a9ee258bcc34b7c0084ef871f2cb734e579b26f62ffce3ca1a33c06074a  

Signierte Nutzlast

POST /LoadAmazonBalance HTTP/1.1
accept:application/json content-type:application/json host:agcod-v2-gamma.amazon.com x-amz-date:20160708T073147Z
x-amz-target:com.amazonaws.agcod.AGCODService.LoadAmazonBalance Authorization:AWS4-HMAC-SHA256 Credential=<Access Key Id used for signing>/20160708/useast-1/AGCODService/aws4_request,
SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target,
Signature=66bd6a9ee258bcc34b7c0084ef871f2cb734e579b26f62ffce3ca1a33c06074a 
{
  "account": {
    "id": "0360002414571003423331033001453",
    "type": "1"
  },
  "partnerId": "PartnerUS",
  "amount": {
    "currencyCode": "USD",
    "value": 4570
  },
  "loadBalanceRequestId": "PartnerUSrequestId1",
  "timestamp": 1464933146000,
  "transactionSource": {
    "sourceId": "12344332",
    "institutionId": "A1234",
    "sourceDetails": "{'name': 'Store'}"
  }
}