Skip to content

Get Instruments API

Method: GET

Path: https://amazonpay.amazon.in/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 Name Data Type Description Mandatory Constraints
merchantId String Merchant ID provided by Amazon Yes
accessToken String Fetched for the user using Access Token API Yes
instrumentTypes String Payment modes for this order Yes Allowed value: "AmazonPayLater"
amount String Amount to be charged Yes If the amount parameter is not provided, the eligibility field is returned as false.

Instrument Types

Value Description
AmazonPayLater Fetches the credit limit for AmazonPayLater and the eligibility of the user. If the customer is not eligible, we will provide the ineligibility reason.

Request Sample

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

Sample Response

Note:

  • For all ineligible scenarios, PSPs must display the exact ineligibility reason from the API response to the customer on the checkout screen.
  • If you face any challenges in displaying these reasons, Please reach out to your SA POC at Amazon Pay for support.
    • ⚠️ Any deviation from the proposed GUI guidelines may block the integration sign-off.
HTTP Status Code Response Description
200 
{
    "amazonPayLater": {
        "enabled": true,
        "priority": 3,
        "availableCredit": "50000",
        "ineligibilityCode": null,
        "ineligibilityReason": null,
        "keyFactStatementUrl": "https://amazonpay.amazon.in/render_kfs?authToken=A&payload=A&iv=a"
    }
}
 When the pre-eligibility API returns a "enabled": true, indicates that the user is eligible for Amazon Pay Later, you will have to display the Key Fact Statement (KFS) to ensure customers can review credit statement before proceeding.

Mandatory Consent Statement: Your checkout interface must display the following complete statement with the KFS as a clickable hyperlink: "By proceeding, I understand and agree to the Key Fact Statement"
200 
{
    "amazonPayLater": {
        "enabled": false,
        "priority": 3,
        "availableCredit": "0",
        "ineligibilityCode": "APL_KYC_EXPIRED",
        "ineligibilityReason": "Your KYC has expired, please update on the Amazon app."
    }
}
 User is ineligible for Amazon Pay Later as their KYC is expired. User should login to Amazon app to complete the KYC to activate Amazon Pay Later
200 
{
    "amazonPayLater": {
        "enabled": false,
        "priority": 3,
        "availableCredit": "0",
        "ineligibilityCode": "APL_UNAVAILABLE",
        "ineligibilityReason": "Amazon Pay Later is unavailable for this transaction."
    }
}
 Amazon Pay Later is currently unavailable for this user.
200 
{
    "amazonPayLater": {
        "enabled": false,
        "priority": 3,
        "availableCredit": "0",
        "ineligibilityCode": "APL_UNREGISTERED_ACCOUNT",
        "ineligibilityReason": "You are not registered with Amazon Pay Later. 
               Please complete your registration on the Amazon app."
    }
}
 User has not completed Amazon Pay Later registration.
User should login to Amazon app to complete registration to activate Amazon Pay Later
200 
{
    "amazonPayLater": {
        "enabled": false,
        "priority": 3,
        "availableCredit": "0",
        "ineligibilityCode": "APL_STANDING_INSTRUCTION_EXCEEDED",
        "ineligibilityReason": "Your standing instructions do not cover the current purchase."
    }
}
 User's standing instructions do not cover this purchase. User should update their standing instructions on the Amazon app.
200 
{
    "amazonPayLater": {
        "enabled": false,
        "priority": 3,
        "availableCredit": "0",
        "ineligibilityCode": "APL_ONE_MONTH_INSTALLMENT_UNAVAILABLE",
        "ineligibilityReason": "Amazon Pay Later is unavailable for this transaction."
    }
}
 Amazon Pay Later one month installment is not available for this transaction.
200 
{
    "amazonPayLater": {
        "enabled": false,
        "priority": 3,
        "availableCredit": "0",
        "ineligibilityCode": "APL_INSUFFICIENT_CREDIT",
        "ineligibilityReason": "Your Amazon Pay Later credit is not available at this merchant."
    }
}
 User does not have sufficient Amazon Pay Later credit for this transaction.

Sample Code

curl --location 'https://amazonpay.amazon.in/v1/payments/instruments?merchantId=A28RUURDCTQXU1&accessToken=Atza|IgEBdsfsdfdsf&instrumentTypes=AmazonPayLater&amount=10.00' \
--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'

/* 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=AmazonPayLater&amount=10.00") 
    .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=AmazonPayLater&amount=10.00',

/* 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=AmazonPayLater&amount=1000', $headers);

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

echo $res->getBody();

Common Errors

HTTP Status Code Response Description
401 
{
  "code": "AuthorizationFailed",
  "message": "Specified signature is invalid."
}
 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.
    		•
    403 
    {
  "code": "InvalidAccessToken",
  "message": "Merchant is not authorized.
     The access token may be either malformed or unusable."    
    }
    		 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.
    400 
    {
  "code": "MerchantIdMismatch",
  "message": "Specified merchant id does not match with x-amz-client-id header value."
}
    		 This error indicates that the the incorrect MID in the request headers.
    Ensure that the correct MID used
    400 
    {
  "code": "InvalidArguments",
  "message": "instrumentTypes must be one of following:
    [AmazonPayBalance, AmazonPayLater, Card, UPI]"    
    }
    		 This error indicates that the the incorrect instrumentTypes in the request headers.
    Ensure that the correct instrumentTypes used
    400 
    {
  "code": "InvalidArguments",
  "message": "amount must be greater than or equal to 0.01"
}
    		 This error indicates that the the when amount passed as 0 in the request
    Ensure that the amount must be greater than or equal to 0.01
    500 
    {
  "code": "InternalServerError",
  "message": "An internal server error has occurred. Try your request again later"
}
    		 This error that server encountered an unexpected error while processing the request.
    Please try again later. If the issue persists, contact the Amazon Pay support team.