API-Referenz zur Inline-Integration

Steve Matlock Annika Munz

| Inhalt | 3

Inhalt Überblick über die Inline-Integration von Bezahlen über Amazon...........................................5

Voraussetzungen................................................................................................................................................... 5 Letzte Änderungen in diesem Dokument.............................................................................................................5

Kapitel 1: API-Übersicht......................................................................................... 7

WSDL- und Schema-Dateien............................................................................................................................... 8 API-Versionierung................................................................................................................................................ 8 API-Version festlegen...............................................................................................................................8 Query-Anfragen.....................................................................................................................................................8 Struktur der GET-Anfrage........................................................................................................................8 Struktur der POST-Anfrage......................................................................................................................9 Antworten............................................................................................................................................................10 Struktur einer Erfolgsmeldung............................................................................................................... 10 Struktur einer Fehlermeldung................................................................................................................. 11 API-Endpoints im Produktivmodus........................................................................................................11 API-Endpoints in der Sandbox...............................................................................................................11 Anfragen signieren..............................................................................................................................................12 Anfragen signieren..................................................................................................................................12 Die Signatur erzeugen............................................................................................................................ 12 Beispiel einer Signaturberechnung für Anfragen...................................................................................13 Schritte zur Generierung einer Signatur.................................................................................................13

Kapitel 2: Amazon-Payments-API für Query-Anfragen.................................... 15

Allgemeine Query-Parameter............................................................................................................................. 16 Liste der Anfragefunktionen...............................................................................................................................17 CreatePurchaseContract...................................................................................................................................... 17 Beschreibung........................................................................................................................................... 17 Anfrageparameter....................................................................................................................................18 Antwortelemente..................................................................................................................................... 18 Beispiele.................................................................................................................................................. 18 GetPurchaseContract........................................................................................................................................... 19 Beschreibung........................................................................................................................................... 19 Anfrageparameter....................................................................................................................................19 Antwortelemente..................................................................................................................................... 19 Beispiele.................................................................................................................................................. 20 SetPurchaseItems.................................................................................................................................................21 Beschreibung........................................................................................................................................... 21 Anfrageparameter....................................................................................................................................21 Antwortelemente..................................................................................................................................... 26 Beispiele.................................................................................................................................................. 26 SetContractCharges............................................................................................................................................. 27 Beschreibung........................................................................................................................................... 27 Anfrageparameter....................................................................................................................................28 Antwortelemente..................................................................................................................................... 29 Beispiele.................................................................................................................................................. 29 CompletePurchaseContract................................................................................................................................. 30 Beschreibung........................................................................................................................................... 30 Anfrageparameter....................................................................................................................................30 Antwortelemente..................................................................................................................................... 31

| Inhalt | 4

Beispiele.................................................................................................................................................. 31

Kapitel 3: Fehlercodes und Beschreibungen........................................................33 HTML-Fehlercodes und Beschreibungen...........................................................................................................34 Anwendungsfehlercodes und Beschreibungen................................................................................................... 35

Überblick über die Inline-Integration von Bezahlen über Amazon Dieser Abschnitt beschreibt, wer dieses Handbuch lesen sollte und wie dieses aufgebaut ist.

Voraussetzungen Bevor Sie die Inline-Integration für Bezahlen über Amazon nutzen können, müssen Sie die folgenden Voraussetzungen erfüllen: • •

Sie müssen mit der Nutzung von Webservice-APIs vertraut sein. Sie müssen mit der Nutzung von JavaScript vertraut sein. (Es gibt verschiedene erforderliche JavaScriptCodebausteine, die Sie in Ihren Einkaufswagen-Code einfügen müssen, um die Inline-Integration durchzuführen.)

Für weitere Informationen zur Nutzung der Inline-Integration lesen Sie bitte die folgenden Handbücher: Inline Checkout Implementation Guide (PDF, englisch) Inline Checkout Widget Reference Guide (PDF, englisch)

• •

Letzte Änderungen in diesem Dokument Veröffentlichungsdatum

Änderungen

05.02.2013

Anfrageparameter auf Seite 21 aktualisiert, um "Condition" als Parameter zu enfernen

30.07.2012

Vollständige Überarbeitung und Übersetzung des Dokuments

07.04.2011

Abschnitt CompletePurchaseContract: Anfrageparameter um Informationen zur Nutzung der MerchantURL und IntegratorURL ergänzt.

15.09.2010

Abschnitt SetContractCharges hinzugefügt.

Kapitel

1

API-Übersicht Themen: • • • • •

WSDL- und Schema-Dateien API-Versionierung Query-Anfragen Antworten Anfragen signieren

| API-Übersicht | 8

WSDL- und Schema-Dateien Datei

URL

WSDL

http://amazonpayments.s3.amazonaws.com/documents/ api/2010-08-31/CheckoutByAmazonService.wsdl

Schema

http://amazonpayments.s3.amazonaws.com/documents/ api/2010-08-31/CheckoutByAmazonService.xsd

API-Versionierung Da neue Funktionen und sonstige Änderungen zu inkompatiblen API-Änderungen führen können, sind alle Aktualisierungen der "Amazon Payments"-APIs versioniert. Indem die Version in die Anfrage eingebunden wird, wird sichergestellt, dass die Clients Antworten erhalten, die sie auch verarbeiten können. Jede neue Version der API erhält eine Versionsnummer im Datumformat Jahr-Monat-Tag (die aktuelle APIVersion lautet 2010-08-31). Die Versionsnummer wird als Versionsparameter eingefügt, wenn Sie Ihre Query-API verwenden. Die Antwort, die von Amazon Payments zurückgegeben wird, wird entsprechend der Versionsnummer in der Anfrage angepasst. Die WSDL-Datei für jede unterstützte API-Version ist unter der folgenden URL verfügbar: http://amazonpayments.s3.amazonaws.com/documents// CheckoutByAmazonService.wsdl Die WSDL-Datei für die neueste Version unserer API ist unter der folgenden URL verfügbar: http://amazonpayments.s3.amazonaws.com/documents/api/2010-08-31/ CheckoutByAmazonService.wsdl

API-Version festlegen Sie müssen für alle Anfragen explizit die Version der API angeben, die Sie nutzen möchten. Indem Sie die Version angeben, stellen Sie sicher, dass der Service keine Antworten zurückgibt, die von Ihrem System nicht verarbeitet werden können. Geben Sie in Query-Anfragen den Version-Parameter an (hervorgehoben). http://payments.amazon.de/cba/api/purchasecontract/?Action= CreatePurchaseContract&AWSAccessKeyId=0GS7573JW74RZM612K0AEXAMPLE &Expires=2010-09-10T12:00:00Z&SignatureMethod=HmacSHA256&SignatureVersion=2 &Version=2010-08-31&Signature=Dqlp3Sd6ljTUA9Uf6SGtEExwUQEXAMPLE

Query-Anfragen Amazon Payments unterstützt Query-Anfragen zum Aufrufen von Aktionen des Services. Query-Anfragen sind einfache HTTPS-Anfragen, welche die GET- oder POST-Methode nutzen. Query-Anfragen müssen einen ActionParameter enthalten, um die auszführende Aktion anzuzeigen. Die Antwort besteht aus einem XML-Dokument, das einem Schema entspricht.

Struktur der GET-Anfrage "Amazon Payments"-GET-Anfragen werden als URLs dargestellt, die direkt in einem Browser genutzt werden können. Die URL enthält die folgenden Elemente: • •

Endpoint - Die Ressource, auf deren Basis die Anfrage ausgeführt wird. Aktion - Die Aktion, die Sie am Endpoint durchführen möchten, z. B. eine Nachricht senden.

| API-Übersicht | 9

•

Parameter - Beliebige Anfrageparameter

Nachfolgend sehen Sie ein Beispiel einer GET-Anfrage um einen Purchase Contract zu generieren. https://payments.amazon.de/cba/api/purchasecontract/ ?Action=CreatePurchaseContract &AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE &Version=2010-08-31 &Expires=2010-10-10T12%30A00%30A00Z &SignatureVersion=2&SignatureMethod=HmacSHA256 &Signature=lBP67vCvGlDMBQ1dofZxg8E8SUEXAMPLE Hinweis: Da die GET-Anfragen aus URLs bestehen, müssen Sie die Parameter-Werte URL-kodieren. Um eine bessere Lesbarkeit zu gewährleisten, werden die Beispiele in diesem Handbuch in geparstem Format dargestellt. In allen Beispielen in diesem Handbuch verwenden wir eine falsche Access Key ID und eine falsche Signatur, beide mit dem Zusatz EXAMPLE. Diese Signatur ist nicht funktionsfähig. Die erste Zeile enthält den Endpoint der Anfrage. Nach dem Endpoint sehen Sie ein Fragezeichen (?), das den Endpoint von den Parametern trennt. Jeder Parameter ist durch ein Und-Zeichen (&) abgetrennt. Der Action-Parameter zeigt die Aktion an, die durchgeführt werden soll (eine Liste aller Aktionen finden Sie im Abschnitt Liste der Anfragefunktionen auf Seite 17). Eine Liste der Parameter, die für alle Anfragen gelten, finden Sie unter Allgemeine Query-Parameter auf Seite 16.

Struktur der POST-Anfrage Amazon Payments akzeptiert außerdem POST-Anfragen. Mit einer POST-Anfrage senden Sie die Query-Paramater als Formular im HTTP-Request-Body wie unten beschrieben. So erzeugen Sie einen POST-Anfrage 1. Stellen Sie aus den Query-Parameter-Namen und Werten ein HTML-Formular zusammen. Das bedeutet: Stellen Sie eine Zeichenkette der Parameter und Werten zusammen, wie Sie es für eine GET-Anfrage tun würden (mit einem Und-Zeichen (&) als Trennzeichen für jedes Parameter-Werte-Paar). Nachfolgend sehen Sie eine Beispielanfrage. Die Zeilenumbrüche haben wir für eine bessere Lesbarkeit eingefügt. Action=EineFunktion &SomeTextInput=Ihre Nachricht &AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE &Version=2010-08-31 &Expires=2010-10-10T12%30A00%30A00Z &SignatureVersion=2 &SignatureMethod=HmacSHA256 2. URL-kodieren Sie diese Zeichenkette auf Basis des Abschnitts "Form Submission" der HTML-Spezifikation (für weitere Informationen lesen Sie bitte http://www.w3.org/MarkUp/html-spec/html-spec_toc.html#SEC8.2.1). Action=EineFunktion &SomeTextInput=Ihre%20Nachricht &AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE &Version=2010-08-31 &Expires=2010-10-10T12%30A00%30A00Z &SignatureVersion=2 &SignatureMethod=HmacSHA256 3. Fügen Sie die Signatur der Anfrage zum Ende der Zeichenkette hinzu. Für weitere Informationen zum Generieren der Signatur lesen Sie bitte "Query-Anfragen signieren". Action=EineFunktion &SomeTextInput=Ihre%20Nachricht

| API-Übersicht | 10

&AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE &Version=2010-08-31 &Expires=2010-10-10T12%30A00%30A00Z &SignatureVersion=2 &SignatureMethod=HmacSHA256 &Signature=lBP67vCvGlDMBQ1dofZxg8E8SUEXAMPLE 4. Stellen Sie das Ergebnis als Body der POST-Anfrage zur Verfügung. 5. Fügen Sie einen Content-Type-HTTP-Header mit dem folgenden Wert ein: application/x-www-formurlencoded Wichtig: Verwenden Sie keine mehrteilige Formulare in Ihrer POST-Anfrage, weil diese sonst fehlschlagen wird. Das folgende Beispiel zeigt eine vollständige POST-Anfrage: POST / HTTP/1.1 Host: payments.amazon.de Content-Type: application/x-www-form-urlencoded Action=EineFunktion &SomeTextInput=Ihre%20Nachricht &AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE &Version=Version=2010-08-31 &Expires=2010-10-10T12%30A00%30A00Z &SignatureVersion=2 &SignatureMethod=HmacSHA256 &Signature=lBP67vCvGlDMBQ1dofZxg8E8SUEXAMPLE Amazon Payments benötigt außer dem Content-Type keine weiteren HTTP-Header in der Anfrage. Hinweis: Ihr HTTP-Client fügt normalerweise die anderen HTTP-Header automatisch zur Anfrage hinzu. Diese zusätzlichen Header zeigen wir in den Beispielen in diesem Handbuch nicht an.

Antworten Amazon Payments gibt als Antwort auf eine Action-Anfrage eine XML-Datenstruktur zurück, die die Ergebnisse der Anfrage enhält. Diese Daten gehen mit dem "Amazon Payments"-Schema konform. Die XSD-Datei definiert die Antwort und kann von Nutzern direkt aufgerufen werden. Für weitere Informationen lesen Sie bitte WSDL- und Schema-Dateien.

Struktur einer Erfolgsmeldung Wenn die Anfage erfolgreich war, wird das Hauptantwortlement nach der Aktion benannt, allerdings mit dem Zusatz "Response" . Beispiel: CreatePurchaseContractResponse ist das Antwortlelement, das bei einer erfolgreichen CreatePurchaseContract-Anfrage zurückgegeben wird. Dieses Element enthält die folgenden Child-Elemente: • •

Ein optionales Element, das die aktionspezifischen Ergebnisse enthält, z. B. das CreatePurchaseContractResponse-Element, das ein Element namens CreatePurchaseContractResult enthält ResponseMetadata, das ein Child-Element namens RequestId enthält

Das XML-Schema beschreibt die XML-Antwort für jede "Amazon Payments"-Aktion. Nachfolgend sehen Sie ein Beispiel einer erfolgreichen Antwort. HTTP/1.1 200

| API-Übersicht | 11

amzn1.contract.1.1.2.816c4711dabbc070c2feefe2afc82420 5f89b701-a92c-11df-a44c-9b7a8313f6cb

Struktur einer Fehlermeldung Wenn eine Anfrage nicht erfolgreich war, wird immer das Hauptantwortlement ErrorResponse zurückgegeben, unabhängig von der aufgerufenen Aktion. Dieses Element enthält mindestens ein Error-Element und ein RequestId-Element. Jedes Error-Element enthält: Ein Type-Element, das anzeigt, ob der Fehler beim Sender oder Empfänger lag. Ein Code-Element, das den Fehlertyp anzeigt. Ein Message-Element, das die Fehlermeldung noch einmal in Klartext beschreibt.

• • •

Nachfolgend sehen Sie ein Beispiel einer Fehlermeldung. Sender InvalidParameterValue Value for parameter PurchaseContractID is invalid. 42d59b56-7407-4c4a-be0f-4c88daeea257

API-Endpoints im Produktivmodus Die folgende Tabelle listet die API-Endpoint-URLs auf, die für die jeweiligen Länder genutzt werden. Land

URL

DE

https://payments.amazon.de/cba/api/purchasecontract/

API-Endpoints in der Sandbox Um Ihre Integration in der Testumgebung (Sandbox) zu testen, geben Sie bitte die folgenden API-Endpoint-URL ein (abhängig vom Land): Land

URL

Deutschland

https://payments-sandbox.amazon.de/cba/api/ purchasecontract/

| API-Übersicht | 12

Anfragen signieren Anfragen signieren Sie müssen die Signatur in jeder Query-Anfrage einbinden. Dieser Abschnitt beschreibt, wie Sie eine Signatur erzeugen können. Die beschriebene Methode ist bekannt als Singatur Version 2. Vorsicht: Falls sie im Moment eine Signatur der Version 1 verwenden: Version 1 ist nicht länger gültig. Sie sollten deshalb so schnell wie möglich auf Version 2 umstellen. Weitere Informationen zur Umstellung und den Unterschieden zwischen Version 2 und Version 1 finden Sie unter Sichere "Amazon Web Service"sAnfragen.

Die Signatur erzeugen Hier sehen Sie eine kurze Zusammenfassung der Schritte, die Sie vornehmen müssen, um eine Signatur zu erzeugen. Für eine detailierte Anleitung mit Beispielen lesen Sie bitte Beispiel einer Signaturberechnung für Anfragen auf Seite 13. 1. Generieren Sie einen korrekt formatierten Query-String, den Sie später im Rahmen dieser Prozedur benötigen werden: a) Sortieren Sie die Komponenten des UTF-8-Query-Strings nach Parameter mit einer natürlichen ByteSortierung. Die Parameter können per GET URI oder durch den POST body übermittelt werden (wenn Content-Type den Wert application/x-www-form-urlencoded enthält). b) URL-kodieren Sie die Parameternamen und -Werte nach den folgenden Regeln: •

URL-kodieren Sie keine unreservierte Zeichen, die durch die RFC 3986 definiert wurden. Diese unreservierte Zeichen sind: Buchstaben von a-Z (Groß- und Kleinschreibung, ohne Umlaute oder sonstige Sonderzeichen), Zahlen von 0-9, Bindestriche (-), Unterstriche (_), Punkt (.) und Tilde (~). • Kodieren Sie alle anderen Zeichen mit einem führenden Prozentzeichen nach dem Muster %XY, wobei X und Y für die Hexadezimalcode mit Zeichen von 0-9 sowie A-F (Großbuchstaben) stehen. • Kodieren Sie erweiterte UTF-8 Zeichen in der Form %XY%ZA... • Kodieren Sie Leerzeichen als %20 (und nicht +, wie es bei allgemeinen Kodierungsschemen geschieht). c) Trennen Sie die kodierten Parameternamen von deren kodierten Werten mit dem Gleichzeichen (=; ASCIIZeichen 61), selbst wenn der Parameterwert leer ist. d) Trennen Sie die Namen-Werte-Paare mit einem Und-Zeichen (&; ASCII-Code 38). 2. Generieren Sie den zu signierenden String gemäß der folgenden Pseudo-Grammatik (das "\n" steht für eine neue Zeile): StringToSign = HTTPVerb + "\n" + ValueOfHostHeaderInLowercase + "\n" + HTTPRequestURI + "\n" + CanonicalizedQueryString Die HTTPRequestURI-Komponente ist der absolute HTTP-Pfad der URI bis zum Query-String (aber exklusive Query-String). Wenn der HTTPRequestURI leer ist, dann verwenden Sie an dieser Stelle einfach einen Slash (/). 3. Berechnen Sie eine RFC-2104-konforme HMAC mit dem String, den Sie gerade generiert haben, Ihrem Secret Access Key als Schlüssel und dem SHA256- oder SHA1-Hash-Algorithmus. Für weitere Informationen lesen Sie bitte http://www.ietf.org/rfc/rfc2104.txt. 4. Konvertieren Sie das Ergebnis in base64. 5. Nutzen Sie das Ergebnis als den Wert des Signatur-Parameters. Wichtig: Die endgültige Signatur die Sie senden muss URL-kodiert sein, wie in RFC 3986 festgelegt (für weitere Informationen lesen Sie bitte http://www.ietf.org/rfc/rfc3986.txt). Falls Ihr Toolkit Ihre endgültige Anfrage URL-kodiert, dann kann es auch die notwendige URL-Kodierung der Signatur bearbeiten. Falls Ihr Toolkit die endgültige Anfrage nicht URL-kodiert, dann stellen Sie bitte sicher, dass Sie die Signatur selbst URL-kodieren, bevor Sie diese in die Anfrage einfügen. Es ist dabei von äußerster Wichtigkeit, dass die Signatur nur einmal URL-kodiert wird. Ein häufig vorkommender Fehler ist eine doppelte URL-Kodierung

| API-Übersicht | 13

der Signatur, wenn die URL erst manuell und anschließend die gesamte Anfrage noch einmal automatisch kodiert wird.

Beispiel einer Signaturberechnung für Anfragen Action=GetPurchaseContract SignatureMethod=HmacSHA256 PurchaseContractId=amzn1.contract.1.1.2.b9173045932801221f107a83429e5a69 AWSAccessKeyId=AKIAJV6MUTXRDBNVXLJA SignatureVersion=2 Version=2010-08-31 Timestamp=2010-08-31T11:45:50.582Z

Schritte zur Generierung einer Signatur 1. Generieren Sie den korrekt formatierten Query-String. a) Sortieren Sie die Komponenten des UTF-8-Query-Strings nach Parameter mit einer natürlichen ByteSortierung. Die Parameter können per GET URI oder durch den POST body übermittelt werden (wenn Content-Type den Wert application/x-www-form-urlencoded enthält). AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE Action=GetPurchaseContract PurchaseContractId=amzn1.contract.1.1.2.b9173045932801221f107a83429e5a69 SignatureMethod=HmacSHA256 SignatureVersion=2 Timestamp=2010-08-31T11:45:50.582Z Version=2010-08-31 b) URL-kodieren Sie die Parameter-Namen und -Werte c) Trennen Sie die kodierten Parameter-Namen von deren kodierten Werten mit dem Gleichheitszeichen (=; ASCII-Zeichen 61), selbst wenn der Parameterwert leer ist. AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE Action=GetPurchaseContract PurchaseContractId=amzn1.contract.1.1.2.b9173045932801221f107a83429e5a69 SignatureMethod=HmacSHA256 SignatureVersion=2 Timestamp=2010-08-31T11%3A45%3A50.582Z Version=2010-08-31 d) Verknüpfen Sie die Parameter und trennen Sie die Namen-Werte-Paare mit einem Und-Zeichen (&; ASCIICode 38). Das Ergebnis ist ein korrekt formatierter Query-String. AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE&Action=GetPurchaseContract &PurchaseContractId=amzn1.contract.1.1.2.b9173045932801221f107a83429e5a69 &SignatureMethod=HmacSHA256&SignatureVersion=2 &Timestamp=2010-08-31T11%3A45%3A50.582Z&Version=2010-08-31 2. Generieren Sie den zu signierenden String gemäß der folgenden Grammatik (das "\n" steht für eine neue Zeile): Bereits voreingetragene Werte werden in normalem Text dargestellt. Werte, die Sie ersetzen müssen, werden kursiv dargestellt. Code

Erklärung

HTTP-Verb

Verwenden Sie ein HTTP-Verb wie "GET" oder "POST"

+ "\n" +

Neue Zeile

Hostname in Kleinbuchstaben

Zum Beispiel "payments-sandbox.amazon.de"

| API-Übersicht | 14

Code

Erklärung Beachten Sie, dass der Hostnamen aus Kleinbuchstaben besteht und dass kein Port angegeben wird, da der Standard-Port 443 verwendet wird.

+ "\n" +

Neue Zeile

HTTP Request URI

Zum Beispiel "/cba/api/purchasecontract/"

+ "\n" +

Neue Zeile

Korrekt formatierter Query-String

Siehe vorheriger Schritt

Beispiel POST payments-sandbox.amazon.de /cba/api/purchasecontract/ AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE&Action=GetPurchaseContract &PurchaseContractId=amzn1.contract.1.1.2.b9173045932801221f107a83429e5a69 &SignatureMethod=HmacSHA256&SignatureVersion=2 &Timestamp=2010-08-31T11%3A45%3A50.582Z&Version=2010-08-31 3. Berechnen Sie eine RFC-2104-conforme HMAC mit dem String, den Sie gerade generiert haben, Ihrem Secret Access Key als Schlüssel und dem SHA256- oder SHA1-Hash-Algorithmus. 4. Konvertieren Sie das Ergebnis in base64. Zum Beispiel 5nB7nu7PFbCiDg+vYyWMj1JzEH3S+IzFoVgwHGjG5Ms=

Kapitel

2

Amazon-Payments-API für Query-Anfragen Themen: • • • • • • •

Allgemeine Query-Parameter Liste der Anfragefunktionen CreatePurchaseContract GetPurchaseContract SetPurchaseItems SetContractCharges CompletePurchaseContract

| Amazon-Payments-API für Query-Anfragen | 16

Allgemeine Query-Parameter Alle Query-Funktionen enthalten allgemeine Parameter, die in jedem Aufruf verwendet werden müssen. Name Action

Beschreibung

Pflicht?

Zeigt an, welche Aktion durchgeführt Ja werden soll. Beispiel: CreatePurchaseContract

Version

Die API-Version die verwendet werden soll, wie in der WSDL festgelegt.

Ja

Beispiel: 2010-08-31 AWSAccessKeyId

Die Access Key ID des Senders der Anfage. Sie finden Ihre Access Key ID in Seller Central unter Integration > Access Key.

Ja

Beispiel: AKIADQKE4SARGYLEXAMPLE Timestamp

Datum und Uhrzeit, zu der die Anfrage signiert wurde. Format:YYYY-MMDDThh:mm:ssZ. Weitere Informationen finden Sie im ISOStandard ISO 8601.

Bedingt

Bedingung: Entweder Timestamp oder Expires muss in der Anfrage vorhanden sein, aber nicht beide Parameter. Beispiel: 2006-07-07T15:04:56Z Beachten Sie, dass das "Z" am Ende nicht erforderlich ist. Expires

Datum und Uhrzeit, zu der die Signatur in der Anfrage abläuft. Format:YYYY-MMDDThh:mm:ssZ. Bedingung: Entweder Expires oder Timestamp muss in der Anfrage vorhanden sein, aber nicht beide Parameter. Beispiel: 2006-07-07T15:04:56Z Beachten Sie, dass das "Z" am Ende nicht erforderlich ist.

Bedingt

| Amazon-Payments-API für Query-Anfragen | 17

Name Signature

Beschreibung

Pflicht?

Die Signatur der Anfrage. Für weitere Informationen lesen Sie bitte "Query-Anfragen signieren".

Ja

Beispiel: Qnpl4Qk/7tINHzfXCiT7VbBatDA= SignatureMethod

Der Hash-Algorithmus, den Sie Ja verwenden, um die Signatur der Anfrage zu generieren. Für weitere Informationen lesen Sie bitte "QueryAnfragen signieren". Gültige Werte: HmacSHA256 | HmacSHA1. Beispiel: HmacSHA256

SignatureVersion

Die Signaturversion, die Sie verwenden, um die Anfrage zu signieren. Verwenden Sie hier den Wert 2. Für weitere Informationen lesen Sie bitte "Query-Anfragen signieren".

Ja

Beispiel: 2 Hinweis: Parameter-Werte müssen URL-kodiert sein. Dies gilt für alle Query-Parameter, die Sie an den Service senden, sowie normalerweise für den Signatur-Parameter. Einige Clients erzeugen automatisch URLkodierte Parameter, allerdings ist das nicht immer der Fall.

Liste der Anfragefunktionen • • • • •

CreatePurchaseContract GetPurchaseContract SetPurchaseItems SetContractCharges CompletePurchaseContract

CreatePurchaseContract Beschreibung Mittels der CreatePurchaseContract-API können Sie eine neue Purchase Contract ID erzeugen. Bitte beachten Sie, dass diese ID nur dann aktiv ist, wenn Sie innerhalb des Inline-Integration-Widgets verwendet wird und der Käufer den Kauf innerhalb dieses Widgets abschließt. Hinweis: Nicht genutzte Purchase Contract IDs laufen drei Stunden nach der Generierung ab. Wenn Sie diese API verwenden, dann müssen Sie die Purchase Contract ID als Input an das InlineCheckoutWidget übergeben. Wenn keine Purchase Contract ID zum

| Amazon-Payments-API für Query-Anfragen | 18

InlineCheckoutWidget übergeben wird, wird das Widget immer eine neue Purchase Contract ID generieren und zurückgeben. In den meisten Fällen müssen Sie diese API nicht verwenden. Eine Purchase Contract ID wird vom InlineCheckoutWidget zurückgegeben. Diese können Sie anschließend für alle anderen APIs verwenden, die in diesem Dokument beschrieben werden.

Anfrageparameter Die folgende Tabelle listet die speziellen Anfrageparameter auf, die von der CreatePurchaseContract-Funktion zusätzlich zu den allgemeinen Parametern genutzt werden. Name PurchaseContractMetadata

Beschreibung

Pflicht?

Base64-kodierte verschlüsselte Daten, die mit dem Purchase Contract gespeichert weren können. Sie können über die GetPurchaseContractFunktion auf diese Daten zugreifen.

Nein

Typ: String Constraints: Maximal 1024 Byte; base64-kodiert Standard: Keine

Antwortelemente Die folgende Tabelle listet alle Elemente der CreatePurchaseContract-Antwort auf, zusätzlich zu den Elementen, die bei allen erfolgreichen Antworten zurückgegeben werden. Name Beschreibung PurchaseContractId Eindeutige ID für den Purchase Contract, die von der API oder dem Widget erzeugt wurde. Typ: String Ancestor: CreatePurchaseContractResult

Beispiele Beispielanfrage https://payments.amazon.de/cba/api/purchasecontract/ ?Action=CreatePurchaseContract &PurchaseContractMetadata=Test%20Daten &SignatureMethod=HmacSHA256 &AWSAccessKeyId=AKIAJKYFSJU7PEXAMPLE &SignatureVersion=2 &Timestamp=2010-08-16T04%3A45%3A30.692-07%3A00

| Amazon-Payments-API für Query-Anfragen | 19

&Signature=BA7CnhukT60ysRrQ8PNwlNw5M3EXAMPLE &Version=2010-08-31 Beispielantwort HTTP Status 200 OK amzn1.contract.1.1.f86d99c2943f98dc28d586c628413080 5cd3ec4f-8047-11df-8d5c-bf56a38ef3b4

GetPurchaseContract Beschreibung Die GetPurchaseContract-API gibt die folgenden Informationen zurück: • • •

Status des Purchase Contracts Lieferinformationen, wenn der Käufer eine Adresse ausgewählt hat Informationen zum gekauften Artikel zurück, wenn Sie die SetPurchaseItems-API im Vorfeld aufrufen.

Anfrageparameter Die folgende Tabelle listet die speziellen Anfrageparameter auf, die von der GetPurchaseContract-Funktion zusätzlich zu den allgemeinen Parametern genutzt werden. Name PurchaseContractId

Beschreibung

Pflicht?

Eindeutige ID des Purchase Contracts.

Ja

Typ: String Constraints: Die ID wird nach der Erzeugung des Purchase Contracts an den Kontobesitzer zurückgegeben. Standard: Keine

Antwortelemente Die folgende Tabelle listet alle Elemente auf, die in einer Antwort enthalten sind, zusätzlich zu den Elementen, die bei allen erfolgreichen Antworten zurückgegeben werden. Name

Beschreibung

PurchaseContract

XML-Dokument, das den durch die API oder Widget erzeugten Purchase Contract beschreibt.

| Amazon-Payments-API für Query-Anfragen | 20

Name

Beschreibung Typ: PurchaseContractType (siehe Schema) Ancestor: GetPurchaseContractResult Hinweis: Die Antwort enthält nur dann eine Lieferadresse, wenn der Käufer die Adresse über das AddressWidget ausgewählt hat. Die gekauften Artikel sind nur dann in der Antwort enthalten, wenn Sie vorher die SetPurchaseItems-API aufgerufen haben.

Beispiele Beispielanfrage https://payments.amazon.de/cba/api/purchasecontract/ ?Action=GetPurchaseContract &SignatureMethod=HmacSHA256 &PurchaseContractId=amzn1.contract.1.1.2.23bc485cc4c6b0dc63cd7f8c0d3d8900 &AWSAccessKeyId=AKIAJKYFSJU7PEXAMPLE &SignatureVersion=2 &Timestamp=2010-08-16T05%3A20%3A14.780-07%3A00 &Signature=CLZOdtJGjAo81IxaLoE7af6HqK0EXAMPLE &Version=2010-08-31 Beispielantwort HTTP Status 200 OK amzn1.contract.1.1.f86d99c2943f98dc28d586c628413080 2010-10-01T01:01:01.000Z AEIOU1234AEIOU AZ4B0753LGLX OPEN #default PHYSICAL München Bayern 80807 DE 5f20169b-7ab2-11df-bcef-d35615e2b044

| Amazon-Payments-API für Query-Anfragen | 21

SetPurchaseItems Beschreibung Wenn der Käufer die Bestellung auf Ihrer Bestellbestätigungsseite abschickt, müssen Sie die SetPurchaseItemsAPI gefolgt von der CompletePurchaseContract-API-Funktion starten, damit Bezahlen über Amazon die Zahlung der Bestellung autorisieren kann. Die SetPurchaseItems-API verwendet die Liste der bestellten Artikel als Input. Sie können einstellen, dass die Bestellsumme in Rahmen dieses API-Aufrufs aufgeschlüsselt wird, so dass die einzelnen Artikelpreise dieser Bestellung verwendet werden. Hinweis: Wenn diese Aktion danach noch einmal aufgerufen wird, wird die Artikelliste gemäß des Purchase Contracts ersetzt. Wenn Sie diese Aktion mehrfach aufrufen, müssen Sie die vollständige Artikelliste für jeden Artikel mit allen notwendigen sowie optionalen Attribute erneut senden.

Anfrageparameter Die folgende Tabelle listet die speziellen Anfrageparameter auf, die von der SetPurchaseItems-Funktion zusätzlich zu den allgemeinen Parametern genutzt werden. Name PurchaseContractId

Beschreibung

Pflicht?

Eindeutige ID des Purchase Contracts.

Ja

Typ: String Constraints: Die ID wird nach der Erzeugung des Purchase Contracts an den Kontobesitzer zurückgegeben. Standard: Keine Nach dem Aufruf der PurchaseContractId können Sie eine Artikeliste als Anfrageparameter weitergeben. Innerhalb eines Purchase Contracts können maximal 50 verschiedene Artikel akzeptiert werden. PurchaseItemParameter müssen nach dem folgenden Schema aufgebaut sein: "PurchaseItems.PurchaseItem", gefolgt von einer Indexnummer und dem Artikel-Attributnamen. Beim zweiten weitergegebenen Artikel sieht das zum Beispiel so aus, wenn Sie den Titel des Artikels weitergeben möchten: PurchaseItems.PurchaseItem.2.Title Hinweis: Indexnummern sind Ganzzahlen (Integer) ohne führende Nullen. Die Indexnummer des ersten Artikels ist immer 1. Name MerchantItemId

Beschreibung

Pflicht?

Eindeutige ID des verkauften Artikels.

Ja

Typ: String Constraints: Jeder Artikel innerhalb des Purchase Contracts muss eine eindeutige und alphanumerische ID haben.

| Amazon-Payments-API für Query-Anfragen | 22

Name

Beschreibung

Pflicht?

Standard: Keine SKU

Die Artikel-SKU.

Nein

Typ: String Constraints: Der String muss alphanumerisch sein (nur Buchstaben von a-z, A-Z und Nummern von 0-9 sind erlaubt. Keine Umlaute oder sonstige Sonderzeichen). Maximale Länge: 40 Zeichen Standard: Keine MerchantId

Die ID des Händlers, der den Artikel verkauft.

Ja

Typ: String Constraints: Sie müssen den Access Key des Händlers verwenden, um die API aufzurufen. Standard: Keine Title

Der Artikelname.

Ja

Typ: String Maximale Länge: 80 Zeichen Standard: Keine Description

Die Artikelbeschreibung.

Nein

Typ: String Maximale Länge: 2.000 Zeichen Standard: Keine UnitPrice.Amount

Der Einzelpreis des Artikels.

Ja

Typ: Positive Gleitkommazahl (Double, nur 2 Dezimalstellen werden unterstützt) Constraints: Der Betrag muss 0 sein, oder höher. Standard: Keine UnitPrice.CurrencyCode

Die Währung des Artikelpreises. Typ: String, ISO-Code der Währung (3 Buchstaben)

Quantity

Ja

| Amazon-Payments-API für Query-Anfragen | 23

Name

Beschreibung

Pflicht?

Stückzahl des bestellten Artikels.

Nein

Typ: Positive Ganzzahl Constraints: Die Menge muss 1 sein, oder höher, bis maximal 999. Standard: 1 (falls keine Menge angegeben wurde) URL

Die URL der Artikeldetailseite.

Nein

Typ: URL Maximale Länge: 2.000 Zeichen Standard: Keine Category

Typ: String

Nein

Standard: Keine FulfillmentNetwork

Typ: String

Nein

Constraints: Der einzige akzeptierte Wert ist MERCHANT. Standard: MERCHANT ItemCustomData

Base64-kodierte verschlüsselte Daten, die mit dem gekauften Artikel gespeichert werden können. Sie können mittels der Bestellbenachrichtigungen (IOPN) auf diese Daten zugreifen.

Nein

Typ: String Constraints: Maximal 1024 Byte; base64-kodiert Standard: Keine ProductType

Typ: String

Nein

Standard: PHYSICAL Die untenstehenden Attribute sind nur für physikalische Waren (PHYSICAL) gültig. Wenn Sie diese Attribute weitergeben möchten, müssen Sie sicherstellen, dass der ProductType "PHYSICAL" eingestellt wurde. Andernfalls wird diese Funktion einen Fehler zurückgeben. Hinweis: Physikalische Artikelattributnamen müssen mit dem Schlüsselwort PhysicalProductAttributes eingeleitet werden. Beispiel: PurchaseItems.PurchaseItem.2.PhysicalProductAttributes.Condition

| Amazon-Payments-API für Query-Anfragen | 24

Name Weight.Value

Beschreibung

Pflicht?

Typ: Positive Gleitkommazahl (Double)

Bedingt

Constraints: Der Wert muss 0 betragen, oder höher. Bedingungen: Muss verwendet werden, wenn Sie eine Gewichtseinheit festgelegt haben. Weight.Unit

Typ: String

Bedingt

Bedingungen: Muss verwendet werden, wenn ein Gewicht festgelegt wurde. DeliveryMethod.ServiceLevel Vordefinierte Liefergeschwindigkeit. Ja Typ: String Constraints: Die einzigen akzeptierten Werte sind Standard, OneDay, TwoDay, oder Expedited Standard: Keine DeliveryMethod.DisplayableShippingLabel Benutzerdefinierter Name für die Lieferart.

Nein

Typ: String Standard: Keine DeliveryMethod.DestinationName Ziel, an das die Artikel zugestellt werden. Der Name entspricht dem Wert des DestinationNameEingabeparameters, der im Adressbuch-Widget festgelegt wird.

Nein

Typ: String Standard: "#default" DeliveryMethod.ShippingCustomData Base64-kodierte verschlüsselte Lieferdaten, die mit dem gekauften Artikel gespeichert werden können. Sie können über die Bestellbenachrichtigungen (IOPN) auf diese Daten zugreifen. Typ: String Constraints: Maximal 1024 Byte; base64-kodiert Standard: Keine

Nein

| Amazon-Payments-API für Query-Anfragen | 25

Unten sehen Sie die Attribute, die auf die von Ihnen berechneten Kosten des physikalischen Artikels anwendbar sind. Alle der untenstehenden Kosten haben 2 untergeordnete Komponenten (mit Ausnahme von PromotionId und Description): Amount und CurrencyCode. Wenn Sie eines dieser Attribute festlegen, müssen Sie auch das andere festlegen. Die Datenytpen sind je nach Attribut positive Gleitkommazahlen oder Strings. Der Betrag muss 0 sein, oder höher. Name Shipping.Amount

Shipping.CurrencyCode

Beschreibung

Pflicht?

Wenn Shipping nicht zur Verfügung gestellt wurde, wird angenommen, dass es keine Versandkosten gibt.

Nein

Der Währungscode muss dem ISO-Code entsprechen und aus 3 Buchstaben bestehen.

Nein

Promotions.Promotion.1.PromotionId Die ID der Werbeaktion, die auf diesen Artikel zutrifft.

Bedingt

Bedingungen: Wenn Werbeaktionen festgelegt wurden, müssen auch die anderen 3 Attribute für Werbeaktionen festgelegt werden. Promotions.Promotion.1.Description Die Beschreibung der Werbeaktion, die auf diesen Artikel zutrifft.

Bedingt

Bedingungen: Wenn Werbeaktionen festgelegt wurden, müssen auch die anderen 3 Attribute für Werbeaktionen festgelegt werden. Promotions.Promotion.1.Discount.Amount Der Betrag der Werbeaktionen, abgezogen vom Artikelpreis.

Bedingt

Bedingungen: Wenn Werbeaktionen festgelegt wurden, müssen auch die anderen 3 Attribute für Werbeaktionen festgelegt werden. Promotions.Promotion.1.Discount.CurrencyCode Die Währung der Werbeaktion, die auf diesen Artikel zutrifft. Der Wert muss dem ISO-Code für Währungen entsprechen (3 Buchstaben).

Bedingt

Bedingungen: Wenn Werbeaktionen festgelegt wurden, müssen auch die anderen 3 Attribute für Werbeaktionen festgelegt werden. Hinweis: Je nach Land kann das Dezimaltrennzeichen aus einem anderen Zeichen bestehen. Beispiel: In England steht 10.49 GBP für 10 Pfund Sterling und 49 Pence. England benutzt einen Punkt (.) als Dezimaltrennzeichen. In Deutschland wird dagegen ein Komma (,) als Dezimaltrennzeichen verwendet, den Betrag würde man korrekt 10,49 GBP schreiben.

| Amazon-Payments-API für Query-Anfragen | 26

Bezahlen über Amazon akzeptiert allerdings ausschließlich einen Punkt (.) als Dezimaltrennzeichen. Bei Berechnungen für Transaktionen in Deutschland müssen Sie Ihren Code entsprechen anpassen, um das Dezimaltrenzeichen von einem Komma in einen Punkt zu konvertieren. Hierfür können Sie zum Beispiel den folgenden Code verwenden: // change parameters["Charges.Shipping.Amount"]= charges.Shipping.Amount.ToString(); // to parameters["Charges.Shipping.Amount"]= Replace(charges.Shipping.Amount.ToString(), ",", "."); Die aktuelle Version der APIs unterstützt nur eine Werbeaktionen für denselben Artikel. Sie können also nur eine Werbeaktion pro Artikel festlegen.

Antwortelemente In der SetPurchaseItems-Antwort gibt es keine weiteren Elemente zusätzlich zu den Elementen, die bereits in allen erfolgreichen Antworten zurückgegeben wurden.

Beispiele Beispielanfragen https://payments.amazon.de/cba/api/purchasecontract/ ?PurchaseContractId= amzn1.contract.1.1.f86d99c2943f98dc28d586c628413080 &Action=SetPurchaseItems &PurchaseItems.PurchaseItem.1.MerchantItemId=1 &PurchaseItems.PurchaseItem.1.SKU=Artikel1SKU &PurchaseItems.PurchaseItem.1.MerchantId=A32EMVWCF1111H &PurchaseItems.PurchaseItem.1.Title=Artikel1Title &PurchaseItems.PurchaseItem.1.Description=ArtikelBeschreibung &PurchaseItems.PurchaseItem.1.UnitPrice.Amount=3.14 &PurchaseItems.PurchaseItem.1.UnitPrice.CurrencyCode=EUR &PurchaseItems.PurchaseItem.1.Quantity=1 &PurchaseItems.PurchaseItem.1.URL=http%3A%2F%2Fexample.com%2Fprodukt &PurchaseItems.PurchaseItem.1.Category=bücher &PurchaseItems.PurchaseItem.1.FulfillmentNetwork=MERCHANT &PurchaseItems.PurchaseItem.1.ItemCustomData=MHhkZWFkYmVlZg%3D%3D &PurchaseItems.PurchaseItem.1.ProductType=PHYSICAL &PurchaseItems.PurchaseItem.1.PhysicalProductAttributes. Weight.Value=3.25 &PurchaseItems.PurchaseItem.1.PhysicalProductAttributes. Weight.Unit=KG &PurchaseItems.PurchaseItem.1.PhysicalProductAttributes. Condition=neu &PurchaseItems.PurchaseItem.1.PhysicalProductAttributes. DeliveryMethod.ServiceLevel=Standard &PurchaseItems.PurchaseItem.1.PhysicalProductAttributes. DeliveryMethod.DisplayableShippingLabel=Express &PurchaseItems.PurchaseItem.1.PhysicalProductAttributes. DeliveryMethod.DestinationName=Artikel1Lieferort &PurchaseItems.PurchaseItem.1.PhysicalProductAttributes. DeliveryMethod.ShippingCustomData=MHhkZWFkYmVlZg%3D%3D &PurchaseItems.PurchaseItem.1.PhysicalProductAttributes. ItemCharges.Shipping.Amount=3.14 &PurchaseItems.PurchaseItem.1.PhysicalProductAttributes. ItemCharges.Shipping.CurrencyCode=EUR &PurchaseItems.PurchaseItem.1.PhysicalProductAttributes. ItemCharges.Promotions.Promotion.1.PromotionId=BEISPIEL

| Amazon-Payments-API für Query-Anfragen | 27

&PurchaseItems.PurchaseItem.1.PhysicalProductAttributes. ItemCharges.Promotions.Promotion.1.Description=BEISPIEL &PurchaseItems.PurchaseItem.1.PhysicalProductAttributes. ItemCharges.Promotions.Promotion.1.Discount.Amount=3.14 &PurchaseItems.PurchaseItem.1.PhysicalProductAttributes. ItemCharges.Promotions.Promotion.1.Discount.CurrencyCode=EUR &SignatureMethod=HmacSHA256&Expires=2010-10-18T12:00:00-07:00 &AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE &SignatureVersion=2 &Signature=Dqlp3Sd61jTUA9Uf6SGtEExwUQEXAMPLE &Version=2010-08-31 Beispielantwort HTTP Status 200 OK f42df4b1-8047-11df-8d5c-bf56a38ef3b4

SetContractCharges Beschreibung Sie können diese API nutzen, um Versandkosten oder Werbeaktionen für den gesamten Purchase Contract festzulegen. Nachdem Sie diese API aufgerufen haben, antwortet die GetPurchaseContract-API und gibt die Purchase-Level-Kosten aus dem Charges-XML-Element zurück. Das Charges-XML-Element ist ein unmittelbares Unterlement des PurchaseContract-XML-Elements. Alle Details zum Schema finden Sie in der XSD-Datei. Nachdem der Purchase Contract vollständig ist (d.h. nachdem die Bestellung aufgegeben wurde), werden die Gesamtkosten auf alle Artikel proportional zu den Artikelkosten verteilt (d.h. die Kosten pro Artikel werden mit der Menge der bestellten Artikel mulipliziert). Die Summe der berechneten Kosten, die auf alle Artikel verteilt werden, ist identisch mit der Summe der Contract-Kosten, die Sie innerhalb dieser API festgelegt haben. Es gibt bestimmte Regeln, die auf die Einstellungen der Kosten durch diese API angewendet werden, insbesondere, wenn sie gemeinsam mit der SetPurchaseItems-API verwendet wird. Kostenzusammenführungsverhalten • •

• • •

Anschließende Aufrufe dieser Aktion ersetzen die vollständige Liste der mit dem Purchase Contract verbundenen Kosten. Wenn Sie diese Aktion mehrmals aufrufen, müssen Sie jeweils die komplette Liste der Kosten übermitteln. Die folgenden Kostenpaare sind als Eingabelemente für diese API gültig: • Versandkosten + Werbeaktionen • Versandkosten + Keine Werbeaktionen • Keine Versandkosten + Werbeaktionen Shipping (Versandkosten) wird entweder auf Artikelebene oder auf Vertragsebene ausgelesen, abhängig davon, welcher der beiden APIs (SetContractCharges und SetPurchaseItems) später aufgerufen wird. Wenn die Versandkosten nur auf Vertagsebene angeboten werden, dann werden die Werbeaktionen auf Artikelebene angewendet, falls vorhanden. Ähnlich verhält es sich, wenn nur Werbeaktionen auf Vertragsebene angeboten werden, dann werden die Versandkosten auf Artikelebene angwendet, wenn vorhanden.

| Amazon-Payments-API für Query-Anfragen | 28

• •

Falls Werbeaktionen sowohl auf Vertragsebene, als auch auf Artikelebene festgelegt wurden, dann werden die auf Vertragsebene festgelegten Werbeaktionen vorgezogen, unabhängig davon, in welcher Reihenfolge sie festgelegt wurden. Die GetPurchaseContract-API gibt eine endgültige Übersicht über die Kosten die auf Artikelebene und Vertragsebene festgelegt wurden zurück und hält sich dabei an die obenstehenden Regeln. Die Complete-API führt eine zusätzliche Prüfung durch, um sicherzustellen, dass die Summe aller Werbeaktionen-Beträge nicht höher ist als die Artikel-Preise, falls die Werbeaktionen-Beträge auf Vertragsebene festgelegt wurden.

•

Anfrageparameter Die folgende Tabelle listet die speziellen Anfrageparameter auf, die von der SetContractCharges-Funktion zusätzlich zu den allgemeinen Parametern genutzt werden. Hinweis: Bitte beachten Sie, dass nur eine Werbeaktion pro Bestellung auf Einkaufswagenebene hinzugefügt werden kann. Name Shipping.Amount

Shipping.CurrencyCode

Beschreibung

Pflicht?

Wenn Shipping nicht zur Verfügung gestellt wurde, wird angenommen, dass es keine Versandkosten gibt.

Bedingt

Der Währungscode muss dem ISO-Code entsprechen und aus 3 Buchstaben bestehen.

Bedingt

Promotions.Promotion.1.PromotionId Die ID der Werbeaktion, die für diesen Vertrag gültig ist.

Bedingt

Bedingungen: Wenn Werbeaktionen festgelegt wurden, müssen auch die anderen 3 Attribute für Werbeaktionen festgelegt werden. Promotions.Promotion.1.Description Die Beschreibung der Werbeaktion, die für diesen Vertrag gültig ist.

Bedingt

Bedingungen: Wenn Werbeaktionen festgelegt wurden, müssen auch die anderen 3 Attribute für Werbeaktionen festgelegt werden. Promotions.Promotion.1.Discount.Amount Der Betrag der Werbeaktionen, abgezogen vom Vertrag.

Bedingt

Bedingungen: Wenn Werbeaktionen festgelegt wurden, müssen auch die anderen 3 Attribute für Werbeaktionen festgelegt werden. Promotions.Promotion.1.Discount.CurrencyCode Die Währung der Werbeaktionen, abgezogen vom Vertrag. Der Wert muss dem ISO-Code für Währungen entsprechen (3 Buchstaben).

Bedingt

| Amazon-Payments-API für Query-Anfragen | 29

Name

Beschreibung

Pflicht?

Bedingungen: Wenn Werbeaktionen festgelegt wurden, müssen auch die anderen 3 Attribute für Werbeaktionen festgelegt werden. PurchaseContractId

Eindeutige ID des Purchase Contracts.

Ja

Typ: String Constraints: Die ID wird nach der Erzeugung des Purchase Contracts an den Kontobesitzer zurückgegeben. Standard: Keine Hinweis: Je nach Land kann das Dezimaltrennzeichen aus einem anderen Zeichen bestehen. Beispiel: In England steht 10.49 GBP für 10 Pfund Sterling und 49 Pence. England benutzt einen Punkt (.) als Dezimaltrennzeichen. In Deutschland wird dagegen ein Komma (,) als Dezimaltrennzeichen verwendet, den Betrag würde man korrekt 10,49 GBP schreiben. Bezahlen über Amazon akzeptiert allerdings ausschließlich einen Punkt (.) als Dezimaltrennzeichen. Bei Berechnungen für Transaktionen in Deutschland müssen Sie Ihren Code entsprechen anpassen, um das Dezimaltrenzeichen von einem Komma in einen Punkt zu konvertieren. Hierfür können Sie zum Beispiel den folgenden Code verwenden: // change parameters["Charges.Shipping.Amount"]= charges.Shipping.Amount.ToString(); // to parameters["Charges.Shipping.Amount"]= Replace(charges.Shipping.Amount.ToString(), ",", ".");

Antwortelemente In der SetContractCharges-Antwort gibt es keine weiteren Elemente zusätzlich zu den Elementen, die bereits in allen erfolgreichen Antworten zurückgegeben wurden.

Beispiele Beispielanfrage https://payments.amazon.de/cba/api/purchasecontract/ ?PurchaseContractId=amzn1.contract.1.1.f86d99c2943f98dc28d586c628413080 &Action=SetContractCharges &Charges.Shipping.Amount=3 &Charges.Shipping.CurrencyCode=EUR &Charges.Promotions.Promotion.1.PromotionId=BEISPIEL &Charges.Promotions.Promotion.1.Description=BEISPIEL &Charges.Promotions.Promotion.1.Discount.Amount=3 &Charges.Promotions.Promotion.1.Discount.CurrencyCode=EUR &AWSAccessKeyId=0GS7553JW74RRM612K02BEISPIEL &SignatureVersion=2 &SignatureMethod=HmacSHA1 &Timestamp=2010-09-10T14%3A47%3A13.000Z &Signature=2RPzkOgQmDybUjk0dA54maCBEISPIEL

| Amazon-Payments-API für Query-Anfragen | 30

Beispielantwort HTTP Status 200 OK f42df4b1-8047-11df-8d5c-bf56a38ef3b4

CompletePurchaseContract Beschreibung Nachdem Sie die Artikel zum Purchase Contract hinzugefügt haben, sollten Sie die CompletePurchaseContract-API aufrufen. Diese API akzeptiert die Purchase-Contract-ID als Eingabeparameter. Diese API wandelt den Purchase Contract in "Bezahlen über Amazon"-Bestellungen um und gibt eine Liste der "Bezahlen über Amazon"-Bestellnummern zurück. Sie können diese Bestellnummern anschließend verwenden, um die Bestellungen zu verwalten.

Anfrageparameter Die folgende Tabelle listet die speziellen Anfrageparameter auf, die von der CompletePurchaseContractFunktion zusätzlich zu den allgemeinen Parametern genutzt werden. Name PurchaseContractId

Beschreibung

Pflichtfeld

Eindeutige ID des Purchase Contracts.

Ja

Typ: String Constraints: Die ID, die nach der Erzeugung des Purchase Contracts an den Kontobesitzer zurückgegeben wird. Standard: Keine IntegratorId

IntegratorName

Bedingungen: Muss verwendet werden, wenn ein Integrator-Name festgelegt wurde.

Bedingt

Bedingungen: Muss verwendet werden, wenn eine Integrator-ID festgelegt wurde.

Bedingt

InstantOrderProcessingNotificationURLs.MerchantURL Typ: URL Standard: Keine Hinweis: Falls die MerchantURL in der API nicht definiert wurde, werden die Werte verwendet, die in Seller Central unter Einstellungen > Einstellungen zum Bestellprozess

Ja

| Amazon-Payments-API für Query-Anfragen | 31

Name

Beschreibung

Pflichtfeld

> IOPN-Einstellungen > HändlerURL festgelegt wurden. InstantOrderProcessingNotificationURLs.IntegratorURL Typ: URL Ja Standard: Keine Hinweis: Falls die IntegratorURL in der API nicht definiert wurde, werden die Werte verwendet, die in Seller Central unter Einstellungen > Einstellungen zum Bestellprozess > IOPNEinstellungen > Integrator-URL festgelegt wurden. Hinweis: Bitte lesen Sie das Handbuch zur Instant Order Processing Notification API für weitere Informationen zur InstantOrderProcessingNotificationURL.

Antwortelemente Die folgende Tabelle listet alle Elemente der CompletePurchaseContract-Antwort auf, zusätzlich zu den Elementen, die bei allen erfolgreichen Antworten zurückgegeben werden. Name

Beschreibung

OrderIds

XML-Dokument, das die Bestellnummern der einzelnen Bestellungen beschreibt, die beim Abschluss von Purchase Contract erzeugt werden. Typ: OrderIdListType (siehe Schema) Ancestor: CompletePurchaseContractResult

Beispiele Beispielanfrage https://payments.amazon.de/cba/api/purchasecontract/ &Action=CompletePurchaseContract ?PurchaseContractId= amzn1.contract.1.1.f86d99c2943f98dc28d586c628413080 &IntegratorId=MNOPQ1234MNOPQ &IntegratorName=Amazon &InstantOrderProcessingNotificationURLs. IntegratorURL=http%3A%2F%2Fexample.com%2Fiopn &InstantOrderProcessingNotificationURLs. MerchantURL=http%3A%2F%2Fmydomain.com%2Fiopn &SignatureMethod=HmacSHA256&Expires=2010-10-18T12:00:00-07:00 &AWSAccessKeyId=0GS7553JW74RRM612K02EXAMPLE &SignatureVersion=2 &Signature=Dqlp3Sd61jTUA9Uf6SGtEExwUQEXAMPLE &Version=2010-08-31 Beispielantwort HTTP Status 200 OK

| Amazon-Payments-API für Query-Anfragen | 32

102-2432725-669014 101-7821075-313967 02055a12-8048-11df-8d5c-bf56a38ef3b4

Kapitel

3

Fehlercodes und Beschreibungen Themen: • •

HTML-Fehlercodes und Beschreibungen Anwendungsfehlercodes und Beschreibungen

| Fehlercodes und Beschreibungen | 34

HTML-Fehlercodes und Beschreibungen Tabelle 1: HTML-Fehlercodes und Beschreibungen HTTP-Code

HTTP-Status

Beschreibung

200

OK

Die Anfrage war erfolgreich.

400

Bad Request

Die vom Client gesendete Anfrage ist nicht wohlgeformt oder sie verletzt Contraints/wirtschaftliche Regeln, die von dem Service befolgt werden müssen. Der Client sollte nicht versuchen, die Anfrage unverändert noch einmal zu senden. Die meisten Fehlermeldungen werden nicht mehr auftreten, wenn der Client richtig integriert wurde. Verbleibende Fehler können von den Clients behoben werden, indem die Bestellprozesse korrekt gestaltet werden. Bitte lesen Sie Anwendungsfehlercodes und Beschreibungen auf Seite 35 für Details zu den Anwendungsfehlercodes.

403

Forbidden

Für diese Anfrage ist eine Anmeldung erforderlich. Entweder wurden vom Clienten keine Authentifizierungsdaten übermittelt, oder die Singatur war ungültig. Bitte lesen Sie Anwendungsfehlercodes und Beschreibungen auf Seite 35 für Details zu den Anwendungsfehlercodes.

500

Internal Server Error

Auf Serverseite ist ein unerwartetes Problem aufgetreten und ein erneuter Sendeversuch wird das Problem nicht beheben. Wenn dieser Fehler auftritt, sollte der Verkäufer das "Bezahlen über Amazon"-Team kontaktieren.

502

Bad Gateway

Auf Serverseite ist ein unerwartetes Problem aufgetreten. Der Client sollte versuchen, die Anfrage erneut zu senden.

503

Service Unavailable

Auf Serverseite ist ein unerwartetes Problem aufgetreten. Der Client sollte versuchen, die Anfrage erneut zu senden.

| Fehlercodes und Beschreibungen | 35

Anwendungsfehlercodes und Beschreibungen CreatePurchaseContract-API HTTP-Code

Anwendungsfehlercode

Beschreibung

400

InvalidParameterValue

PurchaseContractMetadata wurde im falschen Format zur Verfügung gestellt, oder überschreitet die serversetig maximal erlaubte Größe.

403

MissingAuthenticationToken In der Anfrage, die zum Server gesendet wurde, fehlt entweder AWSAccessKeyId oder Signature.

403

InvalidClientTokenId

In der Anfrage, die zum Server geschickt wude, gibt es keine gültige AWSAccessKeyId zur Verifizierung oder die AWSAccessKeyId fehlt ganz.

403

SignatureDoesNotMatch

Die Anfrage wurde mit einer ungültigen Signaturmethode signiert oder die errechnete Signatur ist ungültig.

403

InvalidMerchant

Der Händler hat den Registrierungsprozess von Bezahlen über Amazon noch nicht abgeschlossen.

HTTP-Code

Anwendungsfehlercode

Beschreibung

400

ValidationError

Die Anfrage entspricht nicht den Contraints, die in der WSDL definiert wurden. Die Fehlermeldung zeigt sowohl den/die fehlerhafte(n) Parameter an, als auch die Probleme, die mit dem/den Parameter(n) aufgetreten sind. Die Anfrage kann erst dann erneut gesendet werden, nachdem der Fehler behoben wurde. Für weitere Details sollte der Client die WSDL-Datei konsultieren.

400

InvalidParameterValue

Serverseitige Validierung der Anfrage ist fehlgeschlagen. Die Fehlermeldung zeigt sowohl den fehlerhaften Parameter an, als auch das aufgetretene Problem in einem beschreibenden Format. Die Anfrage kann erst dann erneut gesendet werden, nachdem der Fehler behoben wurde.

SetPurchaseItems-API

| Fehlercodes und Beschreibungen | 36

HTTP-Code

Anwendungsfehlercode

Beschreibung Einige der zusätzlichen Regeln, die Clients hier hinzufügen sollten, sind unten aufgelistet. Weitere Details entnehmen Sie bitte dem jeweiligen Abschnitt des Implementierungshandbuchs. •

•

•

• • • • • • •

Die contractId ist ungültig oder der Vertrag ist nicht Active (andere mögliche Zustände sind Expired (agelaufen) oder Completed (vollständig)). Die MerchantId auf Artikelebene stimmt nicht mit der MerchantId überein, die aus der AWSAccessKeyId der Anfrage abgeleitet wurde. Die Anzahl der in der Anfrage übermittelten Artikel überschreitet die Maximalmenge von 50 erlaubten Artikeln. Nicht jeder Artikel hat eine eindeutige Artikelnummer. Das festgelegte Gewicht ist nicht gültig oder wird von Marketplace nicht unterstützt. Die Beträge, die für UnitPrice oder ItemCharges festgelegt wurden, sind ungültig. Das Währungskürzel für die Beträge ist ungültig oder wird von Marketplace nicht unterstützt. Die Höhe der Werbeaktionen überschreitet die Zwischensumme. Die Länge des Parameters überschreitet die Maximalhöhe. Eine nicht unterstützte Funktion wurde benutzt (weitere Details finden Sie im Implementierungshandbuch).

403

MissingAuthenticationToken In der Anfrage, die zum Server gesendet wurde, fehlt entweder AWSAccessKeyId oder Signature.

403

InvalidClientTokenId

In der Anfrage, die zum Server geschickt wude, gibt es keine gültige AWSAccessKeyId zur Verifizierung oder die AWSAccessKeyId fehlt ganz.

403

SignatureDoesNotMatch

Die Anfrage wurde mit einer ungültigen Signaturmethode signiert

| Fehlercodes und Beschreibungen | 37

HTTP-Code

Anwendungsfehlercode

Beschreibung oder die errechnete Signatur ist ungültig.

InvalidMerchant

Der Händler hat den Registrierungsprozess von Bezahlen über Amazon noch nicht abgeschlossen.

HTTP-Code

Anwendungsfehlercode

Beschreibung

400

ValidationError

Die Anfrage entspricht nicht den Contraints, die in der WSDL definiert wurden. Die Fehlermeldung zeigt sowohl den/die fehlerhafte(n) Parameter an, als auch die Probleme, die mit dem/den Parameter(n) aufgetreten sind. Die Anfrage kann erst dann erneut gesendet werden, nachdem der Fehler behoben wurde. Für weitere Details sollte der Client die WSDL-Datei konsultieren.

400

InvalidParameterValue

Serverseitige Validierung der Anfrage ist fehlgeschlagen. Die Fehlermeldung zeigt sowohl den fehlerhaften Parameter an, als auch das aufgetretene Problem in einem beschreibenden Format. Die Anfrage kann erst dann erneut gesendet werden, nachdem der Fehler behoben wurde.

403

SetContractCharges-API

Grund könnte einer der folgenden sein: •

•

•

403

Die contractIdist ungültig oder der Vertrag ist nicht Active (andere mögliche Zustände sind Expired (agelaufen) oder Completed (vollständig)). Die Währungseinheit, die für eine der ChargeKomponenten definiert wurde (Shipping/Promotions (Versand/Werbeaktionen)) wird nicht unterstützt. Es wurden mehr als eine Promotion (Werbeaktionen) in der Liste der Werbeaktionen angegeben.

MissingAuthenticationToken In der Anfrage, die zum Server gesendet wurde, fehlt entweder

| Fehlercodes und Beschreibungen | 38

HTTP-Code

Anwendungsfehlercode

Beschreibung AWSAccessKeyId oder Signature.

403

InvalidClientTokenId

In der Anfrage, die zum Server geschickt wude, gibt es keine gültige AWSAccessKeyId zur Verifizierung oder die AWSAccessKeyId fehlt ganz.

403

SignatureDoesNotMatch

Die Anfrage wurde mit einer ungültigen Signaturmethode signiert oder die errechnete Signatur ist ungültig.

403

InvalidMerchant

Der Händler hat den Registrierungsprozess von Bezahlen über Amazon noch nicht abgeschlossen.

HTTP-Code

Anwendungsfehlercode

Beschreibung

400

InvalidParameterValue

Serverseitige Validierung der Anfrage ist fehlgeschlagen. Die Fehlermeldung zeigt sowohl den fehlerhaften Parameter an, als auch das aufgetretene Problem in einem beschreibenden Format. Die Anfrage kann erst dann erneut gesendet werden, nachdem der Fehler behoben wurde.

GetPurchaseContract-API

Einige der zusätzlichen Regeln, die Clients hier hinzufügen sollten, sind unten aufgelistet. Weitere Details entnehmen Sie bitte dem jeweiligen Abschnitt des Implementierungshandbuchs. •

• • 403

Die contractIdist ungültig oder der Vertrag ist nicht Active (andere mögliche Zustände sind Expired (agelaufen) oder Completed (vollständig)). Die Länge des Parameters überschreitet die Maximalhöhe. Angegebene URLs wurden falsch formatiert.

MissingAuthenticationToken In der Anfrage, die zum Server gesendet wurde, fehlt entweder AWSAccessKeyId oder Signature.

| Fehlercodes und Beschreibungen | 39

HTTP-Code

Anwendungsfehlercode

Beschreibung

403

InvalidClientTokenId

In der Anfrage, die zum Server geschickt wude, gibt es keine gültige AWSAccessKeyId zur Verifizierung oder die AWSAccessKeyId fehlt ganz.

403

SignatureDoesNotMatch

Die Anfrage wurde mit einer ungültigen Signaturmethode signiert oder die errechnete Signatur ist ungültig.

403

InvalidMerchant

Der Händler hat den Registrierungsprozess von Bezahlen über Amazon noch nicht abgeschlossen.

HTTP-Code

Anwendungsfehlercode

Beschreibung

400

ValidationError

Die Anfrage entspricht nicht den Contraints, die in der WSDL definiert wurden. Die Fehlermeldung zeigt sowohl den/die fehlerhafte(n) Parameter an, als auch die Probleme, die mit dem/den Parameter(n) aufgetreten sind. Die Anfrage kann erst dann erneut gesendet werden, nachdem der Fehler behoben wurde. Für weitere Details sollte der Client die WSDL-Datei konsultieren.

400

InvalidParameterValue

Serverseitige Validierung der Anfrage ist fehlgeschlagen. Die Anfrage kann erst dann erneut gesendet werden, nachdem der Fehler behoben wurde.

CompletePurchaseContract-API

Einige der zusätzlichen Regeln, die Clients hier hinzufügen sollten, sind unten aufgelistet. Weitere Details entnehmen Sie bitte dem jeweiligen Abschnitt des Implementierungshandbuchs. •

•

Die contractIdist ungültig oder der Vertrag ist nicht Active (andere mögliche Zustände sind Expired (agelaufen) oder Completed (vollständig)). Die MerchantId auf Artikelebene stimmt nicht mit der MerchantId überein, die aus der AWSAccessKeyId der Anfrage abgeleitet wurde.

| Fehlercodes und Beschreibungen | 40

HTTP-Code

Anwendungsfehlercode

Beschreibung •

• • • • • • •

Die Anzahl der in der Anfrage übermittelten Artikel überschreitet die Maximalmenge von 50 erlaubten Artikeln. Nicht jeder Artikel hat eine eindeutige Artikelnummer. Das festgelegte Gewicht ist nicht gültig oder wird von Marketplace nicht unterstützt. Die Beträge, die für UnitPrice oder ItemCharges festgelegt wurden, sind ungültig. Das Währungskürzel für die Beträge ist ungültig oder wird von Marketplace nicht unterstützt. Die Höhe der Werbeaktionen überschreitet die Zwischensumme. Die Länge des Parameters überschreitet die Maximalhöhe. Eine nicht unterstützte Funktion wurde benutzt (weitere Details finden Sie im Implementierungshandbuch).

400

BuyerNotRecognized

Es gibt keine Details zum Käufer für den Vertrag, höchstwahrscheinlich deshalb, weil sich der Käufer nicht angemeldet hat, um die Lieferadresse und die Zahlungsart zu wählen. Clients können den Käufer an eine Seite weiterleiten, auf der er sich anmelden und die Liefer- und Zahlugnsdaten auswählen kann.

400

InvalidDestination

Eine der ausgwählten Lieferadressen für die Artikel ist nicht gültig. Grund könnte sein, dass eine falsche Adresse ausgewählt wurde, oder die Adresse ist nicht mehr gültig. Clients können in diesem Fall den Käufer auf eine Seite weiterleiten, auf der er eine neue Lieferadresse auswählen kann.

400

InvalidPaymentDetails

Die angegebenen Zahlungsdaten waren ungültig oder abgelaufen. Clients können in diesem Fall den Käufer auf eine Seite weiterleiten, auf der er eine neue Zahlungsart auswählen kann.

400

NoItemsInContract

Im Purchase Contract befinden sich keine Artikel. Clients müssen zuerst die SetPurchaseItems-Funktion

| Fehlercodes und Beschreibungen | 41

HTTP-Code

Anwendungsfehlercode

Beschreibung aufrufen, bevor sie die Funktion "Complete" aufrufen.

403

MissingAuthenticationToken In der Anfrage, die zum Server gesendet wurde, fehlt entweder AWSAccessKeyId oder Signature.

403

InvalidClientTokenId

In der Anfrage, die zum Server geschickt wude, gibt es keine gültige AWSAccessKeyId zur Verifizierung oder die AWSAccessKeyId fehlt ganz.

403

SignatureDoesNotMatch

Die Anfrage wurde mit einer ungültigen Signaturmethode signiert oder die errechnete Signatur ist ungültig.

403

InvalidMerchant

Der Händler hat den Registrierungsprozess von Bezahlen über Amazon noch nicht abgeschlossen.