@amazonpay/amazon-pay-alexa-utils

amazonpay-alexa-utils

Amazon Pay Alexa Utils for Node.js

The Amazon Pay Alexa Utils package simplifies creating Amazon Pay related payloads and Directives for skills created with the ASK SDK v2 for Node.js. It also offers the Amazon Pay specific APIs to retrieve Buyer Ids and Shipping Addresses and supports with a simple way to handle permissions.

To install it into your project, simply execute npm i @amazonpay/amazon-pay-alexa-utils --save

Setup API

Build payloads for setup operations the easy way - no need to know the payload structure. The builder will take care to give you the right format.

Learn more about the Amazon Pay Setup API

const AmazonPay = require('@amazonpay/amazon-pay-alexa-utils');

const payload = AmazonPay.setupPayload(/*version*/ '2')
    .withSellerId('ABCD1234ADS')
    .withCountryOfEstablishment('DE')
    .withLedgerCurrency('EUR')
    .withCheckoutLanguage('en_GB')
    .withBillingAgreementType('MerchantInitiatedTransaction')
    .withSubscriptionAmount('19.99')
    .withSubscriptionCurrency('EUR')
    .withCustomInformation('so custom')
    .withPlatformId('ABCDE')
    .withSellerBillingAgreementId('12345')
    .withSellerNote('my note')
    .withStoreName('my store')
    .shippingNeeded(true)
    .onSandbox({'eMail': '[e-mail]'}))
    .build();

console.log(JSON.stringify(payload))


{  
    "@type":"SetupAmazonPayRequest",
    "@version":"2",
    "countryOfEstablishment":"DE",
    "ledgerCurrency":"EUR",
    "needAmazonShippingAddress":true,
    "sellerId":"ABCD1234ADS",
    "sandboxCustomerEmailId":"[e-mail]",
    "sandboxMode":true,
    "checkoutLanguage":"en_GB",
    "billingAgreementAttributes":{  
        "@type":"BillingAgreementAttributes",
        "@version":"2",
        "sellerNote":"my note",
        "platformId":"ABCDE",
        "billingAgreementType":"MerchantInitiatedTransaction",
        "subscriptionAmount":{
            "@type":"Price",
            "@version":"2",
            "amount":"19.99",
            "currencyCode":"EUR"
        },
        "sellerBillingAgreementAttributes":{  
            "@type":"SellerBillingAgreementAttributes",
            "@version":"2",
            "storeName":"my store",
            "customInformation":"so custom",
            "sellerBillingAgreementId":"12345"
        }
    }
} 

Charge API

Build payloads for charge operations the easy way - no need to know the payload structure. The builder will take care to give you the right format.

Learn more about the Amazon Pay Charge API

const AmazonPay = require('@amazonpay/amazon-pay-alexa-utils');

const payload = AmazonPay.chargePayload(/* version */ '2')
    .withSellerId('ABCD1234ADS')
    .withBillingAgreementId('B02-12345-12345')
    .withPaymentAction('AUTHORIZEANDCAPTURE')
    .withAuthorizationReferenceId('ref')
    .withAmount('50')
    .withCurrency('EUR')
    .withTransactionTimeout('0')
    .withSellerAuthorizationNote('my auth note')
    .withSoftDescriptor('my store - Alexa skill')
    .withSellerOrderId('12345')
    .withStoreName('my store')
    .withCustomInformation('so custom')
    .withSellerNote('my note')
    .build();

console.log(JSON.stringify(payload))

{
    '@type': 'ChargeAmazonPayRequest',
    '@version': '2',
    'billingAgreementId': 'B02-12345-12345',
    'paymentAction': 'AUTHORIZEANDCAPTURE',
    'sellerId': 'ABCD1234ADS',
    'authorizeAttributes': {
      '@type': 'AuthorizeAttributes',
      '@version': '2',
      'authorizationReferenceId': 'ref',
      'authorizationAmount': {
        '@type': 'Price',
        '@version': '2',
        'amount': '50',
        'currencyCode': 'EUR',
      },
      'sellerAuthorizationNote': 'my auth note',
      'softDescriptor': 'my store - Alexa skill',
      'transactionTimeout': '0',
    },
    'sellerOrderAttributes': {
      '@type': 'SellerOrderAttributes',
      '@version': '2',
      'customInformation': 'so custom',
      'sellerNote': 'my note',
      'sellerOrderId': '12345',
      'storeName': 'my store',
    },
  }

Directives

Directives allow you to execute Amazon Pay operations. Just pass in the right payload and the DirectiveBuilder will hand you the correct directive to execute.

Setup

const AmazonPay = require('@amazonpay/amazon-pay-alexa-utils');

const payloadBuilder = AmazonPay.setupPayload(/* version */ '2')
    .withSellerId('ABCD1234ADS')
    .withCountryOfEstablishment('DE')
    .withLedgerCurrency('EUR');

const directive = AmazonPay
    .setupDirective(payloadBuilder, 'token')
    .build();

console.log(JSON.stringify(directive));

    {
      "name": "Setup",
      "payload": {
        "@type": "SetupAmazonPayRequest",
        "@version": "2",
        "countryOfEstablishment": "DE",
        "ledgerCurrency": "EUR",
        "needAmazonShippingAddress": false,
        "sellerId": "ABCD1234ADS"
      },
      "token": "token",
      "type": "Connections.SendRequest"
    }

Charge

const AmazonPay = require('@amazonpay/amazon-pay-alexa-utils');

const payloadBuilder = AmazonPay.chargePayload(/* version */ '2')
    .withSellerId('ABCD1234ADS')
    .withBillingAgreementId('B02-12345-12345')
    .withAmount('50')
    .withCurrency('EUR')
    .withAuthorizationReferenceId('ref')
    .withPaymentAction('AUTHORIZE');

const directive = AmazonPay
    .chargeDirective(payloadBuilder, 'token')
    .build();

    console.log(JSON.stringify(directive));

    {
      "name": "Charge",
      "payload": {
        "@type": "ChargeAmazonPayRequest",
        "@version": "2",
        "billingAgreementId": "B02-12345-12345",
        "paymentAction": "AUTHORIZE",
        "sellerId": "ABCD1234ADS",
        "authorizeAttributes": {
          "@type": "AuthorizeAttributes",
          "@version": "2",
          "authorizationAmount": {
            "@type": "Price",
            "@version": "2",
            "amount": "50",
            "currencyCode": "EUR"
          },
          "authorizationReferenceId": "ref"
        }
      },
      "token": "token",
      "type": "Connections.SendRequest"
    }

Permissions

Get Permission Status

Knowing if a customer has accepted Amazon Pay permissions is essential. The following method makes this job as easy as possible for you.

const AmazonPay = require('@amazonpay/amazon-pay-alexa-utils');

const permissionIsGranted = AmazonPay.isAmazonPayPermissionGranted(handlerInput.requestEnvelope);

Ask For Permissions - send card and prompt

const AmazonPay = require('@amazonpay/amazon-pay-alexa-utils');

const response = AmazonPay.askForPermissionCard('Spoken message to ask for permission enablement')
  .withAdditionalPermissions(['alexa::profile:email:read', 'alexa::profile:name:read'])
  .send(handlerInput.responseBuilder);

Amazon Pay Buyer Address API

Amazon Pay helps you fulfilling your orders seamlessly, by - among others - offering delivery address data via the Amazon Pay payment objects. Sometimes, this is too late in the flow to personalize the experience. The Amazon Pay Buyer Address API was introduced to help you out. Retrieve the default shipping address of the current buyer via a simple GET request whenever you need it.

Please check for granted Amazon Pay permissions first.

Learn more about the Amazon Pay Buyer Address API.

  const AmazonPay = require('@amazonpay/amazon-pay-alexa-utils');

  async handle: {
  ...

  // use this to have the current locale decide for the region to use
  const buyerAddress = await AmazonPay.getBuyerAddress(requestEnvelope, sellerId);
  
  // if you want to specify the region yourself
  const buyerAddress = await AmazonPay.getBuyerAddressForRegion(requestEnvelope, region, sellerId);
  ...
  
  // if you want to test in sandbox mode
  const buyerAddress = await AmazonPay.getBuyerAddress(requestEnvelope, sellerId, 'sandbox', '[e-mail]');
  
  }

Amazon Pay Buyer Id

The Amazon Pay Buyer Id allows you to personalize the experience immediately for Amazon Pay customers already known to you - without asking them to link accounts. The Id is static, even if a customer deactivated the skill in the past and is consistent across channels. Use this simple abstraction to retrieve it.

Please check for granted Amazon Pay permission first.

Learn more about the Amazon Pay Buyer Id API.

  const AmazonPay = require('@amazonpay/amazon-pay-alexa-utils');

  async handle: {
  ...

  // use this to have the current locale decide for the region to use
  const buyerId = await AmazonPay.getBuyerId(requestEnvelope);
  
  // if you want to specify the region yourself
  const buyerId = await AmazonPay.getBuyerIdForRegion(requestEnvelope, region);
  ...
  }