HomeDocumentationCode SamplesAPI ReferenceAnnouncementsModelsRelease NotesFAQGitHubVideos
Developer HubAPI StatusSupport
Documentation
Developer HubAPI StatusSupport

Third-Party Provider Signature Guidance

Learn how to create third-party payment provider signatures.

To generate a successful signature, follow the instructions that are documented in the RFC 9421 specification. Note that there are aspects of the signature generation that Amazon enforces for TPPs making SP-API requests. These are documented in the following sections.

Signature components

RFC 9421 describes the process of communicating which HTTP message components are signed in a request. You must include the following message components when you generate a signature.

📘

Note

Failure to include the following components results in a signature verification failure. You can add these components in any order.

HTTP fields (message headers)

HeaderDescription
x-amz-access-tokenThe LWA access token that is used to make the request.
x-amzn-content-digestThe request payload's sha-256 digest. For requests without a payload, create the sha-256 digest on an empty string.

For additional information, refer to HTTP Fields.

Derived components

ComponentDescription
@methodThe request's HTTP method. The value must be upper case (for example GET, POST).
@queryThe normalized query string that is defined by the URI and includes the leading ? character.
If the request doesn’t have a query, you must populate the component value with ? when you create the signature base mentioned in RFC 9421.
The value must be derived after you perform all the necessary encoding, such as Percentile-Encoding. Any further modifications you make to queryString, which are not included when you create the signature, cause signature failure.

For additional information, refer to Derived Components.

Signature parameters

ParameterDescription
createdAn epoch timestamp in seconds.
If the created epoch points to a time older than five minutes by the time request is received, the signature is considered expired and the call is denied.
algAn algorithm that you use to sign the signature base.
The value for alg must be PS512. For additional details, refer to Signing algorithm.

For additional information, refer to Signature Parameters.

🚧

Caution

All request header values are case sensitive. If there is any case mismatch, your signature verification fails.

Signature label

RFC 9421 allows multiple signatures within the same header (to disambiguate, use signature labels). SP-API only uses one signature, which is identified by the x-amzn-psd2 signature label. You must use it in the Signature and Signature-Input headers to identify PSD2-related information.

Signing algorithm

A signature is generated on the signature base string that is created when you complete the steps in RFC 9421. After you generate your signature base string, you must use the private key that is associated with your electronic NCA Certificate to sign the request with the PS512 algorithm. This algorithm is the only one that is currently supported for SP-API requests.

The certificate that is associated with the private key you used in the signature must be passed as a header (x-amzn-psd2-certificate) in your SP-API request. The certificate must be a PEM-formatted string in Base64 encoding that begins with -----BEGIN CERTIFICATE----- and ends with -----END CERTIFICATE-----.

If you use any non-allowed characters in the certificate, your SP-API request is denied. You must use only certificates that are intended to sign HTTP requests that are issued by Qualified Trust Service Providers (QTSPs).

🚧

Caution

The certificate that you use must be associated with the organization identifier that you provided in your developer registration. If there is a mismatch, your request is denied.

Error responses

If your request signature validation fails, you get a 403 Error that contains additional information in the body. For example:

{
    "errors": [
        {
            "code": "Unauthorized",
            "message": "Access to requested resource is denied.",
            "details": "Reason for error."
        }
    ]
}

The following is a list of possible values for the details field:

Error messageDescription
TPP certificate required but missing from requestThe x-amzn-psd2-certificate header is missing.
TPP certificate has invalid formatThe provided certificate is not in valid PEM format.
Content Digest header required but missing from requestThe x-amzn-content-digest request header is missing.
Invalid Content DigestThe content digest couldn’t be verified, or you used an unsupported algorithm. Only SHA-256 is supported.
Signature-Input header required but not presentedThe Signature-Input request header is missing.
Signature-Input header is invalidThe Signature-Input header value doesn’t adhere to RFC 9421 specification.
Request PSD2 Signature is InvalidInvalid signature. This can have multiple causes, such as using the wrong private key or certificate, or a typo.
Signature header is required but not presentedThe Signature request header is missing.

Example signature

The following example is a signature base string that contains all required components:

"x-amz-access-token": Atza|IgEBIN...
"x-amzn-content-digest": sha-256=:fadf3qr3TAFASEG3234gADA+krdzMzYayg4YFig=:
"@method": POST
"@query": ?key2=value2&key1=value1
"@signature-params": ("x-amz-access-token" "x-amzn-content-digest" "@method" "@query");created=1720137600;alg="PS512";

The associated Signature-Input header is:

Signature-Input: x-amzn-psd2=("x-amz-access-token" "x-amzn-content-digest" "@method" "@query");created=1720137600;alg="PS512"

The following example is a signature header that has the Signature label:

Signature: x-amzn-psd2=:cyqStwls2k3Xs8SSzDvDhxWEc_P0dNxV5I6Tp... :

Updated 26 days ago