On This Page

Capture Context API

The capture context request contains all of the merchant-specific parameters that tell the front-end JavaScript library what to do within your payment experience.
The capture context is a signed JSON Web Token (JWT) containing this information:
  • Merchant-specific parameters that dictate the customer payment experience for the current payment transaction.
  • A one-time public key that secures the information flow during the current payment transaction.
The capture context request includes these fields:
  • allowedCardNetworks
  • allowedPaymentTypes
  • clientVersion
  • targetOrigins
  • transientTokenResponseOptions.includeCardPrefix
  • completeMandate
For information on JSON Web Tokens, see JSON Web Tokens.
Target Origin
The target origin is defined by the scheme (protocol), hostname (domain), and port number (if used).
You must use the https:// protocol. Sub domains must also be included in the target origin.
Any valid top-level domains, such as .com, .co.uk, and .gov.br, are supported. Wildcards are not supported.
For example, if you are launching
Unified Checkout
 on example.com, the target origin could be any of the following:
You can define the payment cards and digital payments that you want to accept in the capture context.
Allowed Card Networks
Use the
allowedCardNetworks
 field to define the card types.
These card networks are available for card entry:
  • American Express
  • Cartes Bancaires
  • Carnet
  • China UnionPay
  • Diners Club
  • Discover
  • EFTPOS
  • ELO
  • JCB
  • JCrew
  • mada
  • Maestro
  • Mastercard
  • Meeza
  • PayPak
  • Visa
To support dual-branded or co-badged cards, you must list your supported card type values for the
allowedCardNetworks
 field based on your preference for processing card numbers. For example, if a card is dual-branded as Visa and Cartes Bancaires, and Cartes Bancaires is listed first, the card type is set to Cartes Bancaires after the card number is entered in your
Unified Checkout
 card collection form. For information on dual-branded or co-badged cards, see Dual-Branded Cards.
Allowed Payment Types
You can specify the type of
Unified Checkout
 digital payment methods that you want to accept in the capture context.
Use the
allowedPaymentTypes
 field to define the payment type:
  • APPLEPAY
  • CLICKTOPAY
  • GOOGLEPAY
  • PANENTRY
IMPORTANT
Click to Pay
 accepts American Express, Mastercard, and Visa for saved cards. Visa and Mastercard tokenize payment credentials using network tokenization for all
Click to Pay
 requests.
Click to Pay
 uses
Click to Pay
 Token Requester IDs (TRIDs) rather than your existing TRIDs to generate network tokens.
For more information on enabling and managing these digital payment methods, see these topics:
Complete Mandate
The complete mandate feature provides service orchestration within
Unified Checkout
 and simplifies your integration. Service orchestration enables
Unified Checkout
 to orchestrate services on your behalf. The complete mandate feature provides instructions to the
unifiedPayment.complete()
 method in the JavaScript SDK. You must include the
completeMandate
 field object in your capture context to enable
Unified Checkout
 to initiate services on your behalf from the browser.
The complete mandate feature is defined by three fields:
  • completeMandate.type
    : This field is used to indicate how a payment should be processed.
    Possible values:
    • AUTH
      : Authorize the payment and capture the funds at a later date.
    • CAPTURE
      : Perform a sale.
    • PREFER_AUTH
      : Perform an authorization if possible. If a payment method requires the funds to be captured immediately, then
      Unified Checkout
       captures the payment.
  • completeMandate.decisionManager
    : This field determines whether
    Decision Manager
     should be used. To use this field, you must also include
    complete.Mandate.type
     in your request. When this field is set to
    true
    , both
    Decision Manager
     and device fingerprinting services are run. When
    Decision Manager
     runs, it uses the associated
    Decision Manager
     instance based on the merchant ID that is configured for the request. When this field is set to
    false
     or is not included in the request,
    Decision Manager
     and device fingerprinting services do not run.
  • completeMandate.consumerAuthentication
    : This field determines whether
    Payer Authentication
     should be used. To use this field, you must also include
    complete.Mandate.type
     in your request. When this field set to
    true
    ,
    Payer Authentication
     runs. When this field is set to
    false
     or is not included in the request,
    Payer Authentication
     does not run.
    Consumer authentication is available for these card types:
    • American Express
    • Cartes Bancaires
    • China UnionPay
    • Discover
    • ELO
    • JCB
    • Mastercard
    • Visa
Include Card Prefix
You can control the length of the card number prefix to be received in the response to the capture context
/sessions
 request:
  • Six digits
  • Eight digits
  • No prefix
To specify your preferred card number prefix length, include or exclude the
transientTokenResponseOptions.includeCardPrefix
 field in the capture context
/sessions
 request.
To receive a six-digit card number prefix in the response, follow this step:
Do not
 include the
transientTokenResponseOptions.includeCardPrefix
 field in the capture context
/sessions
 request.
This example shows how a six-digit card number prefix
411111
 is returned in the transient token response:
"maskedValue" : "XXXXXXXXXXXX1111”,
"bin" : "411111"
To receive an eight-digit card number prefix in the response, follow this step:
Include the
transientTokenResponseOptions.includeCardPrefix
 field in the capture context request, and set the value to
true
.
IMPORTANT
This PCI DSS requirement applies only to card numbers longer than 15 digits and only for Discover, JCB, Mastercard, UnionPay, and Visa brands.
  • If the card type entered is not part of these brands, a six-digit card number prefix is returned instead.
  • If the card type entered is not part of these brands but is
    co-branded
     with these brands, an eight-digit card number prefix is returned.
This example shows how an eight-digit card prefix
41111102
 is returned in the transient token response:
"maskedValue" : "XXXXXXXXXXXX1111”,
"prefix" : "41111102"
To not receive a card number prefix in the response, follow this step:
Include the
transientTokenResponseOptions.includeCardPrefix
 field in the capture context request, and set the value to
false
.
This example shows how a card number is returned without a card number prefix in the transient token response:
"maskedValue" : "XXXXXXXXXXXX1111"
Best practice:
If your application does not require card number prefix information for routing or identification,
National Australia Bank
 recommends that you include the
transientTokenResponseOptions.includeCardPrefix
 field in the capture context request and set its value to
false
. Doing so limits the exposure of payment data to only what is necessary for your processing needs.
For more information about PCI DSS, see
Frequently Asked Questions
 on the PCI Security Standards Council site.
IMPORTANT
National Australia Bank
 recommends that you dynamically parse the response for the fields that you are looking for when you integrate with
National Australia Bank
 APIs.
National Australia Bank
 may add additional fields in the future.
You must ensure that your integration can handle new fields that are returned in the response. Even though the underlying data structures do not change, you must also ensure that your integration can handle changes to the order in which the data is returned.
National Australia Bank
 uses semantic versioning practices, which enables you to retain backwards compatibility as new fields are introduced in minor version updates.