Skip to main content

Checkout

Payment Options (Javascript Interface)​

Our Checkout flow offers different Payment Options that provides consumers with the means to pay for an order with the payment method of their choice. Payments App developers can create their own Payment Options.

Payment Options configuration params are set via our Payment Provider API by adding checkout_payment_options on the Payment Provider object creation.

Our Checkout triggers a variety of events for which we provide a JavaScript API that allows you to handle these events freely to perform the payment process. Hence, you can implement their (most likely) already existing and widely tested Javascript SDKs.

The file with the handlers implemented for the different options should be hosted on a CDN that must be capable of handling high traffic loads. The HTTPS URL to this file must be set in the Payment Provider checkout_js_url property.

Note: The file mentioned above must use data from method getData of Checkout Context. However, in case you need to use data stored in Local Storage, for example, you should create a Script and use the method postMessage to send information stored in Local Storage from the store domain to Checkout's private domain. With this information inside the secure domain, the checkout_js file will be able to send it to your backend.

Examples​

External Payment Option​

Let's take a look at a simple script for a hypothetical integration with a Payment Provider that redirects the user to 'acmepayments.com' to complete the purchase in their checkout. This is what we call a redirect checkout.

// Call 'LoadCheckoutPaymentContext' method and pass a function as parameter to get access to the Checkout context and the PaymentOptions object.

LoadCheckoutPaymentContext(function (Checkout, PaymentOptions) {
  // Create a new instance of external Payment Option and set its properties.
  var AcmeExternalPaymentOption = PaymentOptions.ExternalPayment({
    // Set the option's unique ID as it is configured on the Payment Provider so they can be related at the checkout.
    id: "acme_redirect",

    // This parameter renders the billing information form and requires the information to the consumer.
    fields: {
      billing_address: true,
    },

    // This function handles the order submission event.
    onSubmit: function (callback) {
      // Gather the minimum required information. You should include all the relevant data here.
      let acmeRelevantData = {
        orderId: Checkout.getData("order.cart.id"),
        currency: Checkout.getData("order.cart.currency"),
        total: Checkout.getData("order.cart.prices.total"),
      };

      // Use the Checkout HTTP library to post a request to our server and fetch the redirect URL.
      Checkout.http
        .post("https://app.acme.com/generate-checkout-url", {
          data: acmeRelevantData,
        })
        .then(function (responseBody) {
          // Once the redirect URL is generated, invoke the callback by passing it as argument.
          if (responseBody.data.success) {
            callback({
              success: true,
              redirect: responseBody.data.redirect_url,
              extraAuthorize: true, // Legacy paameter, but currently required with `true` value. Will be deprecrated soon.
            });
          } else {
          // If the generation of the redirect URL fails, invoke the callback indicating the corresponding error code. E.g.: `consumer_country_invalid`. See the list of available error codes.
            callback({
              success: false,
              error_code: responseBody.data.error_code,
            });
          }
        })
        .catch(function (error) {
          // Handle a potential error in the HTTP request.

          callback({
            success: false,
            error_code: "payment_processing_error",
          });
        });
    },
  });

  // Finally, add the Payment Option to the Checkout object so it can be render according to the configuration set on the Payment Provider.
  Checkout.addPaymentOption(AcmeExternalPaymentOption);

  // or remove payment option loading 
  Checkout.unLoadPaymentMethod('acme_redirect');
});

Card Payment Option​

This is a more complex example, since this is a richer interaction with more control over the user experience. The entire flow happens without leaving the Tiendanube checkout, in what we call a transparent checkout.

This type of payment renders a form where the consumer inputs their credit card information and with which you can interact.

In this example, whenever the consumer inputs or changes the credit card number we fetch the first 6 digits and populate the list of available installments.

LoadCheckoutPaymentContext(function (Checkout, PaymentOptions) {
  var currentTotalPrice = Checkout.getData("order.cart.prices.total");
  var currencCardBin = null;

  // Some helper functions.

  // Get credit the card number from transparent form.
  var getCardNumber = function () {
    return Checkout.getData("form.cardNumber");
  };

  // Get the first 6 digits from the credit card number.
  var getCardNumberBin = function () {
    return getCardNumber().substring(0, 6);
  };

  // Check whether the BIN (first 6 digits of the credit card number) has changed. If so, we intend to update the available installments.
  var mustRefreshInstallments = function () {
    var cardBin = getCardNumberBin();
    var hasCardBin = cardBin && cardBin.length >= 6;
    var hasPrice = Boolean(Checkout.getData("totalPrice"));
    var changedCardBin = cardBin !== currencCardBin;
    var changedPrice = Checkout.getData("totalPrice") !== currentTotalPrice;
    return hasCardBin && hasPrice && (changedCardBin || changedPrice);
  };

  // Update the list of installments available to the consumer.
  var refreshInstallments = function () {
    // Let's imagine the App provides this endpoint to obtain installments.

    Checkout.http
      .post("https://acmepayments.com/card/installments", {
        amount: Checkout.getData("totalPrice"),
        bin: getCardNumberBin(),
      })
      .then(function (response) {
        Checkout.setInstallments(response.data.installments);
      });
  };

  // Create a new instance of card Payment Option and set its properties.
  var AcmeCardPaymentOption = PaymentOptions.Transparent.CardPayment({
    // Set the option's unique ID as it is configured on the Payment Provider so then can be related at the checkout.
    id: "acme_transparent_card",

    // Event handler for form field input.
    onDataChange: Checkout.utils.throttle(function () {
      if (mustRefreshInstallments()) {
        refreshInstallments();
      } else if (!getCardNumberBin()) {
        // Clear installments if customer remove credit card number.
        Checkout.setInstallments(null);
      }
    }),

    onSubmit: function (callback) {
      // Gather the minimum required information.
      var acmeCardRelevantData = {
        orderId: Checkout.getData("order.cart.id"),
        currency: Checkout.getData("order.cart.currency"),
        total: Checkout.getData("order.cart.prices.total"),
        card: {
          number: Checkout.getData("form.cardNumber"),
          name: Checkout.getData("form.cardHolderName"),
          expiration: Checkout.getData("form.cardExpiration"),
          cvv: Checkout.getData("form.cardCvv"),
          installments: Checkout.getData("form.cardInstallments"),
        },
      };
      // Let's imagine the App provides this endpoint to process credit card payments.
      Checkout.http
        .post("https://acmepayments.com/charge", acmeCardRelevantData)
        .then(function (responseBody) {
          if (responseBody.data.success) {
            // If the transaction was successful, invoke the callback to indicate you want to close order.
            callback({
              success: true,
            });
          } else {
            // If the transaction fails, invoke the callback indicating the corresponding error code. E.g.: `card_rejected_insufficient_funds`. See the list of available error codes.
            callback({
              success: false,
              error_code: responseBody.data.error_code,
            });
          }
        })
        .catch(function (error) {
          // Handle a potential error in the HTTP request.

          callback({
            success: false,
            error_code: "payment_processing_error",
          });
        });
    },
  });

  // Finally, add the Payment Option to the Checkout object so it can be render according to the configuration set on the Payment Provider.
  Checkout.addPaymentOption(AcmeCardPaymentOption);
});

Modal is lightbox or modal with an embedded iframe containing the Payment Provider's checkout UI on the merchant's website. The checkout flow is run under the Payment Provider's domain, but the buyer never really leaves the Merchant's website.

When the user submits our checkout, a modal rendered by the Payment Provider is displayed and the user finishes the payment process on it.

LoadCheckoutPaymentContext(function (Checkout, PaymentOptions) {
  var CheckoutPayment = new PaymentOptions.ModalPayment({
    id: "modal",
    name: "Credit Card",
    onSubmit: function (callback) {

      var modalData = {
        storeId: Checkout.getData("storeId"),
        orderId: Checkout.getData("order.cart.id"),
        amount: Checkout.getData("order.cart.prices.total")
      };

      var modalUrl = Checkout.utils.setQueryString("http://localhost:3003/", modalData)
      // http://localhost:3003/?storeId=9999&orderId=123&amount=120.9

      // in this param objet you could pass any iframe attribute
      // Example: src, id, className, frameBorder, style...
      var iframeData = { src: modalUrl }

      var iframeConfigs = { showBackDrop: false }

      this.createModal(iframeData, iframeConfigs);

      // This event listens for the modal's response from your domain
      var modalEventHandler = (event) => {
        // the method `parseModalResponse` validate the response because in some cases it was a string
        var response = this.parseModalResponse(event.data)
        // {
        //   type: 'PAYMENT_MODAL_RESPONSE',
        //   data: {
        //     success: true || false
        //     error_code: null || error string
        //   }
        // }

        if (response.type === "PAYMENT_MODAL_RESPONSE") {
          // removing event to avoid duplicated messages
          window.removeEventListener("message", modalEventHandler)

          // This method should always be called to proceed with payment or failure
          callback(response.data);
        }
      }

      window.addEventListener("message", modalEventHandler);
    },
  });
  Checkout.addPaymentOption(CheckoutPayment);
});

On your website which will be rendered by the iframe you have three possible answers

Close modal button​
window.parent.postMessage({
  type: "PAYMENT_MODAL_RESPONSE",
  data: { success: true, closeModal: true }
}, '*');
Failed payment​
window.parent.postMessage({
  type: "PAYMENT_MODAL_RESPONSE",
  data: { success: false, error_code: 'payment_processing_error' }
}, '*');
Success payment​
window.parent.postMessage({
  type: "PAYMENT_MODAL_RESPONSE",
  data: { success: true }
}, '*');

Checkout Context​

The LoadCheckoutPaymentContext function takes function as a argument, which will be invoked with two arguments, Checkout and PaymentOptions, to provide access to our Checkout's context.

NameDescription
httpMethod to perform AJAX requests. See HTTP.
utilsCollection of helper functions. See Utils.
updateFieldsAllows adding or removing optional input fields from the payment option form.
addPaymentOption Register the option so the checkout can inject the configuration params and render it.
setInstallments Update the attributes of the data. installments object. See Installments.
getDataMethod to obtain the data of the shopping cart, the consumer and more. See getData.
processPaymentMethod to perform backend-to-backend processing of a payment request. See processPayment.
showErrorCodeMethod to display an error message at the payment option form. See showErrorCode.

Checkout​

HTTP​

This object is an Axios instance. Though the fetch is now available on all major object, using this method ensures cross-browser compatibility and it will also allow us to detect unexpected behaviours for which we'll be able to trigger alerts.

Note: This instance of Axios already has a few params set by the Checkout.

Standard POST example​
Checkout.http
  .post("https://acmepayments.com/charge", {
    cartId: cartId,
  })
  .then(function (response) {
    // Do something with the response.
  });
Custom config request example​
Checkout.http({
  url: "https://acmepayments.com/charge",
  method: "post",
  data: {
    cartId: cartId,
  },
}).then(function (response) {
  // Do something with the response.
});

Utils​

  • Checkout.utils.Throttle
  • Checkout.utils.LoadScript
  • Checkout.utils.FlattenObject

getData​

The Checkout object provides the app with access to all the data related with ongoing sale. We've got the following data groups:

  • Cart Information: Checkout.getData('order.cart').
  • Total cart price: Checkout.getData('totalPrice') (also indicated by Checkout.getData('order.cart.prices.total')).
  • ID of the store to which the cart belongs: Checkout.getData('storeId').
  • Customer Contact Information: Checkout.getData('order.contact').
  • Billing Information: Checkout.getData('order.billingAddress').
  • Shipping Information: Checkout.getData('order.shippingAddress').
  • Shipping Method Information: Checkout.getData('order.cart.shipping').
  • Payment Method Information: Checkout.getData('form').

Note: No all Payment Method Information fields are rendered. They can be rendered as explained here.

Here's an example of the data available in the Checkout.getData() object (rendered as JSON for better readability):

{
  "form": {},
  "totalPrice": 135,
  "country": "AR",
  "storeId": 1196173,
  "storeUrl": "https://examplestore.com",
  "callbackUrls": {
    "success": "https://examplestore.com/checkout/v3/success/375854104/aebe04afab671411e6d75352fb4f514898b1667a",
    "failure": "https://examplestore.com/checkout/v3/next/375854104/aebe04afab671411e6d75352fb4f514898b1667a",
    "cancel": "https://examplestore.com/checkout/v3/next/375854104/aebe04afab671411e6d75352fb4f514898b1667a"
  },
  "order": {
    "cart": {
      "id": 375854104,
      "hash": "aebe04afab671411e6d75352fb4f514898b1667a",
      "number": null,
      "prices": {
        "shipping": 15,
        "discount_gateway": 0,
        "discount_coupon": 30,
        "discount_promotion": 0,
        "discount_coupon_and_promotions": 30,
        "subtotal_with_promotions_applied": 150,
        "subtotal_with_promotions_and_coupon_applied": 120,
        "subtotal": 150,
        "total": 135,
        "total_usd": 0
      },
      "lineItems": [
        {
          "id": 451294379,
          "name": "Example Product 1",
          "price": "50.50",
          "quantity": 1,
          "free_shipping": false,
          "product_id": 58979310,
          "variant_id": 175499404,
          "thumbnail": "//d2qa76c3k7tf6c.cloudfront.net/stores/001/196/173/products/example-product-1.jpg",
          "variant_values": "",
          "sku": null,
          "properties": [],
          "url": "https://examplestore.com/productos/example-product-1/?variant=175499404",
          "is_ahora_12_eligible": true
        },
        {
          "id": 451294230,
          "name": "Example Product 2",
          "price": "99.50",
          "quantity": 1,
          "free_shipping": false,
          "product_id": 58979280,
          "variant_id": 175499176,
          "thumbnail": "//d2qa76c3k7tf6c.cloudfront.net/stores/001/196/173/products/example-product-2.jpg",
          "variant_values": "",
          "sku": null,
          "properties": [],
          "url": "https://examplestore.com/productos/example-product-2/?variant=175499176",
          "is_ahora_12_eligible": true
        }
      ],
      "currency": "ARS",
      "currencyFormat": {
        "short": "$%s",
        "long": "$%s ARS"
      },
      "lang": "es",
      "langCode": "es_AR",
      "coupon": {
        "id": 1566261,
        "code": "DESC20",
        "type": "percentage",
        "value": "20.00",
        "valid": true,
        "used": 0,
        "max_uses": null,
        "start_date": null,
        "end_date": null,
        "min_price": null,
        "categories": null
      },
      "shipping": {
        "type": "ship",
        "method": "correo-argentino",
        "option": 6111227,
        "branch": null,
        "disabled": null,
        "raw_name": "Correo Argentino - Encomienda Clásica",
        "suboption": null
      },
      "status": {
        "order": "open",
        "order_cancellation_reason": null,
        "fulfillment": "unpacked",
        "payment": "pending"
      },
      "completedAt": null,
      "minimumValue": null,
      "hasNonShippableProducts": false,
      "hasShippableProducts": true,
      "isAhora12Eligible": true
    },
    "shippingAddress": {
      "first_name": "John",
      "last_name": "Doe",
      "phone": "+54123456789",
      "address": "Example Street",
      "number": "1234",
      "floor": "",
      "locality": "Valentín Alsina",
      "city": "Lanús",
      "state": "Buenos Aires",
      "zipcode": "1822",
      "country": "AR",
      "between_streets": "",
      "reference": "",
      "id_number": "11223344"
    },
    "billingAddress": {
      "first_name": "John",
      "last_name": "Doe",
      "phone": "+54123456789",
      "address": "Example Street",
      "number": "1234",
      "floor": "",
      "locality": "Valentín Alsina",
      "city": "Lanús",
      "state": "Buenos Aires",
      "zipcode": "1822",
      "country": "AR",
      "between_streets": "",
      "reference": "",
      "id_number": "11223344"
    },
    "contact": {
      "email": "john.doe@example.com",
      "name": "John Doe",
      "phone": "+54123456789"
    },
    "customer": 123123123 // logged in user id or undefined if not logged
  }
}

processPayment​

This method allows your app to process backend-to-backend payment requests. As described in our Payment Provider App Development Guide documentation, for this use case our platform implements a generic payment payload that can be adapted to a specific payload that conforms to your app's API. But also, if necessary, this standard payload can be extended by adding custom data inside an extra object. The content of that extra object, wich is optional, must be passed to the processPayment method as parameter.

Here's an example:

LoadCheckoutPaymentContext(function(Checkout, PaymentMethods) {
    var External = PaymentMethods.ExternalPayment({
        id: 'acme_redirect',
        onSubmit: function(callback) {
            let extraData = {
                "email": Checkout.getData('order.contact.email')
            }
            Checkout.processPayment(extraData)
                .then(function(payment) {
                    window.parent.location.href = payment.redirect_url;
                })
                .catch(function(error) {
                    Checkout.showErrorCode(error.response.data.message);
                });
        }
    });
    Checkout.addPaymentOption(External);
});

showErrorCode​

This method displays an error message for the consumer at the payment option form. It takes any value defined in our error code library as a parameter, which will be translated into the corresponding error message according to the language used by the store.

LoadCheckoutPaymentContext(function(Checkout, PaymentMethods) {
    var Custom = PaymentMethods.CustomPayment({
        id: 'acme_custom',
        onSubmit: function(callback) {
            if (Checkout.getData('totalPrice') < 3) {
                Checkout.showErrorCode('order_total_price_too_small');
            }
            ...
        });
    });

PaymentOptions​

The second argument of the function passed as an argument to LoadCheckoutPaymentContext is PaymentOptions. It contains functions for each of the different possible integration types. Each of the functions take a configuration object as an argument and, in turn, will return a javascript instance of the PaymentOption.

NameDescription
ExternalPayment()Returns an instance of the PaymentOption for integration types that require redirecting the consumer to a different website.
ModalPayment()Returns an instance of the PaymentOption for integration types that require opening a Modal in the store's frontend.
CustomPayment()Used internally for the merchant's custom payment methods.
TransparentObject that contains functions to obtain instances for transparent integration types.

Note: ExternalPayment and ModalPayment won't render any input fields on the frontend. The main difference between them is on their onSubmit callback parameters.

Transparent Integration Type​

The PaymentOptions.Transparent has one function per each of the payment methods for which we support transparent integration type. Each of these funcitons return an instance of the PaymentOption for their specific payment methods and, if added to the Checkout using Checkout.addPaymentOption(paymentOptionInstance) a form will be rendered with all the required input fields for that payment method.

NameDescription
CardPayment()For credit_card and debit_card payment methods.
DebitPayment()For bank_debit payment method (aka "online debit").
BoletoPayment()For payments with boleto payment method.
TicketPayment()For payments with ticket payment method.
PixPayment()For payments with pix payment method.
CardPayment​

These are the fields rendered and available on the Checkout.getData('form') object.

NameDescriptionRequiredfields value
cardNumberCard number.Always
cardHolderNameCard holder's name.Always
cardExpirationCard's expiration date in mm/yy format.Always
cardCvvCard's verification code.Always
cardInstallmentsNumber of installments selected by the consumer.Always
cardHolderIdNumberCard holder's identification (CPF, DNI or equivalent).Optionalcard_holder_id_number
cardHolderIdTypeCard holder's identification (CPF, DNI or equivalent).Optionalcard_holder_id_types
cardHolderBirthDateCard holder's birthday in dd/mm/yy format.Optionalcard_holder_birth_date
cardHolderPhoneCard holder's phone number.Optionalcard_holder_phone
bankIdCard's issuing bank.OptionalbankList

cardBrand is inserted after the user enters the first six credit card numbers

DebitPayment​

These are the input fields rendered and available in the object Checkout.getData('form').

NameDescriptionRequiredfields value
bankBank to debit from.Optionalbank_list
holderNameAccount holder's name.Optionaldebit_card_holder_name
holderIdNumberAccount holder's identification (CPF, DNI, or equivalent).Optionaldebit_card_id_number
BoletoPayment​

These are the input fields rendered and available in the object Checkout.getData('form').

NameDescriptionRequiredfields value
holderNameConsumer's name.Optionalboleto_holder_name
holderIdNumberConsumer's identification (CPF, CNPJ or equivalent).Optionalboleto_id_number
TicketPayment​

These are the input fields rendered and available in the object Checkout.getData('form').

NameDescriptionRequiredfields value
brandBrand name for selected cash list optionAlwaysefectivo_list
efectivo_listBrand name for selected ticket or boleto list optionAlways[{ name: 'PagoFacil', code: 'pagofacil' }, { name: 'Rapipago', code: 'rapipago' }, { name: 'Caixa', code: 'caixa' }, { name: 'Itau', code: 'itau' }, ...]
ticketHolderIdNumberbuyer documentOptionalticket_holder_id_number
ticketHolderIdTypebuyer document typeOptionalticket_holder_id_types: [{ "code": "DNI", "name": "DNI" }, { "code": "CI", "name": "Cédula" }, ...]
PixPayment​

These are the input fields rendered and available in the object Checkout.getData('form').

NameDescriptionRequiredfields value
holderNameConsumer's name.Optionalholder_name
holderIdNumberConsumer's identification (CPF).Optionalholder_id_number

PaymentOption Configuration Object and it's properties​

All PaymentOptions functions take a configuration object. The generic properties of the configuration object for all PaymentOptions are:

NameDescription
idMust match the id set in the Payment Provider's checkout_payment_options[i].
namePayment option display name.
fieldsObject containing a propertires of extra input fields for transparent payment options and a boolean value to wither render it or not.
scriptsList of external JavaScript files to be loaded before registering this method.
onLoadFunction to be invoked after registering this method.
onDataChangeFunction to be invoked whenever there's a change in checkout data.
onSubmitFunction to be invoked whenever the consumer clicks on "Finish checkout" and all mandatory fields are filled correctly.
fields property​

For each of the transparent payment options, the following extra input fields can be rendered if specified in this property.

CreditPayment​
NameDescription
bankListBanks list.
issuerListBanks list. (AR only)
card_holder_id_typesCard holder identification type selector.
card_holder_id_numberCard holder identification number.
card_holder_birth_dateCard holder birth date.
card_holder_phoneCard holder number.
DebitPayment​
NameDescription
bank_listBanks list.
BoletoPayment​
NameDescription
boleto_holder_namePayer name.
boleto_id_numberPayer id number.

No including an input field on this object is enough to prevent it from rendering. It's not necessary to set it as false.

For all payment options​
NameDescription
billing_addressBilling information.

PixPayment doesn't render any input. The payment instructions are displayed after closing the order.

Updating the fields dinamically​
Checkout.updateFields({
  method: "acme_transparent_card",
  value: {
    bankId: true,
  },
});
onSubmit​

The handler function for the onSubmit event property receives a callback function argument which must be invoked immediately after finishing the necessary requests to initiate the payment process.

The callback function must be invoked with an object containing the following properties.

NameDescription
successIf true, the checkout process continues and the order is completed. Otherwise, a customizable error message is shown to the consumer.
error_code(Required in case of failure) If success is false, the specified error code will be used to provide the user a message with all the necessary information to allow them to, either correct the problem, or at least understand what went wrong with the transaction. See Transaction Failure Codes and Checkout Runtime Error Codes.
redirect(Optional) External URL to which the consumer will be redirected to continue the payment process. (Only for ExternalPayment()).
Sample Arguments​

Here's an example summarizing all the definitions above.

LoadCheckoutPaymentContext(function (Checkout, PaymentOptions) {
  var Custom = PaymentOptions.Transparent.CardPayment({
    id: "acme_transparent_card",

    fields: {
      card_holder_birth_date: true,
    },

    onLoad: function () {
      // Do something after the script loads.
      // Example: generate a token.
    },

    onDataChange: Checkout.utils.throttle(function () {
      // Do something when the input form data changes.
      // Data changed is already available on `Checkout.getData()`.
      // Example: update credit card installments when the order value changes.
    }, 700),

    onSubmit: function (callback) {
      // Do something when user submits the payment.
      callback({
        success: true, // Or false.
      });
    },
  });

  Checkout.addPaymentOption(Custom);
});

Installments​

In order to offer installment's options you must update the object data.installments by calling setInstallments. This will update the select input for the installments options on the card information form. Installments must be set considering the min_installment_value configured in Payment Provider. The Merchant should be able to configure this field in the Partner's Backend.

Each element of the list must be an object with the following fields.

NameDescription
quantityNumber of installments.
installmentAmountValue of a single installment.
totalAmountTotal value of all installments.
cft(optional)[String] Total financial cost.
Example​
Checkout.setInstallments([
  {
    quantity: 1,
    installmentAmount: 25,
    totalAmount: 25,
    cft: "0,00%",
  },
  {
    quantity: 2,
    installmentAmount: 13,
    totalAmount: 26,
    cft: "199,26%",
  },
  {
    quantity: 3,
    installmentAmount: 10,
    totalAmount: 30,
    cft: "196,59%",
  },
]);

Appendix​

Checkout Runtime Error Codes​

If for some reason the onSubmit event handler fails to execute the action expected by the payment option chosen by the user, together with a success: false callback parameter, a error_code must be specified in order to allow us to give the consumer clear information on what went wrong so the consumer understands what they need to do in order be able to fix the problem.

All Transaction Failure Codes are valid error_codes, in addition to those specified below:

Failure CodeDescription
server_errorThere is a problem accessing the server which prevents either the execution of the payment or the generation of the redirect URL.
server_error_timeoutSame as server_error but the problem is due to a timeout condition.
payment_processing_errorThere was a problem processing the payment. Use this error as default only if it is not possible to use another error code from the list.

Remove payment option loading​

If for some reason, the partner needs to unload a payment option that will not be rendered, they can use the unLoadPaymentMethod method instead of the addPaymentOption method.


LoadCheckoutPaymentContext(function (Checkout, PaymentOptions) {
  var acmeRedirectId = "acme_redirect";

  var AcmeExternalPaymentOption = PaymentOptions.ExternalPayment({
    id: acmeRedirectId,
    onSubmit: function (callback) {
      // onSubmit handle
    },
  });

  var shouldRender = false;

  if (shouldRender) {
    Checkout.addPaymentOption(AcmeExternalPaymentOption);
  } else {
    Checkout.unLoadPaymentMethod(acmeRedirectId);
  }
});