Configuration Options

Checkout

HTML Attribute	JS Prop	Type	Required	Default	Description
asset	asset	string	yes	n/a	Reference code for asset for the sale's amount
reference-id	referenceId	string	yes	n/a	External code created by merchant to reference the payment
contract-id	contractId	string	yes	n/a	epag's contract_id to be used in this sale
amount	amount	number	yes	n/a	Total amount of the payment. Value must have a maximum of two decimal places and must not be less than BRL 0.75
payment-country	paymentCountry	string	yes	BR	Country code in ISO 3166-2 for the payment
payment-currency	paymentCurrency	string	yes	BRL	Currency code in ISO-4217 for the payment

Payment

HTML Attribute	JS Prop	Type	Required	Default	Description
method	method	string	yes	n/a	Payment Method. Valid options: CREDITCARD, DEBITCARD, PIX, BOLETO, PICPAY, OXXO, TIENDAS_Y_FARMACIAS, SPEI, PAYCASH, BANK_TRANSFER, PAGO_EFECTIVO, DEUNA, NEQUI, MACH.
card-installments	cardInstallments	number	no	1	Number of installments. Used if method is CREDITCARD.
soft-descriptor	softDescriptor	string	no	n/a	Soft descriptor to use at card transaction.
process-payment	processPayment	boolean	no	false	Automatically process the payment (CREDITCARD, DEBITCARD only).
delay-capture	delayCapture	boolean	no	false	Pre-authorizes the payment for later capture (CREDITCARD, PICPAY only).
save-card	saveCard	boolean	no	true	Tokenizes card for future uses. Works only if processPayment = true, otherwise saveCard will always be true.
pix-direct	pixDirect	boolean	no	false	true will show the QR code for PIX payment without collecting payer data. Merchants can still send data to be linked to the transaction.
expiration-date	expirationDate	YYYY-MM-DD	no	false	Expiration date for the payment created by this checkout session. If not provided, the system will assume 2 days from the current date. Supported formats: YYYY-MM-DD, YYYY-MM-DDTHH:mm:ss, YYYY-MM-DDTHH:mm:ss-03:00. If the time is not specified, the system will default to 23:59:59. The timezone will be UTC unless explicitly included in the string. The minimum allowed is 1 minute and the maximum is 10 days from the current date.
boleto-line1	boletoLine1	string	no	n/a	First instruction line for cashier and customer.
boleto-line2	boletoLine2	string	no	n/a	Second instruction line for cashier and customer.
boleto-line3	boletoLine3	string	no	n/a	Third instruction line for cashier and customer.
notification-url	notificationUrl	string	no	n/a	Webhook URL for status updates on transactions associated with this. checkout session
support-text	supportText	string	no	n/a	Footer text in customer email for support contact (e.g., "Questions? Email [email protected]").
success-url	successUrl	string	no	n/a	The URL where the customer is redirected after the payment has been successfully completed.
declined-url	declinedUrl	string	no	n/a	The URL where the customer is redirected if the payment is declined by the payment processor.
error-url	errorUrl	string	no	n/a	The URL where the customer is redirected when an unexpected error occurs during payment processing.
lightbox-use-3ds	lightboxUse3ds	boolean	no	false	Enables 3DS authentication if true.
lightbox-use-external-3ds	lightboxUseExternal3ds	boolean	no	false	Enables 3DS authentication with an external MPI if true.

Customer Details

HTML Attribute	JS Prop	Type	Required	Default	Description
address-additional	addressAdditional	string	no	n/a	Additional information for this address (e.g. department).
address-city	addressCity	string	no	n/a	Billing address city.
address-country	addressCountry	string	no	n/a	Country code as ISO 3166-1 alpha-2 code.
address-locality	addressLocality	string	no	n/a	Billing address locality (e.g. neighborhood).
address-main	addressMain	string	no	n/a	Main information of the address (e.g. street or avenue).
address-number	addressNumber	number	no	n/a	Number for this address.
address-state	addressState	string	no	n/a	Billing address state code.
address-zip-code	addressZipCode	string	no	n/a	Billing address zip code.
person-birth	personBirth	YYYY-MM-DD	no	n/a	Date of birth.
person-email	personEmail	string	no	n/a	Person's email provided to the merchant.
person-first-name	personFirstName	string	no	n/a	First name of this person. Min 3 characters for OXXO, SPEI, and TIENDAS_Y_FARMACIAS methods.
person-phone	personPhone	string	no	n/a	Billing address telephone.
person-phone-area	personPhoneArea	number (max 2 digits)	no	n/a	Number of phone area code.
person-phone-country	personPhoneCountry	number (max 2 digits)	no	n/a	Number of country phone code.
person-surname	personSurname	string	no	n/a	Surname of this person.
person-tax-id	personTaxId	string	no	n/a	Unique identifier for this person in country tax system (e.g. in Brazil: CPF).
disable-dob	disableDob	boolean	no	true	Hides the date of birth.
lock-email	lockEmail	boolean	no	false	Prevents editing the person's email.

Widget options

HTML Attribute	JS Prop	Type	Required	Default	Description
button-label	buttonLabel	string	no	Pay now	String that defines the widget button text.
button-color	buttonColor	valid CSS color	no	#3375C9	Valid CSS color for the button.
button-text-color	buttonTextColor	valid CSS color	no	#FFFFFF	Valid CSS color for the button text.

Lightbox options

HTML Attribute	JS Prop	Type	Required	Default	Description
lightbox-logo-url	lightboxLogoUrl	string	no	ePag logo	The URL of your logo (180 x 30 pixels) beginning with https.
lightbox-primary-color	lightboxPrimaryColor	valid CSS color	no	#303740	Color applied to header.
lightbox-secondary-color	lightboxSecondaryColor	valid CSS color	no	#314259	Color applied to action buttons.
lightbox-accent-color	lightboxAccentColor	valid CSS color	no	#027BE3	Color applied to input focus and active stepper.
lightbox-positive-color	lightboxPositiveColor	valid CSS color	no	#A5DC86	Color applied to success icon and success messages.
lightbox-negative-color	lightboxNegativeColor	valid CSS color	no	#F27474	Color applied to error icon and error messages.
lightbox-info-color	lightboxInfoColor	valid CSS color	no	#F8BB86	Color applied to loader icon and info messages.
lightbox-warning-color	lightboxWarningColor	valid CSS color	no	#F2C037	Color applied to warning icon and warning messages.
lightbox-address-bar-color	lightboxAddressBarColor	valid CSS color	no	#292F36	Color applied to address bar when in mobile.
lightbox-disable-address	lightboxDisableAddress	boolean	no	false	If true, disables the user's address collection step.
lightbox-partial-address	lightboxPartialAddress	boolean	no	false	If true, requires only the user's zip code and number.

Events

Event Name	When
checkout-success	Event emitted when successfully processed the payment.
checkout-ready	Event emitted when checkout modal is ready.
checkout-dismissed	Event emitted when checkout modal is closed.
checkout-error	Event emitted when an error occurs with the payment.
boleto-copy	Event emitted when payment with boleto mode is successful and user has copied the barcode.
pix-copy	Event emitted when payment with pix mode is successful and user has copied the pix code.
oxxo-copy	Event emitted when payment with oxxo mode is successful and user has copied the oxxo barcode.
spei-copy	Event emitted when payment with spei mode is successful and user has copied the spei clabe.
tiendas-y-farmacias-copy	Event emitted when payment with tiendas y farmacias mode is successful and user has copied the tiendas y farmacias barcode.
paycash-copy	Event emitted when payment with paycash mode is successful and user has copied the paycash barcode.
3ds-success	Event emitted when successfully processed the 3DS payment.
3ds-unenrolled	Event emitted when card does not allow 3DS authentication.
3ds-failure	Event emitted when an error occurs with the 3DS payment.
3ds-error	Event emitted when an error occurs during 3DS authentication process.

Instance Methods

Method	Parameter	Return	Description
mountIn	HTMLElement / CSS selector	void	Mount the checkout in the DOM and display the pay button.
start	no	void	Mount the checkout in the DOM and launch the lightbox. With this method, the pay button will not get visible.
closeLightbox	no	void	Used for programmatically closing the lightbox.
on	event, function	void	Add an event handler. Acts the same way as .addEventListener from HTML.
off	event, function	void	Remove an event handler. Acts the same way as .removeEventListener from HTML.

Element Methods

Method	Parameter	Return	Description
closeLightbox	no	void	Used for programmatically closing the lightbox.

Handing Events

Using on(event, function) / off(event, function) methods

javascript

   const ePagCheckout = new EPagCheckout({...});
  function handler(event) {
    console.log(event.detail[0])
  };
  // to add a listener
  ePagCheckout.on('checkout-success', handler);
  // to remove a listener
  ePagCheckout.off('checkout-success', handler);

Using addEventListener(type, listener) / removeEventListener(type, listener) methods

javascript

  const ePagCheckout = document.querySelector('epag-checkout');
  function handler(event) {
    console.log(event.detail[0])
  };
  // to add a listener
  ePagCheckout.addEventListener('checkout-success', handler);
  // to remove a listener
  ePagCheckout.removeEventListener('checkout-success', handler);

Closing the lightbox

javascript

  ePagCheckout.closeLightbox()