SDK for PHP V3

Client: Aws\Payments\PaymentsClient
Service ID: payments
Version: 2026-09-23

This page describes the parameters and results for the operations of the AWS Payments (2026-09-23), and shows how to use the Aws\Payments\PaymentsClient object to call the described operations. This documentation is specific to the 2026-09-23 API version of the service.

Operation Summary

Each of the following operations can be created from a client using $client->getCommand('CommandName'), where "CommandName" is the name of one of the following operations. Note: a command is a value that encapsulates an operation and the parameters used to create an HTTP request.

You can also create and send a command immediately using the magic methods available on a client object: $client->commandName(/* parameters */). You can send the command asynchronously (returning a promise) by appending the word "Async" to the operation name: $client->commandNameAsync(/* parameters */).

BatchGetFinancialRecord ( array $params = [] )
Retrieves up to 100 financial records in one request, including the details that are specific to each record's type.
GetAccountBalance ( array $params = [] )
Retrieves one balance of your account, selected by balance type, as one amount for each merchant of record and currency.
GetFinancialRecord ( array $params = [] )
Retrieves a single financial record, including the details that are specific to its type.
GetPaymentInstrument ( array $params = [] )
Retrieves a payment instrument on your account, including the details that are specific to its payment method, such as a card's last four digits.
ListFinancialRecords ( array $params = [] )
Lists the financial records on your account, with the newest first by default.
ListPaymentInstruments ( array $params = [] )
Lists the payment instruments on your account.

Paginators

Paginators handle automatically iterating over paginated API results. Paginators are associated with specific API operations, and they accept the parameters that the corresponding API operation accepts. You can get a paginator from a client class using getPaginator($paginatorName, $operationParameters). This client supports the following paginators:

GetAccountBalance
ListFinancialRecords
ListPaymentInstruments

Operations

BatchGetFinancialRecord

$result = $client->batchGetFinancialRecord([/* ... */]);
$promise = $client->batchGetFinancialRecordAsync([/* ... */]);

Retrieves up to 100 financial records in one request, including the details that are specific to each record's type. Identify each record by its ID or by its invoice ID. Results can be partial: each key that you request appears once in the response, either as a record in financialRecords or as an error in errors. A key that matches no record on your account is returned in errors and doesn't fail the request. This operation provides strongly consistent reads.

To use this operation, you must have Amazon Web Services Identity and Access Management (IAM) permission for both payments:BatchGetFinancialRecord and payments:GetPaymentStatus.

Parameter Syntax

$result = $client->batchGetFinancialRecord([
    'keys' => [ // REQUIRED
        [
            'identifier' => '<string>',
            'invoiceIdentifier' => '<string>',
        ],
        // ...
    ],
]);

Parameter Details

Members
keys
Required: Yes
Type: Array of FinancialRecordKey structures

The keys of the financial records to retrieve. Each key is either the record's ID or its invoice ID.

Result Syntax

[
    'errors' => [
        [
            'code' => 'NOT_FOUND|INTERNAL_ERROR',
            'key' => [
                'identifier' => '<string>',
                'invoiceIdentifier' => '<string>',
            ],
            'message' => '<string>',
        ],
        // ...
    ],
    'financialRecords' => [
        [
            'amount' => [
                'currency' => '<string>',
                'value' => '<string>',
            ],
            'balances' => [
                'canceled' => [
                    'currency' => '<string>',
                    'value' => '<string>',
                ],
                'outstanding' => [
                    'currency' => '<string>',
                    'value' => '<string>',
                ],
                'processing' => [
                    'currency' => '<string>',
                    'value' => '<string>',
                ],
                'settled' => [
                    'currency' => '<string>',
                    'value' => '<string>',
                ],
            ],
            'businessUnit' => [
                'lineOfBusiness' => 'AWS_CLOUD_SERVICES|PROSERVE_MARKETING_AND_TRAINING|AWS_MARKETPLACE',
                'merchantOfRecord' => '<string>',
            ],
            'closedAt' => <DateTime>,
            'details' => [
                'creditMemoDetails' => [
                    'billingPeriod' => [
                        'endDate' => <DateTime>,
                        'startDate' => <DateTime>,
                    ],
                    'invoiceId' => '<string>',
                ],
                'invoiceDetails' => [
                    'billingPeriod' => [
                        'endDate' => <DateTime>,
                        'startDate' => <DateTime>,
                    ],
                    'dueDate' => <DateTime>,
                    'dueStatus' => 'DUE|PAST_DUE',
                    'invoiceFrequency' => 'ONE_TIME|RECURRING',
                    'invoiceId' => '<string>',
                    'paymentTerms' => '<string>',
                ],
            ],
            'id' => '<string>',
            'issuedAt' => <DateTime>,
            'settlementStatus' => 'OPEN|CLOSED',
            'status' => 'OUTSTANDING|PROCESSING|SETTLED|CANCELED',
            'type' => 'INVOICE|CREDIT_MEMO',
        ],
        // ...
    ],
]

Result Details

Members
errors
Required: Yes
Type: Array of FinancialRecordError structures

The errors for the records that the operation couldn't retrieve, one for each record, with the key as you requested it and the reason. This list is empty when the operation retrieved every record.

financialRecords
Required: Yes
Type: Array of FinancialRecord structures

The financial records that the operation retrieved, in no particular order. This list contains fewer records than you requested when errors names one or more keys.

Errors

InternalServerException:

The request processing failed because of an unknown error, exception, or failure. Retry your request.

ThrottlingException:

The request was denied due to request throttling. Reduce the frequency of your requests and try again.

ValidationException:

The request isn't valid. Check reason and fieldList for the cause, correct the request, and try again.

AccessDeniedException:

The request is denied because you don't have sufficient access to perform this operation. Verify that you have the required permissions and try again. This error is also returned, instead of ResourceNotFoundException, when you aren't authorized for the resource, so the response doesn't reveal whether the resource exists.

Examples

Example 1: Invoke BatchGetFinancialRecord
$result = $client->batchGetFinancialRecord([
    'keys' => [
        [
            'identifier' => 'INV-1234-5678-9012-3456',
        ],
        [
            'invoiceIdentifier' => '999999999999',
        ],
    ],
]);

Result syntax:

[
    'errors' => [
        [
            'key' => [
                'invoiceIdentifier' => '999999999999',
            ],
            'code' => 'NOT_FOUND',
            'message' => 'The requested resource was not found',
        ],
    ],
    'financialRecords' => [
        [
            'type' => 'INVOICE',
            'amount' => [
                'value' => '1000.24',
                'currency' => 'USD',
            ],
            'balances' => [
                'canceled' => [
                    'value' => '0.0',
                    'currency' => 'USD',
                ],
                'outstanding' => [
                    'value' => '0.0',
                    'currency' => 'USD',
                ],
                'processing' => [
                    'value' => '0.0',
                    'currency' => 'USD',
                ],
                'settled' => [
                    'value' => '1000.24',
                    'currency' => 'USD',
                ],
            ],
            'businessUnit' => [
                'lineOfBusiness' => 'AWS_CLOUD_SERVICES',
                'merchantOfRecord' => 'Amazon Web Services, Inc.',
            ],
            'closedAt' => ,
            'details' => [
                'invoiceDetails' => [
                    'billingPeriod' => [
                        'endDate' => ,
                        'startDate' => ,
                    ],
                    'dueDate' => ,
                    'invoiceFrequency' => 'RECURRING',
                    'invoiceId' => '536462537364',
                    'paymentTerms' => 'Net30',
                ],
            ],
            'id' => 'INV-1234-5678-9012-3456',
            'issuedAt' => ,
            'settlementStatus' => 'CLOSED',
            'status' => 'SETTLED',
        ],
    ],
]

GetAccountBalance

$result = $client->getAccountBalance([/* ... */]);
$promise = $client->getAccountBalanceAsync([/* ... */]);

Retrieves one balance of your account, selected by balance type, as one amount for each merchant of record and currency. Each amount is the sum of the outstanding balances of your invoices or credit memos that have the status OUTSTANDING. Amounts are never added together across merchants of record or currencies. This operation is eventually consistent. Results are paginated. Use nextToken to retrieve more results.

To use this operation, you must have Amazon Web Services Identity and Access Management (IAM) permission for both payments:GetAccountBalance and payments:GetPaymentStatus.

Parameter Syntax

$result = $client->getAccountBalance([
    'balanceType' => 'INVOICES_DUE|INVOICES_PAST_DUE|OUTSTANDING_CREDIT_MEMOS', // REQUIRED
    'maxResults' => <integer>,
    'nextToken' => '<string>',
]);

Parameter Details

Members
balanceType
Required: Yes
Type: string

The balance to retrieve. You can specify only one balance type in a single request. Each balance adds up the outstanding balance of the records that have the status OUTSTANDING. A record that is PROCESSING, SETTLED, or CANCELED isn't included, even when part of its amount is outstanding. The following values are valid:

  • INVOICES_DUE – The outstanding balance of your OUTSTANDING invoices that aren't past their due date, where dueStatus is DUE.

  • INVOICES_PAST_DUE – The outstanding balance of your OUTSTANDING invoices that are past their due date, where dueStatus is PAST_DUE.

  • OUTSTANDING_CREDIT_MEMOS – The outstanding balance of your OUTSTANDING credit memos: the credit that isn't yet applied to an invoice.

maxResults
Type: int

The maximum number of results to return in one page. The default is 100. A page can contain fewer results even when more remain. Use nextToken to find out whether more results are available.

nextToken
Type: string

The pagination token from the nextToken of the previous response. Omit it to get the first page. Tokens expire. If the token is malformed or expired, or doesn't match the original request, the request fails with ValidationException and the reason INVALID_PAGINATION_TOKEN. In that case, start again from the first page.

Result Syntax

[
    'accountBalances' => [
        [
            'amount' => [
                'currency' => '<string>',
                'value' => '<string>',
            ],
            'merchantOfRecord' => '<string>',
        ],
        // ...
    ],
    'nextToken' => '<string>',
]

Result Details

Members
accountBalances
Required: Yes
Type: Array of AccountBalance structures

The balance, as one amount for each merchant of record and currency. This list is empty when your account has nothing in the requested balance.

nextToken
Type: string

The pagination token that indicates the next set of results to retrieve. This value is absent when there are no more results.

Errors

InternalServerException:

The request processing failed because of an unknown error, exception, or failure. Retry your request.

ThrottlingException:

The request was denied due to request throttling. Reduce the frequency of your requests and try again.

ValidationException:

The request isn't valid. Check reason and fieldList for the cause, correct the request, and try again.

AccessDeniedException:

The request is denied because you don't have sufficient access to perform this operation. Verify that you have the required permissions and try again. This error is also returned, instead of ResourceNotFoundException, when you aren't authorized for the resource, so the response doesn't reveal whether the resource exists.

Examples

Example 1: Invoke GetAccountBalance
$result = $client->getAccountBalance([
    'balanceType' => 'INVOICES_PAST_DUE',
]);

Result syntax:

[
    'accountBalances' => [
        [
            'amount' => [
                'value' => '1250.00',
                'currency' => 'USD',
            ],
            'merchantOfRecord' => 'Amazon Web Services, Inc.',
        ],
        [
            'amount' => [
                'value' => '430.75',
                'currency' => 'INR',
            ],
            'merchantOfRecord' => 'Amazon Web Services India Private Limited',
        ],
    ],
]

GetFinancialRecord

$result = $client->getFinancialRecord([/* ... */]);
$promise = $client->getFinancialRecordAsync([/* ... */]);

Retrieves a single financial record, including the details that are specific to its type. Specify exactly one of the following:

  • The ID that Amazon Web Services Payments issued for the record, in identifier.

  • The invoice ID that Amazon Web Services Invoicing issued for an invoice or a credit memo, in invoiceIdentifier.

If you specify both or neither, the request fails with ValidationException. If no record on your account matches, the request fails with ResourceNotFoundException.

This operation provides strongly consistent reads.

To use this operation, you must have Amazon Web Services Identity and Access Management (IAM) permission for both payments:GetFinancialRecord and payments:GetPaymentStatus.

Parameter Syntax

$result = $client->getFinancialRecord([
    'identifier' => '<string>',
    'invoiceIdentifier' => '<string>',
]);

Parameter Details

Members
identifier
Type: string

The ID that Amazon Web Services Payments issued for the financial record, as returned in id.

invoiceIdentifier
Type: string

The invoice ID that Amazon Web Services Invoicing issued for an invoice or a credit memo. The operation returns the record that has this invoice ID.

Result Syntax

[
    'financialRecord' => [
        'amount' => [
            'currency' => '<string>',
            'value' => '<string>',
        ],
        'balances' => [
            'canceled' => [
                'currency' => '<string>',
                'value' => '<string>',
            ],
            'outstanding' => [
                'currency' => '<string>',
                'value' => '<string>',
            ],
            'processing' => [
                'currency' => '<string>',
                'value' => '<string>',
            ],
            'settled' => [
                'currency' => '<string>',
                'value' => '<string>',
            ],
        ],
        'businessUnit' => [
            'lineOfBusiness' => 'AWS_CLOUD_SERVICES|PROSERVE_MARKETING_AND_TRAINING|AWS_MARKETPLACE',
            'merchantOfRecord' => '<string>',
        ],
        'closedAt' => <DateTime>,
        'details' => [
            'creditMemoDetails' => [
                'billingPeriod' => [
                    'endDate' => <DateTime>,
                    'startDate' => <DateTime>,
                ],
                'invoiceId' => '<string>',
            ],
            'invoiceDetails' => [
                'billingPeriod' => [
                    'endDate' => <DateTime>,
                    'startDate' => <DateTime>,
                ],
                'dueDate' => <DateTime>,
                'dueStatus' => 'DUE|PAST_DUE',
                'invoiceFrequency' => 'ONE_TIME|RECURRING',
                'invoiceId' => '<string>',
                'paymentTerms' => '<string>',
            ],
        ],
        'id' => '<string>',
        'issuedAt' => <DateTime>,
        'settlementStatus' => 'OPEN|CLOSED',
        'status' => 'OUTSTANDING|PROCESSING|SETTLED|CANCELED',
        'type' => 'INVOICE|CREDIT_MEMO',
    ],
]

Result Details

Members
financialRecord
Required: Yes
Type: FinancialRecord structure

The requested financial record.

Errors

InternalServerException:

The request processing failed because of an unknown error, exception, or failure. Retry your request.

ResourceNotFoundException:

The requested resource couldn't be found. Verify that the resource ID is correct. This error is returned only when you're authorized for the resource.

ThrottlingException:

The request was denied due to request throttling. Reduce the frequency of your requests and try again.

ValidationException:

The request isn't valid. Check reason and fieldList for the cause, correct the request, and try again.

AccessDeniedException:

The request is denied because you don't have sufficient access to perform this operation. Verify that you have the required permissions and try again. This error is also returned, instead of ResourceNotFoundException, when you aren't authorized for the resource, so the response doesn't reveal whether the resource exists.

Examples

Example 1: Invoke GetFinancialRecord
$result = $client->getFinancialRecord([
    'identifier' => 'INV-1234-5678-9012-3456',
]);

Result syntax:

[
    'financialRecord' => [
        'type' => 'INVOICE',
        'amount' => [
            'value' => '1000.24',
            'currency' => 'USD',
        ],
        'balances' => [
            'canceled' => [
                'value' => '0.0',
                'currency' => 'USD',
            ],
            'outstanding' => [
                'value' => '0.0',
                'currency' => 'USD',
            ],
            'processing' => [
                'value' => '0.0',
                'currency' => 'USD',
            ],
            'settled' => [
                'value' => '1000.24',
                'currency' => 'USD',
            ],
        ],
        'businessUnit' => [
            'lineOfBusiness' => 'AWS_CLOUD_SERVICES',
            'merchantOfRecord' => 'Amazon Web Services, Inc.',
        ],
        'closedAt' => ,
        'details' => [
            'invoiceDetails' => [
                'billingPeriod' => [
                    'endDate' => ,
                    'startDate' => ,
                ],
                'dueDate' => ,
                'invoiceFrequency' => 'RECURRING',
                'invoiceId' => '536462537364',
                'paymentTerms' => 'Net30',
            ],
        ],
        'id' => 'INV-1234-5678-9012-3456',
        'issuedAt' => ,
        'settlementStatus' => 'CLOSED',
        'status' => 'SETTLED',
    ],
]

GetPaymentInstrument

$result = $client->getPaymentInstrument([/* ... */]);
$promise = $client->getPaymentInstrumentAsync([/* ... */]);

Retrieves a payment instrument on your account, including the details that are specific to its payment method, such as a card's last four digits. Identify the instrument by its Amazon Resource Name (ARN) or by its ID. ListPaymentInstruments returns both.

To use this operation, you must have Amazon Web Services Identity and Access Management (IAM) permission for payments:GetPaymentInstrument. You can scope this permission to the instrument's ARN.

Parameter Syntax

$result = $client->getPaymentInstrument([
    'identifier' => '<string>', // REQUIRED
]);

Parameter Details

Members
identifier
Required: Yes
Type: string

The instrument to retrieve. Specify one of the following:

  • The Amazon Resource Name (ARN) of the instrument, as ListPaymentInstruments returns in arn. The ARN must be for an instrument on your account.

  • The ID of the instrument, as ListPaymentInstruments returns in id.

Result Syntax

[
    'paymentInstrument' => [
        'arn' => '<string>',
        'createdAt' => <DateTime>,
        'details' => [
            'card' => [
                'brand' => 'VISA|MASTERCARD|AMEX|DISCOVER|JCB|RUPAY|CHINA_UNIONPAY',
                'cardType' => 'CREDIT|DEBIT',
                'expirationMonth' => <integer>,
                'expirationYear' => <integer>,
                'issuerCountry' => '<string>',
                'issuingBank' => '<string>',
                'last4' => '<string>',
            ],
            'cnBankRedirect' => [
                'bankCode' => '<string>',
            ],
            'inNetBanking' => [
                'bankCode' => '<string>',
                'bankName' => '<string>',
            ],
            'sepaBankAccount' => [
                'accountHolderName' => '<string>',
                'accountNumberTail' => '<string>',
                'accountType' => 'CHECKING|SAVINGS',
                'bankName' => '<string>',
            ],
            'ukBacsBankAccount' => [
                'accountHolderName' => '<string>',
                'accountNumberTail' => '<string>',
                'accountType' => 'CHECKING|SAVINGS',
                'bankName' => '<string>',
            ],
            'upi' => [
                'appName' => '<string>',
            ],
            'usAchBankAccount' => [
                'accountHolderName' => '<string>',
                'accountNumberTail' => '<string>',
                'accountType' => 'CHECKING|SAVINGS',
                'bankName' => '<string>',
            ],
        ],
        'paymentMethod' => 'CARD|US_ACH_BANK_ACCOUNT|SEPA_BANK_ACCOUNT|UK_BACS_BANK_ACCOUNT|IN_NET_BANKING|CN_BANK_REDIRECT|UPI|PIX|PAY_BY_INVOICE',
        'status' => 'ACTIVE|PENDING_SETUP|SETUP_IN_PROGRESS|INVALID',
        'updatedAt' => <DateTime>,
    ],
]

Result Details

Members
paymentInstrument
Required: Yes
Type: PaymentInstrument structure

The payment instrument, including the details that are specific to its payment method.

Errors

InternalServerException:

The request processing failed because of an unknown error, exception, or failure. Retry your request.

ResourceNotFoundException:

The requested resource couldn't be found. Verify that the resource ID is correct. This error is returned only when you're authorized for the resource.

ThrottlingException:

The request was denied due to request throttling. Reduce the frequency of your requests and try again.

ValidationException:

The request isn't valid. Check reason and fieldList for the cause, correct the request, and try again.

AccessDeniedException:

The request is denied because you don't have sufficient access to perform this operation. Verify that you have the required permissions and try again. This error is also returned, instead of ResourceNotFoundException, when you aren't authorized for the resource, so the response doesn't reveal whether the resource exists.

Examples

Example 1: Invoke GetPaymentInstrument
$result = $client->getPaymentInstrument([
    'identifier' => 'arn:aws:payments::123456789012:payment-instrument:1a2b3c4d-5e6f-7a8b-9c0d-111122223333',
]);

Result syntax:

[
    'paymentInstrument' => [
        'arn' => 'arn:aws:payments::123456789012:payment-instrument:1a2b3c4d-5e6f-7a8b-9c0d-111122223333',
        'createdAt' => ,
        'details' => [
            'card' => [
                'brand' => 'VISA',
                'cardType' => 'CREDIT',
                'expirationMonth' => 7,
                'expirationYear' => 2030,
                'issuerCountry' => 'US',
                'issuingBank' => 'Example Bank',
                'last4' => '1111',
            ],
        ],
        'paymentMethod' => 'CARD',
        'status' => 'ACTIVE',
        'updatedAt' => ,
    ],
]

ListFinancialRecords

$result = $client->listFinancialRecords([/* ... */]);
$promise = $client->listFinancialRecordsAsync([/* ... */]);

Lists the financial records on your account, with the newest first by default. A financial record is an invoice or a credit memo. You must specify at least one record type in types. You can narrow the results further by settlement status and issue date. This operation returns summaries. To get the details that are specific to a record's type, use GetFinancialRecord or BatchGetFinancialRecord. Results are paginated. Use nextToken to retrieve more results.

To use this operation, you must have Amazon Web Services Identity and Access Management (IAM) permission for both payments:ListFinancialRecords and payments:GetPaymentStatus.

Parameter Syntax

$result = $client->listFinancialRecords([
    'issuedAfter' => <integer || string || DateTime>,
    'issuedBefore' => <integer || string || DateTime>,
    'maxResults' => <integer>,
    'nextToken' => '<string>',
    'settlementStatuses' => ['<string>', ...],
    'sortBy' => 'ISSUED_AT',
    'sortOrder' => 'ASCENDING|DESCENDING',
    'types' => ['<string>', ...], // REQUIRED
]);

Parameter Details

Members
issuedAfter
Type: timestamp (string|DateTime or anything parsable by strtotime)

The earliest date and time to return records for, inclusive. The operation returns the records that were issued at or after this time.

issuedBefore
Type: timestamp (string|DateTime or anything parsable by strtotime)

The latest date and time to return records for, exclusive. The operation returns the records that were issued before this time. When you specify both issuedAfter and issuedBefore, issuedBefore must be later than issuedAfter.

maxResults
Type: int

The maximum number of results to return in one page. The default is 100. A page can contain fewer results even when more remain. Use nextToken to find out whether more results are available.

nextToken
Type: string

The pagination token from the nextToken of the previous response. Omit it to get the first page. Tokens expire. If the token is malformed or expired, or doesn't match the original request, the request fails with ValidationException and the reason INVALID_PAGINATION_TOKEN. In that case, start again from the first page.

settlementStatuses
Type: Array of strings

The settlement statuses to filter by. OPEN returns records whose status is OUTSTANDING or PROCESSING. CLOSED returns records whose status is SETTLED or CANCELED. When you omit this member, the operation returns records with both settlement statuses.

sortBy
Type: string

The field to sort the results by. The default is ISSUED_AT, the date and time when the record was issued.

sortOrder
Type: string

The order to sort the results in. The default is DESCENDING, which returns the newest records first. ASCENDING returns the oldest records first.

types
Required: Yes
Type: Array of strings

The financial record types to return. The following values are valid:

  • INVOICE – An invoice: a bill from Amazon Web Services. Payments and credit memos applied to the invoice settle it.

  • CREDIT_MEMO – A credit memo: a credit issued to your account, for example for a billing correction or a service credit. Applying it to one or more invoices settles it.

Result Syntax

[
    'financialRecordSummaries' => [
        [
            'amount' => [
                'currency' => '<string>',
                'value' => '<string>',
            ],
            'balances' => [
                'canceled' => [
                    'currency' => '<string>',
                    'value' => '<string>',
                ],
                'outstanding' => [
                    'currency' => '<string>',
                    'value' => '<string>',
                ],
                'processing' => [
                    'currency' => '<string>',
                    'value' => '<string>',
                ],
                'settled' => [
                    'currency' => '<string>',
                    'value' => '<string>',
                ],
            ],
            'businessUnit' => [
                'lineOfBusiness' => 'AWS_CLOUD_SERVICES|PROSERVE_MARKETING_AND_TRAINING|AWS_MARKETPLACE',
                'merchantOfRecord' => '<string>',
            ],
            'closedAt' => <DateTime>,
            'id' => '<string>',
            'issuedAt' => <DateTime>,
            'settlementStatus' => 'OPEN|CLOSED',
            'status' => 'OUTSTANDING|PROCESSING|SETTLED|CANCELED',
            'type' => 'INVOICE|CREDIT_MEMO',
        ],
        // ...
    ],
    'nextToken' => '<string>',
]

Result Details

Members
financialRecordSummaries
Required: Yes
Type: Array of FinancialRecordSummary structures

The financial record summaries that match your filters, in the requested order. This list is empty when no record matches.

nextToken
Type: string

The pagination token that indicates the next set of results to retrieve. This value is absent when there are no more results.

Errors

InternalServerException:

The request processing failed because of an unknown error, exception, or failure. Retry your request.

ThrottlingException:

The request was denied due to request throttling. Reduce the frequency of your requests and try again.

ValidationException:

The request isn't valid. Check reason and fieldList for the cause, correct the request, and try again.

AccessDeniedException:

The request is denied because you don't have sufficient access to perform this operation. Verify that you have the required permissions and try again. This error is also returned, instead of ResourceNotFoundException, when you aren't authorized for the resource, so the response doesn't reveal whether the resource exists.

Examples

Example 1: Invoke ListFinancialRecords
$result = $client->listFinancialRecords([
    'maxResults' => 5,
    'settlementStatuses' => [
        'CLOSED',
    ],
    'sortBy' => 'ISSUED_AT',
    'sortOrder' => 'DESCENDING',
    'types' => [
        'INVOICE',
    ],
]);

Result syntax:

[
    'financialRecordSummaries' => [
        [
            'type' => 'INVOICE',
            'amount' => [
                'value' => '1000.24',
                'currency' => 'USD',
            ],
            'balances' => [
                'canceled' => [
                    'value' => '0.0',
                    'currency' => 'USD',
                ],
                'outstanding' => [
                    'value' => '0.0',
                    'currency' => 'USD',
                ],
                'processing' => [
                    'value' => '0.0',
                    'currency' => 'USD',
                ],
                'settled' => [
                    'value' => '1000.24',
                    'currency' => 'USD',
                ],
            ],
            'businessUnit' => [
                'lineOfBusiness' => 'AWS_CLOUD_SERVICES',
                'merchantOfRecord' => 'Amazon Web Services, Inc.',
            ],
            'closedAt' => ,
            'id' => 'INV-1234-5678-9012-3456',
            'issuedAt' => ,
            'settlementStatus' => 'CLOSED',
            'status' => 'SETTLED',
        ],
    ],
]

ListPaymentInstruments

$result = $client->listPaymentInstruments([/* ... */]);
$promise = $client->listPaymentInstrumentsAsync([/* ... */]);

Lists the payment instruments on your account. This operation returns summaries. To get the details that are specific to an instrument's payment method, use GetPaymentInstrument. Results are paginated. Use nextToken to retrieve more results.

To use this operation, you must have Amazon Web Services Identity and Access Management (IAM) permission for payments:ListPaymentInstruments.

Parameter Syntax

$result = $client->listPaymentInstruments([
    'maxResults' => <integer>,
    'nextToken' => '<string>',
]);

Parameter Details

Members
maxResults
Type: int

The maximum number of payment instruments to return in one page. The default is 25. A page can contain fewer payment instruments even when more remain. Use nextToken to find out whether more payment instruments are available.

nextToken
Type: string

The pagination token from the nextToken of the previous response. Omit it to get the first page. Tokens expire. If the token is malformed or expired, or doesn't match the original request, the request fails with ValidationException and the reason INVALID_PAGINATION_TOKEN. In that case, start again from the first page.

Result Syntax

[
    'nextToken' => '<string>',
    'paymentInstrumentSummaries' => [
        [
            'arn' => '<string>',
            'createdAt' => <DateTime>,
            'id' => '<string>',
            'paymentMethod' => 'CARD|US_ACH_BANK_ACCOUNT|SEPA_BANK_ACCOUNT|UK_BACS_BANK_ACCOUNT|IN_NET_BANKING|CN_BANK_REDIRECT|UPI|PIX|PAY_BY_INVOICE',
            'status' => 'ACTIVE|PENDING_SETUP|SETUP_IN_PROGRESS|INVALID',
            'updatedAt' => <DateTime>,
        ],
        // ...
    ],
]

Result Details

Members
nextToken
Type: string

The pagination token that indicates the next set of results to retrieve. This value is absent when there are no more results.

paymentInstrumentSummaries
Required: Yes
Type: Array of PaymentInstrumentSummary structures

The payment instruments on your account, one summary for each instrument. This list is empty when your account has no payment instruments.

Errors

InternalServerException:

The request processing failed because of an unknown error, exception, or failure. Retry your request.

ThrottlingException:

The request was denied due to request throttling. Reduce the frequency of your requests and try again.

ValidationException:

The request isn't valid. Check reason and fieldList for the cause, correct the request, and try again.

AccessDeniedException:

The request is denied because you don't have sufficient access to perform this operation. Verify that you have the required permissions and try again. This error is also returned, instead of ResourceNotFoundException, when you aren't authorized for the resource, so the response doesn't reveal whether the resource exists.

Examples

Example 1: Invoke ListPaymentInstruments
$result = $client->listPaymentInstruments([
    'maxResults' => 5,
]);

Result syntax:

[
    'paymentInstrumentSummaries' => [
        [
            'arn' => 'arn:aws:payments::123456789012:payment-instrument:1a2b3c4d-5e6f-7a8b-9c0d-111122223333',
            'createdAt' => ,
            'id' => '1a2b3c4d-5e6f-7a8b-9c0d-111122223333',
            'paymentMethod' => 'CARD',
            'status' => 'ACTIVE',
            'updatedAt' => ,
        ],
        [
            'arn' => 'arn:aws:payments::123456789012:payment-instrument:2b3c4d5e-6f7a-8b9c-0d1e-444455556666',
            'createdAt' => ,
            'id' => '2b3c4d5e-6f7a-8b9c-0d1e-444455556666',
            'paymentMethod' => 'US_ACH_BANK_ACCOUNT',
            'status' => 'ACTIVE',
            'updatedAt' => ,
        ],
    ],
]

Shapes

AccessDeniedException

Description

The request is denied because you don't have sufficient access to perform this operation. Verify that you have the required permissions and try again. This error is also returned, instead of ResourceNotFoundException, when you aren't authorized for the resource, so the response doesn't reveal whether the resource exists.

Members
message
Required: Yes
Type: string
reason
Type: string

The reason that access was denied. The following values are valid:

  • NOT_AUTHORIZED – Your IAM policies don't allow this action.

  • INVALID_ACCOUNT_STATE – Your Amazon Web Services account isn't in a state that allows this action, for example because registration isn't complete or the account is suspended.

  • OTHER – Access was denied for another reason.

AccountBalance

Description

An amount of the balance that GetAccountBalance returns: the total for one merchant of record in one currency.

Members
amount
Required: Yes
Type: CurrencyAmount structure

The amount, in the currency that the records making up this balance were issued in.

merchantOfRecord
Required: Yes
Type: string

The merchant of record that issued the invoices or credit memos that make up this amount.

Balances

Description

How much of the record's amount is outstanding, processing, settled, and canceled. The four balances add up to amount. Each balance is in the currency of amount, and a balance with nothing in it is 0.

Members
canceled
Required: Yes
Type: CurrencyAmount structure

The part of the amount that was canceled and isn't settled, for example when an invoice is voided. When a partly settled record is canceled, it keeps its settled balance, and the rest of the amount moves to canceled. This balance is more than 0 only when the status is CANCELED.

outstanding
Required: Yes
Type: CurrencyAmount structure

The part of the amount that isn't settled and has no settlement in progress. For an invoice, this is what remains to pay. For a credit memo, this is the credit that isn't yet applied. This balance doesn't include processing.

processing
Required: Yes
Type: CurrencyAmount structure

The part of the amount with a settlement in progress, for example a payment that's submitted but not yet confirmed. It moves to settled when the settlement completes, and back to outstanding when the settlement fails. This balance is more than 0 only when the status is PROCESSING.

settled
Required: Yes
Type: CurrencyAmount structure

The part of the amount that is settled. For an invoice, this is the amount paid or covered by credit memos. For a credit memo, this is the amount applied to invoices. This balance is 0 when nothing is settled yet.

BillingPeriod

Description

A billing period, as a half-open date range: startDate is inclusive and endDate is exclusive. Both members are calendar dates, carried as the timestamp of 00:00:00 UTC on that day.

Members
endDate
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The day after the last day of the billing period, exclusive, as the timestamp of 00:00:00 UTC on that day. A calendar month runs from the first of the month to the first of the next month.

startDate
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The first day of the billing period, inclusive, as the timestamp of 00:00:00 UTC on that day.

BusinessUnit

Description

The Amazon Web Services business unit that issued a financial record. A business unit has two parts: the merchant of record, which is the Amazon Web Services entity that issued the record, and the line of business within that entity.

Members
lineOfBusiness
Type: string

The line of business within the merchant of record that issued the record. This member is absent when the line of business isn't known for the record. The following values are valid:

  • AWS_CLOUD_SERVICES – Your usage of Amazon Web Services services.

  • PROSERVE_MARKETING_AND_TRAINING – Amazon Web Services Professional Services, marketing, and training: consulting, events, and training that Amazon Web Services sells.

  • AWS_MARKETPLACE – Products that you bought from sellers in Amazon Web Services Marketplace.

merchantOfRecord
Required: Yes
Type: string

The Amazon Web Services entity that issued the invoice and collects payment for it, such as Amazon Web Services, Inc. or Amazon Web Services EMEA SARL. This is the invoicing entity shown in the Amazon Web Services Billing and Cost Management console. For Amazon Web Services Marketplace purchases, it can differ from the seller of record.

Card

Description

The details of a card payment instrument.

Members
brand
Type: string

The network the card runs on.

cardType
Type: string

Whether the card is a credit card or a debit card.

expirationMonth
Type: int

The calendar month that the card expires in.

expirationYear
Type: int

The calendar year that the card expires in.

issuerCountry
Type: string

The country of the bank that issued the card.

issuingBank
Type: string

The bank that issued the card.

last4
Required: Yes
Type: string

The last four digits of the card number.

CnBankRedirect

Description

The details of a China bank redirect instrument. A retail instrument is registered with one bank and carries that bank's code. A corporate instrument isn't registered with a bank.

Members
bankCode
Type: string

The code of the bank that the instrument is registered with. This member is present only for retail instruments.

CreditMemoDetails

Description

The details of a credit memo: the invoice ID that Amazon Web Services Invoicing issued for it and the billing period that it applies to.

Members
billingPeriod
Required: Yes
Type: BillingPeriod structure

The billing period the credit memo applies to: the period of the usage it credits.

invoiceId
Required: Yes
Type: string

The invoice ID that Amazon Web Services Invoicing issued for the credit memo: the document number printed on it, shown in the Amazon Web Services Billing and Cost Management console and returned by the Amazon Web Services Invoicing API as InvoiceId. GetFinancialRecord and BatchGetFinancialRecord also accept it, as invoiceIdentifier.

CurrencyAmount

Description

A monetary amount expressed as a decimal string in the currency's standard unit.

Members
currency
Required: Yes
Type: string

The ISO 4217 currency code for the amount (for example, USD).

value
Required: Yes
Type: string

The amount, as a decimal string, such as 10.99. The number of decimal places can differ between amounts, for example 0.0 and 1000.24.

FinancialRecord

Description

An invoice or a credit memo on your account, with the details that are specific to its type.

Members
amount
Required: Yes
Type: CurrencyAmount structure

The total amount of the financial record, in the currency that the record was issued in. The amount doesn't change as the record is settled. balances shows how much of it is in each settlement state.

balances
Required: Yes
Type: Balances structure

How much of amount is outstanding, processing, settled, and canceled.

businessUnit
Required: Yes
Type: BusinessUnit structure

The Amazon Web Services business unit that issued the record: its merchant of record and its line of business.

closedAt
Type: timestamp (string|DateTime or anything parsable by strtotime)

The date and time, in UTC, when the record was last closed, that is, when its status last became SETTLED or CANCELED. This member is absent while the settlementStatus is OPEN, including after a closed record reopens.

details
Required: Yes
Type: FinancialRecordDetails structure

The attributes that exist only for the record's type. The populated member matches type: invoiceDetails for an INVOICE, creditMemoDetails for a CREDIT_MEMO.

id
Required: Yes
Type: string

The ID that Amazon Web Services Payments issued for the record, such as INV-5364-6253-7364-1342. To retrieve the record again, pass this value to GetFinancialRecord or BatchGetFinancialRecord as identifier.

issuedAt
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The date and time, in UTC, when this record was issued.

settlementStatus
Required: Yes
Type: string

Whether the record is open or closed. If you receive a status value that you don't recognize, use this member to tell open records from closed ones. The following values are valid:

  • OPEN – Part of the amount is outstanding or processing. The status is OUTSTANDING or PROCESSING.

  • CLOSED – The whole amount is settled or canceled. The status is SETTLED or CANCELED.

A CLOSED record becomes OPEN again if a payment or credit applied to it is reversed. Its closedAt is then absent until the record closes again.

status
Required: Yes
Type: string

The settlement stage of the record. The following values are valid:

  • OUTSTANDING – Part of the amount isn't settled, and no settlement is in progress on the record. For an invoice, dueStatus shows whether it's due or past due. The settlementStatus is OPEN.

  • PROCESSING – A settlement of part or all of the amount is in progress, for example a payment that's submitted but not yet confirmed. PROCESSING takes precedence over OUTSTANDING: while any part of the amount is processing, the status is PROCESSING, even if another part is still outstanding. The settlementStatus is OPEN.

  • SETTLED – The whole amount is settled. The settlementStatus is CLOSED.

  • CANCELED – The record is canceled. The part of the amount that wasn't settled isn't collected or applied. The settlementStatus is CLOSED.

type
Required: Yes
Type: string

The type of the financial record. The populated member of details matches this type. The following values are valid:

  • INVOICE – An invoice: a bill from Amazon Web Services. Payments and credit memos applied to the invoice settle it.

  • CREDIT_MEMO – A credit memo: a credit issued to your account, for example for a billing correction or a service credit. Applying it to one or more invoices settles it.

FinancialRecordDetails

Description

The attributes that exist only for one type of financial record. The populated member matches the record's type.

Members
creditMemoDetails
Type: CreditMemoDetails structure

The details of a credit memo. Populated when type is CREDIT_MEMO.

invoiceDetails
Type: InvoiceDetails structure

The details of an invoice. Populated when type is INVOICE.

FinancialRecordError

Description

The reason that one of the records requested from BatchGetFinancialRecord couldn't be returned. The other records in the request are unaffected.

Members
code
Required: Yes
Type: string

The error code that indicates why the retrieval failed. The following values are valid:

  • NOT_FOUND – No financial record on your account matches the key.

  • INTERNAL_ERROR – An internal error occurred while processing this record. The other records in the request are unaffected. You can retry this record.

key
Required: Yes
Type: FinancialRecordKey structure

The key of the record that couldn't be retrieved, as you requested it.

message
Required: Yes
Type: string

A description of why the operation couldn't retrieve this record. The wording can change at any time and isn't localized, so don't parse this value. To handle the error in your code, use code instead.

FinancialRecordKey

Description

A way to identify a financial record. Specify exactly one member: the ID that Amazon Web Services Payments issued, in identifier, or the invoice ID that Amazon Web Services Invoicing issued, in invoiceIdentifier. If you specify both or neither, the request fails with ValidationException.

Members
identifier
Type: string

The ID that Amazon Web Services Payments issued for the record.

invoiceIdentifier
Type: string

The invoice ID that Amazon Web Services Invoicing issued for an invoice or a credit memo.

FinancialRecordSummary

Description

A financial record as ListFinancialRecords returns it, without the details that are specific to its type. To get the full record, use GetFinancialRecord or BatchGetFinancialRecord.

Members
amount
Required: Yes
Type: CurrencyAmount structure

The total amount of the financial record, in the currency that the record was issued in. The amount doesn't change as the record is settled. balances shows how much of it is in each settlement state.

balances
Required: Yes
Type: Balances structure

How much of amount is outstanding, processing, settled, and canceled.

businessUnit
Required: Yes
Type: BusinessUnit structure

The Amazon Web Services business unit that issued the record: its merchant of record and its line of business.

closedAt
Type: timestamp (string|DateTime or anything parsable by strtotime)

The date and time, in UTC, when the record was last closed, that is, when its status last became SETTLED or CANCELED. This member is absent while the settlementStatus is OPEN, including after a closed record reopens.

id
Required: Yes
Type: string

The ID that Amazon Web Services Payments issued for the record. To retrieve the full record, pass this value to GetFinancialRecord or BatchGetFinancialRecord as identifier.

issuedAt
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The date and time, in UTC, when this record was issued.

settlementStatus
Required: Yes
Type: string

Whether the record is open or closed. If you receive a status value that you don't recognize, use this member to tell open records from closed ones. The following values are valid:

  • OPEN – Part of the amount is outstanding or processing. The status is OUTSTANDING or PROCESSING.

  • CLOSED – The whole amount is settled or canceled. The status is SETTLED or CANCELED.

A CLOSED record becomes OPEN again if a payment or credit applied to it is reversed. Its closedAt is then absent until the record closes again.

status
Required: Yes
Type: string

The settlement stage of the record. The following values are valid:

  • OUTSTANDING – Part of the amount isn't settled, and no settlement is in progress on the record. For an invoice, dueStatus shows whether it's due or past due. The settlementStatus is OPEN.

  • PROCESSING – A settlement of part or all of the amount is in progress, for example a payment that's submitted but not yet confirmed. PROCESSING takes precedence over OUTSTANDING: while any part of the amount is processing, the status is PROCESSING, even if another part is still outstanding. The settlementStatus is OPEN.

  • SETTLED – The whole amount is settled. The settlementStatus is CLOSED.

  • CANCELED – The record is canceled. The part of the amount that wasn't settled isn't collected or applied. The settlementStatus is CLOSED.

type
Required: Yes
Type: string

The type of the financial record. On the full record, the populated member of details matches this type. The following values are valid:

  • INVOICE – An invoice: a bill from Amazon Web Services. Payments and credit memos applied to the invoice settle it.

  • CREDIT_MEMO – A credit memo: a credit issued to your account, for example for a billing correction or a service credit. Applying it to one or more invoices settles it.

InNetBanking

Description

The details of an India net banking instrument. The instrument is registered with one bank.

Members
bankCode
Required: Yes
Type: string

The code of the bank that the instrument is registered with.

bankName
Type: string

The name of the bank that the instrument is registered with.

InternalServerException

Description

The request processing failed because of an unknown error, exception, or failure. Retry your request.

Members
message
Required: Yes
Type: string
retryAfterSeconds
Type: int

The suggested number of seconds to wait before retrying the request.

InvoiceDetails

Description

The details of an invoice: the invoice ID that Amazon Web Services Invoicing issued, the billing period that the invoice covers, its due date and due status, its payment terms, and its frequency.

Members
billingPeriod
Required: Yes
Type: BillingPeriod structure

The billing period the invoice covers: the period of the usage it bills.

dueDate
Required: Yes
Type: timestamp (string|DateTime or anything parsable by strtotime)

The calendar date by which the invoice must be paid, as the timestamp of 00:00:00 UTC on that day. The invoice is past due from the following day.

dueStatus
Type: string

Whether the invoice is due or past its due date. This member is present only while the invoice's status is OUTSTANDING. It's absent when the status is PROCESSING, SETTLED, or CANCELED. The following values are valid:

  • DUE – The due date hasn't passed.

  • PAST_DUE – The due date has passed, and the invoice is still outstanding.

invoiceFrequency
Required: Yes
Type: string

Whether the invoice was issued once or as part of a billing cycle. The following values are valid:

  • ONE_TIME – A single invoice that isn't part of a billing cycle.

  • RECURRING – One invoice of a billing cycle, such as your monthly invoice.

invoiceId
Required: Yes
Type: string

The invoice ID that Amazon Web Services Invoicing issued for the invoice: the document number printed on it, shown in the Amazon Web Services Billing and Cost Management console and returned by the Amazon Web Services Invoicing API as InvoiceId. GetFinancialRecord and BatchGetFinancialRecord also accept it, as invoiceIdentifier.

paymentTerms
Type: string

The payment terms for the invoice, as Amazon Web Services Invoicing issued them, such as Net30. The due date follows from these terms. This member is absent when Amazon Web Services Invoicing didn't issue payment terms for the invoice.

PaymentInstrument

Description

A payment instrument on your account, such as a card or a bank account.

Members
arn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the instrument. To allow or deny GetPaymentInstrument for this instrument, use the ARN in the Resource element of an Amazon Web Services Identity and Access Management (IAM) policy.

createdAt
Type: timestamp (string|DateTime or anything parsable by strtotime)

The date and time, in UTC, when the instrument was registered.

details
Type: PaymentInstrumentDetails structure

The details that are specific to the instrument's payment method. This member is absent for a payment method that has no additional details.

paymentMethod
Required: Yes
Type: string

The payment method of the instrument. The following values are valid:

  • CARD – A credit or debit card.

  • US_ACH_BANK_ACCOUNT – A US bank account debited over Automated Clearing House (ACH).

  • SEPA_BANK_ACCOUNT – A bank account debited over Single Euro Payments Area (SEPA) Direct Debit.

  • UK_BACS_BANK_ACCOUNT – A UK bank account debited over Bacs Direct Debit.

  • IN_NET_BANKING – India net banking. You authorize each payment on your bank's website.

  • CN_BANK_REDIRECT – China bank redirect. You authorize each payment on your bank's website.

  • UPI – Unified Payments Interface, the India real-time payment system.

  • PIX – Pix, the Brazilian Central Bank instant payment system.

  • PAY_BY_INVOICE – Pay by invoice. You pay each invoice yourself, for example by bank transfer, instead of Amazon Web Services collecting payment from a card or a bank account.

status
Required: Yes
Type: string

The current status of the instrument. The following values are valid:

  • ACTIVE – The instrument is set up, and Amazon Web Services can use it for payments. ACTIVE doesn't confirm that the instrument is verified or that a payment with it will succeed. You don't need to take action.

  • INVALID – Amazon Web Services can't use the instrument for payments, for example because its Direct Debit or UPI mandate is no longer valid. This status is permanent. The instrument doesn't return to ACTIVE. To pay with this payment method again, add a new payment instrument.

  • PENDING_SETUP – The instrument needs an action from you before Amazon Web Services can use it, such as resuming a paused UPI mandate in your UPI app. Amazon Web Services doesn't use the instrument for payments until you complete that action.

  • SETUP_IN_PROGRESS – You completed the setup steps, and setup of the instrument is in progress, for example while a Direct Debit or UPI mandate waits for confirmation. Amazon Web Services doesn't use the instrument for payments until setup is complete. You don't need to take action.

updatedAt
Type: timestamp (string|DateTime or anything parsable by strtotime)

The date and time, in UTC, when the instrument was last changed.

PaymentInstrumentDetails

Description

The details that are specific to a payment instrument's payment method.

Members
card
Type: Card structure

The details of a card payment instrument.

cnBankRedirect
Type: CnBankRedirect structure

The details of a China bank redirect instrument.

inNetBanking
Type: InNetBanking structure

The details of an India net banking instrument.

sepaBankAccount
Type: SepaBankAccount structure

The details of a bank account that is debited over Single Euro Payments Area (SEPA) Direct Debit.

ukBacsBankAccount
Type: UkBacsBankAccount structure

The details of a bank account that is debited over Bacs Direct Debit.

upi
Type: Upi structure

The details of a Unified Payments Interface (UPI) instrument.

usAchBankAccount
Type: UsAchBankAccount structure

The details of a bank account that is debited over Automated Clearing House (ACH).

PaymentInstrumentSummary

Description

A payment instrument as it appears in ListPaymentInstruments. Call GetPaymentInstrument for the full instrument, including the details specific to its payment method such as a card's last four digits and expiration.

Members
arn
Required: Yes
Type: string

The Amazon Resource Name (ARN) of the instrument. To allow or deny GetPaymentInstrument for this instrument, use the ARN in the Resource element of an Amazon Web Services Identity and Access Management (IAM) policy.

createdAt
Type: timestamp (string|DateTime or anything parsable by strtotime)

The date and time, in UTC, when the instrument was registered.

id
Required: Yes
Type: string

The ID of the instrument, unique within your account. It's the last segment of the instrument's ARN.

paymentMethod
Required: Yes
Type: string

The payment method of the instrument. The following values are valid:

  • CARD – A credit or debit card.

  • US_ACH_BANK_ACCOUNT – A US bank account debited over Automated Clearing House (ACH).

  • SEPA_BANK_ACCOUNT – A bank account debited over Single Euro Payments Area (SEPA) Direct Debit.

  • UK_BACS_BANK_ACCOUNT – A UK bank account debited over Bacs Direct Debit.

  • IN_NET_BANKING – India net banking. You authorize each payment on your bank's website.

  • CN_BANK_REDIRECT – China bank redirect. You authorize each payment on your bank's website.

  • UPI – Unified Payments Interface, the India real-time payment system.

  • PIX – Pix, the Brazilian Central Bank instant payment system.

  • PAY_BY_INVOICE – Pay by invoice. You pay each invoice yourself, for example by bank transfer, instead of Amazon Web Services collecting payment from a card or a bank account.

status
Required: Yes
Type: string

The current status of the instrument. The following values are valid:

  • ACTIVE – The instrument is set up, and Amazon Web Services can use it for payments. ACTIVE doesn't confirm that the instrument is verified or that a payment with it will succeed. You don't need to take action.

  • INVALID – Amazon Web Services can't use the instrument for payments, for example because its Direct Debit or UPI mandate is no longer valid. This status is permanent. The instrument doesn't return to ACTIVE. To pay with this payment method again, add a new payment instrument.

  • PENDING_SETUP – The instrument needs an action from you before Amazon Web Services can use it, such as resuming a paused UPI mandate in your UPI app. Amazon Web Services doesn't use the instrument for payments until you complete that action.

  • SETUP_IN_PROGRESS – You completed the setup steps, and setup of the instrument is in progress, for example while a Direct Debit or UPI mandate waits for confirmation. Amazon Web Services doesn't use the instrument for payments until setup is complete. You don't need to take action.

updatedAt
Type: timestamp (string|DateTime or anything parsable by strtotime)

The date and time, in UTC, when the instrument was last changed.

ResourceNotFoundException

Description

The requested resource couldn't be found. Verify that the resource ID is correct. This error is returned only when you're authorized for the resource.

Members
message
Required: Yes
Type: string
resourceId
Type: string

The ID of the resource that wasn't found.

resourceType
Type: string

The type of the resource that wasn't found.

SepaBankAccount

Description

The details of a bank account that is debited over Single Euro Payments Area (SEPA) Direct Debit.

Members
accountHolderName
Type: string

The name on the account.

accountNumberTail
Type: string

The last one to four characters of the account number. This member is absent until your bank provides the account details, for example before you complete authentication with your bank.

accountType
Type: string

Whether the account is a checking account or a savings account.

bankName
Type: string

The bank holding the account.

ThrottlingException

Description

The request was denied due to request throttling. Reduce the frequency of your requests and try again.

Members
message
Required: Yes
Type: string
retryAfterSeconds
Type: int

The suggested number of seconds to wait before retrying the request.

UkBacsBankAccount

Description

The details of a bank account that is debited over Bacs Direct Debit.

Members
accountHolderName
Type: string

The name on the account.

accountNumberTail
Type: string

The last one to four characters of the account number. This member is absent until your bank provides the account details, for example before you complete authentication with your bank.

accountType
Type: string

Whether the account is a checking account or a savings account.

bankName
Type: string

The bank holding the account.

Upi

Description

The details of a Unified Payments Interface (UPI) instrument.

Members
appName
Type: string

The name of the UPI app that the instrument is registered with.

UsAchBankAccount

Description

The details of a bank account that is debited over Automated Clearing House (ACH).

Members
accountHolderName
Type: string

The name on the account.

accountNumberTail
Type: string

The last one to four characters of the account number. This member is absent until your bank provides the account details, for example before you complete authentication with your bank.

accountType
Type: string

Whether the account is a checking account or a savings account.

bankName
Type: string

The bank holding the account.

ValidationException

Description

The request isn't valid. Check reason and fieldList for the cause, correct the request, and try again.

Members
fieldList
Type: Array of ValidationExceptionField structures

The request members that failed validation. This member is populated when reason is FIELD_VALIDATION_FAILED.

message
Required: Yes
Type: string
reason
Required: Yes
Type: string

The reason that validation failed. The following values are valid:

  • CANNOT_PARSE – The request body couldn't be parsed, or a value isn't of the expected type.

  • FIELD_VALIDATION_FAILED – One or more members failed validation. fieldList names them.

  • INVALID_PAGINATION_TOKEN – The nextToken is malformed or expired, or doesn't match the original request. Start again from the first page.

  • UNSUPPORTED_ACTION – The request is well formed, but the action isn't supported for your account, Region, or resource.

  • OTHER – The request isn't valid for another reason.

ValidationExceptionField

Description

A request member that failed validation.

Members
message
Required: Yes
Type: string

A description of why this member failed validation.

name
Required: Yes
Type: string

The name of the request member that failed validation. For a member nested inside another member, the name is a path from the request root, with the segments separated by periods.