Buyer
The Buyer object includes details about the buyer such as name, email, unique Amazon Pay identifier, default shipping address postal and country code. You should only use this object if you’ve implemented Amazon Sign-in and only because you need to retrieve Buyer details before the buyer starts Amazon Pay checkout. Once checkout has started, you should use Get Checkout Session and Get Charge Permission instead.
Note: If your publicKeyId
does not have an environment prefix (does not begin with 'SANDBOX' or 'LIVE') follow
these instructions instead.
Note: If your publicKeyId has an environment prefix (for example: SANDBOX-AFVX7ULWSGBZ5535PCUQOY7B) follow
these instructions instead.
Supported operations:
- Get Buyer - GET https://pay-api.amazon.com/:version/buyers/:buyerToken
- Get Buyer - GET https://pay-api.amazon.eu/:version/buyers/:buyerToken
- Get Buyer - GET https://pay-api.amazon.jp/:version/buyers/:buyerToken
- Get Buyer - GET https://pay-api.amazon.com/:environment/:version/buyers/:buyerToken
- Get Buyer - GET https://pay-api.amazon.eu/:environment/:version/buyers/:buyerToken
- Get Buyer - GET https://pay-api.amazon.jp/:environment/:version/buyers/:buyerToken
Buyer object
Parameter
|
Description
|
buyer
Type: buyer
|
Details about the buyer, such as their unique identifier, name, and email
|
Type: buyer
Parameter
|
Description
|
buyerId
Type: string
|
Unique Amazon Pay buyer identifier
|
countryCode
Type: string
|
Buyer default shipping address country
|
email
Type: string
|
Buyer email address
|
name
Type: string
|
Buyer name
|
postalCode
Type: string
|
Buyer default shipping address postal code
|
shippingAddress
Type: address
|
Buyer default shipping address
|
billingAddress
Type: address
|
Buyer default billing address
|
phoneNumber
Type: string
|
Buyer default billing address phone number
|
primeMembershipTypes
Type: list<primeMembershipType>
|
List of buyer Prime memberships. This data is not available for general use
|
Type: address
Parameter
|
Description
|
name
Type: string
|
Address name
Max length: 50 characters/bytes
|
addressLine1
Type: string
|
The first line of the address
Max length: 180 characters/bytes
|
addressLine2
Type: string
|
The second line of the address
Max length: 60 characters/bytes
|
addressLine3
Type: string
|
The third line of the address
Max length: 60 characters/bytes
|
city
Type: string
|
City of the address
Max length: 50 characters/bytes
|
county
Type: string
|
County of the address
Max length: 50 characters/bytes
|
district
Type: string
|
District of the address
Max length: 50 characters/bytes
|
stateOrRegion
Type: string
|
The state or region:
- US and CA addresses - Response will always be a 2-character code
- All other countries - This element is free text and can be either a 2-character code, fully spelled out, or abbreviated
Max length: 50 characters/bytes
|
postalCode
Type: string
|
Postal code of the address
Max length: 20 characters/bytes
|
countryCode
Type: string
|
Country code of the address in ISO 3166 format
Max length: 3 characters/bytes
|
phoneNumber
Type: string
|
Phone number
Max length: 20 characters/bytes
|
Operations
Get Buyer
Get Buyer will only return buyerId by default. You must explicitly request access to additional buyer details using the button signInScopes parameter.
Amazon Pay will only provide the token required to retrieve buyer details after the buyer signs in. It will be appended to the signInReturnUrl as a query parameter and expires after 24 hours.
Request
curl "https://pay-api.amazon.com/:version/buyers/:buyerToken" \
-X GET
-H "authorization:Px2e5oHhQZ88vVhc0DO%2FsShHj8MDDg%3DEXAMPLESIGNATURE"
-H "x-amz-pay-date:20201012T235046Z"
curl "https://pay-api.amazon.com/:environment/:version/buyers/:buyerToken" \
-X GET
-H "authorization:Px2e5oHhQZ88vVhc0DO%2FsShHj8MDDg%3DEXAMPLESIGNATURE"
-H "x-amz-pay-date:20201012T235046Z"
Request parameters
Name
|
Location
|
Description
|
buyerToken
(required)
Type: string
|
Path Parameter
|
Token used to retrieve buyer details. This value is appended as a query parameter to signInReturnUrl
Max length: 1000 characters/bytes
|
Sample Code
<?php
include 'vendor/autoload.php';
$amazonpay_config = array(
'public_key_id' => 'YOUR_PUBLIC_KEY_ID',
'private_key' => 'keys/private.pem', // Path to RSA Private Key (or a string representation)
'region' => 'YOUR_REGION_CODE',
'algorithm' => 'AMZN-PAY-RSASSA-PSS-V2'
);
try {
$buyerToken = 'eyL7YthG12BvRUYiLCJlbmMiOiJBMjU2R0NNIiwidGFnIjoiNXQ3NmhOTVhKN0tidkpSbHR0WmggBn12JmnY6yI6IkExMjhHQ01LVyIsIml2IjoidXFUeWl5NzUtMlU1RVk0RyJ9.iy6tY93sESc2fHVj49ynJO3e45ZiGkpDbmVYjgAimiM.K4nVJFzrHV-Pbotw.CumBT12hN5Bih_V0UI635PuIZ_IAD-HcH42hy5NuliOhFoAoFf4uNnVpjjDbPWnkYcdgtettavJlKGPG5wG2zaHJc2AFODXuuHklYGUbOwX1Z9JBXJExXfcLyvM_d5Zh4eaXkJWB3BUCfrP4afG9llHmwOHRvORu4vyGzG4JuBrZVeZ69EK0yqDMOYgbR44Bospf9XCDeV_NQfkmZWerjHaWe_ltYgCEcbUQu4-Snb76NbVT8Uf85KNocQfi4SYJn5tUKTjh2uR9XHeQhQY.f7UR3zVnUDe_WfqsvrPMNw';
$client = new Amazon\Pay\API\Client($amazonpay_config);
$result = $client->getBuyer($buyerToken);
if ($result['status'] === 200) {
$response = json_decode($result['response'], true);
} else {
// check the error
echo 'status=' . $result['status'] . '; response=' . $result['response'];
}
} catch (Exception $e) {
// handle the exception
echo $e;
}
?>
using Amazon.Pay.API;
using Amazon.Pay.API.Types;
using Amazon.Pay.API.WebStore;
using Amazon.Pay.API.WebStore.Types;
using Amazon.Pay.API.WebStore.Buyer;
using Microsoft.AspNetCore.Mvc.RazorPages;
public class Sample : PageModel
{
public BuyerResponse Buyer { get; private set; }
public WebStoreClient InitiateClient()
{
// set up config
var payConfiguration = new ApiConfiguration
(
region: Region.YOUR_REGION_CODE,
publicKeyId: "YOUR_PUBLIC_KEY_ID",
privateKey: "PATH_OR_CONTENT_OF_YOUR_PRIVATE_KEY",
algorithm: AmazonSignatureAlgorithm.V2
);
// init API client
var client = new WebStoreClient(payConfiguration);
return client;
}
public void OnGet()
{
// the token as retrieved from the URL
string buyerToken = HttpContext.Request.Query["buyerToken"];
// get the buyer details
// NOTE: the BuyerResponse that is returned here contains properties for buyerId, name, email, shippingAddress, phoneNumber etc.
Buyer = client.GetBuyer(buyerToken);
if (!result.Success)
{
// handle the API error (use Status field to get the numeric error code)
} else {
// do something with the result, for instance:
Address buyerAddress = result.ShippingAddress;
string buyerEmail = result.Email;
}
}
}
import com.amazon.pay.api.AmazonPayResponse;
import com.amazon.pay.api.PayConfiguration;
import com.amazon.pay.api.WebstoreClient;
import com.amazon.pay.api.exceptions.AmazonPayClientException;
import com.amazon.pay.api.types.Region;
public void sample() {
PayConfiguration payConfiguration = null;
try {
String buyerToken = "eyL7YthG12BvRUYiLCJlbmMiOiJBMjU2R0NNIiwidGFnIjoiNXQ3NmhOTVhKN0tidkpSbHR0WmggBn12JmnY6yI6IkExMjhHQ01LVyIsIml2IjoidXFUeWl5NzUtMlU1RVk0RyJ9.iy6tY93sESc2fHVj49ynJO3e45ZiGkpDbmVYjgAimiM.K4nVJFzrHV-Pbotw.CumBT12hN5Bih_V0UI635PuIZ_IAD-HcH42hy5NuliOhFoAoFf4uNnVpjjDbPWnkYcdgtettavJlKGPG5wG2zaHJc2AFODXuuHklYGUbOwX1Z9JBXJExXfcLyvM_d5Zh4eaXkJWB3BUCfrP4afG9llHmwOHRvORu4vyGzG4JuBrZVeZ69EK0yqDMOYgbR44Bospf9XCDeV_NQfkmZWerjHaWe_ltYgCEcbUQu4-Snb76NbVT8Uf85KNocQfi4SYJn5tUKTjh2uR9XHeQhQY.f7UR3zVnUDe_WfqsvrPMNw";
payConfiguration = new PayConfiguration()
.setPublicKeyId("YOUR_PUBLIC_KEY_ID")
.setRegion(Region.YOUR_REGION_CODE)
.setPrivateKey("YOUR_PRIVATE_KEY".toCharArray())
.setAlgorithm("AMZN-PAY-RSASSA-PSS-V2");
WebstoreClient webstoreClient = new WebstoreClient(payConfiguration);
AmazonPayResponse response = webstoreClient.getBuyer(buyerToken);
} catch (AmazonPayClientException e) {
e.printStackTrace();
}
}
const fs = require('fs');
const Client = require('@amazonpay/amazon-pay-api-sdk-nodejs');
const config = {
publicKeyId: 'YOUR_PUBLIC_KEY_ID',
privateKey: fs.readFileSync('tst/private.pem'),
region: 'YOUR_REGION_CODE',
algorithm: 'AMZN-PAY-RSASSA-PSS-V2'
};
const buyerToken = "eyL7YthG12BvRUYiLCJlbmMiOiJBMjU2R0NNIiwidGFnIjoiNXQ3NmhOTVhKN0tidkpSbHR0WmggBn12JmnY6yI6IkExMjhHQ01LVyIsIml2IjoidXFUeWl5NzUtMlU1RVk0RyJ9.iy6tY93sESc2fHVj49ynJO3e45ZiGkpDbmVYjgAimiM.K4nVJFzrHV-Pbotw.CumBT12hN5Bih_V0UI635PuIZ_IAD-HcH42hy5NuliOhFoAoFf4uNnVpjjDbPWnkYcdgtettavJlKGPG5wG2zaHJc2AFODXuuHklYGUbOwX1Z9JBXJExXfcLyvM_d5Zh4eaXkJWB3BUCfrP4afG9llHmwOHRvORu4vyGzG4JuBrZVeZ69EK0yqDMOYgbR44Bospf9XCDeV_NQfkmZWerjHaWe_ltYgCEcbUQu4-Snb76NbVT8Uf85KNocQfi4SYJn5tUKTjh2uR9XHeQhQY.f7UR3zVnUDe_WfqsvrPMNw";
const testPayClient = new Client.WebStoreClient(config);
const response = testPayClient.getBuyer(buyerToken);
response.then(function (result) {
console.log(result.data);
}).catch(err => {
console.log(err);
});
<?php
include 'vendor/autoload.php';
$amazonpay_config = array(
'public_key_id' => 'YOUR_PUBLIC_KEY_ID',
'private_key' => 'keys/private.pem', // Path to RSA Private Key (or a string representation)
'region' => 'YOUR_REGION_CODE',
'sandbox' => true,
'algorithm' => 'AMZN-PAY-RSASSA-PSS-V2'
);
try {
$buyerToken = 'eyL7YthG12BvRUYiLCJlbmMiOiJBMjU2R0NNIiwidGFnIjoiNXQ3NmhOTVhKN0tidkpSbHR0WmggBn12JmnY6yI6IkExMjhHQ01LVyIsIml2IjoidXFUeWl5NzUtMlU1RVk0RyJ9.iy6tY93sESc2fHVj49ynJO3e45ZiGkpDbmVYjgAimiM.K4nVJFzrHV-Pbotw.CumBT12hN5Bih_V0UI635PuIZ_IAD-HcH42hy5NuliOhFoAoFf4uNnVpjjDbPWnkYcdgtettavJlKGPG5wG2zaHJc2AFODXuuHklYGUbOwX1Z9JBXJExXfcLyvM_d5Zh4eaXkJWB3BUCfrP4afG9llHmwOHRvORu4vyGzG4JuBrZVeZ69EK0yqDMOYgbR44Bospf9XCDeV_NQfkmZWerjHaWe_ltYgCEcbUQu4-Snb76NbVT8Uf85KNocQfi4SYJn5tUKTjh2uR9XHeQhQY.f7UR3zVnUDe_WfqsvrPMNw';
$client = new Amazon\Pay\API\Client($amazonpay_config);
$result = $client->getBuyer($buyerToken);
if ($result['status'] === 200) {
$response = json_decode($result['response'], true);
} else {
// check the error
echo 'status=' . $result['status'] . '; response=' . $result['response'];
}
} catch (Exception $e) {
// handle the exception
echo $e;
}
?>
using Amazon.Pay.API;
using Amazon.Pay.API.Types;
using Amazon.Pay.API.WebStore;
using Amazon.Pay.API.WebStore.Types;
using Amazon.Pay.API.WebStore.Buyer;
using Microsoft.AspNetCore.Mvc.RazorPages;
public class Sample : PageModel
{
public BuyerResponse Buyer { get; private set; }
public WebStoreClient InitiateClient()
{
// set up config
var payConfiguration = new ApiConfiguration
(
region: Region.YOUR_REGION_CODE,
environment: Environment.Sandbox,
publicKeyId: "YOUR_PUBLIC_KEY_ID",
privateKey: "PATH_OR_CONTENT_OF_YOUR_PRIVATE_KEY",
algorithm: AmazonSignatureAlgorithm.V2
);
// init API client
var client = new WebStoreClient(payConfiguration);
return client;
}
public void OnGet()
{
// the token as retrieved from the URL
string buyerToken = HttpContext.Request.Query["buyerToken"];
// get the buyer details
// NOTE: the BuyerResponse that is returned here contains properties for buyerId, name, email, shippingAddress, phoneNumber etc.
Buyer = client.GetBuyer(buyerToken);
if (!result.Success)
{
// handle the API error (use Status field to get the numeric error code)
} else {
// do something with the result, for instance:
Address buyerAddress = result.ShippingAddress;
string buyerEmail = result.Email;
}
}
}
import com.amazon.pay.api.AmazonPayResponse;
import com.amazon.pay.api.PayConfiguration;
import com.amazon.pay.api.WebstoreClient;
import com.amazon.pay.api.exceptions.AmazonPayClientException;
import com.amazon.pay.api.types.Environment;
import com.amazon.pay.api.types.Region;
public void sample() {
PayConfiguration payConfiguration = null;
try {
String buyerToken = "eyL7YthG12BvRUYiLCJlbmMiOiJBMjU2R0NNIiwidGFnIjoiNXQ3NmhOTVhKN0tidkpSbHR0WmggBn12JmnY6yI6IkExMjhHQ01LVyIsIml2IjoidXFUeWl5NzUtMlU1RVk0RyJ9.iy6tY93sESc2fHVj49ynJO3e45ZiGkpDbmVYjgAimiM.K4nVJFzrHV-Pbotw.CumBT12hN5Bih_V0UI635PuIZ_IAD-HcH42hy5NuliOhFoAoFf4uNnVpjjDbPWnkYcdgtettavJlKGPG5wG2zaHJc2AFODXuuHklYGUbOwX1Z9JBXJExXfcLyvM_d5Zh4eaXkJWB3BUCfrP4afG9llHmwOHRvORu4vyGzG4JuBrZVeZ69EK0yqDMOYgbR44Bospf9XCDeV_NQfkmZWerjHaWe_ltYgCEcbUQu4-Snb76NbVT8Uf85KNocQfi4SYJn5tUKTjh2uR9XHeQhQY.f7UR3zVnUDe_WfqsvrPMNw";
payConfiguration = new PayConfiguration()
.setPublicKeyId("YOUR_PUBLIC_KEY_ID")
.setRegion(Region.YOUR_REGION_CODE)
.setPrivateKey("YOUR_PRIVATE_KEY".toCharArray())
.setEnvironment(Environment.SANDBOX)
.setAlgorithm("AMZN-PAY-RSASSA-PSS-V2");
WebstoreClient webstoreClient = new WebstoreClient(payConfiguration);
AmazonPayResponse response = webstoreClient.getBuyer(buyerToken);
} catch (AmazonPayClientException e) {
e.printStackTrace();
}
}
const fs = require('fs');
const Client = require('@amazonpay/amazon-pay-api-sdk-nodejs');
const config = {
publicKeyId: 'YOUR_PUBLIC_KEY_ID',
privateKey: fs.readFileSync('tst/private.pem'),
region: 'YOUR_REGION_CODE',
sandbox: true,
algorithm: 'AMZN-PAY-RSASSA-PSS-V2'
};
const buyerToken = "eyL7YthG12BvRUYiLCJlbmMiOiJBMjU2R0NNIiwidGFnIjoiNXQ3NmhOTVhKN0tidkpSbHR0WmggBn12JmnY6yI6IkExMjhHQ01LVyIsIml2IjoidXFUeWl5NzUtMlU1RVk0RyJ9.iy6tY93sESc2fHVj49ynJO3e45ZiGkpDbmVYjgAimiM.K4nVJFzrHV-Pbotw.CumBT12hN5Bih_V0UI635PuIZ_IAD-HcH42hy5NuliOhFoAoFf4uNnVpjjDbPWnkYcdgtettavJlKGPG5wG2zaHJc2AFODXuuHklYGUbOwX1Z9JBXJExXfcLyvM_d5Zh4eaXkJWB3BUCfrP4afG9llHmwOHRvORu4vyGzG4JuBrZVeZ69EK0yqDMOYgbR44Bospf9XCDeV_NQfkmZWerjHaWe_ltYgCEcbUQu4-Snb76NbVT8Uf85KNocQfi4SYJn5tUKTjh2uR9XHeQhQY.f7UR3zVnUDe_WfqsvrPMNw";
const testPayClient = new Client.WebStoreClient(config);
const response = testPayClient.getBuyer(buyerToken);
response.then(function (result) {
console.log(result.data);
}).catch(err => {
console.log(err);
});
Response
Returns HTTP 200 status response code if the operation was successful.
{
"name": "John Example",
"email": "johnexample@amazon.com",
"postalCode": "12345",
"countryCode": "US",
"buyerId": "DIRECTEDBUYERID",
"phoneNumber": "1234567811" // default billing address phone number
"shippingAddress": {
"name": "John",
"addressLine1": "15th Street",
"addressLine2": "",
"addressLine3": "",
"city": "Seattle",
"county": "",
"district": "",
"stateOrRegion": "WA",
"country": "USA",
"postalCode": "98121",
"phoneNumber": "1234567899"
},
"billingAddress": null,
"primeMembershipTypes": null
}
Error codes
HTTP status code
|
Reason code
|
Description
|
400 BAD_REQUEST
|
InvalidBuyerToken
|
The token provided is expired, revoked, malformed, or invalid for some other reason
|
Generic errors can be found here.
