Класс PaymentClient

Точка входа для взаимодействия с Meta Pay.

Примеры

Ниже показан пример использования PaymentClient.

Сначала создайте запрос на платеж. Объект PaymentRequest содержит информацию о платеже, которая должна отображаться для клиента, а также параметры и конфигурации для создания платежного ответа для партнера по платежам, обрабатывающего эту транзакцию.

function buildPaymentRequest(): PaymentRequest 
{
  return
  {
    paymentDetails:
    {
     total: {label: 'Board Game', amount: {value: '19.99', currency: 'USD'}},
    },
    paymentOptions:
    {
      requestPayerName: true,
      requestPayerEmail: false,
      requestPayerPhone: false,
      requestShipping: false,
      allowOfferCodes: false
    },
    paymentConfiguration:
    {
      mode: 'TEST',
      partnerId: 'TEST_PARTNER_ID',
      partnerMerchantId: '<your merchant id>',
      acquirerCountryCode: 'US',
      supportedContainers: {
        'basic-card-v1': {}, // no configurations, use {}
      },
      containerContext: '<a unique identifier for the payment>',
    },
  };
}

Затем создайте объект PaymentClient и определите, доступен ли сервис Meta Pay в среде браузера, который использует ваш клиент. Если Meta Pay доступен, покажите кнопку Meta Pay и прикрепите к ней метод, который будет вызываться при ее нажатии.

const paymentClient = new window.metapay.PaymentClient('1.0');

window.onload = async function ()
{
  const availability = await paymentClient.getAvailability();
  
  if (availability === 'AVAILABLE')
  {
    // display the Meta Pay button
    await paymentClient.renderButton
    (
      '#btn_container',
      buildPaymentRequest,
      responsePromise => onMetaPayClick(responsePromise),
      {theme: 'light'}
    );

    async function onMetaPayClick(responsePromise)
    {
      const response = await responsePromise;

      try
      {
        // process payment by sending response.container to partner
        // ...

        // dismiss the Meta Pay interface with a successful signal
        await response.complete(PaymentComplete.success);
      }
      catch (err)
      {
        // error handling
        // ...
  
        // dismiss the Meta Pay interface with a failure signal
        await response.complete(PaymentComplete.fail);
      }

      // more code
      // ...
    };
  }
  else
  {
    console.log('Meta Pay is not available');
  }
};

Проактивный процесс оформления заказа

В некоторых контекстах (например, когда пользователь с сохраненным способом оплаты переходит к оформлению заказа в приложении семейства Meta, например Facebook или Instagram) SDK может проактивно инициировать упрощенный процесс оформления заказа. Принцип работы показан на следующей схеме:

В некоторых пользовательских контекстах начало оформления заказа при загрузке страницы не является правильным (например, если пользователь находится на странице сведений о товаре, где имеется кнопка Buy with MetaPay, но еще не выразил явное желание сделать покупку). Чтобы обрабатывать такие сценарии, в которых оформление покупки ещё не началось, установите для объекта PaymentConfiguration свойство uxFlags, например paymentConfig.uxFlags = ['DISABLE_PROACTIVE_CHECKOUT']

Конструкторы

PaymentClient(clientVersion: string): PaymentClient

Создает объект PaymentClient.

Методы

getAvailability

getAvailability(paymentConfig: PaymentConfiguration): Promise<string>

Прежде чем отображать кнопку Meta Pay на сайте, вызовите метод getAvailability, позволяющий определить, доступен ли сервис Meta Pay в среде браузера, который использует ваш клиент. Эта проверка позволяет гарантировать, что интерфейс Meta Pay предлагается только там, где он поддерживается. Если Meta Pay поддерживается, покажите кнопку Meta Pay.

Этот метод возвращает значение Availability или PaymentError.

renderButton

renderButton(container: string, providePaymentRequest: () => PaymentRequest, onResponse: (responsePromise: Promise<PaymentResponse>) => void, _options?: ThemeOptions): Promise<void>

После проверки поддержки Meta Pay используйте этот метод, чтобы показать на веб-странице кнопку Meta Pay. Стиль кнопки задается параметром _options в соответствии со стилями и ресурсами в сети CDN. Этот метод подключит прослушивание загрузки и кликов для поддержки запуска формы оплаты Meta Pay, когда пользователь нажмет на кнопку, используя переданный в этот метод paymentRequest. Когда пользователь завершит работу с формой оплаты, будет вызван объект promise onResponse с ответом об оплате.

Кроме того, с помощь. PaymentRequest, возвращенного providePaymentRequest, и функции onResponse можно автоматически начать отображение формы оплаты, чтобы ускорить процесс оформления для допустимых пользователей Meta Pay.

Чтобы отвечать на действия пользователя, когда форма оплаты открыта, задайте в экземпляре PaymentClient обработчики событий onPaymentDetailsChanged и onPaymentConsent.

[упразднено] preparePaymentSheet

preparePaymentSheet(paymentConfig: PaymentConfiguration): Promise<PaymentSheetStatus>

Этот метод позволяет подготовить форму оплаты Meta Pay. Он вызывается в ответ на действие клиента, например нажатие кнопки, позволяя форме оплаты создать компоненты пользовательского интерфейса, такие как всплывающее окно.

После вызова preparePaymentSheet выполните вызов к getPaymentResponse, чтобы предоставить информацию о запросе на платеж.

Если вызвать getPaymentResponse без предварительного вызова preparePaymentSheet, SDK попытается инициировать создание формы оплаты. При этом при отсутствии предварительного действия со стороны клиента вызов getPaymentResponse может завершиться ошибкой.

Этот метод возвращает PaymentSheetStatus или PaymentError.

getPaymentResponse

getPaymentResponse(request: PaymentRequest): Promise<PaymentResponse>

Этот метод создает интерфейс Meta Pay. Клиент может выбрать способ оплаты и, если будет предложено, предоставить информацию, такую как имя и данные для доставки, в объекте PaymentOptions запроса.

Этот метод возвращает PaymentResponse.

attemptProactivePayment

attemptProactivePayment(request: PaymentRequest): Promise<PaymentResponse>

Как и getPaymentResponse, этот метод создает интерфейс Meta Pay. Однако его можно вызвать при отображении кнопки Meta Pay. На поддерживаемых платформах это позволяет сделать интерфейс оплаты удобнее для клиентов.

Этот метод возвращает PaymentResponse>. Если проактивное оформление заказа не поддерживается, объект promise будет отклонен с ошибкой.

События

onPaymentConsent

Необязательный обработчик события, с помощью которого продавец может попытаться авторизовать платеж, прежде чем будет закрыта форма оплаты.

При использовании этого обработчика интерфейс формы оплаты ожидает, пока не будет разрешен возвращаемый обработчиком объект promise. Если событие возвращает PaymentAuthorizationResult, где параметр authorizationState имеет значение ERROR, для клиента отображается сообщение и он может обновить или изменить способ оплаты.

onPaymentConsent Example

// before you call paymentClient.renderButton() attach a consent handler
paymentClient.onPaymentConsent = paymentConsentHandler;

async function paymentConsentHandler(paymentResponse)
{
  try
  {
    console.log('payment response received');

    // submit paymentResponse to payment processor for authorization
    return Promise.resolve({authorizationState: 'SUCCESS'});
  }
  catch (error)
  {
    return Promise.reject
    ({
       authorizationState: 'ERROR',
       error:
       {
         reason: 'INVALID_PAYMENT_DATA',
         message: 'We were unable to process payment. Please try again with a different card.'
       },
    });
  }
}

onPaymentDetailsChanged

Необязательный обработчик события, который позволяет продавцу обновить начальное значение FBPaymentRequest в ответе в соответствии с изменениями, сделанными клиентом в форме оплаты. Кроме того, его можно использовать для отображения ошибок для клиента, если какие-либо изменения приведут к тому, что продавец признает транзакцию недействительной. Этот обратный вызов обновляет paymentDetails.total и (или) paymentDetails.summaryItems в ответ на изменения, сделанные клиентом в форме. Этот обратный вызов необходимо реализовать, когда первоначальный запрос на платеж предоставляется по следующим сценариям:

• параметр paymentOptions.requestShipping имеет значение true;
• параметр paymentOptions.shippingType имеет значение PICKUP;
• параметр paymentOptions.requestBilling имеет значение true и сумму налогов необходимо пересчитать для общей стоимости;
• параметр paymentOptions.allowOfferCodes имеет значение true (обработчик должен изменить итоговые и суммарные значения в соответствии с изменениями, связанными с выбранным покупателем кодом предложения).

Этот обратный вызов должен возвращать объект Promise<PaymentDetailsUpdate>.

onPaymentDetailsChanged Example

// before you call paymentClient.renderButton() attach a handler
paymentClient.onPaymentDetailsChanged = paymentDetailsChangedHandler;

async function paymentDetailsChangedHandler(event)
{	
  // Create an PaymentDetailsUpdate object
  let update = {
  	paymentDetails: event.paymentDetails,
  	errors: [],
  }
  if (event.changeTypes.length != 0) {
  	// Modify the FBPaymentDetailsUpdate object based on 
  	// the incoming FBPaymentDetailsChangedEvent
  	// ...
  }
  
  return Promise.resolve(update);
}

Статьи по теме

• Обзор интеграции Meta Pay
• JavaScript SDK для Meta Pay