Set payment info
[Step 4 of 9] In this step, you will set the order total and specify how the buyer should be charged. At the end of this step, you will be able to redirect the buyer to a unique amazonRedirectUrl
for transaction processing.
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.
1. Set payment info
Call Update Checkout Session to set payment info (such as the order amount) and transaction metadata. Use the checkoutResultReturnUrl
parameter to specify the URL the buyer is redirected to after checkout is completed on the Amazon Pay-hosted page.
Note: You must add the checkoutReviewReturnUrl domain you plan on using if it's different from the domain where you rendered the Amazon Pay button, to the Seller Central. See
Add domains to Seller Central for more information.
Set chargeAmount
to the value that should be processed using the paymentIntent
during checkout. If you need to split the order to capture additional payment after checkout is complete, use the optional totalOrderAmount
parameter to set the full order amount.
Request
curl "https://pay-api.amazon.com/:version/checkoutSessions/:checkoutSessionId" \
-X PATCH
-H "authorization:Px2e5oHhQZ88vVhc0DO%2FsShHj8MDDg%3DEXAMPLESIGNATURE"
-H "x-amz-pay-date:20201012T235046Z"
-d @request_body
curl "https://pay-api.amazon.com/:environment/:version/checkoutSessions/:checkoutSessionId" \
-X PATCH
-H "authorization:Px2e5oHhQZ88vVhc0DO%2FsShHj8MDDg%3DEXAMPLESIGNATURE"
-H "x-amz-pay-date:20201012T235046Z"
-d @request_body
Request body
{
"webCheckoutDetails": {
"checkoutResultReturnUrl": "https://a.com/merchant-confirm-page"
},
"paymentDetails": {
"paymentIntent": "AuthorizeWithCapture",
"canHandlePendingAuthorization":false,
"softDescriptor": "Descriptor",
"chargeAmount": {
"amount": "1",
"currencyCode": "USD"
}
},
"merchantMetadata": {
"merchantReferenceId": "Merchant reference ID",
"merchantStoreName": "Merchant store name",
"noteToBuyer": "Note to buyer",
"customInformation": "Custom information"
}
}
Request parameters
Name
Location
Description
checkoutSessionId (required) Type: string
Path parameter
Checkout Session identifier
webCheckoutDetails Type: webCheckoutDetails
Body
Checkout result URL provided by the merchant. Amazon Pay will redirect to this URL after completing the transaction Modifiable: Multiple times before the buyer is redirected to the amazonPayReturnUrl
paymentDetails Type: paymentDetails
Body
Payment details specified by the merchant, such as the amount and method for charging the buyer Modifiable: Multiple times before the buyer is redirected to the amazonPayReturnUrl
merchantMetadata Type: merchantMetadata
Body
External order details provided by the merchant Modifiable: Multiple times before the buyer is redirected to the amazonPayReturnUrl
platformId Type: string
Body
Merchant identifier of the Solution Provider (SP). Only SPs should use this field. Modifiable: Multiple times before the buyer is redirected to the amazonPayReturnUrl
providerMetadata Type: providerMetadata
Body
Transaction identifier created by the Payment Service Provider (PSP). Only PSPs should use these fields. Modifiable: Multiple times before the buyer is redirected to the amazonPayReturnUrl
.
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'
);
$payload = array(
'webCheckoutDetails' => array(
'checkoutResultReturnUrl' => 'https://a.com/merchant-confirm-page'
),
'paymentDetails' => array(
'paymentIntent' => 'AuthorizeWithCapture',
'canHandlePendingAuthorization' => false,
'softDescriptor' => 'Descriptor',
'chargeAmount' => array(
'amount' => '1',
'currencyCode' => 'USD'
)
),
'merchantMetadata' => array(
'merchantReferenceId' => 'Merchant reference ID',
'merchantStoreName' => 'Merchant store name',
'noteToBuyer' => 'Note to buyer',
'customInformation' => 'Custom information'
)
);
try {
$client = new Amazon\Pay\API\Client($amazonpay_config);
$result = $client->updateCheckoutSession('bd504926-f659-4ad7-a1a9-9a747aaf5275', $payload);
if ($result['status'] === 200) {
$response = json_decode($result['response'], true);
$amazonPayRedirectUrl = $response['webCheckoutDetails']['amazonPayRedirectUrl'];
} else {
// check the error
echo 'status=' . $result['status'] . '; response=' . $result['response'];
}
} catch (Exception $e) {
// handle the exception
echo $e;
}
?>
using Amazon.Pay.API.Types;
using Amazon.Pay.API.WebStore.CheckoutSession;
using Amazon.Pay.API.WebStore;
using Amazon.Pay.API.WebStore.Types;
public class Sample
{
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 CheckoutSessionResponse UpdateCheckoutSession(string checkoutSessionId)
{
// prepare the request
var request = new UpdateCheckoutSessionRequest()
{
WebCheckoutDetails = {
CheckoutResultReturnUrl = "https://a.com/merchant-confirm-page"
},
PaymentDetails = {
ChargeAmount = {
Amount = 1.00M,
CurrencyCode = Currency.USD
},
CanHandlePendingAuthorization = false,
SoftDescriptor = "Descriptor",
PaymentIntent = PaymentIntent.AuthorizeWithCapture
},
MerchantMetadata = {
MerchantReferenceId = "Merchant reference ID",
MerchantStoreName = "Merchant store name",
NoteToBuyer = "Note to buyer",
CustomInformation = "Custom information"
}
};
// send the request
var result = client.UpdateCheckoutSession(checkoutSessionId, request);
// check if API call was successful
if (!result.Success)
{
// do something, e.g. throw an error
}
return result;
}
}
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;
import org.json.JSONObject;
public void sample() {
PayConfiguration payConfiguration = null;
try {
payConfiguration = new PayConfiguration()
.setPublicKeyId("YOUR_PUBLIC_KEY_ID")
.setRegion(Region.YOUR_REGION_CODE)
.setPrivateKey("YOUR_PRIVATE_KEY")
.setAlgorithm("AMZN-PAY-RSASSA-PSS-V2");
WebstoreClient webstoreClient = new WebstoreClient(payConfiguration);
AmazonPayResponse response = null;
String checkoutSessionId = "bd504926-f659-4ad7-a1a9-9a747aaf5275";
JSONObject payload = new JSONObject();
JSONObject updateWebCheckoutDetails = new JSONObject();
updateWebCheckoutDetails.put("checkoutResultReturnUrl", "https://a.com/merchant-confirm-page");
payload.put("webCheckoutDetails", updateWebCheckoutDetails);
JSONObject paymentDetails = new JSONObject();
paymentDetails.put("paymentIntent" , "AuthorizeWithCapture");
paymentDetails.put("canHandlePendingAuthorization", false);
paymentDetails.put("softDescriptor", "Descriptor");
JSONObject chargeAmount = new JSONObject();
chargeAmount.put("amount", "1");
chargeAmount.put("currencyCode", "USD");
paymentDetails.put("chargeAmount", chargeAmount);
payload.put("paymentDetails", paymentDetails);
JSONObject merchantMetadata = new JSONObject();
merchantMetadata.put("merchantReferenceId", "Merchant reference ID");
merchantMetadata.put("merchantStoreName", "Merchant store name");
merchantMetadata.put("noteToBuyer", "Note to buyer");
merchantMetadata.put("customInformation", "Custom information");
payload.put("merchantMetadata", merchantMetadata);
response = webstoreClient.updateCheckoutSession(checkoutSessionId, payload);
} 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 payload = {
webCheckoutDetails: {
checkoutResultReturnUrl: "https://a.com/merchant-confirm-page"
},
paymentDetails: {
paymentIntent: "AuthorizeWithCapture",
canHandlePendingAuthorization: false,
softDescriptor: "Descriptor",
chargeAmount: {
amount: "1",
currencyCode: "USD"
}
},
merchantMetadata: {
merchantReferenceId: "Merchant reference ID",
merchantStoreName: "Merchant store name",
noteToBuyer: "Note to buyer",
customInformation: "Custom information"
}
};
const testPayClient = new Client.WebStoreClient(config);
const response = testPayClient.updateCheckoutSession('bd504926-f659-4ad7-a1a9-9a747aaf5275', payload);
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'
);
$payload = array(
'webCheckoutDetails' => array(
'checkoutResultReturnUrl' => 'https://a.com/merchant-confirm-page'
),
'paymentDetails' => array(
'paymentIntent' => 'AuthorizeWithCapture',
'canHandlePendingAuthorization' => false,
'softDescriptor' => 'Descriptor',
'chargeAmount' => array(
'amount' => '1',
'currencyCode' => 'USD'
)
),
'merchantMetadata' => array(
'merchantReferenceId' => 'Merchant reference ID',
'merchantStoreName' => 'Merchant store name',
'noteToBuyer' => 'Note to buyer',
'customInformation' => 'Custom information'
)
);
try {
$client = new Amazon\Pay\API\Client($amazonpay_config);
$result = $client->updateCheckoutSession('bd504926-f659-4ad7-a1a9-9a747aaf5275', $payload);
if ($result['status'] === 200) {
$response = json_decode($result['response'], true);
$amazonPayRedirectUrl = $response['webCheckoutDetails']['amazonPayRedirectUrl'];
} else {
// check the error
echo 'status=' . $result['status'] . '; response=' . $result['response'];
}
} catch (Exception $e) {
// handle the exception
echo $e;
}
?>
using Amazon.Pay.API.Types;
using Amazon.Pay.API.WebStore.CheckoutSession;
using Amazon.Pay.API.WebStore;
using Amazon.Pay.API.WebStore.Types;
public class Sample
{
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 CheckoutSessionResponse UpdateCheckoutSession(string checkoutSessionId)
{
// prepare the request
var request = new UpdateCheckoutSessionRequest()
{
WebCheckoutDetails = {
CheckoutResultReturnUrl = "https://a.com/merchant-confirm-page"
},
PaymentDetails = {
ChargeAmount = {
Amount = 1.00M,
CurrencyCode = Currency.USD
},
CanHandlePendingAuthorization = false,
SoftDescriptor = "Descriptor",
PaymentIntent = PaymentIntent.AuthorizeWithCapture
},
MerchantMetadata = {
MerchantReferenceId = "Merchant reference ID",
MerchantStoreName = "Merchant store name",
NoteToBuyer = "Note to buyer",
CustomInformation = "Custom information"
}
};
// send the request
var result = client.UpdateCheckoutSession(checkoutSessionId, request);
// check if API call was successful
if (!result.Success)
{
// do something, e.g. throw an error
}
return result;
}
}
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;
import org.json.JSONObject;
public void sample() {
PayConfiguration payConfiguration = null;
try {
payConfiguration = new PayConfiguration()
.setPublicKeyId("YOUR_PUBLIC_KEY_ID")
.setRegion(Region.YOUR_REGION_CODE)
.setPrivateKey("YOUR_PRIVATE_KEY")
.setEnvironment(Environment.SANDBOX)
.setAlgorithm("AMZN-PAY-RSASSA-PSS-V2");
WebstoreClient webstoreClient = new WebstoreClient(payConfiguration);
AmazonPayResponse response = null;
String checkoutSessionId = "bd504926-f659-4ad7-a1a9-9a747aaf5275";
JSONObject payload = new JSONObject();
JSONObject updateWebCheckoutDetails = new JSONObject();
updateWebCheckoutDetails.put("checkoutResultReturnUrl", "https://a.com/merchant-confirm-page");
payload.put("webCheckoutDetails", updateWebCheckoutDetails);
JSONObject paymentDetails = new JSONObject();
paymentDetails.put("paymentIntent" , "AuthorizeWithCapture");
paymentDetails.put("canHandlePendingAuthorization", false);
paymentDetails.put("softDescriptor", "Descriptor");
JSONObject chargeAmount = new JSONObject();
chargeAmount.put("amount", "1");
chargeAmount.put("currencyCode", "USD");
paymentDetails.put("chargeAmount", chargeAmount);
payload.put("paymentDetails", paymentDetails);
JSONObject merchantMetadata = new JSONObject();
merchantMetadata.put("merchantReferenceId", "Merchant reference ID");
merchantMetadata.put("merchantStoreName", "Merchant store name");
merchantMetadata.put("noteToBuyer", "Note to buyer");
merchantMetadata.put("customInformation", "Custom information");
payload.put("merchantMetadata", merchantMetadata);
response = webstoreClient.updateCheckoutSession(checkoutSessionId, payload);
} 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 payload = {
webCheckoutDetails: {
checkoutResultReturnUrl: "https://a.com/merchant-confirm-page"
},
paymentDetails: {
paymentIntent: "AuthorizeWithCapture",
canHandlePendingAuthorization: false,
softDescriptor: "Descriptor",
chargeAmount: {
amount: "1",
currencyCode: "USD"
}
},
merchantMetadata: {
merchantReferenceId: "Merchant reference ID",
merchantStoreName: "Merchant store name",
noteToBuyer: "Note to buyer",
customInformation: "Custom information"
}
};
const testPayClient = new Client.WebStoreClient(config);
const response = testPayClient.updateCheckoutSession('bd504926-f659-4ad7-a1a9-9a747aaf5275', payload);
response.then(function (result) {
console.log(result.data);
}).catch(err => {
console.log(err);
});
Response
{
"checkoutSessionId": "bd504926-f659-4ad7-a1a9-9a747aaf5275",
"webCheckoutDetails": {
"checkoutReviewReturnUrl": "https://a.com/merchant-review-page",
"checkoutResultReturnUrl": "https://a.com/merchant-confirm-page",
"checkoutCancelUrl": null,
"amazonPayRedirectUrl": "https://pay.amazon.com/redirect/checkoutId-1"
},
"productType": "PayAndShip",
"paymentDetails": {
"paymentIntent": "AuthorizeWithCapture",
"canHandlePendingAuthorization": false,
"chargeAmount": {
"amount": "1",
"currencyCode": "USD"
},
"totalOrderAmount": null,
"softDescriptor": "Descriptor",
"presentmentCurrency": "USD",
"allowOvercharge": null,
"extendExpiration": null
},
"merchantMetadata": {
"merchantReferenceId": "Merchant reference ID",
"merchantStoreName": "Merchant store name",
"noteToBuyer": "Note to buyer",
"customInformation": "Custom information"
},
"supplementaryData": null, // Amazon Pay system data
"buyer": {
"buyerId": "buyerId",
"name": "name-1",
"email": "name@amazon.com",
"phoneNumber": "800-000-0000",
"primeMembershipTypes": null
},
"billingAddress":{
"name": "Work",
"addressLine1": "440 Terry Ave",
"addressLine2": "",
"addressLine3": "",
"city": "Seattle",
"county": "King",
"district": "Seattle",
"stateOrRegion": "WA",
"postalCode": "98121",
"countryCode": "US",
"phoneNumber": "800-000-0000"
},
"paymentPreferences": [
{
"paymentDescriptor": "Visa ****1111 (Amazon Pay)"
}
],
"statusDetails": {
"state": "Open",
"reasonCode": null,
"reasonDescription": null,
"lastUpdatedTimestamp": "20191015T195703Z"
},
"shippingAddress": { // Null for PayOnly product type
"name": "Susie Smith",
"addressLine1": "10 Ditka Ave",
"addressLine2": "Suite 2500",
"addressLine3": null,
"city": "Chicago",
"county": null,
"district": null,
"stateOrRegion": "IL",
"postalCode": "60602",
"countryCode": "US",
"phoneNumber": "800-000-0000"
},
"platformId": null,
"chargePermissionId": null,
"chargeId": null,
"constraints": [],
"creationTimestamp": "20191015T195655Z",
"expirationTimestamp": "20191016T195655Z",
"storeId": "amzn1.application-oa2-client.8b5e45312b5248b69eeaStoreId",
"deliverySpecifications": {
"specialRestrictions": ["RestrictPOBoxes"],
"addressRestrictions": {
"type": "Allowed",
"restrictions": {
"US": {
"statesOrRegions": ["WA"],
"zipCodes": ["95050", "93405"]
},
"GB": {
"zipCodes": ["72046", "72047"]
},
"IN": {
"statesOrRegions": ["AP"]
},
"JP": {}
}
}
},
"providerMetadata": {
"providerReferenceId": null
},
"checkoutButtonText": null,
"releaseEnvironment": "Sandbox"
}
2. Redirect to AmazonPayRedirectUrl
Update Checkout Session response will include a Constraint object until all mandatory parameters have been provided. The mandatory parameters are:
checkoutResultReturnUrl
chargeAmount
paymentIntent
Once there are no constraints, the response will return a unique amazonPayRedirectUrl
. Redirect the buyer to that URL to complete checkout.