Get Instruments API

Method: GET

Path: <endpoint>/v1/payments/instruments

Description: This API retrieves one or more payment instruments based on the request. It enables the retrieval of specific details which is crucial for displaying user payment details on your payments UI.

Request Parameters

Parameter	Type	Description
merchantId	String	Your merchant ID with Amazon Pay
accessToken	String	Access token fetched for the user
instrumentTypes	String	Types of user's payment instruments with Amazon Pay. Allowed value - AmazonPayBalance

Instrument Types

Value	Description
AmazonPayBalance	Fetches the balance of the user.

Request Sample

https://{{endpoint}}/v1/payments/instruments?merchantId=A28RUURDCTQXU1&accessToken=Atza|IgEBdsfsdfdsf&instrumentTypes=AmazonPayBalance

Sample Response

{
  "amazonPayBalance": {
    "enabled": true,
    "priority": 0,
    "totalBalance": "7675.34",
    "redeemableBalance": "7675.34"
  }
}

NOTE: redeemableBalance is the balance you must display to the user.

Sample Code

Sample Request (Curl)

curl --location 'https://amazonpay.amazon.in//v1/payments/instruments?merchantId=A28RUURDCTQXU1&accessToken=Atza|IgEBdsfsdfdsf&instrumentTypes=AmazonPayBalance' \
--header 'x-amz-date: 20220311T135700Z' \
--header 'x-amz-user-ip: 52.95.75.13' \
--header 'x-amz-user-agent: Postman' \
--header 'x-amz-client-id: AZ4WQCLDT2DF0' \
--header 'x-amz-expires: 900' \
--header 'x-amz-algorithm: AWS4-HMAC-SHA384' \
--header 'x-amz-source: Browser' \
--header 'Authorization: AMZ+f57bbc68-fa6a-4c5e-a281-d39db51a26c6:98htMuBl6MKdfJMlxVRTjvq0T3rMYaM'

Sample Response (Curl)

{
  "amazonPayBalance": {
    "enabled": true,
    "priority": 0,
    "totalBalance": "1500.00",
    "redeemableBalance": "1500.00"
  }
}

JavaNodeJSPHP

/* Create HTTP request Object */
OkHttpClient client = new OkHttpClient().newBuilder().build();

/* API headers */
MediaType mediaType = MediaType.parse("text/plain"); 
RequestBody body = RequestBody.create(mediaType, "");

/* Querry parameters */
Request request = new Request.Builder() 
    .url("https://amazonpay.amazon.in/v1/payments/instruments?merchantId=A28RUURDCTQXU1&accessToken=Atza|IgEBdsfsdfdsf&instrumentTypes=AmazonPayBalance") 
    .method("GET", body) 
    .addHeader("x-amz-date", "20220311T135700Z") 
    .addHeader("x-amz-user-ip", "52.95.75.13") 
    .addHeader("x-amz-user-agent", "Postman") 
    .addHeader("x-amz-client-id", "AZ4WQCLDT2DF0") 
    .addHeader("x-amz-expires", "900") 
    .addHeader("x-amz-algorithm", "AWS4-HMAC-SHA384") 
    .addHeader("x-amz-source", "Browser") 
    .addHeader("Authorization", "AMZ+f57bbc68-fa6a-4c5e-a281-XXXXXX:98htMuBl6MKdfJMlxVRTjvq0T3rMYaMnElO_ekbXMJqohP9jOHfHcfmPU0drNtua") 
    .build();

/* Capture Response */
Response response = client.newCall(request).execute();

var request = require('request');

/* Prepearing API request */
var options = { 'method': 'GET', 'url': 'https://amazonpay.amazon.in/v1/payments/instruments?merchantId=A28RUURDCTQXU1&accessToken=Atza|IgEBdsfsdfdsf&instrumentTypes=AmazonPayBalance',

/* Adding API headers */
'headers': { 'x-amz-date': '20220311T135700Z', 'x-amz-user-ip': '52.95.75.13', 'x-amz-user-agent': 'Postman', 'x-amz-client-id': 'AZ4WQCLDT2DF0', 'x-amz-expires': '900', 'x-amz-algorithm': 'AWS4-HMAC-SHA384', 'x-amz-source': 'Browser', 'Authorization': 'AMZ+f57bbc68-fa6a-4c5e-a281-XXXXXXX:98htMuBl6MKdfJMlxVRTjvq0T3rMYaMnElO_ekbXMJqohP9jOHfHcfmPU0drNtua' } };

/* Capture Response */
request(options, function (error, response) { 
    if (error) throw new Error(error);

    console.log(response.body); 
});

$client = new Client();

/* API headers */
$headers = [ 'x-amz-date' => '20220311T135700Z', 'x-amz-user-ip' => '52.95.75.13', 'x-amz-user-agent' => 'Postman', 'x-amz-client-id' => 'AZ4WQCLDT2DF0', 'x-amz-expires' => '900', 'x-amz-algorithm' => 'AWS4-HMAC-SHA384', 'x-amz-source' => 'Browser', 'Authorization' => 'AMZ+f57bbc68-fa6a-4c5e-a281-XXXXXXXX:98htMuBl6MKdfJMlxVRTjvq0T3rMYaMnElO_ekbXMJqohP9jOHfHcfmPU0drNtua' ];

/* API request */
$request = new Request('GET', 'https://amazonpay.amazon.in/v1/payments/instruments?merchantId=AZ4WQCLDT2DF0&accessToken=Atza|YgF-5lV&instrumentTypes=AmazonPayBalance', $headers);

/* Capture Response */
$res = $client->sendAsync($request)->wait();

echo $res->getBody();

Common Errors

Error	Resolution
InvalidAccessToken	This error indicates that the access token has turned stale and is no longer valid or doesn't have the right permissions. Access tokens turn stale 60 minutes after they are requested. To resolve, request a new access token. If the error persists, ask the user to re-link the account.
Missing Amount in API request	This error message indicates that there is no amount specified in the API request. Ensure that the right amount is specified.
Signature error	To resolve errors related to signatures: Ensure that the right keys are used Ensure that the Signature generation process is followed, parameters are sorted while generating the canonical request, and timestamp used in canonical request, string to sign, API request, and the header are appropriate.