AWS Payments

2026/11/20 - AWS Payments - 6 new api methods

Changes  Initial release of AWS Payments API, which lets you view your account balance, invoices, credit memos, and payment instruments.

GetPaymentInstrument (new) Link ¶

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.

See also: AWS API Documentation

Request Syntax

client.get_payment_instrument(
    identifier='string'
)
type identifier:

string

param identifier:

[REQUIRED]

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.

rtype:

dict

returns:

Response Syntax

{
    'paymentInstrument': {
        'arn': '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',
        'details': {
            'card': {
                'brand': 'VISA'|'MASTERCARD'|'AMEX'|'DISCOVER'|'JCB'|'RUPAY'|'CHINA_UNIONPAY',
                'last4': 'string',
                'expirationMonth': 123,
                'expirationYear': 123,
                'cardType': 'CREDIT'|'DEBIT',
                'issuingBank': 'string',
                'issuerCountry': 'string'
            },
            'usAchBankAccount': {
                'accountNumberTail': 'string',
                'accountHolderName': 'string',
                'bankName': 'string',
                'accountType': 'CHECKING'|'SAVINGS'
            },
            'sepaBankAccount': {
                'accountNumberTail': 'string',
                'accountHolderName': 'string',
                'bankName': 'string',
                'accountType': 'CHECKING'|'SAVINGS'
            },
            'ukBacsBankAccount': {
                'accountNumberTail': 'string',
                'accountHolderName': 'string',
                'bankName': 'string',
                'accountType': 'CHECKING'|'SAVINGS'
            },
            'inNetBanking': {
                'bankCode': 'string',
                'bankName': 'string'
            },
            'cnBankRedirect': {
                'bankCode': 'string'
            },
            'upi': {
                'appName': 'string'
            }
        },
        'createdAt': datetime(2015, 1, 1),
        'updatedAt': datetime(2015, 1, 1)
    }
}

Response Structure

  • (dict) --

    • paymentInstrument (dict) --

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

      • arn (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.

      • paymentMethod (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 (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.

      • details (dict) --

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

        • card (dict) --

          The details of a card payment instrument.

          • brand (string) --

            The network the card runs on.

          • last4 (string) --

            The last four digits of the card number.

          • expirationMonth (integer) --

            The calendar month that the card expires in.

          • expirationYear (integer) --

            The calendar year that the card expires in.

          • cardType (string) --

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

          • issuingBank (string) --

            The bank that issued the card.

          • issuerCountry (string) --

            The country of the bank that issued the card.

        • usAchBankAccount (dict) --

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

          • accountNumberTail (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.

          • accountHolderName (string) --

            The name on the account.

          • bankName (string) --

            The bank holding the account.

          • accountType (string) --

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

        • sepaBankAccount (dict) --

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

          • accountNumberTail (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.

          • accountHolderName (string) --

            The name on the account.

          • bankName (string) --

            The bank holding the account.

          • accountType (string) --

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

        • ukBacsBankAccount (dict) --

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

          • accountNumberTail (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.

          • accountHolderName (string) --

            The name on the account.

          • bankName (string) --

            The bank holding the account.

          • accountType (string) --

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

        • inNetBanking (dict) --

          The details of an India net banking instrument.

          • bankCode (string) --

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

          • bankName (string) --

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

        • cnBankRedirect (dict) --

          The details of a China bank redirect instrument.

          • bankCode (string) --

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

        • upi (dict) --

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

          • appName (string) --

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

      • createdAt (datetime) --

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

      • updatedAt (datetime) --

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

GetFinancialRecord (new) Link ¶

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.

See also: AWS API Documentation

Request Syntax

client.get_financial_record(
    identifier='string',
    invoiceIdentifier='string'
)
type identifier:

string

param identifier:

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

type invoiceIdentifier:

string

param invoiceIdentifier:

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.

rtype:

dict

returns:

Response Syntax

{
    'financialRecord': {
        'id': 'string',
        'type': 'INVOICE'|'CREDIT_MEMO',
        'businessUnit': {
            'merchantOfRecord': 'string',
            'lineOfBusiness': 'AWS_CLOUD_SERVICES'|'PROSERVE_MARKETING_AND_TRAINING'|'AWS_MARKETPLACE'
        },
        'amount': {
            'value': 'string',
            'currency': 'string'
        },
        'balances': {
            'outstanding': {
                'value': 'string',
                'currency': 'string'
            },
            'processing': {
                'value': 'string',
                'currency': 'string'
            },
            'settled': {
                'value': 'string',
                'currency': 'string'
            },
            'canceled': {
                'value': 'string',
                'currency': 'string'
            }
        },
        'settlementStatus': 'OPEN'|'CLOSED',
        'status': 'OUTSTANDING'|'PROCESSING'|'SETTLED'|'CANCELED',
        'issuedAt': datetime(2015, 1, 1),
        'closedAt': datetime(2015, 1, 1),
        'details': {
            'invoiceDetails': {
                'invoiceId': 'string',
                'dueStatus': 'DUE'|'PAST_DUE',
                'billingPeriod': {
                    'startDate': datetime(2015, 1, 1),
                    'endDate': datetime(2015, 1, 1)
                },
                'dueDate': datetime(2015, 1, 1),
                'paymentTerms': 'string',
                'invoiceFrequency': 'ONE_TIME'|'RECURRING'
            },
            'creditMemoDetails': {
                'invoiceId': 'string',
                'billingPeriod': {
                    'startDate': datetime(2015, 1, 1),
                    'endDate': datetime(2015, 1, 1)
                }
            }
        }
    }
}

Response Structure

  • (dict) --

    • financialRecord (dict) --

      The requested financial record.

      • id (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.

      • 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.

      • businessUnit (dict) --

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

        • merchantOfRecord (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.

        • lineOfBusiness (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.

      • amount (dict) --

        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.

        • value (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.

        • currency (string) --

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

      • balances (dict) --

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

        • outstanding (dict) --

          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.

          • value (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.

          • currency (string) --

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

        • processing (dict) --

          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.

          • value (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.

          • currency (string) --

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

        • settled (dict) --

          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.

          • value (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.

          • currency (string) --

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

        • canceled (dict) --

          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.

          • value (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.

          • currency (string) --

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

      • settlementStatus (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 (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.

      • issuedAt (datetime) --

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

      • closedAt (datetime) --

        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 (dict) --

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

        • invoiceDetails (dict) --

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

          • invoiceId (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.

          • dueStatus (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.

          • billingPeriod (dict) --

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

            • startDate (datetime) --

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

            • endDate (datetime) --

              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.

          • dueDate (datetime) --

            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.

          • paymentTerms (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.

          • invoiceFrequency (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.

        • creditMemoDetails (dict) --

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

          • invoiceId (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.

          • billingPeriod (dict) --

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

            • startDate (datetime) --

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

            • endDate (datetime) --

              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.

ListPaymentInstruments (new) Link ¶

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.

See also: AWS API Documentation

Request Syntax

client.list_payment_instruments(
    nextToken='string',
    maxResults=123
)
type nextToken:

string

param nextToken:

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.

type maxResults:

integer

param maxResults:

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.

rtype:

dict

returns:

Response Syntax

{
    'paymentInstrumentSummaries': [
        {
            'id': 'string',
            'arn': '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',
            'createdAt': datetime(2015, 1, 1),
            'updatedAt': datetime(2015, 1, 1)
        },
    ],
    'nextToken': 'string'
}

Response Structure

  • (dict) --

    • paymentInstrumentSummaries (list) --

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

      • (dict) --

        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.

        • id (string) --

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

        • arn (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.

        • paymentMethod (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 (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.

        • createdAt (datetime) --

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

        • updatedAt (datetime) --

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

    • nextToken (string) --

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

GetAccountBalance (new) Link ¶

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.

See also: AWS API Documentation

Request Syntax

client.get_account_balance(
    balanceType='INVOICES_DUE'|'INVOICES_PAST_DUE'|'OUTSTANDING_CREDIT_MEMOS',
    nextToken='string',
    maxResults=123
)
type balanceType:

string

param balanceType:

[REQUIRED]

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.

type nextToken:

string

param nextToken:

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.

type maxResults:

integer

param maxResults:

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.

rtype:

dict

returns:

Response Syntax

{
    'accountBalances': [
        {
            'amount': {
                'value': 'string',
                'currency': 'string'
            },
            'merchantOfRecord': 'string'
        },
    ],
    'nextToken': 'string'
}

Response Structure

  • (dict) --

    • accountBalances (list) --

      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.

      • (dict) --

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

        • amount (dict) --

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

          • value (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.

          • currency (string) --

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

        • merchantOfRecord (string) --

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

    • nextToken (string) --

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

ListFinancialRecords (new) Link ¶

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.

See also: AWS API Documentation

Request Syntax

client.list_financial_records(
    types=[
        'INVOICE'|'CREDIT_MEMO',
    ],
    settlementStatuses=[
        'OPEN'|'CLOSED',
    ],
    issuedAfter=datetime(2015, 1, 1),
    issuedBefore=datetime(2015, 1, 1),
    sortBy='ISSUED_AT',
    sortOrder='ASCENDING'|'DESCENDING',
    nextToken='string',
    maxResults=123
)
type types:

list

param types:

[REQUIRED]

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.

  • (string) --

type settlementStatuses:

list

param settlementStatuses:

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.

  • (string) --

type issuedAfter:

datetime

param issuedAfter:

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

type issuedBefore:

datetime

param issuedBefore:

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.

type sortBy:

string

param sortBy:

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

type sortOrder:

string

param sortOrder:

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

type nextToken:

string

param nextToken:

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.

type maxResults:

integer

param maxResults:

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.

rtype:

dict

returns:

Response Syntax

{
    'financialRecordSummaries': [
        {
            'id': 'string',
            'type': 'INVOICE'|'CREDIT_MEMO',
            'businessUnit': {
                'merchantOfRecord': 'string',
                'lineOfBusiness': 'AWS_CLOUD_SERVICES'|'PROSERVE_MARKETING_AND_TRAINING'|'AWS_MARKETPLACE'
            },
            'amount': {
                'value': 'string',
                'currency': 'string'
            },
            'balances': {
                'outstanding': {
                    'value': 'string',
                    'currency': 'string'
                },
                'processing': {
                    'value': 'string',
                    'currency': 'string'
                },
                'settled': {
                    'value': 'string',
                    'currency': 'string'
                },
                'canceled': {
                    'value': 'string',
                    'currency': 'string'
                }
            },
            'settlementStatus': 'OPEN'|'CLOSED',
            'status': 'OUTSTANDING'|'PROCESSING'|'SETTLED'|'CANCELED',
            'issuedAt': datetime(2015, 1, 1),
            'closedAt': datetime(2015, 1, 1)
        },
    ],
    'nextToken': 'string'
}

Response Structure

  • (dict) --

    • financialRecordSummaries (list) --

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

      • (dict) --

        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.

        • id (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.

        • 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.

        • businessUnit (dict) --

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

          • merchantOfRecord (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.

          • lineOfBusiness (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.

        • amount (dict) --

          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.

          • value (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.

          • currency (string) --

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

        • balances (dict) --

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

          • outstanding (dict) --

            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.

            • value (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.

            • currency (string) --

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

          • processing (dict) --

            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.

            • value (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.

            • currency (string) --

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

          • settled (dict) --

            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.

            • value (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.

            • currency (string) --

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

          • canceled (dict) --

            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.

            • value (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.

            • currency (string) --

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

        • settlementStatus (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 (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.

        • issuedAt (datetime) --

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

        • closedAt (datetime) --

          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.

    • nextToken (string) --

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

BatchGetFinancialRecord (new) Link ¶

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.

See also: AWS API Documentation

Request Syntax

client.batch_get_financial_record(
    keys=[
        {
            'identifier': 'string',
            'invoiceIdentifier': 'string'
        },
    ]
)
type keys:

list

param keys:

[REQUIRED]

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

  • (dict) --

    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.

    • identifier (string) --

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

    • invoiceIdentifier (string) --

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

rtype:

dict

returns:

Response Syntax

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

Response Structure

  • (dict) --

    • financialRecords (list) --

      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.

      • (dict) --

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

        • id (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.

        • 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.

        • businessUnit (dict) --

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

          • merchantOfRecord (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.

          • lineOfBusiness (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.

        • amount (dict) --

          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.

          • value (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.

          • currency (string) --

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

        • balances (dict) --

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

          • outstanding (dict) --

            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.

            • value (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.

            • currency (string) --

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

          • processing (dict) --

            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.

            • value (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.

            • currency (string) --

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

          • settled (dict) --

            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.

            • value (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.

            • currency (string) --

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

          • canceled (dict) --

            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.

            • value (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.

            • currency (string) --

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

        • settlementStatus (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 (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.

        • issuedAt (datetime) --

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

        • closedAt (datetime) --

          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 (dict) --

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

          • invoiceDetails (dict) --

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

            • invoiceId (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.

            • dueStatus (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.

            • billingPeriod (dict) --

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

              • startDate (datetime) --

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

              • endDate (datetime) --

                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.

            • dueDate (datetime) --

              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.

            • paymentTerms (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.

            • invoiceFrequency (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.

          • creditMemoDetails (dict) --

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

            • invoiceId (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.

            • billingPeriod (dict) --

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

              • startDate (datetime) --

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

              • endDate (datetime) --

                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.

    • errors (list) --

      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.

      • (dict) --

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

        • key (dict) --

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

          • identifier (string) --

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

          • invoiceIdentifier (string) --

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

        • code (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.

        • message (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.