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.

Supported operations:

Buyer object
Get Buyer

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.