LocalPayment

LocalPayment

This class represents a LocalPayment component. Instances of this class can open a LocalPayment window for paying with alternate payments local to a specific country. Any additional UI, such as disabling the page while authentication is taking place, is up to the developer.

Constructor

new LocalPayment(options)

Do not use this constructor directly. Use braintree-web.local-payment.create instead.

Parameters:
Name Type Description
options object

see local-payment.create
Source:

Methods

closeWindow() → {void}

Closes the LocalPayment window if it is open.

Source:
Example
localPaymentInstance.closeWindow();

focusWindow() → {void}

Focuses the LocalPayment window if it is open.

Source:
Example
localPaymentInstance.focusWindow();

hasTokenizationParams() → {Boolean}

Checks if required tokenization parameters are available in querystring for manual tokenization requests.

Source:
Example
// if query string contains
// ?btLpToken=token&btLpPaymentId=payment-id&btLpPayerId=payer-id
localPaymentInstance.hasTokenizationParams(); // true

// if query string is missing required params
localPaymentInstance.hasTokenizationParams(); // false

if (localPaymentInstance.hasTokenizationParams()) {
  localPaymentInstance.tokenize();
}

startPayment(options, callback) → {Promise|void}

Launches the local payment flow and returns a nonce payload. Only one local payment flow should be active at a time. One way to achieve this is to disable your local payment button while the flow is open.

Parameters:
Name Type Description
options LocalPayment~StartPaymentOptions | LocalPayment~StartPaymentPayUponInvoiceOptions

Options for initiating the local payment payment flow.
callback callback

The second argument, data, is a startPaymentPayload. If no callback is provided, the method will return a Promise that resolves with a startPaymentPayload.
Source:
Examples
localPaymentInstance.startPayment({
  paymentType: 'ideal',
  paymentTypeCountryCode: 'NL',
  fallback: {
    buttonText: 'Return to Merchant',
    url: 'https://example.com/my-checkout-page'
  },
  amount: '10.00',
  currencyCode: 'EUR',
  givenName: 'Joe',
  surname: 'Doe',
  address: {
    countryCode: 'NL'
  },
  onPaymentStart: function (data, continueCallback) {
    // Do any preprocessing before starting the flow
    // data.paymentId is the ID of the localPayment
    continueCallback();
  }
}).then(function (payload) {
  // Submit payload.nonce to your server
}).catch(function (startPaymentError) {
  // Handle flow errors or premature flow closure
  console.error('Error!', startPaymentError);
});

Pay Upon Invoice 

localPaymentInstance.startPayment({
  paymentType: 'pay_upon_invoice',
  amount: '100.00',
  currencyCode: 'EUR',
  givenName: 'Max',
  surname: 'Mustermann',
  address: { // This is used as the shipping address.
    streetAddress: 'Taunusanlage 12',
    locality: 'Frankfurt',
    postalCode: '60325',
    countryCode: 'DE',
  },
  billingAddress: {
    streetAddress: 'Schönhauser Allee 84',
    locality: 'Berlin',
    postalCode: '10439',
    countryCode: 'DE'
  },
  birthDate: '1990-01-01',
  email: 'buyer@example.com',
  locale: 'en-DE',
  customerServiceInstructions: 'Customer service phone is +49 6912345678.',
  lineItems: [{
    category: 'PHYSICAL_GOODS',
    name: 'Basketball Shoes',
    quantity: '1',
    unitAmount: '81.00',
    unitTaxAmount: '19.00',
  }],
  phone: '6912345678',
  phoneCountryCode: '49',
  correlationId: correlationId,
  onPaymentStart: function (data) {
    // NOTE: It is critical here to store data.paymentId on your server
    //       so it can be mapped to a webhook sent by Braintree once the
    //       buyer completes their payment.
    console.log('Payment ID:', data.paymentId);
  },
}).catch(function (err) {
  // Handle any error calling startPayment.
  console.error(err);
});

teardown(callbackopt) → {Promise|void}

Cleanly remove anything set up by create.

Parameters:
Name Type Attributes Description
callback callback <optional>

Called on completion.
Source:
Examples
localPaymentInstance.teardown();

With callback 

localPaymentInstance.teardown(function () {
  // teardown is complete
});

tokenize(paramsopt, callbackopt) → {Promise|void}

Manually tokenizes params for a local payment received from PayPal.When app switching back from a mobile application (such as a bank application for an iDEAL payment), the window may lose context with the parent page. In that case, a fallback url is used, and this method can be used to finish the flow.

Parameters:
Name Type Attributes Description
params object <optional>

All options for tokenizing local payment parameters. If no params are passed in, the params will be pulled off of the query string of the page.

Properties
Name Type Description
btLpToken string

The token representing the local payment. Aliased to token if btLpToken is not present.
btLpPaymentId string

The payment id for the local payment. Aliased to paymentId if btLpPaymentId is not present.
btLpPayerId string

The payer id for the local payment. Aliased to PayerID if btLpPayerId is not present.
callback callback <optional>

The second argument, data, is a startPaymentPayload. If no callback is provided, the method will return a Promise that resolves with a startPaymentPayload.
Source:
Example
localPaymentInstance.tokenize().then(function (payload) {
  // send payload.nonce to your server
}).catch(function (err) {
  // handle tokenization error
});

Type Definitions

StartPaymentOptions :object

Options used for most local payment types.

Properties:
Name Type Attributes Description
fallback object

Configuration for what to do when app switching back from a Bank app on a mobile device.

Properties
Name Type Description
buttonText string

The text to display in a button to redirect back to the merchant page.
url string

The url to redirect to when the redirect button is pressed. Query params will be added to the url to process the data returned from the bank.
cancelButtonText string

The text to display in a button to redirect back to the merchant page when the customer cancels. If no cancelButtonText is provided, buttonText will be used.
cancelUrl string

The url to redirect to when the redirect button is pressed when the customer cancels. Query params will be added to the url to check the state of the payment. If no cancelUrl is provided, url will be used.
windowOptions object <optional>

The options for configuring the window that is opened when starting the payment.

Properties
Name Type Attributes Default Description
width number <optional>
 1282

The width in pixels of the window opened when starting the payment. The default width size is this large to allow various banking partner landing pages to display the QR Code to be scanned by the bank's mobile app. Many will not display the QR code when the window size is smaller than a standard desktop screen.
height number <optional>
 720

The height in pixels of the window opened when starting the payment.
amount string

The amount to authorize for the transaction.
currencyCode string

The currency to process the payment.
displayName string <optional>

The merchant name displayed inside of the window that is opened when starting the payment.
paymentType string

The type of local payment.
paymentTypeCountryCode string

The country code of the local payment. This value must be one of the supported country codes for a given local payment type listed here. For local payments supported in multiple countries, this value may determine which banks are presented to the customer.
email string

Payer email of the customer.
givenName string

First name of the customer.
surname string

Last name of the customer.
phone string

Phone number of the customer.
bic string

Bank Identification Code of the customer (specific to iDEAL transactions).
shippingAddressRequired boolean

Indicates whether or not the payment needs to be shipped. For digital goods, this should be false. Defaults to false.
address object

The shipping address.

Properties
Name Type Description
streetAddress string

Line 1 of the Address (eg. number, street, etc). An error will occur if this address is not valid.
extendedAddress string

Line 2 of the Address (eg. suite, apt #, etc.). An error will occur if this address is not valid.
locality string

Customer's city.
region string

Customer's region or state.
postalCode string

Customer's postal code.
countryCode string

Customer's country code.
onPaymentStart function

A function that will be called with two parameters: an object containing the paymentId and a continueCallback that must be called to launch the flow. You can use method to do any preprocessing on your server before the flow begins..
Source:

StartPaymentPayUponInvoiceOptions :object

Options used for the Pay Upon Invoice local payment type.

Properties:
Name Type Attributes Description
amount string

The amount to authorize for the transaction.
currencyCode string

The currency to process the payment.
displayName string <optional>

The merchant name displayed inside of the window that is opened when starting the payment.
paymentType string

The type of local payment. Must be pay_upon_invoice.
paymentTypeCountryCode string <optional>

The country code of the local payment. This value must be one of the supported country codes for a given local payment type listed here. For local payments supported in multiple countries, this value may determine which banks are presented to the customer.
email string

Payer email of the customer.
givenName string

First name of the customer.
surname string

Last name of the customer.
phone string

Phone number of the customer.
phoneCountryCode string

The country calling code.
birthDate string

The birth date of the customer in YYYY-MM-DD format.
address object

The shipping address.

Properties
Name Type Attributes Description
streetAddress string

Line 1 of the Address (eg. number, street, etc). An error will occur if this address is not valid.
extendedAddress string <optional>

Line 2 of the Address (eg. suite, apt #, etc.). An error will occur if this address is not valid.
locality string

Customer's city.
region string <optional>

Customer's region or state.
postalCode string

Customer's postal code.
countryCode string

Customer's country code.
shippingAmount string <optional>

The shipping fee for all items. This value can not be a negative number.
discountAmount string <optional>

The discount for all items. This value can not be a negative number.
billingAddress object

The billing address.

Properties
Name Type Attributes Description
streetAddress string

Line 1 of the Address (eg. number, street, etc). An error will occur if this address is not valid.
extendedAddress string <optional>

Line 2 of the Address (eg. suite, apt #, etc.). An error will occur if this address is not valid.
locality string

Customer's city.
region string <optional>

Customer's region or state.
postalCode string

Customer's postal code.
countryCode string

Customer's country code.
lineItems Array.<object>

List of line items.

Properties
Name Type Description
category string

The item category type: 'DIGITAL_GOODS', 'PHYSICAL_GOODS', or 'DONATION'.
name string

Item name. Maximum 127 characters.
quantity string

Number of units of the item purchased. This value must be a whole number and can't be negative or zero.
unitAmount string

Per-unit price of the item. Can include up to 2 decimal places. This value can't be negative or zero.
unitTaxAmount string

Per-unit tax price of the item. Can include up to 2 decimal places. This value can't be negative.
locale string

The BCP 47-formatted locale. PayPal supports a five-character code. For example, en-DE, da-DK, he-IL, id-ID, ja-JP, no-NO, pt-BR, ru-RU, sv-SE, th-TH, zh-CN, zh-HK, or zh-TW.
customerServiceInstructions string

Instructions for how to contact the merchant's customer service. Maximum 4,000 characters.
correlationId string

Used to correlate user sessions with server transactions.
onPaymentStart function

A function that will be called with an object containing the paymentId. The continueCallback is not provided as it is not needed for this use case.
Source: