Amazon Processor and API

This page explains the Amazon Gift Card On Demand integration from an operations and customer-service perspective: how Amazon orders are issued, which settings control each regional brand, and what evidence to gather before escalating a failed issue or cancellation.

What Amazon does

Amazon is a synchronous processor for digital gift cards, but it is not always a single-attempt flow. The application submits an AGCOD request directly to Amazon, retries temporary RESEND responses automatically, and stores Amazon's creationRequestId as the processor reference when a code is issued successfully.

The processor is configured as:

Order lifecycle

1. A partner orders an Amazon brand and amount through the normal gift-card API.
2. The processor selects credentials from config/amazon.php for the current brand slug and, when present, the partner's Tillo entity override.
3. The issue payload uses Amazon's CreateGiftCard operation. It sends a generated creationRequestId, the Amazon partnerId, the requested amount and currency, and the internal sale UUID as externalReference.
4. If the brand config enables sendProgramID, the payload also includes a programId. This is the partner's slug, but if there has been an agreement with Amazon can be overridden with programId partner attribute when one is configured.
5. When Amazon responds with SUCCESS, the application stores the returned creationRequestId as the processor reference, stores the gcClaimCode, formats the expiry timestamp, creates the delivery URL/barcode, and marks the card successful.
6. When Amazon responds with RESEND, the processor retries automatically up to three total attempts with short backoff delays.
7. If all issue attempts still end in RESEND, the issue fails and the application dispatches an AmazonCancellation job that waits for the code to become issuable and then attempts to cancel the original Amazon request using the returned creationRequestId and gcId.

!IMPORTANT Do not manually place a second Amazon order while a RESEND case or queued cancellation is still unresolved. The original request may still complete successfully, and a manual re-order can create a duplicate purchase.

Settings

Processor settings

The processor-level settings are environment-backed values in config/amazon.php.

Each supported brand slug then has its own regional AGCOD configuration, including endpoint, AWS region, and a default discountStandard credential set with accessKey, secretKey, and partnerID.

The repository currently defines separate brand entries for amazon, amazon-rewards, amazon-vb, amazon-de, amazon-fr, amazon-it, amazon-es, amazon-nl, amazon-se, amazon-usa, amazon-ca, amazon-au, amazon-at, amazon-be, amazon-pl, amazon-eb-uk, amazon-pt, amazon-ie, and amazon-rewards-ie.

Some brand entries have extra credential variants. For example, amazon-usa defines both discountStandardBackup credentials and a tilloinc credential override. The processor also checks for entity-specific credentials using the current partner's Tillo entity slug, so the same Amazon brand can route through different AGCOD accounts depending on the partner setup.

Brand settings

Amazon orders by amount rather than by a per-denomination provider SKU. The repository does not define Amazon brand-to-SKU mappings like the asynchronous processor guides do.

Brand setup still matters in three places:

1. The brand slug must match the correct regional config entry so the processor uses the right endpoint, region, and AGCOD account.
2. The brand's enabled denominations must allow the requested value. The original Amazon UK brand was seeded with fixed values from £5 to £100 plus open-value.
3. If sendProgramID is enabled for that brand, the partner slug is forwarded to Amazon as programId. If a non-empty partner attribute named programId set is forwarded to Amazon as programId instead. This supports partners that need an alternative Amazon program identifier.

Alternative programId

Use the partner attribute named programId when Amazon requires a program identifier that differs from the partner slug. The override applies only when the Amazon brand configuration has sendProgramID enabled; it is sent on the CreateGiftCard request and does not change the credentials or partnerId used for the request.

For an order using an owner with:

• sendProgramID: true; and
• a non-empty programId partner attribute;

Amazon receives that attribute value. Without a non-empty attribute, Amazon receives the owner's slug. When investigating a program-routing issue, check both the brand's sendProgramID setting and the owner's programId partner attribute before treating the value as incorrect.

API operations

Amazon requests are JSON payloads signed with AWS Signature Version 4 and sent to the configured AGCOD endpoint. The processor uses these named operations:

The processor class also defines a GetGiftCard operation constant, but the documented business flow in this repository is issue and cancel rather than customer-service balance checking.

Customer-service investigation

When an Amazon order or cancellation needs investigation, check these values in order:

1. The Amazon brand slug, currency, and requested amount.
2. Whether the partner's Tillo entity should have used default credentials or an entity-specific Amazon account.
3. The sale UUID, which is sent to Amazon as externalReference.
4. The sale's processor reference, which is Amazon's creationRequestId.
5. The processor interaction audit request and response for the relevant sale.
6. Whether the last issue response was SUCCESS, RESEND, or FAILURE.
7. For cancellations, the original audit record's requestID and gcId, because the cancellation payload is built from those values rather than from the displayed gift code.

Returned gcClaimCode values are hashed before processor interaction responses are stored, so support should rely on the sale record, processor reference, and audit metadata rather than expecting to retrieve the raw code from the interaction log.

If the issue failed with F300 / InsufficientFunds, treat it as a processor funding problem rather than a customer-input problem. If cancellation failed with F200 / CancelRequestArrivedAfterTimeLimit, the repository treats that as a warning-level late-cancellation case, which means the code was already too old for Amazon's cancellation window.

Limitations and support contacts

The repository does not implement Amazon balance lookup as a customer-service operation. Cancellation is implemented, but it is time-sensitive and can return a late-arrival warning once the request is older than 15 minutes.

When escalating, include the sale UUID, processor reference, partner slug, timestamps, brand slug, and relevant request/response evidence. Do not include raw credentials, and do not assume the visible gift code in the customer journey is available in stored processor interaction logs.

Related code

• app/Processors/AmazonProcessor.php — issue, cancellation, retry, credential selection, and audit logging.
• app/Jobs/Amazon/AmazonCancellation.php — queued cancellation recovery after repeated temporary issue failures.
• config/amazon.php — global throttling, regional endpoints, and brand credential sets.
• database/migrations/2018_03_16_163107_RCC-2572_add_issuer_attributes.php — Amazon support and commercial contacts.
• database/migrations/2016_08_03_091949_add_denominations_for_amazon_brand.php — original Amazon denomination setup.
• database/migrations/2024_01_11_092649_r_c_c-13432_update_amazon_park_processor_types.php — processor type update to SKU_IN_ENV.
• tests/Characterisation/Unit/Processors/AmazonProcessorTest.php — successful issue and cancellation behaviour, credential overrides, and audit expectations.
• tests/Feature/Processors/AmazonProcessorTest.php — insufficient-funds handling and operational logging.
• tests/Unit/App/Jobs/AmazonCancellationTest.php — cancellation job logging and retry flow.