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
- Amazon "Vor Ort aufladen"
- Onboarding
- Mindest- und Höchstbetrag pro Transaktion und Land
- Zweistufiger Saldoerhöhungsvorgang
- Einstufiger Saldoerhöhungsvorgang
- Vorgänge mit Beispielen
- Anforderungsparameter
- ValidateAccountForAmazonBalanceLoad
- Beispiel 1: Anforderung und Erfolgsantwort für Kontotyp mit Barcode
- Beispiel 2: Anforderung und Erfolgsantwort für Kontotyp mit Telefonnummer
- Beispiel 3: Anforderung und Partial_Success-Antwort für Kontotyp mit Telefonnummer
- Beispiel 4: Fehlerantwort
- Beispiel 5: Erneute Übermittlung Fehlerantwort
- Beispiel 6: Vergleich von Antworten (für Typ mit Barcode und mit Telefonnummer)
- LoadAmazonBalance
- VoidAmazonBalanceLoad
- Testdaten
- Digitale Signaturen – Signaturvorgang
- Beispiel für das Signieren von AWS V4
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:
- 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
- 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:
- 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.
- Der Kassierer gibt den Betrag in das Kassenterminal ein und bestätigt mit dem Kunden.
- 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.
- 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).
- 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:
- 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.
- Der Kassierer gibt den Betrag in das Kassenterminal ein, bestätigt mit dem Kunden und nimmt dann das Geld vom Kunden entgegen.
- Das Kassenterminal sendet eine LoadAmazonBalance-Anforderung über Ihr Netzwerk an Amazon.
- 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.
- Langform – Sie stellen für jede Transaktion spezifische Daten zum Speicherort bereit (müssen
sourceId
,institutionId
undsourceDetails
enthalten). - Kurzform – Sie geben nur die
sourceId
und dieinstitutionId
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 |
- 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:
- Langform – Ein Partner stellt für jede Transaktion spezifische Shopstandortdaten bereit (muss
sourceId
,institutionId
undsourceDetails
enthalten) - Kurzform – Ein Partner stellt nur die
sourceId
undinstitutionId
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'}"
}
}