Physische Karten aktivieren

Physische Karten aktivieren

Bevor Sie mit der Integration beginnen können, müssen Sie Ihr Amazon Incentives-API-Konto einrichten. Erstellen Sie ein Incentives-API-Konto.


Mit der Incentives-API können Sie Amazon-Geschenkgutscheincodes bei Bedarf erstellen und verteilen. Mit dieser API können Sie Einlösungscodes in elektronische Geschenkgutscheine einfügen, Gruppengeschenke unterstützen und Echtzeit-Einlösung von Einlösungscodes in Treueprogrammen (z. B. Punkteprogrammen) ermöglichen.

Jeder Geschenkgutschein ist mit einer eindeutigen zuvor generierten webaktivierten Karte (WAK) und einem Nennwert (Dollarwert) verknüpft. Der Geschenkgutschein kann in Echtzeit aktiviert werden. Nach der Aktivierung kann der mit der WAK verknüpfte Geschenkgutschein verteilt werden und der Kunde kann ihn für Einkäufe bei Amazon verwenden.

Die Webaktivierungsvorgänge der Incentives-API bieten eine Programmierschnittstelle, mit der Sie Geschenktgutscheine in Echtzeit aktivieren/deaktivieren können. Sie stellen synchrone Anforderungen an den Endpunkt. Bei Karten ohne Nennwert wird der Wert der gewünschten zu aktivierenden WAK angegeben und bei Karten mit voreingestelltem Nennwert wird der passende voreingestellte Nennwert angegeben. Die API reagiert mit dem Erfolgs- oder Fehlerstatus des Vorgangs.

Es gibt zwei Arten von webaktivierten Karten:

  • Mit Nennwert (fester Betrag) – Betrag ist für den Einlösungscode bereits vorbestimmt
  • Ohne Nennwert (variabler Betrag) – bei Aktivierung des Einlösungscodes zugewiesener Betrag

Ihr Account Manager gibt bei Bedarf die WAK-Nummern zusammen mit den zugehörigen Einlösungscodes an.

Hinweis: Webaktivierte Karten können nur von Partnern aktiviert werden, die dafür zugelassen wurden.

Anforderungsbezeichner

Ein Aufruf eines Endpunkts enthält einen RequestId-Wert im Text der Anforderung.

  • activationRequestId – Ein eindeutiger Bezeichner für jeden ActivateGiftCard/DeactivateGiftCard-Aufruf, der zum Aktivieren/Deaktivieren einer webaktivierten Karte (WAK) führt. Sie müssen für jede Aktivierungsanforderung einen neuen Wert generieren (außer für Wiederholungen). Jeder activationRequestId-Wert beginnt mit Ihrer partnerId, gefolgt von einem von Ihnen generierten alphanumerischen Wert, der in Ihren Systemen eindeutig ist. Ein activationRequestId-Wert darf 40 Zeichen nicht überschreiten. Ein zweiter Aufruf mit demselben activationRequestId-Wert gibt den ursprünglichen Status zurück, der beim ersten Aufruf mit dem activationRequestId-Wert erstellt wurde.
  • statusCheckRequestId – Ein Bezeichner, der zu einem beliebigen Zeitpunkt nach einer erfolgreichen ActivateGiftCard-Anforderung in einem ActivationStatusCheck-Aufruf verwendet wird, um den Status einer WAK abzurufen. Dieser Wert muss mit dem activationRequestId-Wert übereinstimmen, der im vorherigen ActivateGiftCard-Aufruf verwendet wurde.

Nummer der webaktivierten Karte und Prüfsumme – Die bei Endpunktanforderungen gesendete 16-stellige WAK-Nummer mit der dreistelligen Prüfsumme (Beispiel: 1400000005567585358). Da Kartennummern in der Regel über einen Bereich ausgegeben werden (Beispiel: 1400000005567585–1400000005568000), überprüfen Sie anhand der Prüfsumme, ob in Ihrer Aktivierungsanforderung die korrekte Kartennummer gesendet wurde. Diese Prüfung ist besonders wichtig, wenn eine Karte manuell aktiviert wird und Kartennummern mündlich abgelesen werden. Beachten Sie das folgende Beispiel mit WAKs. Beachten Sie, dass Amazon bei der Bereitstellung von WAKs/Einlösungscodes für das Anwendungsszenario mit Webaktivierung ein ähnliches Format verwendet.

SEQUENCE CARD NUMBER CHECKSUM AMOUNT CLAIM CODE
1 1400000005567585 358 $0.00 WA2W-A3CYCB-RDAMZ
2 1400000005567586 149 $0.00 WAS3-C8PP8R-MZMMD

Transaktionsquelle (nur Partner mit physischen Verkaufsstellen) – Standortdaten zur Identifizierung des Ortes, an dem der Geschenkgutschein aktiviert wurde. Dieser Parameter ist für alle POSA-Anforderungen (an physischen Verkaufsstellen) erforderlich.

Der Parameter setzt sich aus folgenden Komponenten zusammen:

Komponente Beschreibung
sourceId Bezeichner einer Transaktionsquellenentitä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 die Zeichenfolge der sourceId.
sourceDetails , um weitere Angaben zur Transaktionsquelle zu machen. Sie muss den institutionName-Schlüssel enthalten, wobei der Wert der Name der Quelle sein muss (z. B. Händlername). Weitere Informationen wie Standort, Telefonnummer der Quelle usw. sollten enthalten sein.
institutionParentCompany Name der Muttergesellschaft für institutionName. Wenn es keine Muttergesellschaft gibt, sollte institutionName wiederholt werden.

Zum Senden von Standortdaten des Amazon-Shops haben Sie zwei Möglichkeiten.

  1. Lange Form – Sie geben für jede Transaktion spezifische Daten zum Standort des Shops an (sourceId, institutionId und sourceDetails müssen enthalten sein).
  2. Kurze Form – Sie geben in der API-Anforderung nur die sourceId und die institutionId an. Eine separate Standortzuordnungsdatei muss gesendet werden, damit Amazon die Daten analysieren kann.

Anweisungen zur Standortzuordnungsdatei

Die folgenden Beispiele zeigen die "lange Form" einer Nutzlast für die Transaktionsquelle sowohl im XML- als auch im JSON-Format. Beachten Sie, dass sourceDetails als JSON-Blob formatiert werden müssen.

XML

<ActivateGiftCardRequest>
   <value>
      <currencyCode>USD</currencyCode>
      <amount>150</amount>
   </value>
   <activationRequestId>Awssb0327141418PM</activationRequestId>
   <cardNumber>6215366885893081</cardNumber>
   <partnerId>Apppt</partnerId>
   <externalReference>{"promoCode":"855238"}</externalReference>
   <transactionSource>
      <sourceDetails>{"institutionName" : "Fred Meyer", "institutionParentCompany" : "Kroger", "address1" : "2041 148th Ave NE", "address2" : "", "city" : "Bellevue", "state" : "Washington", "zip" : "98007", "phoneNumber" : "+14258658560"}</sourceDetails>
      <id>{"institutionId" : "97263700007" , "sourceId" : "84000000109"}</id>
   </transactionSource>
</ActivateGiftCardRequest>

JSON

{"value": {"currencyCode": "USD", "amount": 150}, "activationRequestId": "Awssb0327141418PM", "cardNumber": "6215366885893081", "partnerId": "Apppt", "externalReference": "{\"promoCode\":\"855238\"}", "transactionSource": {"sourceDetails": "{\"institutionName\" : \"Fred Meyer\", \"institutionParentCompany\" : \"Kroger\", \"address1\" : \"2041 148th Ave NE\", \"address2\" : \"\", \"city\" : \"Bellevue\", \"state\" : \"Washington\", \"zip\" : \"98007\", \"phoneNumber\" : \"+14258658560\"}", "id": "{\"institutionId\" : \"97263700007\" , \"sourceId\" : \"84000000109\"}"}}

Nur für Wiederverkäufer erforderlich – ProgramID

Sie können das Feld programID verwenden, um eine bessere Nachverfolgung von Client- und Anwendungsfalltransaktionen zu ermöglichen. Die programID ist ein genehmigter Bezeichner, der von Amazon im Rahmen eines Übermittlungsprozesses bereitgestellt wird, bei dem Sie über das Incentives-API-Portal Informationen zum Kunden und zum Anwendungsfall übermitteln. Genehmigte Übermittlungen erhalten eine Referenznummer, die jedem Transaktionsaufruf der API hinzugefügt wird. Die programID ist alphanumerisch und kann bis zu 100 Zeichen lang sein.

Die folgende Beispielmeldung zeigt die Änderungen an, die für das Feld programID erforderlich sind.

<ActivateGiftCardRequest>
  <activationRequestId>Awssb0327141418PM</activationRequestId>
  <partnerId>Awssb</partnerId>
  <cardNumber>1700000005489413</cardNumber>
  <value>
    <currencyCode>USD</currencyCode>
    <amount>10</amount>
  </value>
  <programId>ObY8ftkZQoG3lp2cmEleqg</programId>
</ActivateGiftCardRequest>

Hinweis: Bei Warengutschein-Partnern ändert sich das Anforderungsformat nicht, da die gesendete 'cardNumber' während der Kartenerstellung dem entsprechenden Warengutschein-Typ zugeordnet wird.

Vorgänge

Vorgang Beschreibung
ActivateGiftCard Versetzt eine physische Karte in einen aktiven Zustand, so dass sie von einem Kunden eingelöst werden kann.
DeactivateGiftCard Versetzt eine physische Karte in einen inaktiven Zustand, sodass sie nicht eingelöst werden kann.
ActivationStatusCheck Meldet den Aktivierungsstatus eines physischen Geschenkgutscheins.

Allgemeine Parameter

Parameter Beispielwert
HTTP-Anforderungsmethode POST
Kanonischer URI (beginnt mit /)
Kanonische Abfragezeichenfolge (leere Zeichenfolge)
Kanonische Header (siehe unten)
SignedHeaders content-type;host;x-amz-date;x-amz-target
Algorithmus AWS4-HMAC-SHA256
Anforderungsdatum 20140327T212600Z
CredentialScope 20140327/us-east-1/AGCODService/aws4_request
Dienstname AGCODService
Aktivierungsanforderungs-ID Awssb0327141418PM
Host agcod-v2-gamma.amazon.com (den zutreffenden Endpunkt finden Sie in der technischen Spezifikation)
Name der Region us-east-1 (die zutreffende Region finden Sie in der technischen Spezifikation)
Partner-ID Awssb (eigene Partner-ID verwenden)
Kartennummer 1700000005489413

Kanonische Header können sein:

content-type:application/json
host: agcod-v2-gamma.amazon.com
x-amz-date: 20140327T212600Z
x-amz-target: com.amazonaws.agcod.AGCODService.ActivateGiftCard 

oder

content-type:application/x-www-form-urlencoded; charset=UTF-8
host: agcod-v2-gamma.amazon.com
x-amz-date: 20140327T212600Z
x-amz-target: com.amazonaws.agcod.AGCODService.ActivateGiftCard 

ActivateGiftCard

Der ActivateGiftCard-Vorgang versetzt eine physische Karte in einen aktiven Zustand. Eine physische Karte im aktiven Zustand kann von einem Kunden eingelöst werden.

Sie senden eine activationRequestId, die diese Aktivierungsanforderung eindeutig identifiziert, zusammen mit anderen Details wie Nennwert, Währung usw. (zusätzlich zu den Metadaten zu dieser Anforderung, Authentifizierungsinformationen usw.).

Um diesen Vorgang auszuführen, senden Sie eine ActivateGiftCard-Anforderung. Amazon überprüft Ihr Amazon Payments-Konto oder ein anderes Vorauszahlungskonto auf ausreichendes Guthaben, bucht dann Guthaben vom Konto ab und antwortet mit einer synchronen Antwort, die den Aktivierungsstatus, cardNumber, cardStatus und activationRequestId enthält. Sie müssen die activationRequestId, den amount und den currencyCode für alle nachfolgenden Anforderungen im Zusammenhang mit derselben Transaktion speichern. Die Antwortnachricht enthält auch einige Metadaten sowie den Ausführungsstatus. Derzeit sind die zurückgegebenen Status webaktivierter Karten (WAKs) entweder Activated, AwaitingActivation, oder Invalidated.

Dieser Vorgang ist idempotent. Wenn die Incentives-API also mehr als eine Anforderung mit derselben activationRequestId erhält, führt die erste Anforderung zur Aktivierung einer neuen WAK, während alle nachfolgenden Antworten die ursprünglich aktivierte WAK zurückgeben und nicht als gesonderte Transaktionen behandelt werden.

Hinweise:

  • Ein ActivateGiftCard-Aufruf führt zu einer einzigen Aktivierung. (Die Massenaktivierung wird derzeit nicht unterstützt).
  • Als zusätzlicher Schutz gegen Betrug wird der WAK-Status in Invalidated geändert, wenn drei Einlöseversuche für einen Einlösungscode durchgeführt werden, der mit einer WAK mit variablem Nennwert verknüpft ist (Anfangsnennwert 0 $), wenn sich diese im Status AwaitingActivation befindet. Der ActivateGiftCard/DeactivateGiftCard-Aufruf kann nicht auf eine WAK im Status Invalidated angewendet werden. Wenn Sie eine große Anzahl von WAKs mit dem Status Invalidated feststellen, könnte dies auf betrügerische Aktivitäten gegen die WAK-Karten oder Prozessfehler auf Ihrer Seite hinweisen. Bitte wenden Sie sich an Ihren Account Manager, der Ihnen gerne weiterhilft.
  • Der Wert für die Währung variiert je nach Ihrem nationalen Marktsegment.

Beispiel für die HTTP-POST-Anforderung ActivateGiftCard mit JSON-Nutzlast

POST /ActivateGiftCard HTTP/1.1
accept:application/json
content-type:application/json
host:agcod-v2-gamma.amazon.com
x-amz-date:20140327T211822Z
x-amz-target:com.amazonaws.agcod.AGCODService.ActivateGiftCard
Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20140327/us-east-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=519cd671dd26ab45cca71f8a1cbd56d07409b4649b0dbba0b2f5aa248a489b1c
{
  "activationRequestId": "Awssb0327141418PM",
  "partnerId": "Awssb",
  "cardNumber": "1700000005489413",
  "value": {
    "currencyCode": "USD",
    "amount": 10
  }
}

Beispiel für die HTTP-POST-Anforderung ActivateGiftCard mit XML-Nutzlast

SIGNED REQUEST

POST /ActivateGiftCard HTTP/1.1
accept:charset=UTF-8
content-type:charset=UTF-8
host:agcod-v2-gamma.amazon.com
x-amz-date:20140327T212600Z
x-amz-target:com.amazonaws.agcod.AGCODService.ActivateGiftCard
Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20140327/us-east-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=bb4acbe8b115e24e07627fb862d2b3ea21c4f043fd4344c6f24b0a4d39961d9c
<ActivateGiftCardRequest>
    <activationRequestId>Awssb0327141418PM</activationRequestId>
    <partnerId>Awssb</partnerId>
    <cardNumber>1700000005489413</cardNumber>
    <value>
        <currencyCode>USD</currencyCode>
        <amount>10</amount>
    </value>
</ActivateGiftCardRequest>

Beispiel für ActivationGiftCardResponse

JSON

{
  "activationRequestId": "Awssb0327141418PM",
  "cardInfo": {
    "cardNumber": "1700000005489413",
    "cardStatus": "Activated",
    "expirationDate": null,
    "value": {
      "amount": 10
      "currencyCode": "USD"
    }
  },
  "status": "SUCCESS"
}

XML

<ActivateGiftCardResponse>
  <cardInfo>
    <value>
      <amount>10.0</amount>
      <currencyCode>USD</currencyCode>
    </value>
    <cardStatus>Activated</cardStatus>
    <cardNumber>1700000005489413</cardNumber>
  </cardInfo>
  <status>SUCCESS</status>
  <activationRequestId>Awssb0327141418PM</activationRequestId>
</ActivateGiftCardResponse>

Zusätzliche Anforderungen an Standorte mit physischen Verkaufsstellen

Jeder Aufruf von ActivateGiftCard, der an einem physischen Standort stattfindet, muss Details des Ortes enthalten, an dem die Transaktion stattgefunden hat. Anforderungen an diese Endpunkte können ein transactionSource-Objekt enthalten, das den physischen Standort des Ereignisses beschreibt.

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

Zum Senden von Standortdaten des Shops an Amazon gibt es zwei Möglichkeiten:

  1. Langform – Partner gibt für jede Transaktion spezifische Shop-Standortdaten an (sourceId, institutionId und sourceDetails müssen enthalten sein)
  2. Kurzform – Partner gibt in der API-Anforderung nur die sourceId und die institutionId an. Es muss eine separate Standortzuordnungsdatei gesendet werden, die diese Bezeichner physischen Standorten zuordnet. Siehe Anweisungen zur Standortzuordnungsdatei in dieser Tabelle.

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

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

<ActivateGiftCardRequest>
   <value>
      <currencyCode>USD</currencyCode>
      <amount>150</amount>
   </value>
   <activationRequestId>Awssb0327141418PM</activationRequestId>
   <cardNumber>6215366885893081</cardNumber>
   <partnerId>Apppt</partnerId>
   <externalReference>{"promoCode":"855238"}</externalReference>
   <transactionSource>
      <sourceDetails>{"institutionName" : "Fred Meyer", "institutionParentCompany" : "Kroger", "address1" : "2041 148th Ave NE", "address2" : "", "city" : "Bellevue", "state" : "Washington", "zip" : "98007", "phoneNumber" : "+14258658560"}</sourceDetails>
      <id>{"institutionId" : "97263700007" , "sourceId" : "84000000109"}</id>
   </transactionSource>
</ActivateGiftCardRequest>

Beispiel für die Langform eines JSON-Textes:

{
  "value": {
    "currencyCode": "USD",
    "amount": 150
  },
  "activationRequestId": "Awssb0327141418PM",
  "cardNumber": "6215366885893081",
  "partnerId": "Apppt",
  "externalReference": "{\"promoCode\":\"855238\"}",
  "transactionSource": {
    "sourceDetails": "{\"institutionName\" : \"Fred Meyer\", \"institutionParentCompany\" : \"Kroger\", \"address1\" : \"2041 148th Ave NE\", \"address2\" : \"\", \"city\" : \"Bellevue\", \"state\" : \"Washington\", \"zip\" : \"98007\", \"phoneNumber\" : \"+14258658560\"}",
    "id": "{\"institutionId\" : \"97263700007\" , \"sourceId\" : \"84000000109\"}"
  }
}

DeactivateGiftCard

Der DeactivateGiftCard-Vorgang versetzt eine physische Karte in einen inaktiven Zustand. Eine inaktive Karte kann nicht von einem Kunden eingelöst werden.

Sie können eine WAK unter folgenden Bedingungen deaktivieren:

  • Der mit der WAK verknüpfte Einlösungscode wird nicht von einem Amazon-Kunden beansprucht.
  • Die WAK befindet sich nicht im Status Invalidated.
  • Die WAK wurde zuvor von demselben Partner aktiviert. Sowohl die ursprüngliche zum Aktivieren der WAK verwendete activationRequestId als auch die Kartennummer müssen für einen DeactivateGiftCard-Vorgang angegeben werden.

Um diesen Vorgang auszuführen, senden Sie eine DeactivateGiftCard-Anforderung. Die Incentives-API antwortet mit einer synchronen DeactivateGiftCardResponse.

Dieser Vorgang ist idempotent. Wenn also die Incentives-API mehr als eine Anforderung mit derselben activationRequestId, empfängt, führt die erste Anforderung zur Deaktivierung der WAK, während alle nachfolgenden Antworten nichts bewirken (sie werden nicht als gesonderte Transaktion behandelt).

Hinweis: ActivateGiftCard/DeactivateGiftCard-Vorgänge sollten nur mit physischen Geschenkgutscheinen und nicht mit Einlösungscodes verwendet werden, die mit der CreateGiftCard-API erstellt wurden.

Beispiel für die HTTP-POST-Anforderung DeactivateGiftCard mit JSON-Nutzlast

SIGNED REQUEST

POST /DeactivateGiftCard HTTP/1.1
accept:application/json
content-type:application/json
host:agcod-v2-gamma.amazon.com
x-amz-date:20140327T213727Z
x-amz-target:com.amazonaws.agcod.AGCODService.DeactivateGiftCard
Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20140327/us-east-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=86a6ce1bfdb1e0e5842b5e351ad87058b673bdc6f7fd770c6fdb8349a1de1bde
{"activationRequestId": "Awssb0327141418PM", "partnerId": "Awssb", "cardNumber": "1700000005489413"}

Beispiel für die POST-Anforderung DeactivateGiftCard mit XML-Nutzlast

SIGNED REQUEST

POST /DeactivateGiftCard HTTP/1.1
accept:charset=UTF-8
content-type:charset=UTF-8
host:agcod-v2-gamma.amazon.com
x-amz-date:20140327T213942Z
x-amz-target:com.amazonaws.agcod.AGCODService.DeactivateGiftCard
Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20140327/us-east-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=0ace0a2eaefc9ecf62e1224c7e59abe46af934a8e772b808c18dccdfdab009a5
<DeactivateGiftCardRequest>
    <activationRequestId>Awssb0327141418PM</activationRequestId>
    <partnerId>Awssb</partnerId>
    <cardNumber>1700000005489413</cardNumber>
</DeactivateGiftCardRequest>

Beispiel für DeactivateGiftCardResponse

JSON

{
  "activationRequestId": "Awssb0327141418PM",
  "cardInfo": {
    "cardNumber": "1700000005489413",
    "cardStatus": "AwaitingActivation",
    "expirationDate": null,
    "value": null
  },
  "status": "SUCCESS"
}

XML

<DeactivateGiftCardResponse>
  <cardInfo>
    <cardStatus>AwaitingActivation</cardStatus>
    <cardNumber>1700000005489413</cardNumber>
  </cardInfo>
  <status>SUCCESS</status>
  <activationRequestId>Awssb0327141418PM</activationRequestId>
</DeactivateGiftCardResponse>

ActivationStatusCheck

Verwenden Sie den ActivationStatusCheck-Vorgang, um den Status der WAK nach dem Ausführen des ActivateGiftCard/DeactivateGiftCard-Aufrufs zu überprüfen. Amazon antwortet mit einer synchronen ActivationStatusCheckResponse, die den aktuellen Status der WAK angibt.

Die zurückgegebenen WAK-Status sind Activated, AwaitingActivation oder Invalidated.

Hinweis: Die Vorgänge CreateGiftCard/CancelGiftCard und ActivateGiftCard/DeactivateGiftCard sollten nicht vermischt werden. Beispielsweise sollte ein Einlösungscode, der mit dem CreateGiftCard-Aufruf erstellt wurde, nicht mit dem DeactivateGiftCard-Aufruf deaktiviert werden. Ebenso sollte ein mit ActivateGiftCard aktivierter Einlösungscode nicht mit dem CancelGiftCard-Aufruf storniert werden.

Beispiel für dieHTTP POST-Anforderung ActivationStatusCheck mit JSON-Nutzlast

SIGNED REQUEST

POST /ActivationStatusCheck HTTP/1.1
accept:application/json
content-type:application/json
host:agcod-v2-gamma.amazon.com
x-amz-date:20140327T234321Z
x-amz-target:com.amazonaws.agcod.AGCODService.ActivationStatusCheck
Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20140327/us-east-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=ae3aa76cdc3043d45ca962a3a85ea9b95c6202a87f9700e7fe04b4c8d956ca31
{"statusCheckRequestId": "Awssb0327141418PM", "partnerId": "Awssb", "cardNumber": "1700000005489413"}

Beispiel für die HTTP-POST-Anforderung ActivationStatusCheck mit XML-Nutzlast

SIGNED REQUEST

POST /ActivationStatusCheck HTTP/1.1
accept:charset=UTF-8
content-type:charset=UTF-8
host:agcod-v2-gamma.amazon.com
x-amz-date:20140327T234634Z
x-amz-target:com.amazonaws.agcod.AGCODService.ActivationStatusCheck
Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20140327/us-east-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=96025ab925782595bffde21366bcd1927406ce5ddb723e89088f2cb0026040e8
<ActivationStatusCheckRequest>
  <statusCheckRequestId>Awssb0327141418PM</statusCheckRequestId>
  <partnerId>Awssb</partnerId>
  <cardNumber>1700000005489413</cardNumber>
</ActivationStatusCheckRequest>

Beispiel für ActivationStatusCheckResponse

JSON

Wenn die WAK noch nicht aktiviert ist:

{
  "cardInfo": {
    "cardNumber": "1700000005489413",
    "cardStatus": "AwaitingActivation",
    "expirationDate": null,
    "value": null
  },
  "status": "SUCCESS",
  "statusCheckRequestId": "Awssb0327141418PM"
}

ODER, wenn die WAK bereits aktiviert ist:

{
  "cardInfo": {
    "cardNumber": "1700000005489413",
    "cardStatus": "Activated",
    "value": null
  },
  "status": "SUCCESS",
  "statusCheckRequestId": " Awssb0327141418PM"
}

XML

Wenn die WAK noch nicht aktiviert ist:

<ActivationStatusCheckResponse>
  <cardInfo>
    <cardStatus>AwaitingActivation</cardStatus>
    <cardNumber>1700000005489413</cardNumber>
  </cardInfo>
  <status>SUCCESS</status>
  <statusCheckRequestId>Awssb0327141418PM</statusCheckRequestId>
</ActivationStatusCheckResponse>

ODER, wenn die WAK bereits aktiviert ist:

<ActivationStatusCheckResponse>
  <cardInfo>
    <cardStatus>Activated</cardStatus>
    <cardNumber>1700000005489413</cardNumber>
  </cardInfo>
  <status>SUCCESS</status>
  < statusCheckRequestId> Awssb0327141418PM</statusCheckRequestId>
</ActivationStatusCheckResponse>

Testbeispiele

Wir haben Simulations-Fehleranforderungs-IDs bereitgestellt, um bestimmte Antworten mit den Aufrufen Activate/Deactivate zu simulieren. Beim Simulieren einer Fehlerantwort muss die Simulations-Fehleranforderungs-ID als activationRequestId übergeben werden. Die für die übrigen Felder angegebenen Werte werden in der Antwort wiederholt.

SUCCESS-Testsimulation mit requestId "F0000"

SIGNED REQUEST

POST /ActivateGiftCard HTTP/1.1
accept:charset=UTF-8
content-type:charset=UTF-8
host:agcod-v2-gamma.amazon.com
x-amz-date:20140402T234117Z
x-amz-target:com.amazonaws.agcod.AGCODService.ActivateGiftCard
Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20140402/us-east-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=fdd5f610c04cea390b07d6f2e4891516f6bdfa0158595e7deda8eedc8468422d
<ActivateGiftCardRequest><activationRequestId>F0000</activationRequestId> <partnerId>Awssb</partnerId><cardNumber>abc123</cardNumber><value><currencyCode>phonybucks</currencyCode><amount>10</amount></value></ActivateGiftCardRequest>

RESPONSE

<ActivateGiftCardResponse>
  <cardInfo>
    <value>
      <amount>10.0</amount>
      <currencyCode>phonybucks</currencyCode>
    </value>
    <cardStatus>Activated</cardStatus>
    <cardNumber>abc123</cardNumber>
  </cardInfo>
  <status>SUCCESS</status>
  <activationRequestId>F0000</activationRequestId>
</ActivateGiftCardResponse>

FAILURE-Testsimulation mit requestId "F2005"

SIGNED REQUEST

POST /ActivateGiftCard HTTP/1.1
accept:charset=UTF-8
content-type:charset=UTF-8
host:agcod-v2-gamma.amazon.com
x-amz-date:20140402T234840Z
x-amz-target:com.amazonaws.agcod.AGCODService.ActivateGiftCard
Authorization:AWS4-HMAC-SHA256 Credential=AKIAJBYCL67O6NJUNYBQ/20140402/us-east-1/AGCODService/aws4_request, SignedHeaders=accept;content-type;host;x-amz-date;x-amz-target, Signature=fa280d821ac7a8ba3e031e463c7c121509642cd6f7bf54c3a4586bfc2d8eae8f
<ActivateGiftCardRequest><activationRequestId>F2005</activationRequestId> <partnerId>Awssb</partnerId><cardNumber>abcdef</cardNumber><value><currencyCode>phonybucks</currencyCode><amount>10</amount></value></ActivateGiftCardRequest>

RESPONSE

<AGCODValidationException>
  <Message>Currency Code can't be null or empty</Message>
  <errorType>InvalidCurrencyCodeInput</errorType>
  <errorCode>F200</errorCode>
  <agcodResponse>
    <status>FAILURE</status>
  </agcodResponse>
</AGCODValidationException>

Testskript zum Aktivieren von physischem Bestand (andere Bezeichnung: POSA)

Um Ihre Integration mit der API zu überprüfen, führen Sie die folgenden Tests durch:

Testbeschreibung Einzelheiten zum Testfall Erwartetes Ergebnis
1. Statusüberprüfung Senden Sie eine ActivationStatusCheck-Anforderung für eine Sandbox-Kartennummer, die zuvor nicht verwendet wurde. Als Antwort sollten Sie eine SUCCESS-Meldung mit dem Kartenstatus Aktiviert erhalten.
2. Karte aktivieren Senden Sie eine ActivateGiftCard-Anforderung an die Sandbox-URL für die Kartennummer, die in der Statusüberprüfung (1) verwendet wird. Als Antwort sollten Sie eine SUCCESS-Meldung mit dem Kartenstatus Activated erhalten.
3. Karte deaktivieren Senden Sie eine DeactivateGiftCard-Anforderung mit derselben requestId für die aktivierte Kartennummer (2). Als Antwort sollten Sie die Meldung SUCCESS mit dem Kartenstatus AwaitingActivation erhalten.
4. Idempotenz aktivieren Senden Sie eine neue ActivateGiftCard-Anforderung und notieren Sie die Antwort. Senden Sie dieselbe Aktivierungsanforderung erneut mit derselben Anforderungsnummer und demselben Betrag. Sie sollten ein SUCCESS-Meldung mit der gleichen Antwort wie die ursprüngliche Anforderung erhalten.

Häufig gestellte Fragen zur Webaktivierung

F.1 Wie verwende ich die APIs zum Aktivieren und Deaktivieren?

A.1 Verwenden Sie den ActivateGiftCard-Vorgang, um einen Geschenkgutschein zu aktivieren, indem Sie die activationRequestId und den Betrag (je nach Kartentyp Betrag mit oder ohne Nennwert) eingeben. Wenn Sie einen Geschenkgutschein bereits erfolgreich aktiviert haben und ihn stornieren müssen, müssen Sie die ursprüngliche activationRequestId sowie die Werte für Betrag und Währung angeben, die Sie in dem erfolgreichen ActivateGiftCard-Vorgang verwendet haben. Wenn bei der Durchführung eines ActivateGiftCard- oder DeactivateGiftCard-Vorgangs eine Zeitüberschreitung vom AGCOD Gateway angezeigt wird, und Sie nicht sicher sind, ob der Aufruf erfolgreich war, rufen Sie ActivationStatusCheck auf, um den Status des Gutscheins zu überprüfen.


F.2 Bei einem ActivateGiftCard-Aufruf erhalte ich die Fehlermeldung "Die Karte wurde bereits mit einer anderen Anforderungs-ID aktiviert".

A.2 Dies kann durch dieselbe Kartenseriennummer verursacht werden, die mit einer anderen activationRequestId aktiviert wurde. Suchen Sie die ursprüngliche activationRequestId und versuchen Sie den Aufruf erneut.


F.3 Gibt es Zeitlimits ab dem Zeitpunkt, an dem eine ActivateGiftCard-Anforderung gestellt und zu dem eine DeactivateGiftCard akzeptiert wird?

A.3 Derzeit gibt es kein Zeitlimit. Aufrufe von DeactivateGiftCard schlagen fehl, nachdem eine Verwendungstransaktion für den Geschenkgutschein verarbeitet wurde. Wenn der Geschenkgutschein beispielsweise von Ihrem Endkunden beansprucht wurde, schlägt ein Aufruf von DeactivateGiftCard fehl. Darüber hinaus kann ein aktivierter Geschenkgutschein nach dem Ablaufdatum nicht deaktiviert werden. Geschenkgutscheine, die in den USA, Kanada und Australien ausgestellt wurden, laufen nicht ab.