Key Upgrade API
The Amazon Pay CV2 Key Upgrade API allows you to exchange Amazon Pay CV1 Credentials (AWS Access Key Id and Secret Access Key) against credentials required for Amazon Pay CV2 APIs programmatically. Using the AWS AccessKey Id and a signature calculated with the Secret Access Key, call the GetPublicKeyId action to generate a Public Key Id that will be used to make API calls to the CV2 API.
How to use the publicKeyId : The Public Key ID you receive will be set in the authorization header of each CV2 API call. Here is an example of a request using the public key Id:
Host: pay-api.amazon.com
Accept: application/json
Authorization: AMZN-PAY-RSASSA-PSS PublicKeyId=f4fc06fc-c5a7-11e7-abc4-cec278b6b50a,
SignedHeaders=content-type;x-amz-pay-date,
Signature=4164128ec5d1b9da1700167ab2ccda8125f472c8bb9de447cebf5d741ee317c8
X-Amz-Pay-Date: 20190305T024410Z
Content-type: application/json
GET https://pay-api.amazon.com/live/v1/authorizationTokens/amzn.mws.123456789?merchantId=aX123BFs343
Generating Private and Public key pair
In order to generate the key pair required for the key upgrade, see the Manually Generating Key Pairs guide.
Request
You can call the HTTP GET request with the endpoint, path, and parameters specified below.
| Region | Endpoint |
|---|---|
| NA | pay-api.amazon.com |
| EU | pay-api.amazon.eu |
| JP | pay-api.amazon.jp |
Path: /live/v2/publicKeyId
Request query parameters
| Parameter | Description | Valid values |
|---|---|---|
| Action (required) Type:String | The action to be performed | GetPublicKeyID |
| AWSAccessKeyId (required) Type:String | The MWSAccessKeyId that you received when you registered for Amazon MWS. | |
| MerchantId (required) Type:String | Your Amazon Pay merchant ID | |
| PublicKey (required) Type:String | The public key from your self-generated private/public key pair | Your public key string (the text value of the public.pem file generated in the steps above) |
| SignatureVersion (required) Type:String | Which signature version is being used. This is Amazon MWS-specific information that tells Amazon MWS the algorithm you used to form the string that is the basis of the signature. | 2 |
| SignatureMethod (required) Type:String | The HMAC hash algorithm you are using to calculate your signature. Both HmacSHA256 and HmacSHA1 are supported hash algorithms, but Amazon recommends using HmacSHA256. | HmacSHA256 |
| Signature (required) Type:String | For steps to calculate the signature using the Secret Access Key, see How to calculate the signature. | |
| Timestamp (required) Type:DateTime | The current time | The current date and time or the expiration date and time for the request in ISO 8601 date time format. |
See additional description of parameters Required request parameters
Watch our Amazon Pay University video on Locating your MWS Keys
Successful response headers
| Header | Description |
|---|---|
| Content-Type | text/json |
Successful response elements
| Parameter | Description |
|---|---|
| publicKeyID Type:String | Public Key ID that will be used to make future CV2 API calls |
| publicKeyIDName Type:String | Public Key ID Name that will be used to make future CV2 API calls |
Sample requests and responses
Request message example
- Note : In the actual Query request, there are no spaces or newline characters. The request is a continuous line of text. The version below is formatted for human readability.
Accept: application/json
Content-type: application/json
GET https://pay-api.amazon.com/live/v2/publicKeyId?
MerchantId=AKI12345
&AWSAccessKeyId=AKIAIOSFODNN7EXAMPLE
&Action=GetPublicKeyId
&SignatureMethod=HmacSHA256
&SignatureVersion=2
&Timestamp=2022-07-28T15%3A19%3A30
&PublicKey=SamplePublicKey
&Signature=<signature_calculated_with_secret_key>
See here for detailed information on how to generate the value for the request parameter Signature.
Example response
HTTP/1.1 201 Created
Server: Server
Date: Thu, 01 Dec 2022 03:04:33 GMT
Content-Type: application/json
Content-Length: 105
Connection: keep-alive
x-amz-rid: H43Z5RG0QPKP6NPHTEST
X-Amz-Pay-Request-Id: 06bf7dc2-b364-4c08-b5ca-4761ba526bd0
Vary: Content-Type,Accept-Encoding,User-Agent
Strict-Transport-Security: max-age=47474747; includeSubDomains; preload
{"publicKeyId":"AFZO6SDUYY5P6LEAZRJ2TEST","publicKeyIdName":"TEST345_KRX_dv9zPjzYvNHJANrEsSmiVEc"}
Error response message example
HTTP/1.1 400 Bad Request
Server: Server
Date: Wed, 30 Nov 2022 22:38:07 GMT
Content-Type: application/json
Content-Length: 132
Connection: keep-alive
x-amz-rid: 954JA5DWNKDS2WJENNBS
X-Amz-Pay-Request-Id: f897b885-bda1-472c-b9f4-b0d079ef6056
Vary: Content-Type,Accept-Encoding,User-Agent
Strict-Transport-Security: max-age=47474747; includeSubDomains; preload
{"reasonCode":"InvalidRequest","message":"The query string parameters [AWSAccessKeyId] are required and are missing in the request"}
Error response elements
| Parameter | Description | Type |
|---|---|---|
| Code | Machine readable error code | String |
| Message | Human-readable error description | String |
Error response message examples
If there is a problem fulfilling your request, you will receive an HTTP error response. The error codes for the GetPublicKeyID API request include:
| Status | Error code |
|---|---|
| 400 BAD_REQUEST | InvalidParameterValue |
| 400 BAD_REQUEST | InvalidRequest |
| 401 UNAUTHORIZED | InvalidRequestSignature |
| 403 FORBIDDEN | AccessDenied |
| 500 INTERNAL_SERVER_ERROR | InternalServerError |
| 503 SERVICE_UNAVAILABLE | ServiceUnavailable |
Generic errors can be found here.