Update info post-checkout
Call Update Charge Permission to update external merchant metadata or the recurringMetadata if subscription details change post-checkout. You can update merchantMetadata child parameters multiple times if the Charge Permission is in a Chargeable or NonChargeable state. You can update merchantMetadata child parameters if the Charge Permission is in a Closed state only if chargePermissionType is Onetime and if the child parameter value to be updated is either null or an empty string. Note that buyer communication will not reflect the updated value if the Charge Permission is in a Closed state.
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.
Request
curl "https://pay-api.amazon.com/:version/chargePermissions/:chargePermissionId" \
-X PATCH
-H "authorization:Px2e5oHhQZ88vVhc0DO%2FsShHj8MDDg%3DEXAMPLESIGNATURE"
-H "x-amz-pay-date:20201012T235046Z"
-d @request_body
curl "https://pay-api.amazon.com/:environment/:version/chargePermissions/:chargePermissionId" \
-X PATCH
-H "authorization:Px2e5oHhQZ88vVhc0DO%2FsShHj8MDDg%3DEXAMPLESIGNATURE"
-H "x-amz-pay-date:20201012T235046Z"
-d @request_body
Request body
{
"merchantMetadata": {
"merchantReferenceId": "123-77-876",
"merchantStoreName": "AmazonTestStoreFront",
"noteToBuyer": "merchantNoteForBuyer",
"customInformation": "This is custom information"
},
"recurringMetadata": {
"frequency": {
"unit": "Month",
"value": "1"
},
"amount": {
"amount": "14",
"currencyCode": "USD"
}
}
}
Request parameters
Name
|
Location
|
Description
|
chargePermissionId
(required)
Type: string
|
Path Parameter
|
Charge Permission identifier
|
recurringMetadata
Type: recurringMetadata
|
Body
|
Metadata about how the recurring Charge Permission will be used. Amazon Pay only uses this information to calculate the Charge Permission expiration date and in buyer communication
Note that it is still your responsibility to call Create Charge to charge the buyer for each billing cycle
|
merchantMetadata
Type: merchantMetadata
|
Body
|
Merchant-provided order details
See update info post-checkout for limits to how many times this value can be modified
|
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(
'merchantMetadata' => array(
'merchantReferenceId' => '123-77-876',
'merchantStoreName' => 'AmazonTestStoreFront',
'noteToBuyer' => 'merchantNoteForBuyer',
'customInformation' => 'This is custom information'
),
'recurringMetadata' => array(
'frequency' => array(
'unit' => 'Month',
'value' => '1'
),
'amount' => array(
'amount' => '30',
'currencyCode' => 'USD'
)
)
);
$headers = array('x-amz-pay-Idempotency-Key' => uniqid());
try {
$client = new Amazon\Pay\API\Client($amazonpay_config);
$result = $client->updateChargePermission('S01-5105180-3221187', $payload);
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.Types;
using Amazon.Pay.API.WebStore;
using Amazon.Pay.API.WebStore.Types;
using Amazon.Pay.API.WebStore.ChargePermission;
public class Sample
{
public WebStoreClient InitiateClient()
{
// set up config
var payConfiguration = new ApiConfiguration
(
region: Region.UnitedStates,
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 UpdateChargePermission()
{
// prepare the request
var chargePermissionId = "S01-5105180-3221187";
var request = new UpdateCheckoutSessionRequest()
{
RecurringMetadata =
{
Frequency = {
Unit = FrequencyUnit.Month,
Value = 1
},
Amount = {
Amount = 14,
CurrencyCode = Currency.USD
}
},
MerchantMetadata = {
MerchantReferenceId = "123-77-876",
MerchantStoreName = "AmazonTestStoreFront",
NoteToBuyer = "merchantNoteForBuyer",
CustomInformation = "This is custom information"
}
};
// send the request
ChargePermissionResponse result = client.UpdateChargePermission(chargePermissionId, request);
// check if API call was successful
if (!result.Success)
{
// handle the API error (use Status field to get the numeric error code)
}
// do something with the result, for instance:
State chargePermissionState = result.StatusDetails.State;
}
}
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;
// for generating an idempotency key
import java.util.HashMap;
import java.util.Map;
import java.util.UUID;
public void sample() {
PayConfiguration payConfiguration = null;
try {
payConfiguration = new PayConfiguration()
.setPublicKeyId("YOUR_PUBLIC_KEY_ID")
.setRegion(Region.NA)
.setPrivateKey("YOUR_PRIVATE_KEY")
.setAlgorithm("AMZN-PAY-RSASSA-PSS-V2");
WebstoreClient webstoreClient = new WebstoreClient(payConfiguration);
AmazonPayResponse response = null;
String chargePermissionId = "S01-5105180-3221187";
JSONObject payload = new JSONObject();
JSONObject merchantMetadata = new JSONObject();
merchantMetadata.put("merchantReferenceId", "32-41-323141");
merchantMetadata.put("merchantStoreName", "AmazonTestStoreName");
merchantMetadata.put("noteToBuyer", "merchantNoteForBuyer");
merchantMetadata.put("customInformation", "This is custom information");
payload.put("merchantMetadata", merchantMetadata);
JSONObject recurringMetadata = new JSONObject();
JSONObject frequency = new JSONObject();
frequency.put("unit","Month");
frequency.put("value","1");
recurringMetadata.put("frequency", frequency);
JSONObject amount = new JSONObject();
amount.put("amount","14");
amount.put("currencyCode","USD");
recurringMetadata.put("amount", amount);
payload.put("recurringMetadata", recurringMetadata);
response = webstoreClient.updateChargePermission(chargePermissionId, payload);
} catch (AmazonPayClientException e) {
e.printStackTrace();
}
}
const fs = require('fs');
const Client = require('@amazonpay/amazon-pay-api-sdk-nodejs');
const uuidv4 = require('uuid/v4');
const config = {
publicKeyId: 'YOUR_PUBLIC_KEY_ID',
privateKey: fs.readFileSync('tst/private.pem'),
region: 'us',
algorithm: 'AMZN-PAY-RSASSA-PSS-V2'
};
const payload = {
merchantMetadata: {
merchantReferenceId: "123-77-876",
merchantStoreName: "AmazonTestStoreFront",
noteToBuyer: "merchantNoteForBuyer",
customInformation: "This is custom information"
},
recurringMetadata: {
frequency: {
unit: "Month",
value: "1"
},
amount: {
amount: "14",
currencyCode: "USD"
}
}
}
const testPayClient = new Client.WebStoreClient(config);
const response = testPayClient.updateChargePermission('S01-5105180-3221187',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(
'merchantMetadata' => array(
'merchantReferenceId' => '123-77-876',
'merchantStoreName' => 'AmazonTestStoreFront',
'noteToBuyer' => 'merchantNoteForBuyer',
'customInformation' => 'This is custom information'
),
'recurringMetadata' => array(
'frequency' => array(
'unit' => 'Month',
'value' => '1'
),
'amount' => array(
'amount' => '30',
'currencyCode' => 'USD'
)
)
);
$headers = array('x-amz-pay-Idempotency-Key' => uniqid());
try {
$client = new Amazon\Pay\API\Client($amazonpay_config);
$result = $client->updateChargePermission('S01-5105180-3221187', $payload);
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.Types;
using Amazon.Pay.API.WebStore;
using Amazon.Pay.API.WebStore.Types;
using Amazon.Pay.API.WebStore.ChargePermission;
public class Sample
{
public WebStoreClient InitiateClient()
{
// set up config
var payConfiguration = new ApiConfiguration
(
region: Region.UnitedStates,
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 UpdateChargePermission()
{
// prepare the request
var chargePermissionId = "S01-5105180-3221187";
var request = new UpdateCheckoutSessionRequest()
{
RecurringMetadata =
{
Frequency = {
Unit = FrequencyUnit.Month,
Value = 1
},
Amount = {
Amount = 14,
CurrencyCode = Currency.USD
}
},
MerchantMetadata = {
MerchantReferenceId = "123-77-876",
MerchantStoreName = "AmazonTestStoreFront",
NoteToBuyer = "merchantNoteForBuyer",
CustomInformation = "This is custom information"
}
};
// send the request
ChargePermissionResponse result = client.UpdateChargePermission(chargePermissionId, request);
// check if API call was successful
if (!result.Success)
{
// handle the API error (use Status field to get the numeric error code)
}
// do something with the result, for instance:
State chargePermissionState = result.StatusDetails.State;
}
}
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;
// for generating an idempotency key
import java.util.HashMap;
import java.util.Map;
import java.util.UUID;
public void sample() {
PayConfiguration payConfiguration = null;
try {
payConfiguration = new PayConfiguration()
.setPublicKeyId("YOUR_PUBLIC_KEY_ID")
.setRegion(Region.NA)
.setPrivateKey("YOUR_PRIVATE_KEY")
.setEnvironment(Environment.SANDBOX)
.setAlgorithm("AMZN-PAY-RSASSA-PSS-V2");
WebstoreClient webstoreClient = new WebstoreClient(payConfiguration);
AmazonPayResponse response = null;
String chargePermissionId = "S01-5105180-3221187";
JSONObject payload = new JSONObject();
JSONObject merchantMetadata = new JSONObject();
merchantMetadata.put("merchantReferenceId", "32-41-323141");
merchantMetadata.put("merchantStoreName", "AmazonTestStoreName");
merchantMetadata.put("noteToBuyer", "merchantNoteForBuyer");
merchantMetadata.put("customInformation", "This is custom information");
payload.put("merchantMetadata", merchantMetadata);
JSONObject recurringMetadata = new JSONObject();
JSONObject frequency = new JSONObject();
frequency.put("unit","Month");
frequency.put("value","1");
recurringMetadata.put("frequency", frequency);
JSONObject amount = new JSONObject();
amount.put("amount","14");
amount.put("currencyCode","USD");
recurringMetadata.put("amount", amount);
payload.put("recurringMetadata", recurringMetadata);
response = webstoreClient.updateChargePermission(chargePermissionId, payload);
} catch (AmazonPayClientException e) {
e.printStackTrace();
}
}
const fs = require('fs');
const Client = require('@amazonpay/amazon-pay-api-sdk-nodejs');
const uuidv4 = require('uuid/v4');
const config = {
publicKeyId: 'YOUR_PUBLIC_KEY_ID',
privateKey: fs.readFileSync('tst/private.pem'),
region: 'us',
sandbox: true,
algorithm: 'AMZN-PAY-RSASSA-PSS-V2'
};
const payload = {
merchantMetadata: {
merchantReferenceId: "123-77-876",
merchantStoreName: "AmazonTestStoreFront",
noteToBuyer: "merchantNoteForBuyer",
customInformation: "This is custom information"
},
recurringMetadata: {
frequency: {
unit: "Month",
value: "1"
},
amount: {
amount: "14",
currencyCode: "USD"
}
}
}
const testPayClient = new Client.WebStoreClient(config);
const response = testPayClient.updateChargePermission('S01-5105180-3221187',payload);
response.then(function (result) {
console.log(result.data);
}).catch(err => {
console.log(err);
});
Response
{
"chargePermissionId": "S01-5105180-3221187",
"chargePermissionReferenceId": null,
"chargePermissionType": "Recurring",
"recurringMetadata": {
"frequency": {
"unit": "Month",
"value": "1"
},
"amount": {
"amount": "14",
"currencyCode": "USD"
}
},
"buyer": {
"buyerId": "buyerId",
"name": "name-1",
"email": "name@amazon.com",
"phoneNumber": "800-000-0000",
"primeMembershipTypes": null
},
"releaseEnvironment": "Live",
"shippingAddress":{ // Null for PayOnly product type
"name": "Work",
"addressLine1": "440 Terry Ave",
"addressLine2": "",
"addressLine3": "",
"city": "Seattle",
"county": "King",
"district": "Seattle",
"stateOrRegion": "WA",
"postalCode": "98121",
"countryCode": "US",
"phoneNumber": "800-000-0000"
},
"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": null
}],
"statusDetails": {
"state": "Chargeable",
"reasons": null,
"lastUpdatedTimestamp": "20190714T155300Z"
},
"creationTimestamp": "20190714T155300Z",
"expirationTimestamp": "20190715T155300Z",
"merchantMetadata": {
"merchantReferenceId": "123-77-876",
"merchantStoreName": "AmazonTestStoreFront",
"noteToBuyer": "merchantNoteForBuyer",
"customInformation": "This is custom information"
},
"platformId": "SPId",
"limits": {
"amountLimit": {
"amount": "14.00",
"currencyCode": "USD"
},
"amountBalance": {
"amount": "14.00",
"currencyCode": "USD"
}
},
"presentmentCurrency": "USD"
}
