All Products
Search

This Product

    Object Storage Service:Pay-by-requester (PHP SDK V2)

    Document Center

    Object Storage Service:Pay-by-requester (PHP SDK V2)

    Last Updated:Mar 20, 2026

    In pay-by-requester mode, the requester pays for the traffic and request fees generated when data is read from a bucket, while the bucket owner pays only for storage fees. Use this mode to share data without incurring the request and traffic costs when your bucket is accessed.

    Prerequisites

    Before you begin, ensure that you have:

    • An OSS bucket

    • The oss:PutBucketRequestPayment permission to enable pay-by-requester mode

    • The oss:GetBucketRequestPayment permission to query the pay-by-requester configuration

    For permission setup, see Attach a custom access policy to a RAM user.

    Usage notes

    • The sample code uses cn-hangzhou (China (Hangzhou)) as the example region and a public endpoint by default. To access OSS from other Alibaba Cloud products in the same region, use an internal endpoint. For endpoint mappings, see Regions and endpoints.

    • Set the payer to Requester to enable pay-by-requester mode.

    Sample code

    Set the pay-by-requester mode

    Call putBucketRequestPayment with RequestPaymentConfiguration('Requester') to enable pay-by-requester mode.

    <?php

require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// Define command line arguments.
$optsdesc = [
    "region" => ['help' => 'The region in which the bucket is located.', 'required' => True],
    "endpoint" => ['help' => 'The domain names that other services can use to access OSS.', 'required' => False],
    "bucket" => ['help' => 'The name of the bucket.', 'required' => True],
];
$longopts = \array_map(function ($key) {
    return "$key:";
}, array_keys($optsdesc));

$options = getopt("", $longopts);

foreach ($optsdesc as $key => $value) {
    if ($value['required'] === True && empty($options[$key])) {
        $help = $value['help'];
        echo "Error: the following arguments are required: --$key, $help";
        exit(1);
    }
}

$region = $options["region"];
$bucket = $options["bucket"];

// Load credentials from environment variables (OSS_ACCESS_KEY_ID, OSS_ACCESS_KEY_SECRET).
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider($credentialsProvider);
$cfg->setRegion($region);
if (isset($options["endpoint"])) {
    $cfg->setEndpoint($options["endpoint"]);
}

$client = new Oss\Client($cfg);

// Set the payer to Requester to enable pay-by-requester mode.
$request = new Oss\Models\PutBucketRequestPaymentRequest(
    $bucket,
    new Oss\Models\RequestPaymentConfiguration('Requester')
);

$result = $client->putBucketRequestPayment($request);

printf(
    'status code: ' . $result->statusCode . PHP_EOL .
    'request ID: ' . $result->requestId
);

    For the complete sample, see GitHub: PutBucketRequestPayment.php.

    Query the pay-by-requester configuration

    Call getBucketRequestPayment to retrieve the current payer configuration. The response returns either Requester or BucketOwner.

    <?php

require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// Define command line arguments.
$optsdesc = [
    "region" => ['help' => 'The region in which the bucket is located.', 'required' => True],
    "endpoint" => ['help' => 'The domain names that other services can use to access OSS.', 'required' => False],
    "bucket" => ['help' => 'The name of the bucket.', 'required' => True],
];
$longopts = \array_map(function ($key) {
    return "$key:";
}, array_keys($optsdesc));

$options = getopt("", $longopts);

foreach ($optsdesc as $key => $value) {
    if ($value['required'] === True && empty($options[$key])) {
        $help = $value['help'];
        echo "Error: the following arguments are required: --$key, $help";
        exit(1);
    }
}

$region = $options["region"];
$bucket = $options["bucket"];

// Load credentials from environment variables (OSS_ACCESS_KEY_ID, OSS_ACCESS_KEY_SECRET).
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider($credentialsProvider);
$cfg->setRegion($region);
if (isset($options["endpoint"])) {
    $cfg->setEndpoint($options["endpoint"]);
}

$client = new Oss\Client($cfg);

$request = new Oss\Models\GetBucketRequestPaymentRequest($bucket);

$result = $client->getBucketRequestPayment($request);

// payer is either Requester or BucketOwner.
printf(
    'status code: ' . $result->statusCode . PHP_EOL .
    'request ID: ' . $result->requestId . PHP_EOL .
    'payer: ' . $result->requestPaymentConfiguration->payer
);

    For the complete sample, see GitHub: GetBucketRequestPayment.php.

    References