Checkout

Overview

Descripción: A través de está opción podrás realizar la transacción de un pago que hayas generado desde nuestro generador de pagos todo por medio de conexión API, dándote la libertad de usar el diseño que tu tengas para tu aplicación, solo ten en cuenta que necesitaremos la siguiente información en el body de la petición en formato JSON:

Payment Parameters

Nombre del campo Descripción Reglas
payment Información de pago generado tipo api requerido
payment.id Id del pago generado requerido
payment.token Token generado requerido

Customer Parameters

Nombre del campo Descripción Reglas
customer_payer Información para el cliente requerido
customer_payer.name Nombre del usuario a realizar el pago requerido
customer_payer.address_1 Dirección principal del usuario requerido, string, min:5, max:100
customer_payer.address_2 Dirección secundaria del usuario requerido, string, min:1, max:100
customer_payer.city Ciudad del usuario requerido, string, min:1, max:100
customer_payer.state Estado/Región del usuario requerido, string, min:1, max:100
customer_payer.zip_code Código postal requerido, string, numérico
customer_payer.country País del usuario correspondiente al ISO3 requerido, countries iso3_code

Delivery Address Parameters

Si el pago generado se configuró con "advance_options" y existe request_address_delivery se requerirá la siguiente información, de lo contrario no necesita enviarse.

Nombre del campo Descripción Reglas
delivery_address Información de dirección de envió requerido
delivery_address.address Dirección del usuario Debe ser una cadena entre 5 y 100 caracteres. requerido, cadena entre 5 y 100
delivery_address.department_id Id de la lista de departamentos. requerido, id departamento valido
delivery_address.city_id Id del la lista de ciudades requerido, id ciudad valido
delivery_address.observations Es opcional, puede ser nulo. nullable

Checkout Tarjetas

Parametros Tarjeta

Adicional a los parámetros anteriores se deben agregar los siguientes:

Nombre del campo Descripción Reglas
payment_card Información para los datos de la tarjeta requerido
payment_card.token El token correspondiente a una tarjeta generado con el tokenizador Este campo no debe ir acompañado de otro dentro de paymet_card
payment_card.number Numero de la tarjeta crédito o débito del usuario requerido sin:payment_card.token, numérico, dígitos entre:14,16, ausente con:payment_card.token
payment_card.name Nombre que aparece en la tarjeta del usuario requerido sin:payment_card.token, solo letras ,ausente con:payment_card.token
payment_card.expiration_date Número de expiración de la tarjeta del usuario requerido sin:payment_card.token, date después o igual:yyyy-mm, formato:yyyy-mm, ausente con:payment_card.token
payment_card.cvv Numero de 3 o 4 dígitos de la parte de atrás de la tarjeta requerido sin:payment_card.token, integer, dígitos entre:3,4, ausente con:payment_card.token
payment_card.identification_type Identificación del usuario requerido
payment_card.id_number Número de identidad del usuario requerido, entre 5 y 20 dígitos
payment_card.installments Numero de cuotas requerido, integer, Entre 1 y 60
payment_card.dialling_code Código del país para teléfono requerido, Formato +123
payment_card.cellphone Numero de celular del usuario requerido, numérico, dígitos entre 5 y 15

Parametros Http Client

Adicional a los parámetros anteriores puedes agregar información sobre el cliente que esta haciendo la transacción: Nombre del campo Descripción Reglas
browser_information Objeto con la información del navegador del cliente opcional
browser_information.acceptLanguage Especifica las preferencias de lenguage del buscador del usuario "en-US" opcional
browser_information.ipAddress Dirección ip del cliente que hace la solicitud opcional
browser_information.sessionId identificador unico para la sesión del usuario opcional
browser_information.userAgent Información sobre el buscador y sistema operativo del usuario opcional

Ejemplo para tarjetas

Ejemplo de solicitud sin token:

curl -X POST \
"/api/v1/payment/transaction-checkout" \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H "Content-type: application/json" \
-d '{
    "payment": {
        "id": "9a6f8166-644e-4680-bc37-66535e591ea5",
        "token": "1rV9zc9DApoOw3a"
    },
    "customer_payer": {
        "name": "Efipay",
        "email": "efipay@gmail.com"
    },
    "payment_card": {
        "number": "5249314023340339",
        "name": "efipay",
        "expiration_date": "2025-05",
        "cvv": "478",
        "identification_type": "CC",
        "id_number": "342343243",
        "installments": "1",
        "dialling_code": "57",
        "cellphone": "3004564884"
    },
    "browser_information": {
        "acceptLanguage": "es-ES",
        "ipAddress": "190.150.0.1",
        "sessionId": "dfds54fds534sd534dsds",
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"
    }
}'

Ejemplo de solicitud con token:

curl -X POST\
'/api/v1/payment/transaction-checkout'\
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H "Content-type: application/json" \
-d '{
    "payment": {
        "id": "9abca90d-978d-4722-891f-b41b6ebbae1e",
        "token": "quSOdCbSljI31wT"
    },
    "customer_payer": {
        "name": "Efipay",
        "email": "email@email.com"
    },
    "payment_card": {
        "token": "eyJpdiI6IkdzaG44RFV5dE5GNlE2MWRSM2lBTGc9PSIsInZhbHVlIjoiZWxyRzkyYTE4THNtY2VseCs5VzlKbW5pa0NicCtiRWhGNWQ5ZTBwTGM1VXF0UXlEemtVWEJyY21ueVIwZ2U5cHNGS2FvdFg1SHVTcmtiQ0phQWNia1JsTUZtQjU3OFpCR0p3bVVlTy9OVVMwM3hJNnJOWGZTbitwL3dlVmtmRStRN2xBZ3paWHI4bDFS
                        N0lBVHhRa2hBPT0iLCJtYWMiOiJlNDY0NmM4YThhNWMzMDYyOGMxNDAxMjA5MmVlMjNjYjNiYWEyMjczNjA5ZGNkMzM0NmMxMzg0YjZhYjgyY2ZhIiwidGFnIjoiIn0=",
        "identification_type": "CC",
        "id_number": "342343243",
        "installments": "1",
        "dialling_code": "57",
        "cellphone": "3004564884"
    }
}'

Flujo 3Ds

Flujo 3Ds

Para implementar el flujo de 3Ds mediante api se requiere que el comercio realize el desarrollo del flujo para estos casos. Como aclaración se debe tener en cuenta que se tienen dos implementaciones diferentes según la franquicia que de la tarjeta, a continuación se explicaran con detalle ambos casos.

Para habilitar 3Ds en transacciones con Visa y Mastercard adicionar el atributo enable_3ds el cual sera obligatorio a partir del dd/mm/aaaa adicionalmente se debe adicionar información del cliente del navegador browser_information Ver flujo 3Ds

Nombre del campo Descripción Reglas
enable_3ds Habilita el flujo de 3Ds por api Opcional,boolean
browser_information Objeto con la información del navegador requerido si enable 3ds esta presente y tiene true como valor
browser_information.colorDepth colorDepth del navegador requerido
browser_information.language language del navegador requerido
browser_information.screenHeight screenHeight del navegador requerido
browser_information.screenWidth screenWidth del navegador requerido
browser_information.timeDifference timeDifference del navegador requerido
browser_information.javaScriptEnabled javaScriptEnabled del navegador requerido
browser_information.javaEnabled javaEnabled del navegador requerido

Par obtener la información del navegador puedes usar esta función para javascript

function getBrowserInformation() {
    // Get color depth
    const colorDepth = window.screen.colorDepth;
    // Check if JavaScript is enabled (if this runs, JavaScript is enabled)
    const jsEnabled = true;
    let javaEnabled = false;
    try {
        javaEnabled = navigator.javaEnabled();
    } catch (error) {
        const javaEnabled = false;
    }
    // Get browser language
    const language = navigator.language || navigator.userLanguage;
    // Get screen height and width
    const screenHeight = window.innerHeight;
    const screenWidth = window.innerWidth;
    // Calculate time difference from UTC (in hours)
    const timeDifference = new Date().getTimezoneOffset();

    return {
        colorDepth,
        language,
        screenHeight,
        screenWidth,
        timeDifference,
        javaScriptEnabled: jsEnabled,
        javaEnabled,
    }
}

Ejemplo compra con 3Ds habilitado

curl -X POST\
'{{ URL::to('/api/v1/payment/transaction-checkout') }}'\
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H "Content-type: application/json" \
-d '{
    "payment": {
        "id": "9a6f8166-644e-4680-bc37-66535e591ea5",
        "token": "1rV9zc9DApoOw3a"
    },
    "customer_payer": {
        "name": "Efipay",
        "email": "efipay@gmail.com"
    },
    "payment_card": {
        "number": "5249314023340339",
        "name": "efipay",
        "expiration_date": "2025-05",
        "cvv": "478",
        "identification_type": "CC",
        "id_number": "342343243",
        "installments": "1",
        "dialling_code": "57",
        "cellphone": "3004564884"
    },
    "browser_information": {
        "colorDepth": "24",
        "language": "es-ES",
        "screenHeight": 726,
        "screenWidth": 2133,
        "timeDifference": 300,
        "javaScriptEnabled": true,
        "javaEnabled": false
    },
    "enable_3ds": true
}'

Flujo Visa "CredibanCo"

1. Inicio autenticación 3Ds

Al iniciar la trx se responderá con un objeto con información para continuar con el flujo de 3ds, el cual tendrá el nombre de la implementación, un código html para agregar en el navegador del cliente y una url para validar el éxito de la operación, en caso de que el objeto 3Ds no sea devuelto se devolverá el objeto con la transacción con su información del estado de la misma.

Ejemplo respuesta 3Ds para continuar con la autenticación.

{
    "save": true,
    "transaction": {
        "transaction_id": 1,
        "amount": 100000,
        "currency_type": "COP",
        "value_cop": 100000,
        "payment_method": "credit",
        "payment_method_source": "Credibanco",
        "trazability_id": null,
        "authorization_code": null,
        "transaction_details": {
            "name": "Efipay",
            "identification_type": "CC",
            "identification_number": "123456789",
            "email": "efipay@efipay.com",
            "country": "+57",
            "phone": "3001234567",
            "number_card": "123456******1234",
            "installments": "1",
            "franchise": "Credibanco",
            "status_message": "Transacción en proceso: Recolectando Data"
        },
        "status": "Pendiente",
        "url_response": "https://sag.efipay.co/Checkout/Transaction/9e84d84b-e1e6-4a6a-a0eb-53becc71c359/Response",
        "approved_at": null,
        "production": true,
        "created_at": "2025-03-25 15:20:17",
        "customer_payer": {
            "name": "Efipay",
            "email": "efipay@efipay.com",
            "country": "COL",
            "zip_code": "0000",
            "state": "Bogota",
            "city": "Bogota",
            "address_2": "Cr 23",
            "address_1": "Apto 1A",
            "created_at": "2024-11-07 18:39:40",
            "updated_at": "2024-11-07 18:39:40"
        },
        "currency_rate_conversion": {
            "id": 1,
            "usd_to_cop": 4288.58,
            "eur_to_cop": 4640.617049,
            "trm_for_cop": 1,
            "active": 1,
            "created_at": "2024-10-21T16:20:23.000000Z",
            "updated_at": "2024-10-21T16:20:23.000000Z",
            "deleted_at": null
        },
        "description": "Transacción en proceso: Recolectando Data"
    },
    "3Ds": {
        "implementation" : "credibanco",
        "browser_response" : "<div>...</div>",
        "centinelapistag" : "https://centinelapistag..."
    },
}

Recibida esta respuesta con la transacción pendiente y el objeto de 3Ds puedes tomar el siguiente ejemplo para implementar en tu navegador.

const setup3DsIframe = (browserResponse, centinelapistag) => {
    const wrappedElement = document.getElementById("hidden3ds");
    wrappedElement.innerHTML = iframe;

    const ddcForm = document.querySelector('#ddc-form');
    if (ddcForm) {
        console.log('ddcForm', ddcForm);
        ddcForm.submit();
    }
    let eventMessage3ds = false;
    const threeDsTimeOut = setTimeout(() => {
        if (!eventMessage3ds) {
            //rechazar transacción
            console.log('Error red demasiado tiempo esperando mensaje 3ds');
        }
    }, 50000);

    window.addEventListener("message", (event) => {
        eventMessage3ds = true;
        clearTimeout(threeDsTimeOut)
        if (event.origin === centinelapistag) {
            let data = JSON.parse(event.data);
            console.log('Merchant received a message:', data);
            if (data !== undefined && data.Status) {
                console.log('Songbird ran DF successfully');
                enrollTransaction(); // Continuar con -> 2. Consumir el enroll 3Ds
            } else {
                //rechazar transacción
                console.log('Error evento de mensaje front status 3ds');
            }
        }
    }, false);
}

2. Consumir el enroll 3Ds

Cuando se obtenga la repuesta satisfactoria del evento se puede continuar con el consumo del enroll, aquí se pueden presentar dos casos, el primero en donde 3Ds determine la autenticación exitosa y se pueda procesar la transacción sin mas pasos, la segunda donde 3Ds determine hacer una validación adicional con un challenge para autenticar al tarjetahabiente

Para el primer caso se devolverá la transacción con su estado correspondiente a como es costumbre.

Para el caso donde se solicite el challenge se responderá con un nuevo objeto 3Ds así:

Recuerde que este flujo puede presentarse un challenge del banco que redirige al cliente a una nueva ventana para que el cliente pase el challenge por lo que si desea volver a ser redirigido automáticamente a una pagina de tu integración deberás configurar las opciones avanzadas con result_urls, adicional puede usar el webhook para obtener la respuesta en paralelo a su integración.

Request Endpoint: /api/v1/payment/3ds/enroll/{transaction_id}

{
    "payment_card": {
        "number": "4000000000001091",
        "name": "Efipay",
        "expiration_date": "2025-12",
        "cvv": "123"
    },
    "browser_information": {
        "colorDepth": "24",
        "language": "es-ES",
        "screenHeight": 726,
        "screenWidth": 2133,
        "timeDifference": 300,
        "javaScriptEnabled": true
    }

}

Response

"transaction" : {...},
"3Ds" : {
    "implementation": "credibanco",
    "browser_response" : "<div>...</div>"
    },

Ejemplo cliente

const setup3dsChallenge = browserResponse => {
    const wrappedElement = document.getElementById("challenge3ds");
    wrappedElement.innerHTML = iframe;

    var stepUpForm = document.querySelector('#step-up-form');
    if (stepUpForm) {
        stepUpForm.submit();
    }
}

Tarjetas de prueba

  1. 4000000000001018
  2. 4000000000001059
  3. 4000000000001091

Flujo MasterCard "Redeban"

1. Inicio autenticación 3Ds

l iniciar la trx se responderá con un objeto con información para continuar con el flujo de 3ds, el cual tendrá el nombre de la implementación, un código html para agregar en el navegador del cliente, en caso de que el objeto 3Ds no sea devuelto se devolverá el objeto con la transacción con su información del estado de la misma.

Ejemplo respuesta 3Ds para continuar con la autenticación.

{
    "save": true,
    "transaction": {
        "transaction_id": 1,
        "amount": 100000,
        "currency_type": "COP",
        "value_cop": 100000,
        "payment_method": "credit",
        "payment_method_source": "Credibanco",
        "trazability_id": null,
        "authorization_code": null,
        "transaction_details": {
            "name": "Efipay",
            "identification_type": "CC",
            "identification_number": "123456789",
            "email": "efipay@efipay.com",
            "country": "+57",
            "phone": "3001234567",
            "number_card": "123456******1234",
            "installments": "1",
            "franchise": "Credibanco",
            "status_message": "Transacción en proceso: Recolectando Data"
        },
        "status": "Pendiente",
        "url_response": "https://sag.efipay.co/Checkout/Transaction/9e84d84b-e1e6-4a6a-a0eb-53becc71c359/Response",
        "approved_at": null,
        "production": true,
        "created_at": "2025-03-25 15:20:17",
        "customer_payer": {
            "name": "Efipay",
            "email": "efipay@efipay.com",
            "country": "COL",
            "zip_code": "0000",
            "state": "Bogota",
            "city": "Bogota",
            "address_2": "Cr 23",
            "address_1": "Apto 1A",
            "created_at": "2024-11-07 18:39:40",
            "updated_at": "2024-11-07 18:39:40"
        },
        "currency_rate_conversion": {
            "id": 1,
            "usd_to_cop": 4288.58,
            "eur_to_cop": 4640.617049,
            "trm_for_cop": 1,
            "active": 1,
            "created_at": "2024-10-21T16:20:23.000000Z",
            "updated_at": "2024-10-21T16:20:23.000000Z",
            "deleted_at": null
        },
        "description": "Transacción en proceso: Recolectando Data"
    },
    "3Ds": {
        "implementation" : "redeban",
        "browser_response" : "<div>...</div>",
    },
}

Recibida esta respuesta con la transacción pendiente y el objeto de 3Ds puedes tomar el siguiente ejemplo para implementar en tu navegador.

const setup3DsIframe = iframe => {
    const wrappedElement = document.getElementById("hidden3ds");
    wrappedElement.innerHTML = iframe;
    Array.from(wrappedElement.querySelectorAll("script"))
        .forEach( oldScriptEl => {
        const newScriptEl = document.createElement("script");

        Array.from(oldScriptEl.attributes).forEach( attr => {
            newScriptEl.setAttribute(attr.name, attr.value)
        });

        const scriptText = document.createTextNode(oldScriptEl.innerHTML);
        newScriptEl.appendChild(scriptText);

        oldScriptEl.parentNode.replaceChild(newScriptEl, oldScriptEl);
    });
    setTimeout(() => {
            console.log("run timeout 5sec");
            authContinueTransaction();// Continuar con -> 2. Consumir el auth continue 3Ds
    }, 5000);
}

2. Consumir el auth continue 3Ds

Cuando se obtenga la repuesta satisfactoria del evento se puede continuar con el consumo del enroll, aquí se pueden presentar dos casos, el primero en donde 3Ds determine la autenticación exitosa y se pueda procesar la transacción sin mas pasos, la segunda donde 3Ds determine hacer una validación adicional con un challenge para autenticar al tarjetahabiente

Para el primer caso se devolverá la transacción con su estado correspondiente a como es costumbre.

Para el caso donde se solicite el challenge se responderá con un nuevo objeto 3Ds así:

Request Endpoint: /api/v1/payment/3ds/auth-continue/{transaction_id}

{
    "payment_card": {
        "number": "4000000000001091",
        "name": "Efipay",
        "expiration_date": "2025-12",
        "cvv": "123"
    },
    "browser_information": {
        "colorDepth": "24",
        "language": "es-ES",
        "screenHeight": 726,
        "screenWidth": 2133,
        "timeDifference": 300,
        "javaScriptEnabled": true
    }

}

Response

"transaction" : {...},
"3Ds" : {
    "implementation": "redeban",
    "browser_response" : "<div>...</div>"
    },

Ejemplo cliente

const setup3dsChallenge = browserResponse => {
    const wrappedElement = document.getElementById("challenge3ds");
    wrappedElement.innerHTML = iframe;

    Array.from(wrappedElement.querySelectorAll("script"))
        .forEach( oldScriptEl => {
        const newScriptEl = document.createElement("script");

        Array.from(oldScriptEl.attributes).forEach( attr => {
            newScriptEl.setAttribute(attr.name, attr.value)
        });

        const scriptText = document.createTextNode(oldScriptEl.innerHTML);
        newScriptEl.appendChild(scriptText);

        oldScriptEl.parentNode.replaceChild(newScriptEl, oldScriptEl);
    });
}

Checkout PSE

Parametros pse

Cuando realizes la petición recibirás una url a la cual deberás redireccionar al usuario para que pueda realizar el pago, cuando el usuario realize el pago en su banco y regrese al comercio sera redireccionado a uno de las siguientes opciones; a la url si agregaste el custom_redirect_url en este checkout si no al checkout de respuesta de efipay.

La validación del pago lo podrás hacer a través de nuestro webhook o consultando el status al ser redireccionado a una de tus url personalizadas de redirección.

Consulta la lista de bancos disponibles aquí. Consulta la lista de datos del formulario para pse aquí.

Adicional a los parámetros anteriores se deben agregar los siguientes:

Nombre del campo Descripción Reglas
pse Objeto requerido. requerido
pse.financialInstitutionCode Código numérico de la lista de bancos
pse.userType Hace referencia al tipo de usuario de la lista con las opciones disponibles. requerido
pse.identificationType Hace referencia al tipo de usuario de la lista con las opciones disponibles. requerido
pse.identificationNumber Numero de identificación del usuario a pagar requerido, dígitos entre 5 y 15
pse.fullName Nombre del usuario a pagar requerido
pse.cellphoneNumber Celular del usuario a pagar requerido
pse.address Dirección del usuario a pagar requerido
pse.email Email del usuario a pagar requerido, email
pse.redirect Url para redirigir al usuario después del pago opcional, url valida

Ejemplo para pse

curl -X POST\
"/api/v1/payment/transaction-checkout/pse"\
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H "Content-type: application/json" \
-d '{
    "payment": {
        "id": "generated_payment_id", //9a6f8166-644e-4680-bc37-66535e591ea5
        "token": "token_payment" //1rV9zc9DApoOw3a
    },
    "customer_payer": {
        "name": "Pepito perez",
        "email": "pepito@email.com"
    },
    "pse": {
        "financialInstitutionCode": "0000",
        "userType": "person",
        "identificationType": "CedulaDeCiudadania",
        "identificationNumber": "123456789",
        "fullName": "Pepito Perez",
        "cellphoneNumber": "3123456789",
        "address": "calle 93 # 32",
        "email": "pepito@email.com",
        "redirect": "https://efipay.co/"
    }
}'

Checkout Efectivos

Parametros Efectivos

Ten presente que al usar este checkout para pagos en efectivos al realizar la petición todas las transacciones darán como respuesta el estado por pagar, y la información del cupón para que tu usuario realize el pago en la sucursal de efectivo correspondiente.

Para poder validar el pago de este tipo de transacciones te ofrecemos dos opciones; la primera y más sencilla usar nuestro webhook para notificarte la nueva información sobre las transacciones y la segunda es que realizes una consulta del estado del pago después del tiempo de expiración que también te proporcionamos en la respuesta.

Podrás consultar la lista de efectivos disponibles para ti aquí

Adicional a los parámetros anteriores se deben agregar los siguientes:

Nombre del campo Descripción Reglas
cash Objeto requerido requerido

| cash.franchise | Hace referencia al nombre de la sucursal del efectivo.| requerido| | cash.cellphone_number | Requerido.| requerido, Máximo 10 dígitos| | payment_card.identification_number | Numero de identificación de la persona a pagar | requerido, numérico, dígitos entre 5 y 15 |

Ejemplo para efectivos

curl -X POST\
"/api/v1/payment/transaction-checkout/cash"\
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H "Content-type: application/json" \
-d '{
    'payment': {
        'id': 'generated_payment_id', //9a6f8166-644e-4680-bc37-66535e591ea5
        'token': 'token_payment' //1rV9zc9DApoOw3a
    },
    'customer_payer': {
        'name': 'Pepito peres',
        'email': 'pepito@gmail.com'
    },
    "cash" : {
        "franchise": "Efecty",
        "cellphone_number": "3123456789",
        "identification_number": "123456789"
    }
}'