3DS SDK

In order to integrate 3DS 2.0 payments in your checkout.

Prerequisite

Host the 3DS SDK available here.
Have valid contract ID.
Have notification URL for payment status change callbacks.

How to implement

To import the 3DS SDK, place the script in the head, or in the body section of your HTML page.

html
{
<script src="https://3ds.epag.io/scripts/client-v1.0.min.js"></script>
}

Configure the SDK. Call the setUp method, and inform the environment and the contractId.

JavaScript
{
EPag.setUp({
    env: 'PROD',
    contractId: 'MY_CONTRACT_ID',
});
}

Create the request object.

JavaScript
{
const request = {
    "notificationUrl": "https://mynotificationurl.com",
    "referenceId": "MY_REFERENCE",
    "disableAddress": false,
    "customer": {
        "id": "39784045087",
        "name": "Alice Sonnentag",
        "email": "[email protected]",
        "phones": [
            {
                "country": "55",
                "area": "11",
                "number": "912345678",
                "type": "MOBILE"
            }
        ]
    },
    "paymentMethod": {
        "type": "CREDIT_CARD", // or DEBIT_CARD
        "installments": "1",
        "card": {
            "number": "4000000000002503",
            "expMonth": "12",
            "expYear": "2028",
            "cvv": "123",
            "holder": {
                "name": "Alice Sonnentag"
            }
        }
    },
    "amount": {
        "value": 2503, // cents
        "currency": "BRL"
    },
    "billingAddress": {
        "partialAddress": false,
        "street": "Rua Araguari",
        "number": "817",
        "complement": "Conj. 74",
        "regionCode": "SP",
        "country": "BRA",
        "city": "São Paulo",
        "postalCode": "04514041"
    },
    "shippingAddress": {
        "partialAddress": false,
        "street": "Rua Araguari",
        "number": "817",
        "complement": "Conj. 74",
        "regionCode": "SP",
        "country": "BRA",
        "city": "São Paulo",
        "postalCode": "04514041"
    }
}
}

notificationUrl (required/string): Url to notify when the payment status changes.
referenceId (required/string): External code created by merchant to reference the payment.
disableAddress (optional/boolean): If true disables the person's address. billingAddress and shippingAddress is no longer required and can be omitted. Default: false.
customer (required/object): Object containing the person's data.
- id (required/string): Unique identifier for this person in country tax system (e.g. in Brazil: CPF).
- name (required/string): Person’s full name.
- email (required/string): Person’s email provided to the merchant.
- phones (required/array): Person's telephone list provided to the merchant.
  - country (required/integer): Person's telephone country code. Default: 55.
  - area (required/integer): Person's telephone area code. Must be two digits.
  - number (required/integer): Person's telephone number. Must be between 8 and 9 digits.
  - type (required/string): Person's telephone type. Valid option: MOBILE.
paymentMethod (required/object): Object containing the payment method data.
- type (required/string): Payment Method. Valid option: CREDIT_CARD, DEBIT_CARD.
- installments (optional/integer): Number of installments. Must be between 1 and 12. Default: 1.
- card (required/object): Object containing the card's data.
  - number (required/string): Credit Card number (only numbers).
  - expMonth (required/string): Expiration month of the card.
  - expYear (required/string): Expiration year of the card (with century, e.g. 2028).
  - cvv (required/string): Security code of the card.
  - holder (required/object): Object containing the card holder's data.
    - name (required/string): Name of credit card owner as printed on the credit card.
amount (required/object): Object containing the amount of the payment.
- value (required/number): Total amount of the payment (in cents).
- currency (required/string): Asset used in this amount. Valid option: BRL.
billingAddress (required/object): Object containing the card's billing address data. Can be omitted if disableAddress is true.
- partialAddress (optional/boolean): If true, billingAddress requires only postalCode and number.
- street (required/string): Main information of the address (e.g. street or avenue). Optional if partialAddress is true.
- number (required/string): Number for this address.
- complement (optional/string): Additional information for this address (e.g. department).
- regionCode (required/string): Address state code. Optional if partialAddress is true.
- country (optional/string): Country code as ISO 3166-1 alpha-3 code. Optional if partialAddress is true. Default: BRA.
- city (required/string): Address city. Optional if partialAddress is true.
- postalCode (required/string): Address zip code (8 digits).
- shippingAddress (optional/object): Object containing the person's shipping address data. Can be omitted if disableAddress is true.
- partialAddress (optional/boolean): If true, billingAddress requires only postalCode and number.
- street (required/string): Main information of the address (e.g. street or avenue). Optional if partialAddress is true.
- number (required/string): Number for this address.
- complement (optional/string): Additional information for this address (e.g. department).
- regionCode (required/string): Address state code. Optional if partialAddress is true.
- country (optional/string): Country code as ISO 3166-1 alpha-3 code. Optional if partialAddress is true. Default: BRA.
- city (required/string): Address city. Optional if partialAddress is true.
- postalCode (required/string): Address zip code (8 digits).
shippingAddress (optional/object): Object containing the person's shipping address data. Can be omitted if disableAddress is true.
- partialAddress (optional/boolean): If true, billingAddress requires only postalCode and number.
- street (required/string): Main information of the address (e.g. street or avenue). Optional if partialAddress is true.
- number (required/string): Number for this address.
- complement (optional/string): Additional information for this address (e.g. department).
- regionCode (required/string): Address state code. Optional if partialAddress is true.
- country (optional/string): Country code as ISO 3166-1 alpha-3 code. Optional if partialAddress is true. Default: BRA.
- city (required/string): Address city. Optional if partialAddress is true.
- postalCode (required/string): Address zip code (8 digits).

Call the authenticate3DS method, pass the request as parameter and handle the callback events.

json
{
await EPag.authenticate3DS(request, {
    onSuccess: (e) => {
        const id = e.id;
        const paymentToken = e.paymentToken;
    },
    onUnenrolled: () => {
    },
    onFailure: () => {
    },
    onError: (e) => {
    },
});
}

note

The authenticate3DS method returns a Promise, so use await or then.

Event	Description
onSuccess	Card allows authentication and customer was successfully authenticated. id: The 3DS authentication id. Use it to process payment. paymentToken: Token to identify the payment.
onUnenrolled	Card allows authentication, however, customer authentication did not succeed.
onFailure	Card does not allow authentication.
onError	Error during authentication process.

Use the received 3DS id and paymentToken on Process Internal 3DS Payment endpoint to process the payment.

Prerequisite​

How to implement​

Prerequisite

How to implement