Payments / Client / get_payment_instrument

get_payment_instrument

Payments.Client.get_payment_instrument(**kwargs)

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

response = client.get_payment_instrument(
    identifier='string'
)
Parameters:

identifier (string) –

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

Return type:

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.

        Note

        This is a Tagged Union structure. Only one of the following top level keys will be set: card, usAchBankAccount, sepaBankAccount, ukBacsBankAccount, inNetBanking, cnBankRedirect, upi. If a client receives an unknown member it will set SDK_UNKNOWN_MEMBER as the top level key, which maps to the name or tag of the unknown member. The structure of SDK_UNKNOWN_MEMBER is as follows:

        'SDK_UNKNOWN_MEMBER': {'name': 'UnknownMemberName'}
        
        • 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.

Exceptions