NAV
shell python php

Introducción

El API Shieldgate by Afirme es un API REST. Nuestra API tiene URLs predecibles, orientados a recursos y utiliza códigos de respuesta de HTTP para indicar el estado de la respuesta. Un objeto JSON es devuelto en todas las respuestas del API, incluidos los errores, aunque nuestra API convierte la respuesta en objetos apropiados.

Nunca debe exponer las credenciales de tipo Server en código público de cara al cliente, por ejemplo una website.

Para iniciar con la integración, usted deberá solicitar al equipo Shieldgate by Afirme integraciones@shieldgate.mx una cuenta de Desarrollo / Sandbox. Por favor envíenos su correo electrónico para identificarlo como desarrollador y el nombre de su empresa.

Crearemos una Application y le daremos el código de la aplicación. A partir de ahora, este será el identificador de su aplicación en toda la integración. También le damos una cuenta de desarrollador basada en el correo electrónico que nos proporcionó. Le enviaremos la contraseña por correo electrónico para acceder a su cuenta de desarrollador. Podrá acceder a esta configuración aquí:

Ambiente URL
development https://dashboard-stg.shieldgate.mx
production https://dashboard.shieldgate.mx

Usted puede cambiar su password si lo olvida, utilizando la opción forgot password para recuperarla. En el sistema de administración de Shieldgate by Afirme usted podrá ver todas sus transacciones, cambiarle la configuración de su aplicación (incluyendo los URLs de la aplicación, la llave de la aplicación) y muchas más acciones.

Las configuraciones deben de hacerse para las aplicaciones tanto en ambiente de desarrollo como en producción, los URLs y llaves de la aplicación son distintos para cada ambiente. El ambiente de desarrollo estará siempre disponible para pruebas, incluso una vez lanzada su aplicación en producción.

Ambientes

Para usar nuestra API, usted necesita utilizar alguna de las siguientes URLs base, dependiendo del ambiente:

Método de pago con Tarjeta

Ambiente URL
development https://ccapi-stg.shieldgate.mx
production https://ccapi.shieldgate.mx
Ambiente URL
development https://noccapi-stg.shieldgate.mx
production https://noccapi.shieldgate.mx

Autenticación

Para construir el auth_token, puede utilizar el siguiente código:

#!/usr/bin/env python
import time
import hashlib
from base64 import b64encode
print '#########################################################'
print '####### AUTH TOKEN TEST'
print '#########################################################'
server_application_code = ''
server_app_key = ''
unix_timestamp = str(int(time.time()))
print 'UNIX TIMESTAMP: %s' % unix_timestamp
uniq_token_string = server_app_key + unix_timestamp
print 'UNIQ STRING: %s' % uniq_token_string
uniq_token_hash = hashlib.sha256(uniq_token_string).hexdigest()
print 'UNIQ HASH: %s' % uniq_token_hash
auth_token = b64encode('%s;%s;%s' % (server_application_code,
unix_timestamp, uniq_token_hash))
print 'AUTH TOKEN: %s' % auth_token


import time
import hashlib
from base64 import b64encode
print '#########################################################'
print '####### AUTH TOKEN TEST'
print '#########################################################'
server_application_code = ''
server_app_key = ''
unix_timestamp = str(int(time.time()))
print 'UNIX TIMESTAMP: %s' % unix_timestamp
uniq_token_string = server_app_key + unix_timestamp
print 'UNIQ STRING: %s' % uniq_token_string
uniq_token_hash = hashlib.sha256(uniq_token_string).hexdigest()
print 'UNIQ HASH: %s' % uniq_token_hash
auth_token = b64encode('%s;%s;%s' % (server_application_code,
unix_timestamp, uniq_token_hash))
print 'AUTH TOKEN: %s' % auth_token

<?php
const API_LOGIN_DEV     = "Application Code Server";
const API_KEY_DEV       = "Application Key Server";

$server_application_code = API_LOGIN_DEV;
$server_app_key = API_KEY_DEV ;
$date = new DateTime();
$unix_timestamp = $date->getTimestamp();
// $unix_timestamp = "1546543146";
$uniq_token_string = $server_app_key.$unix_timestamp;
$uniq_token_hash = hash('sha256', $uniq_token_string);
$auth_token = base64_encode($server_application_code.";".$unix_timestamp.";".$uniq_token_hash);
echo "TIMESTAMP: $unix_timestamp";
echo "\nUNIQTOKENST: $uniq_token_string";
echo "\nUNIQTOHAS: $uniq_token_hash";
echo "\nAUTHTOKEN: $auth_token";
?>

Todos los request deben contener en el encabezado Auth-Token:. Esta es una cadena codificada en base64, la cadena debe crearse de la siguiente manera (considere el ; entre cada una):

APPLICATION-CODE;UNIXTIMESTAMP;UNIQ-TOKEN

Elemento Descripción
APPLICATION-CODE Solicitalo al equipo de Shieldgate by Afirme
UNIXTIMESTAMP Este debe ser creada al mismo tiempo que el request, tenga en cuenta que la hora es UTC y en SEGUNDOS, tendrá 15 segundos antes de que necesite crear una nueva, o su request será rechazado (error.type: Invalid timestamp).
UNIQ-TOKEN Es la representación hexa de un hash sha256 que se genera a partir de la cadena “secret-key“ + “timestamp“, el secret-key la proporciona el equipo de Shieldgate by Afirme

Una vez que tenga el UNIQ-TOKEN, debe aplicar el sha256 y la conversión hexa, puede usar el siguiente ejemplo de Python, solo agregue sus server_application_code y server_app_key:

Métodos de Pago

Efectivo

A través de esta plataforma es posible generar una referencia de pago en efectivo.

Generar una referencia

curl -k  -L -X POST -H 'Content-Type: application/json'
-H 'Auth-Token: auth_token' -d '{
    "carrier":{
        "id": "payvalida"
    },
    "user": {
        "id": "sadfasdf",
        "email": "user@example.com"
    },
    "order": {
        "country": "COL",
        "currency": "COP",
        "dev_reference": "prueba_stg_2",
        "amount": 50001,
        "expiration_days": 5,
        "recurrent": false,
        "description": "Esto es una prueba desde rest client"
    }
}' 'https://noccapi-stg.shieldgate.mx/order/'

Para el request previo, la respuesta es un JSON estructurado como sigue:

{
    "application": {
        "code": "AbiColApp"
    },
    "commerce": {
        "merchant_id": "example"
    },
    "user": {
        "email": "user@example.com",
        "id": "sadfasdf"
    },
    "transaction": {
        "currency": "COP",
        "country": "COL",
        "dev_reference": "prueba_stg_2",
        "amount": 50001.0,
        "expiration_date": "2018-07-01",
        "recurrent": false,
        "description": "Esto es una prueba desde rest client",
        "reference": "69193",
        "agreement": {
          "baloto": 95715,
          "efecty": 110342,
          "dimonex": 110342,
          "puntored": 113042,
          "redservi": 761
        },
        "status": "pending",
        "id": "PV-0000000000021"
    }
}

Genera una referencia para realizar la transacción de efectivo, a través de un procesador de pagos.

POST https://noccapi-stg.shieldgate.mx/order/

Parámetro Tipo Requerido Descripción
carrier.id String Yes Indica el método por el cuál la referencia será creada. Revisa la lista de procesadores
carrier.extra_params.user.name String Yes (*) Nombre del usuario.
carrier.extra_params.user.last_name String Yes (*) Apellido del usuario.
carrier.extra_params.user.phone String Yes (*) Teléfono de usuario
carrier.extra_params.user.fiscal_number String Yes (*) El Número Fiscal (número de identificación) dado por el usuario.
carrier.extra_params.user.address Json Yes (*) Objecto con la dirección del usuario, Vea la especificación para Address.
user.id String Yes Identificador del comprador/usuario.
user.email String Yes Correo electrónico del comprador, un e-mail con formato válido.
order.dev_reference String Yes Referencia del comercio para identificar la orden.
order.amount Number Yes Monto total a pagar. Formato: Decimal con dos dígitos de fracciones.
order.expiration_days Number No Número de días en que vence la referencia de pago. Predeterminado 2.
order.recurrent Boolean No Indicar si el pago es recurrente o no.
order.description String Yes Descripción de la orden.
order.hours Number No Opcional. Si hay valor, la referencia durará horas.
order.country String Optional País donde se realizará el pago. Por defecto se usará la configuración de las credenciales.
order.currency String Optional Moneda que se usará para el pago. Por defecto se usará la configuración de las credenciales.

Parámetro Descripción
application.code Identificador de la aplicación.
commerce.merchant_id Identificador del comercio.
user.email Correo electrónico registrado en la orden, del comprador.
user.id Identificador del comprador.
transaction.currency Moneda de transacción.
transaction.country País donde se realizó la transacción.
transaction.dev_reference Referencia del comercio para identificar la orden.
transaction.amount Cantidad total a pagar.
transaction.expiration Fecha límite para pagar la referencia.
transaction.recurrent Muestra si la transacción será recurrente
transaction.reference Referencia para realizar el pago en una tienda
transaction.agreement Objeto Json con todos los convenios para pagar (Para payvalida).
transaction.status Estado del pago (pendiente, aprobado, cancelada).
transaction.id Id generado por Shieldgate by Afirme
transaction.url_reference Detalle imprimible de la transaction.reference

Procesadores

Procesador Campos en la respuesta necesarios para pagar
oxxo transaction.reference que debe de ser convertido en un código de barras.
bradesco transaction.url_reference, permite descargar el formato imprimible

Campos necesarios para cada procesador de pagos en Efectivo

Procesador Campos necesarios en extra_params
oxxo user.name, user.last_name
bradesco user.name, user.last_name, user.fiscal_number, user.address
Dirección

En caso de enviar la dirección del usuario, debe ser en el siguiente formato:

Ejemplo con dirección del usuario:

curl -k  -L -X POST -H 'Content-Type: application/json'
-H 'Auth-Token: auth_token' -d '{
     "carrier":{
         "id": "bradesco",
          "extra_params":{
            "extra_amount": 0,
            "user":{
                "name": "Pay",
                "last_name": "Mentez",
                "fiscal_number": "68753238850",
                "address": {
                    "state": "SP",
                    "city": "Sao Paulo",
                    "zip_code": "01418000",
                    "street": "Alameda Santos",
                    "house_number": "200",
                    "district": "Cerqueira",
                    "additional_address_info": "additional test"
                }
            }
          }
     },
     "user": {
         "email": "lcruz@email.com",
         "id": 1
     },
     "order": {
        "dev_reference": "prueba_stg_2",
        "amount": 10,
        "expiration_days": 2,
        "currency":"BRL",
        "description": "Esto es una prueba desde rest client"
     }
}' 'https://noccapi-stg.shieldgate.mx/order/'
Parámetro Tipo Requerido Descripción
state String No Estado en formato ISO 3166-2 code
city String No Nombre de la ciudad, maximo 30 caracteres
zip_code String No Codigo postal
street String No Nombre de la calle.
house_number String No Número de casa
district String No El distrito
additional_address_info String No Información adicional, complemento

Tarjetas

En esta plataforma podemos almacenar de forma segura los datos confidenciales de la tarjeta de crédito o débito.

Estos datos se transforman en un código encriptado llamado token, que se puede almacenar en una base de datos. Con esta plataforma, la tienda podrá ofrecer funciones como "comprar con un click" y "reintentar la transacción", preservando siempre la integridad y la confidencialidad de la información.

Agregar una Tarjeta

curl -k  -L -X POST -H 'Content-Type: application/json' -H 'Auth-Token: auth_token' -d '{
    "user": {
        "id": "4",
        "email": "test@example.com"
    },
    "card": {
        "number": "5119159076977991",
        "holder_name": "citlali calderon",
        "expiry_month": 9,
        "expiry_year": 2020,
        "cvc": "123",
        "type": "vi"
    }
}' 'https://ccapi-stg.shieldgate.mx/v2/card/add'

Para el request previo, la respuesta es un JSON estructurado como sigue:

{
    "card": {
        "bin": "511915",
        "status": "review",
        "token": "17121538682542236138",
        "message": "",
        "expiry_year": "2020",
        "expiry_month": "9",
        "transaction_reference": "CI-488",
        "type": "vi",
        "number": "7991",
        "origin": "ORIGIN"
    }
}

Este endpoint agrega una tarjeta a la plataforma, relacionandola con un usuario.

HTTP Request

POST https://ccapi-stg.shieldgate.mx/v2/card/add

Parámetros URL
Parámetro Tipo Requerido Descripción
session_id String No Parámetro utilizado para el anti fraude. Hash numérico de longitud 32.
user.id String Yes Identificador del cliente. Este es el identificador que usa dentro de su aplicación.
user.email String Yes Correo electrónico del comprador, con formato de correo electrónico válido.
user.phone String No Teléfono del comprador.
user.ip_address String No Dirección IP del usuario. IP v4 válida.
user.fiscal_number String No El número fiscal dado por el comprador. Nota: Para los tipos de tarjeta ex, ak, vr, sx, ol, ep y cd este campo es obligatorio.
card.number String Yes Un número de tarjeta de crédito válido.
card.holder_name String Yes El nombre del titular de la tarjeta de crédito.
card.expiry_month Number Yes El mes de expiración de la tarjeta de crédito.
card.expiry_year Number Yes El año de caducidad de la tarjeta de crédito.
card.cvc String Yes El número de seguridad de la tarjeta de crédito.
card.type String No Tipo de tarjeta abreviado. Revise las opciones válidas
card.account_type String No Los valores correspondientes para las cuentas de tipo: Crédito, Corriente y Ahorros son: C, R y A respectivamente. Campo Obligatorio para QR Colombia.
extra_params Json No Parámetros opcionales (objetos 3DS 2 incluídos) utilizados para algunos comercios en formato Json. Por favor, póngase en contacto con su ejecutivo comercial para más detalles.
billing_address Json No Objeto con la dirección de facturación de la tarjeta, vea las especificaciones para la dirección.
Respuesta
Parámetro Descripción
card.bin El BIN de la tarjeta (primeros seis dígitos de la tarjeta).
card.status Cualquiera de los siguientes estados: valid, review, pending y rejected. Si la respuesta es "review" o "pending", el usuario debe verificar la transacción asociada al intento de agregar una tarjeta (transaction_reference) para configurar esta tarjeta como válida.
card.token Nuevo identificador de tarjeta. Este código es único entre todas las tarjetas, solo se devuelve si el estado es valid o review, "" de lo contrario.
card.message Si hubiera alguno, sería el mensaje del procesador, por ejemplo, en caso de ser rechazado por el proveedor.
card.expiry_year El año en que expira la tarjeta.
card.expiry_month El mes de expiración de la tarjeta.
card.transaction_reference El transaction.id que originó la adición de la tarjeta (solo si fue enviada a revisión, por el sistema antifraude, de lo contrario null).
card.type Abreviatura del tipo de tarjeta. Revise las opciones válidas
card.number Los últimos cuatro dígitos de la tarjeta.
card.origin El origen de la tarjeta de crédito. Podría ser uno de los siguientes: Shieldgate, VisaCheckout, Masterpass.

Obtener todas las tarjetas

curl \
-k -L -H 'Content-Type: application/json' \
-H 'Auth-Token: auth_token' \
'https://ccapi-stg.shieldgate.mx/v2/card/list?uid=4'

Para el request previo, la respuesta es un JSON estructurado como sigue:

{
    "cards": [
        {
            "bin": "511915",
            "status": "review",
            "token": "17121538682542236138",
            "holder_name": "citlali calderon",
            "expiry_year": "2020",
            "expiry_month": "9",
            "transaction_reference": "CI-473",
            "type": "vi",
            "number": "7991"
        },
        {
            "bin": "422023",
            "status": "valid",
            "token": "15363681013452573066",
            "holder_name": "citlali calderon",
            "expiry_year": "2020",
            "expiry_month": "9",
            "transaction_reference": null,
            "type": "mc",
            "number": "8431"
        },
        {
            "bin": "453254",
            "status": "valid",
            "token": "10135134879450157925",
            "holder_name": "citlali calderon",
            "expiry_year": "2020",
            "expiry_month": "9",
            "transaction_reference": null,
            "type": "vi",
            "number": "8311"
        }
    ],
    "result_size": 3
}

Este endpoint recupera todas las tarjetas relacionadas a un usuario.

HTTP Request

GET https://ccapi-stg.shieldgate.mx/v2/card/list

Parámetros URL
Parámetro Tipo Requerido Descripción
uid String Yes Identificador del cliente. Este es el identificador que usted usa dentro de su aplicación.
Respuesta

Una lista de tarjetas

Parámetro Descripción
result_size Número de elementos de la lista de tarjetas.
card.bin El BIN de la tarjeta (primeros seis dígitos de la tarjeta).
card.status Cualquiera de los siguientes estados: valid, review, pending y rejected. Si la respuesta es "review" o "pending", el usuario debe verificar la transacción asociada al intento de agregar una tarjeta (transaction_reference) para configurar esta tarjeta como válida.
card.token Identificador de la tarjeta. Este código es único entre todas las tarjetas.
card.holder_name El nombre del titular de la tarjeta de crédito.
card.expiry_year El año en que expira la tarjeta.
card.expiry_month El mes de expiración de la tarjeta.
card.transaction_reference El transaction.id que originó la adición de la tarjeta (solo si fue enviada a revisión, por el sistema antifraude, de lo contrario null).
card.type Abreviatura del tipo de tarjeta. Revise las opciones válidas
card.number Los últimos cuatro dígitos de la tarjeta.

Eliminar una tarjeta

curl -k  -L -X POST -H 'Content-Type: application/json' -H 'Auth-Token: auth_token' -d '{
   "card": {
        "token": "2293795539132514250"
    },
    "user": {
        "id": "4"
    }
}' 'https://ccapi-stg.shieldgate.mx/v2/card/delete/'

Para el request previo, la respuesta es un JSON estructurado como sigue:

{
  "message": "card deleted"
}

Este endpoint elimina una tarjeta relacionada con un usuario

HTTP Request

POST https://ccapi-stg.shieldgate.mx/v2/card/delete/

Parámetros URL
Parámetro Tipo Requerido Descripción
card.token String Yes Identificador de la tarjeta. Este código es único entre todas las tarjetas. Formato: Long Integer.
user.id String Yes Identificador del cliente. Este es el identificador que usted usa dentro de su aplicación.

Inicializar una Referencia

Este es un ejemplo de request solo con campos requeridos para generar una referencia

curl -k  -L -X POST -H 'Content-Type: application/json' -H 'Auth-Token: auth_token' -d '{
   "locale":"es",
   "order":{
      "amount":100.00,
      "description":"Jhon Doe",
      "vat":0,
      "dev_reference":"Jhon Doe Buying",
      "installments_type":0
   },
   "user":{
      "id":"117",
      "email":"jhon@doe.com"
   }
}' 'https://ccapi-stg.shieldgate.mx/v2/transaction/init_reference/'

Este es un ejemplo de request con más parámetros

curl -k  -L -X POST -H 'Content-Type: application/json' -H 'Auth-Token: auth_token' -d '{
   "locale":"es",
   "session_id":"",
   "origin":"",
   "antifraud":{
      "device_fingerprint":"testa.a92176a7552eb582e1b10b30edc7ac522085d15c54f6",
      "server_ip_address":"54.236.214.202",
      "shopping_cart":[
         {
            "category":"16",
            "tax_value":0,
            "name":"Testing product",
            "price":399.9,
            "id":"1119",
            "quantity":1
         },
         {
            "category":"10",
            "tax_value":0,
            "name":"Testing name",
            "price":399.9,
            "id":"1119",
            "quantity":1
         }
      ],
      "merchant_custom_data":{
         "1":"campo1",
         "2":"dos"
      }
   },
   "order":{
      "amount":100.00,
      "description":"Jhon Doe",
      "vat":0,
      "dev_reference":"Jhon Doe Buying",
      "installments_type":0
   },
   "user":{
      "id":"117",
      "email":"jhon@doe.com"
   },
   "conf":{
      "theme":{
          "logo": "https://mysite.com/images/logo.png",
          "primary_color": "#00BF84",
          "secondary_color": "#545454"
        }
      }
   },
   "billing_address":{
      "street":"Calle 1 Sur",
      "city":"Chia",
      "country":"COL",
      "district":"Chia",
      "zip":"69885",
      "state":"CU",
      "house_number":"179",
      "additional_address_info":"Casa 53"
   }
}' 'https://ccapi-stg.shieldgate.mx/v2/transaction/init_reference/'

Para el request previo, la respuesta es un JSON estructurado como sigue:

{
   "checkout_url":"https://ccapi-stg.shieldgate.mx/v2/transaction/checkout?reference=12438255612471559230",
   "reference":"12438255612471559230"
}

Este endpoint crea una referencia para poder hacer el render del checkout.

HTTP Request

POST https://ccapi-stg.shieldgate.mx/v2/transaction/init_reference/

Parámetros URL
Parámetro Tipo Requerido Descripción
locale String Yes Idioma a usar en el checkout (es, en, pt). El idioma predeterminado es Inglés
session_id String No Parámetro utilizado para el anti fraude. Hash numérico de longitud 32.
antifraud Json No Objeto con datos requeridos por algunos sistemas antifraudes , Vea las especificaciones para antifraud.
order.amount Number Yes Monto a cobrar. Formato: decimal con dos dígitos de fracción.
order.description String Yes Descripción de la orden a ser comprada. Formato: (Longitud Máxima 250)
order.vat Number Yes Importe del impuesto sobre las ventas, incluido en el costo del producto. Formato: decimal con dos dígitos de fracción.
order.dev_reference String Yes Referencia de la orden en el comercio. Usted identificará esta compra utilizando esta referencia
order.installments_type Number No Sólo disponible para Ecuador y México. Revise los valores permitidos
conf Json No Objeto con datos requeridos por conf, Vea las especificaciones para conf.
billing_address Json No Objeto con la dirección de facturación de la tarjeta, vea las especificaciones para la dirección.
user.id String Yes Identificador del cliente. Este es el identificador que usa dentro de su aplicación.
user.email String Yes Correo electrónico del comprador, con formato de correo válido.
Respuesta
Parámetro Descripción
checkout_url URL para generar el checkout
reference Referencia usada, para mostrar el checkout.

Datos para conf

Cuando la integración es vía API, configuración requerida.
Parámetro Tipo Requerido Descripción
conf.allowed_card_brands String No Marca permitida para la operación, Revise las opciones válidas
conf.allowed_card_types String No Tipo de Tarjeta permitida
conf.invalid_card_type_message String No Mensaje personalizado, cuándo una tarjeta no es permitida
conf.theme JSON No Parámetros para personalizar colores y logo en el checkout

Cobro con Token

Caso base

curl -k  -L -X POST -H 'Content-Type: application/json' -H 'Auth-Token: auth_token' -d '{
    "user": {
        "id": "4",
        "email": "user@example.com"
    },
    "order": {
        "amount": 99.0,
        "description": "pozole",
        "dev_reference": "referencia",
        "vat": 0.00
    },
    "card": {
        "token": "2293795539132514250"
    }
}' 'https://ccapi-stg.shieldgate.mx/v2/transaction/debit/'

Para el request previo, la respuesta es un JSON estructurado como sigue:

{
  "transaction": {
    "status": "success",
    "payment_date": "2017-09-26T21:00:47",
    "amount": 11.1,
    "authorization_code": "088428",
    "installments": 1,
    "dev_reference": "referencia",
    "message": "Operation Successful",
    "carrier_code": "6",
    "id": "CI-489",
    "status_detail": 3,
    "installments_type": "Revolving credit",
    "payment_method_type": "0",
    "product_description": "pozole"
  },
  "card": {
    "bin": "450700",
    "expiry_year": "2020",
    "expiry_month": "9",
    "transaction_reference": "CI-489",
    "type": "vi",
    "number": "6651",
    "origin": "ORIGIN"
  }
}

Este es un ejemplo de respuesta de un request realizado con objetos para 3DS 2:

{
  "transaction": {
    "status": "failure",
    "payment_date": null,
    "amount": 11.1,
    "authorization_code": null,
    "installments": 1,
    "dev_reference": "referencia",
    "message": null,
    "carrier_code": null,
    "id": "RB-5969",
    "status_detail": 37
  },
  "card": {
    "bin": "401600",
    "status": "",
    "token": "",
    "expiry_year": "2020",
    "expiry_month": "9",
    "transaction_reference": "RB-5969",
    "type": "vi",
    "number": "0051",
    "origin": "ORIGIN"
  },
  "3ds": {
    "sdk_response": {
      "acs_trans_id": "00000000-0005-5a5a-8000-016ab2e4246c",
      "acs_signed_content": null,
      "acs_reference_number": "JCB0002"
    },
    "authentication": {
      "status": "U",
      "return_message": "U-status/Challenge authentication via ACS: ",
      "version": null,
      "xid": "MDAwMDAwMDAwMDAwMDAwMDAyMDg=",
      "reference_id": "ffffffff-9002-51a3-8000-0000000345a2",
      "cavv": null,
      "return_code": "5",
      "eci": null
    },
    "browser_response": {
      "hidden_iframe": "",
      "challenge_request": ""
    }
  }
}

Este endpoint genera un cobro con una tarjeta previamente guardada en la plataforma. Si desea realizar la compra con autenticación 3D Secure 2. Necesitará incluir extra_params en el request, que serán utilizados para autenticar. (Revise objetos para autenticación).

HTTP Request

POST https://ccapi-stg.shieldgate.mx/v2/transaction/debit/

Parámetros URL
Parámetro Tipo Requerido Descripción
session_id String No Parámetro utilizado para el anti fraude. Hash numérico de longitud 32.
order.amount Number Yes Monto a cobrar. Formato: decimal con dos dígitos de fracción.
order.description String Yes Descripción de la orden a ser comprada. Formato: (Longitud Máxima 250)
order.dev_reference String Yes Referencia de la orden en el comercio. Usted identificará esta compra utilizando esta referencia
order.vat Number Yes Importe del impuesto sobre las ventas, incluido en el costo del producto. Formato: decimal con dos dígitos de fracción.
order.installments Number No El número de cuotas para el pago, solo para COP, MXN, BRL, PEN, CLP y USD (Ecuador).
order.installments_type Number No Sólo disponible para Ecuador y México. Revise los valores permitidos
order.taxable_amount Number No Solo disponible para Ecuador. El importe imponible es el total de todos los items imponibles o gravables excluyendo el iva. Si no se envía, se calcula sobre el total. Formato: decimal con dos dígitos de fracción.
order.tax_percentage Number No Solo disponible para Ecuador. La tasa de impuesto que se aplicará a este pedido. Debe de ser 0 o 12.
order.months_grace Number No Solo disponible para México y Ecuador (Medianet), el número de meses de gracia para un pago diferido.
user.id String Yes Identificador del cliente. Este es el identificador que usa dentro de su aplicación.
user.first_name String No Nombre del Usuario.
user.last_name String No Apellido del Usuario.
user.email String Yes Correo electrónico del comprador, con formato de correo válido.
user.phone String No Numero de teléfono del comprador.
user.ip_address String No Direccion IP del usuario. Formato: IP v4 válida.
user.fiscal_number String No El número fiscal dado por el comprador. Nota: Para los tipos de tarjeta ex, ak, vr, sx, ol, ep y cd este campo es obligatorio.
card.token String No Identificador de tarjeta. Este código es único entre todas las tarjetas. Formato: Long Integer.
card.cvc String No El número de seguridad de la tarjeta de crédito.
wallet.type String No Tipo de billetera, los valores posibles son: 'VisaCheckout', 'Masterpass' y 'CyberSource'.
wallet.key String No El Id de la billetera (ya sea el callid, el transactionId o subscriptionID).
extra_params Json No Parámetros opcionales (objetos 3DS 2 incluídos) utilizados para algunos comercios en formato Json. Por favor, póngase en contacto con su ejecutivo comercial para más detalles.
shipping_address Json No Objeto con la dirección de envió del pedido, vea las especificaciones para la dirección.
airline Json No Objecto con datos de aerolínea, Vea las especificaciones para aerolínea.
hotel Json No Objeto con datos de hotel, Vea las especificaciones para hotel.
Respuesta
Parámetro Descripción
transaction.status Puede ser success, failure or pending.
transaction.payment_date En ambiente de pruebas la fecha estará en UTC, de lo contrario dependerá del Procesador.
transaction.amount El importe de la transacción.
transaction.authorization_code En caso de éxito el código de autorización que respondió el Procesador.
transaction.installments El número de cuotas para el pago.
transaction.dev_reference Referencia de la orden del comerciante.
transaction.message El mensaje devuelto por el Procesador o el sistema de análisis de fraude.
transaction.carrier_code El código devuelto del Procesador.
transaction.id Identificador de la transacción. Este código es único entre todas las transacciones.
transaction.status_detail El detalle del estado de la transacción, para más información, detalle del estado.
transaction.installments_type Sólo disponible para Ecuador y México. Revise los valores permitidos
transaction.payment_method_type Tipo de método de pago de la transacción, para mas información payment_method_types
transaction.product_description Descripción de la ordén.
transaction.trace_number Sólo disponible para Ecuador y México.
transaction.lot_number Sólo disponible para Ecuador.
card.bin El BIN de la tarjeta (primeros seis dígitos de la tarjeta).
card.expiry_year El año en que expira la tarjeta.
card.expiry_month El mes de expiración de la tarjeta.
card.transaction_reference Si se regresa será un transaction.id
card.type Abreviatura del tipo de tarjeta. Revise las opciones válidas
card.number Los últimos cuatro dígitos de la tarjeta.
card.origin El origen de la tarjeta de crédito. Podría ser uno de los siguientes: Shieldgate, VisaCheckout, Masterpass.

En el caso de transacciones que se autenticaron con 3DS 2, la respuesta incluirá:

Parámetro Descripción
3ds.sdk_response.acs_trans_id ID de la transacción en el ACS
3ds.sdk_response.acs_signed_content Contenido firmado por el ACS
3ds.sdk_response.acs_reference_number Número de referencia de ACS
3ds.authentication.status El estado de autenticación puede ser: "Y", "N", "U", "A", "R", "C" o "-" si el valor no está disponible debido a errores o no está registrado, para obtener más información authentication_status.
3ds.authentication.xid Identificador de transacción enviado al MPI.
3ds.authentication.return_code Código devuelto por MPI, que proporciona toda la información que se necesita para determinar cómo administrar la transacción, para obtener más información códigos de retorno mpi
3ds.authentication.eci Indicador de comercio electrónico, con tarjetas de visa, el valor que se debe pasar en el mensaje de Autorización.
3ds.authentication.return_message Descripción del código de retorno.
3ds.authentication.version Versión de mensaje 3DS utilizada.
3ds.authentication.cavv Valor de verificación de autenticación del titular de la tarjeta, determinado por ACS. Formato: base64
3ds.authentication.reference_id Id en el server del directorio (DS transaction Id)
3ds.browser_response.challenge_request Si se inscribió al titular de la tarjeta y/o se solicitó la autenticación por desafío, la página de pago debe redireccionar el navegador del usuario al ACS. Si este campo no está vacío, contendrá el html para redirigir.
3ds.browser_response.hidden_iframe Si este campo no está vacío, el contenido debe procesarse en una página intermedia en un iframe invisible y esperar unos 5 segundos.
3ds.service El nombre del servicio de MPI que autenticó la transacción.
Objetos para autenticación

Antes de realizar un pago, ya sea a través de un cobro con token, un cobro con tarjeta o una autorización, es posible realizar primero una autenticación 3D Secure, enviando estos objetos en extra_params:

Nombre del Objeto Descripción
threeDS2_data Si la autenticación se realizará directamente en cobro/autorización, este objeto es obligatorio.
browser_info Requerido para tipo de dispositivo browser.
auth_data Utilice este objeto si previamente realizó la autenticación.
risk_indicator Campos de riesgo adicionales para 3DS 2. Incluya esto en su request cuando esté disponible.
Parámetro Tipo Requerido Descripción
extra_params.threeDS2_data.term_url String Yes La URL de la página del comerciante, donde ACS publicará (a través del navegador del usuario) el mensaje CRes después de la autenticación.
extra_params.threeDS2_data.device_type String Yes Tipo de dispositivo. Cadenas válidas: browser, SDK.
extra_params.threeDS2_data.process_anyway Boolean No Procesa de cualquier manera, es decir, no importando el resultado de la autenticación, se realizará el cobro / autorización. Si no se proporciona por defecto, falso.
extra_params.threeDS2_data.reference_id String Yes* Obligatorio sólo para el MPI CyberSource, el ID utilizado para construir el jwt que se envía en el método init de front end.
extra_params.browser_info.ip String C Dirección IP del usuario. Dirección IP v4 válida.
extra_params.browser_info.language String C Idioma del navegador.
extra_params.browser_info.java_enabled Boolean C Si Java está habilitado en el navegador.
extra_params.browser_info.js_enabled Boolean C Si JavaScript está habilitado en el navegador.
extra_params.browser_info.color_depth Number C Profundidad de color del navegador.
extra_params.browser_info.screen_height Number C Altura de la pantalla del navegador.
extra_params.browser_info.screen_width Number C Ancho de pantalla del navegador.
extra_params.browser_info.timezone_offset Number C Desplazamiento de zona horaria.
extra_params.browser_info.user_agent String C Agente de usuario.
extra_params.browser_info.accept_header String C Aceptar encabezado.
extra_params.auth_data.cavv String Yes Valor de verificación de autenticación del titular de la tarjeta, determinado por ACS. Formato: base64
extra_params.auth_data.xid String No Identificador de transacción enviado al MPI.
extra_params.auth_data.eci String Yes Indicador de comercio electrónico, con tarjetas de visa, el valor que se debe pasar en el mensaje de Autorización.
extra_params.auth_data.version String Yes Versión de mensaje 3DS utilizada.
extra_params.auth_data.reference_id UUID Yes Id en el server del directorio (DS transaction Id)
extra_params.auth_data.status String Yes Estado de la autenticación, podría ser: "Y", "N", "U", "A", "R" o "C", para obtener más información authentication_status
Dirección

Este es un ejemplo de un request con el objeto Billing Address:

curl -k  -L -X POST -H 'Content-Type: application/json' -H 'Auth-Token: auth_token' -d '{
    "user": {
        "id": "4",
        "email": "user@example.com",
        "phone": "1234567890123"
    },
    "order":{
        "amount": 11.1,
        "description": "una paleta",
        "vat": 0,
        "dev_reference": "referencia",
        "installments": 4
    },
    "card": {
        "number": "4456530000001047",
        "holder_name": "citlali calderon",
        "expiry_month": 12,
        "expiry_year": 2024,
        "cvc": "123",
        "type": "vi"
    },
     "billing_address": {
        "street": "Street Test",
        "house_number": "24",
        "city": "ciudad de mexico",
        "zip": "67890",
        "state": "DF",
        "country": "MEX",
        "district": "colonia",
        "additional_address_info": ""
    },
    "extra_params": {
        "threeDS2_data": {
            "term_url": "https://your.url.com/YOUR_3DS_NOTIFICATION_URL",
            "device_type": "browser",
            "reference_id": "2"
        },
        "browser_info": {
            "ip": "88.196.25.166",
            "language": "en-US",
            "java_enabled": false,
            "js_enabled": true,
            "color_depth": 24,
            "screen_height": 1200,
            "screen_width": 1920,
            "timezone_offset": 0,
            "user_agent": "Mozilla\/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/70.0.3538.110 Safari\/537.36",
            "accept_header": "text/html"
        }
    }
}' 'https://ccapi-stg.shieldgate.mx/v2/transaction/debit_cc'

En caso de que envíe la información de la dirección de facturación o de envío, el formato del objeto Json es el siguiente:

Parámetro Tipo Requerido Descripción
first_name String No Nombre del la persona en la dirección.
last_name String No Apellido del la persona en la dirección.
street String No El nombre de la calle.
city String No El nombre de la ciudad, máximo de 50 caracteres.
state String No El estado. Formato 3166-2 código de 2 caracteres en caso de transacciones que se autenticarán con 3DS, formato libre en otro caso.
district String No El distrito.
zip String No Código Postal, máximo de 50 caracteres.
house_number String No El número de la casa.
country String No País en formato ISO 3166-1 alpha-3, por ejemplo: COL, MEX, ECU.
additional_address_info String No Información adicional, sin formato.
Datos para hotel

Ejemplo de request con datos de hotel.

 curl -k  -L -X POST -H 'Content-Type: application/json' -H 'Auth-Token: auth_token' -d '{
     "card": {
             "cvc": "",
             "expiry_month": 5,
             "expiry_year": 2024,
             "holder_name": "GMC",
             "number": "5123450000000008"
         },
         "order": {
             "amount": 200,
             "description": "PASSIVE99465427",
             "dev_reference": "PASSIVE99465427",
             "installments_type": 0,
             "taxable_amount": 0,
             "vat": 0
         },
         "origin": "ORIGIN",
         "user": {
             "email": "PASSIVE99465427@test.com",
             "fiscal_number": "",
             "id": "PASSIVE99465427",
             "ip_address": "127.0.0.1",
             "phone": ""
         }
         "hotel": {
                 "booking_reference ": "4556778999",
                 "booking_country": "CO",
                 "issue_date": "2021-08-24 12:55:11",
                 "name": "Fiesta Americana",
                 "code": "HT001",
                 "arrival_date": "2021-09-24 12:55:11",
                 "departure_date": "2021-09-30 12:55:11",
                 "payer_in": true,
                 "country": "MX",
                 "numbers_child": 2,
                 "numbers_adt": 1,
                 "transportation_include": true,
                 "transport_name": "latam"
             }
 }' 'https://ccapi-stg.shieldgate.mx/v2/transaction/debit_cc'

En caso de que necesite enviar datos para hotel, se debe usar un formato de tipo json.

Parámetro Tipo Requerido Descripción
booking_reference String Yes Referencia de la reservación.
booking_country String No País donde se realiza la reservación, Formato: ISO 3166-2.
issue_date String Yes Fecha de reservación en el siguiente formato: YYYY-MM-DD HH:MM:SS.
name String Yes Nombre del hotel.
code String Yes Código de hotel.
arrival_date String Yes Fecha de ingreso en el siguiente formato: YYYY-MM-DD HH:MM:SS.
departure_date String Yes Fecha de salida en el siguiente formato: YYYY-MM-DD HH:MM:SS.
payer_in Boolean No True si el pagador viaja en la reserva.
country String Yes País destino de la reserva de hotel, Formato: ISO 3166-2.
numbers_child Number Yes Número de niños en la reserva.
numbers_adt Number Yes Número de adultos en la reserva.
transportation_include Boolean No True si la reserva incluye transporte.
transport_name String No Nombre de empresa encargada de transportar a los pasajeros.
Datos para aerolineas

Ejemplo de request con datos de aerolinea.

curl -k  -L -X POST -H 'Content-Type: application/json' -H 'Auth-Token: auth_token' -d '{
    "card": {
            "cvc": "",
            "expiry_month": 5,
            "expiry_year": 2024,
            "holder_name": "GMC",
            "number": "5123450000000008"
        },
        "order": {
            "amount": 200,
            "description": "PASSIVE99465427",
            "dev_reference": "PASSIVE99465427",
            "installments_type": 0,
            "taxable_amount": 0,
            "vat": 0
        },
        "origin": "ORIGIN",
        "user": {
            "email": "PASSIVE99465427@test.com",
            "fiscal_number": "",
            "id": "PASSIVE99465427",
            "ip_address": "127.0.0.1",
            "phone": ""
        }
        "airline": {
                "flight_legs": [
                    {
                        "carrier_code": "T1",
                        "departure_airport": "TAO",
                        "departure_date": "2021-09-30 08:00:00",
                        "destination_airport": "TAD",
                        "arrival_date": "2021-09-30 11:00:00",
                        "flight_number": "123456"
                    }
                ],
                "passengers": [
                    {
                        "first_name": "Gabriel",
                        "last_name": "Cruz",
                        "middle_name": "Omar",
                        "title": "Mr Dr"
                    },
                    {
                        "first_name": "Jhon",
                        "last_name": "Doe",
                        "middle_name": "",
                        "title": "Mr"
                    },
                    {
                        "first_name": "Jane",
                        "last_name": "Doe",
                        "middle_name": "",
                        "title": "Mrs"
                    }
                ],
                "reservation": {
                    "airline_code": "T1",
                    "booking_reference": "1234567890",
                    "document_type": "ELECTRONIC_TICKET",
                    "issue_date": "2021-09-30 00:00:00",
                    "ticket_number": "12345678901",
                    "travel_agent_code": "TESTAIR1",
                    "travel_agent_name": "TestAirline",
                    "itinerary_type": "ONE_WAY"
                }
        }
}' 'https://ccapi-stg.shieldgate.mx/v2/transaction/debit_cc'

En caso de que necesite enviar datos para aerlineas, se debe usar un formato de tipo json.

Parámetro Tipo Requerido Descripción
flight_legs Array Yes Arreglo con uno o más objetos flight_leg. Ver detalle del objeto flight_leg
passengers Array Yes Arreglo con uno o mas objetos passenger. Ver detalle del objeto passengers
reservation.airline_code String Yes Código de aerolínea.
reservation.booking_reference String Yes Referencia de la reservación.
reservation.document_type String Yes Tipo de Documento (ELECTRONIC_TICKET u OTHER).
reservation.issue_date Date Time Yes Fecha de reservación en el siguiente formato: YYYY-MM-DD HH:MM:SS.
reservation.ticket_number String No Numero de ticket.
reservation.travel_agent_code String Yes Código de la agencia de viajes.
reservation.travel_agent_name String Yes Nombre de la agencia de viajes.
reservation.itinerary_type String No Tipo de itinerario (MULTI_DESTINATION, ONE_WAY, ROUND_TRIP).
reservation.complete_route String No concatenamos ruta completa ejemplo: SFO-JFK:JFK-LHR:LHR-CDG
reservation.frequent_flyer String No Número de código de fidelidad del viajero frecuente, si son varios separar con _
reservation.delta_days Number No Delta entre fecha de salida x fecha de regreso.
reservation.city_departure String No Ciudad donde se inicia el viaje comprado por el cliente.
reservation.city_arrival String No Ciudad donde finaliza el viaje comprado por el cliente.
Detalles para objeto flight leg.
Parámetro Tipo Requerido Descripción
carrier_code String Yes Código de carrier.
departure_airport String Yes Aeropuerto de salida.
departure_date Date Time Yes Fecha de salida en el siguiente formato: YYYY-MM-DD HH:MM:SS
destination_airport String Yes Aeropuerto de destino.
arrival_date Date Time Yes Fecha de llegada en el siguiente formato: YYYY-MM-DD HH:MM:SS
flight_number String Yes Numero de vuelo.
stopover_allowed Boolean No Con escalas.
Detalles para objeto passenger.
Parámetro Tipo Requerido Descripción
id String No Identificador del usuario.
first_name String Yes Nombre del pasajero.
last_name String Yes Apellido del pasajero.
middle_name String No Segundo nombre del pasajero.
title String Yes Titulo del pasajero.
email String No Correo electronico del pasajero.
type String No Tipo de pasajero puede ser : ADT, INF ó CHD.
phone String No Numero de teléfono del pasajero.
amount Number No Monto a cobrar. Formato: decimal con dos dígitos de fracción.
Tipos de Diferidos

Los tipos de diferidos son sólo permitidos para Ecuador y México. Para estos países si manda coutas, entonces el parámetro installment_type es obligatorio. Los valores validos son:

Tipo Descripción
0 Crédito Rotativo.
1 Rotativo y diferido sin intereses (el banco pagará al comercio la cuota, mes a mes).
2 Diferido con intereses.
3 Diferido sin intereses.
7 Diferido con intereses y meses de gracia.
6 Diferido sin intereses pago mes a mes. (*)
9 Diferido sin intereses y meses de gracia.
10 Diferido sin intereses promoción bimensual. (*)
21 Exclusivo para Diners Club, diferido con y sin intereses.
22 Exclusivo para Diners Club, diferido con y sin intereses.
30 Diferido con intereses pago mes a mes. (*)
50 Diferido sin intereses promociones (Supermaxi). (*)
51 Diferido con intereses (Cuota fácil). (*)
52 Sin intereses (Rendecion Produmillas). (*)
53 Sin intereses venta con promociones. (*)
70 Diferido especial sin intereses (*)
72 Crédito sin intereses (cte smax). (*)
73 Crédito Especial sin intereses (smax). (*)
74 Prepago sin intereses (smax). (*)
75 Crédito diferido sin intereses (smax). (*)
90 Sin intereses con meses de gracia (Supermaxi). (*)

Split de pagos

curl -k  -L -X POST -H 'Content-Type: application/json' -H 'Auth-Token: auth_token' -d '{
    "user": {
        "id": "11",
        "email": "test@test.com"
    },
    "order": {
        "amount": 19000,
        "description": "RBM-TES",
        "dev_reference": "11372",
        "vat": 0.0,
        "installments": 1
    },
    "card": {
        "token": "4813322119168991180"
    },
    "extra_params": {
        "split": {
            "transactions": [
                {
                    "application_code": "App2",
                    "installments": 1,
                    "amount": 10000
                },
                {
                    "application_code": "App1",
                    "installments": 1,
                    "amount": 9000
                }
            ]
        }
    }
}' 'https://ccapi-stg.shieldgate.mx/v2/transaction/debit/'

Para el request previo, la respuesta es un JSON estructurado como sigue:

{
  "transaction": {
    "status": "success",
    "payment_date": "2020-01-28T21:09:55.424",
    "amount": 19000.0,
    "authorization_code": "615246",
    "installments": 1,
    "dev_reference": "11372",
    "message": "Aprobado",
    "carrier_code": "00",
    "id": "RB-37",
    "status_detail": 3
  },
  "split": {
    "transactions": [
      {
        "installments": 1,
        "amount": 10000.0,
        "id": "RB-37-1",
        "application_code": "App2",
        "authorization_code": "615246"
      },
      {
        "installments": 1,
        "amount": 9000.0,
        "id": "RB-37-2",
        "application_code": "App1",
        "authorization_code": "580705"
      }
    ]
  },
  "card": {
    "bin": "377813",
    "status": "valid",
    "token": "6837968442995217183",
    "expiry_year": "2021",
    "expiry_month": "3",
    "transaction_reference": "RB-37",
    "type": "ax",
    "number": "9063",
    "origin": "ORIGIN"
  }
}

En este endpoint podrán realizar pagos que permitiran dividir el monto total entre distintas aplicaciones (Disponible sólo para Colombia).

HTTP Request

POST https://ccapi-stg.shieldgate.mx/v2/transaction/debit/

Parámetros URL
Parámetro Tipo Requerido Descripción
session_id String No Parámetro utilizado para el anti fraude. Hash numérico de longitud 32.
order.amount Number Yes Monto a cobrar. Formato: decimal con dos dígitos de fracción.
order.description String Yes Descripción de la orden a ser comprada. Formato: (Longitud Maxima 250)
order.dev_reference String Yes Referencia de la orden en el comercio. Usted identificará esta compra utilizando esta referencia
order.vat Number Yes Importe del impuesto sobre las ventas, incluido en el costo del producto. Formato: decimal con dos dígitos de fracción.
order.installments Number No El número de cuotas para el pago, solo para COP, MXN, BRL, PEN, CLP y USD (Ecuador).
user.id String Yes Identificador del cliente. Este es el identificador que usa dentro de su aplicación.
user.email String Yes Correo electrónico del comprador, con formato de correo válido.
user.phone String No Numero de teléfono del comprador.
user.ip_address String No Direccion IP del usuario. Formato: IP v4 válida.
user.fiscal_number String No El número fiscal dado por el comprador. Nota: Para los tipos de tarjeta ex, ak, vr, sx, ol, ep y cd este campo es obligatorio.
card.token String Yes Identificador de tarjeta. Este código es único entre todas las tarjetas. Formato: Long Integer.
extra_params Json Yes Párametros necesarios para poder generar una transacción de split de pagos Ver párametros para split de pagos
Párametros para split
Parámetro Tipo Requerido Descripción
split.transactions Array Yes Arreglo con la información de cómo se dividirá el pago entre los distintos comercios/aplicaciones
split.transactions.application_code String Yes Aplicación que tiene la cuenta a la cual se enviará un monto parcial
split.transactions.amount Number Yes Monto parcial del total del pago
split.transactions.installments Number Yes Número de mensualidades a pagar para este monto parcial
Respuesta para split
Parámetro Descripción
transaction.status Puede ser success, failure, pending, expired* o **canceled.
transaction.payment_date En ambiente de pruebas la fecha estará en UTC, de lo contrario dependerá del Procesador.
transaction.amount El importe de la transacción.
transaction.authorization_code En caso de éxito el código de autorización que respondió el Procesador.
transaction.installments El número de cuotas para el pago.
transaction.dev_reference Referencia de la orden del comerciante.
transaction.message El mensaje devuelto por el Procesador o el sistema de análisis de fraude.
transaction.carrier_code El código devuelto del Procesador.
transaction.id Identificador de la transacción. Este código es único entre todas las transacciones.
transaction.status_detail El detalle del estado de la transacción, para más información, detalle del estado.
card.bin El BIN de la tarjeta (primeros seis dígitos de la tarjeta).
card.expiry_year El año en que expira la tarjeta.
card.expiry_month El mes de expiración de la tarjeta.
card.transaction_reference Si se regresa será un transaction.id
card.type Abreviatura del tipo de tarjeta. Revise las opciones válidas
card.number Los últimos cuatro dígitos de la tarjeta.
card.origin El origen de la tarjeta de crédito. Podría ser uno de los siguientes: Shieldgate, VisaCheckout, Masterpass.
split.transactions Arreglo que contiene las transacciones autorizadas en el pago con split
split.transactions.application_code Aplicación que corresponde a ese pago
split.transactions.amount Monto parcial del total de la orden
split.transactions.id Identificador de la transacción de split
split.transactions.installments Número de meses en que se parcializo la transacción
split.transactions.authorization_code Número de autorización de la transacción

Cobro con QR

curl -k  -L -X POST -H 'Content-Type: application/json' -H 'Auth-Token: auth_token' -d '{
    "user": {
        "id": "11",
        "email": "example@example.com",
        "fiscal_number": "1111111111",
        "phone": "111112222333"
    },
    "order": {
        "amount": 123,
        "description": "Product Description",
        "dev_reference": "nnnnn",
        "vat": 0
    },
    "card": {
        "token": "1111222233334444555",
    },
    "extra_params": {
        "qr_data": {
            "complete_info": {
                "is_new": false,
                "qr_type": "DINAMICO",
                "data_amount": {
                    "base_amount": 123,
                    "inc": 0,
                    "iva": 0,
                    "tip": 0,
                    "total_amount": 123,
                    "transaction_amount": 123
                },
                "qr_entity": {
                    "address": "my address",
                    "country_code": null,
                    "crc": null,
                    "max_inc_percentage": "0.0",
                    "max_iva_percentage": "0.0",
                    "merchant_category_code": null,
                    "merchant_city": null,
                    "merchant_name": "Product Description",
                    "merchant_account_information_c": {
                        "id_acquirer": null,
                        "unique_code_merchant": "1111112222",
                        "unique_code_merchant_agree": null
                    },
                    "merchant_additional_data_c": {
                        "id_acquirer": null,
                        "bill_number": null,
                        "customer_label": null,
                        "loyalty_number": null,
                        "mobile_number": null,
                        "purpose_of_transaction": null,
                        "reference_label": null,
                        "store_label": null,
                        "terminal_label": "XXXXYYY12"
                    },
                    "merchant_a_unreserved_c": {
                        "base_iva": "0",
                        "channel": "DA",
                        "condition_inc": "N",
                        "condition_iva": "N",
                        "condition_tax_one": null,
                        "condition_tax_two": null,
                        "consecutive_transaction": "4321",
                        "security_field": null,
                        "tax_one": null,
                        "tax_two": null,
                        "value_inc": "0",
                        "value_iva": "0"
                    },
                    "merchant_information_languaje_c": {
                        "language_preference": null,
                        "merchant_city_alternate_language": null,
                        "merchant_name_alternate_language": null
                    },
                    "payload_format_indicator": null,
                    "point_of_initiation_method": "D",
                    "postal_code": null,
                    "tip_or_convenience_indicator": "N",
                    "total_amount": "123",
                    "transaction_amount": "123",
                    "transaction_currency": null,
                    "value_of_convenience_fee_fixed": "0",
                    "value_of_convenience_fee_percentage": "0.0"
                }
            }
        }
    }
}' 'https://ccapi-stg.shieldgate.mx/v2/transaction/debit/'

Este endpoint genera una transacción de cobro con un código QR, sólo aplica para Colombia (COP).

Es una solución que permite pagar las compras, a través de un código QR que es generado por el datáfono o aplicación móvil y que se escanea desde la billetera móvil de cualquier cliente.

HTTP Request

POST https://ccapi-stg.shieldgate.mx/v2/transaction/debit/

Parámetros URL
Parámetro Tipo Requerido Descripción
session_id String No Parámetro utilizado para el anti fraude. Hash numérico de longitud 32.
order.amount Number Yes Monto a cobrar. Formato: decimal con dos dígitos de fracción.
order.description String Yes Descripción de la orden a ser comprada. Formato: (Longitud Maxima 250)
order.dev_reference String Yes Referencia de la orden en el comercio. Usted identificará esta compra utilizando esta referencia
order.vat Number Yes Importe del impuesto sobre las ventas, incluido en el costo del producto. Formato: decimal con dos dígitos de fracción.
order.installments Number No El número de cuotas para el pago, solo para COP, MXN, BRL, PEN, CLP y USD (Ecuador).
user.id String Yes Identificador del cliente. Este es el identificador que usa dentro de su aplicación.
user.email String Yes Correo electrónico del comprador, con formato de correo válido.
user.phone String No Numero de teléfono del comprador.
user.ip_address String No Direccion IP del usuario. Formato: IP v4 válida.
user.fiscal_number String No El número fiscal dado por el comprador. Nota: Para los tipos de tarjeta ex, ak, vr, sx, ol, ep y cd este campo es obligatorio.
user.fiscal_number_type String No Indica el tipo de número fiscal (identificación del usuario).
card.token String Yes Identificador de tarjeta. Este código es único entre todas las tarjetas. Formato: Long Integer.
card.account_type String No Los valores correspondientes para las cuentas de tipo: Crédito, Corriente y Ahorros son: C, R y A respectivamente.
extra_params.qr_data Json Yes Json que responde el SDK.
Respuesta

Ver Objetos en la respuesta

Cobro con Tarjeta Crédito

Caso base


curl -k  -L -X POST -H 'Content-Type: application/json' -H 'Auth-Token: auth_token' -d '{
    "user": {
        "id": "4",
        "email": "user@example.com"
    },
    "order":{
        "amount": 11.1,
        "description": "una paleta",
        "vat": 0,
        "dev_reference": "referencia"
    },
    "card": {
        "number": "4507000397186651",
        "holder_name": "citlali calderon",
        "expiry_month": 9,
        "expiry_year": 2020,
        "cvc": "123",
        "type": "vi"
    }
}' 'https://ccapi-stg.shieldgate.mx/v2/transaction/debit_cc'

Para el request previo, la respuesta es un JSON estructurado como sigue:

{
  "transaction": {
    "status": "success",
    "payment_date": "2017-10-12T21:07:22",
    "amount": 11.1,
    "authorization_code": "472921",
    "installments": 1,
    "dev_reference": "referencia",
    "message": "Operation Successful",
    "carrier_code": "6",
    "id": "CI-507",
    "status_detail": 3,
    "installments_type": "Revolving credit",
    "product_description": "una paleta",
    "payment_method_type": "0"
  },
  "card": {
    "bin": "450700",
    "expiry_year": "2020",
    "expiry_month": "9",
    "transaction_reference": "CI-507",
    "type": "vi",
    "number": "6651",
    "origin": "ORIGIN"
  }
}

Este es un ejemplo de request con extra_params:


curl -k  -L -X POST -H 'Content-Type: application/json' -H 'Auth-Token: auth_token' -d '{
    "user": {
        "id": "4",
        "email": "user@example.com"
    },
    "order":{
        "amount": 11.1,
        "description": "una paleta",
        "vat": 0,
        "dev_reference": "referencia"
    },
    "card": {
        "number": "4507000397186651",
        "holder_name": "citlali calderon",
        "expiry_month": 9,
        "expiry_year": 2020,
        "cvc": "123",
        "type": "vi"
    },
    "extra_params": {
        "config_01": "value_01",
        "config_02": {"name_01": "name_v01"}
    }
}' 'https://ccapi-stg.shieldgate.mx/v2/transaction/debit_cc'

Este es un ejemplo de un request realizado con objetos para 3DS 2:


curl -k  -L -X POST -H 'Content-Type: application/json' -H 'Auth-Token: auth_token' -d '{
    "user": {
        "id": "4",
        "email": "user@example.com"
    },
    "order":{
        "amount": 11.1,
        "description": "una paleta",
        "vat": 0,
        "dev_reference": "referencia"
    },
    "card": {
        "number": "4507000397186651",
        "holder_name": "citlali calderon",
        "expiry_month": 9,
        "expiry_year": 2020,
        "cvc": "123",
        "type": "vi"
    },
    "extra_params": {
        "threeDS2_data": {
            "term_url": "https://your.url.com/YOUR_3DS_NOTIFICATION_URL",
            "device_type": "browser",
            "process_anyway": false
        },
        "browser_info": {
            "ip": "88.196.25.166",
            "language": "en-US",
            "java_enabled": false,
            "js_enabled": true,
            "color_depth": 24,
            "screen_height": 1200,
            "screen_width": 1920,
            "timezone_offset": 0,
            "user_agent": "Mozilla\/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/70.0.3538.110 Safari\/537.36",
            "accept_header": "text/html"
        }
    }

}' 'https://ccapi-stg.shieldgate.mx/v2/transaction/debit_cc'

Este endpoint genera una transacción de cobro con una tarjeta de crédito.

Si desea realizar la compra con autenticación 3D Secure 2. Necesitará incluir extra_params en el request, que serán utilizados para autenticar. (Revise objetos para autenticación).

HTTP Request

POST https://ccapi-stg.shieldgate.mx/v2/transaction/debit_cc/

Parámetros URL
Parámetro Tipo Requerido Descripción
session_id String No Parámetro utilizado para el anti fraude. Hash numérico de longitud 32.
order.amount Number Yes Monto a cobrar. Formato: decimal con dos dígitos de fracción.
order.description String Yes Descripción de la orden a ser comprada. Formato: (Longitud Máxima 250)
order.dev_reference String Yes Referencia de la orden en el comercio. Usted identificará esta compra utilizando esta referencia
order.vat Number Yes Importe del impuesto sobre las ventas, incluido en el costo del producto. Formato: decimal con dos dígitos de fracción.
order.installments Number No El número de cuotas para el pago, solo para COP, MXN, BRL, PEN, CLP y USD (Ecuador).
order.installments_type Number No Solo disponible para Ecuador y México. Revise los valores permitidos
order.taxable_amount Number No Solo disponible para Ecuador. El importe imponible es el total de todos los items imponibles o gravables excluyendo el iva. Si no se envía, se calcula sobre el total. Formato: decimal con dos dígitos de fracción.
order.tax_percentage Number No Solo disponible para Ecuador. La tasa de impuesto que se aplicará a este pedido. Debe de ser 0 o 12.
order.months_grace Number No Solo disponible para México y Ecuador (Medianet), el número de meses de gracia para un pago diferido.
user.id String Yes Identificador del cliente. Este es el identificador que usa dentro de su aplicación.
user.first_name String No Nombre del Usuario.
user.last_name String No Apellido del Usuario.
user.email String Yes Correo electrónico del comprador, con formato de correo válido.
user.phone String No Numero de teléfono del comprador.
user.ip_address String No Direccion IP del usuario. Formato: IP v4 válida.
user.fiscal_number String No El número fiscal dado por el comprador. Nota: Para los tipos de tarjeta ex, ak, vr, sx, ol, ep y cd este campo es obligatorio.
card.number String Yes Un número de tarjeta de crédito válido.
card.holder_name String Yes El nombre del titular de la tarjeta de crédito.
card.expiry_month Number Yes El mes de expiración de la tarjeta de crédito.
card.expiry_year Number Yes El año de caducidad de la tarjeta de crédito.
card.cvc String Yes El número de seguridad de la tarjeta de crédito.
card.type String No Tipo de tarjeta abreviado. Revise las opciones válidas
extra_params Json No Parámetros opcionales (objetos 3DS 2 incluídos) utilizados para algunos comercios en formato Json. Por favor, póngase en contacto con su ejecutivo comercial para más detalles.
billing_address Json No Objeto con la dirección de facturación de la tarjeta, vea las especificaciones para la dirección.
shipping_address Json No Objeto con la dirección de envió del pedido, vea las especificaciones para la dirección.
airline Json No Objecto con datos de aerolínea, Vea las especificaciones para aerolínea.
hotel Json No Objeto con datos de hotel, Vea las especificaciones para hotel.
Respuesta

Ver Objetos en la respuesta

Split de pagos

curl -k  -L -X POST -H 'Content-Type: application/json' -H 'Auth-Token: auth_token' -d '{
    "user": {
        "id": "11",
        "email": "test@test.com"
    },
    "order": {
        "amount": 19000,
        "description": "Split TEST",
        "vat": 0,
        "dev_reference": "117"
    },
    "card": {
        "number": "4276981328765847",
        "holder_name": "Leidy Cruz",
        "expiry_month": 12,
        "expiry_year": 2022,
        "cvc": "355"
    },
     "extra_params": {
        "split": {
            "transactions": [
                {
                    "application_code": "APP_1",
                    "installments": 1,
                    "amount": 10000
                },
                {
                    "application_code": "APP_2",
                    "installments": 1,
                    "amount": 9000
                }
            ]
        }
    }
}' 'https://ccapi-stg.shieldgate.mx/v2/transaction/debit_cc'

Para el request previo, la respuesta es un JSON estructurado como sigue:

{
    "transaction": {
        "status": "success",
        "payment_date": "2021-02-09T15:58:00.272",
        "amount": 19000.0,
        "authorization_code": "845889",
        "installments": 1,
        "dev_reference": "117",
        "message": "Aprobado",
        "carrier_code": "00",
        "id": "RB-7",
        "status_detail": 3
    },
    "split": {
        "size": 2,
        "transactions": [
            {
                "installments": 1,
                "amount": 10000.0,
                "id": "RB-7-1",
                "application_code": "APP_1",
                "authorization_code": "845889"
            },
            {
                "installments": 1,
                "amount": 9000.0,
                "id": "RB-7-2",
                "application_code": "APP_2",
                "authorization_code": "152244"
            }
        ]
    },
    "card": {
        "bin": "427698",
        "expiry_year": "2022",
        "expiry_month": "12",
        "transaction_reference": "RB-7",
        "type": "vi",
        "number": "5847",
        "origin": "ORIGIN"
    }
}

En este endpoint podrán realizar pagos que permitiran dividir el monto total entre distintas aplicaciones (Disponible sólo para Colombia).

HTTP Request

POST https://ccapi-stg.shieldgate.mx/v2/transaction/debit_cc/

Parámetros URL
Parámetro Tipo Requerido Descripción
session_id String No Parámetro utilizado para el anti fraude. Hash numérico de longitud 32.
order.amount Number Yes Monto a cobrar. Formato: decimal con dos dígitos de fracción.
order.description String Yes Descripción de la orden a ser comprada. Formato: (Longitud Maxima 250)
order.dev_reference String Yes Referencia de la orden en el comercio. Usted identificará esta compra utilizando esta referencia
order.vat Number Yes Importe del impuesto sobre las ventas, incluido en el costo del producto. Formato: decimal con dos dígitos de fracción.
order.installments Number No El número de cuotas para el pago, solo para COP, MXN, BRL, PEN, CLP y USD (Ecuador).
user.id String Yes Identificador del cliente. Este es el identificador que usa dentro de su aplicación.
user.email String Yes Correo electrónico del comprador, con formato de correo válido.
user.phone String No Numero de teléfono del comprador.
user.ip_address String No Direccion IP del usuario. Formato: IP v4 válida.
user.fiscal_number String No El número fiscal dado por el comprador. Nota: Para los tipos de tarjeta ex, ak, vr, sx, ol, ep y cd este campo es obligatorio.
card.number String Yes Un número de tarjeta de crédito válido.
card.holder_name String Yes El nombre del titular de la tarjeta de crédito.
card.expiry_month Number Yes El mes de expiración de la tarjeta de crédito.
card.expiry_year Number Yes El año de caducidad de la tarjeta de crédito.
card.cvc String Yes El número de seguridad de la tarjeta de crédito.
card.type String No Tipo de tarjeta abreviado. Revise las opciones válidas
extra_params Json Yes Párametros necesarios para poder generar una transacción de split de pagos Ver párametros para split de pagos
Párametros para split
Parámetro Tipo Requerido Descripción
split.transactions Array Yes Arreglo con la información de cómo se dividirá el pago entre los distintos comercios/aplicaciones
split.transactions.application_code String Yes Aplicación que tiene la cuenta a la cual se enviará un monto parcial
split.transactions.amount Number Yes Monto parcial del total del pago
split.transactions.installments Number Yes Número de mensualidades a pagar para este monto parcial
Respuesta para split
Parámetro Descripción
transaction.status Puede ser success, failure, pending, expired* o **canceled.
transaction.payment_date En ambiente de pruebas la fecha estará en UTC, de lo contrario dependerá del Procesador.
transaction.amount El importe de la transacción.
transaction.authorization_code En caso de éxito el código de autorización que respondió el Procesador.
transaction.installments El número de cuotas para el pago.
transaction.dev_reference Referencia de la orden del comerciante.
transaction.message El mensaje devuelto por el Procesador o el sistema de análisis de fraude.
transaction.carrier_code El código devuelto del Procesador.
transaction.id Identificador de la transacción. Este código es único entre todas las transacciones.
transaction.status_detail El detalle del estado de la transacción, para más información, detalle del estado.
card.bin El BIN de la tarjeta (primeros seis dígitos de la tarjeta).
card.expiry_year El año en que expira la tarjeta.
card.expiry_month El mes de expiración de la tarjeta.
card.transaction_reference Si se regresa será un transaction.id
card.type Abreviatura del tipo de tarjeta. Revise las opciones válidas
card.number Los últimos cuatro dígitos de la tarjeta.
card.origin El origen de la tarjeta de crédito. Podría ser uno de los siguientes: Shieldgate, VisaCheckout, Masterpass.
split.transactions Arreglo que contiene las transacciones autorizadas en el pago con split
split.transactions.application_code Aplicación que corresponde a ese pago
split.transactions.amount Monto parcial del total de la orden
split.transactions.id Identificador de la transacción de split
split.transactions.installments Número de meses en que se parcializo la transacción
split.transactions.authorization_code Número de autorización de la transacción

Pasos para cobro con 3DS

Si desea realizar el cobro con su propio checkout web, será necesario incluir pasos extra en su desarrollo y realizar llamados en JavaScript a componentes del MPI de CyberSource. Estos pasos son para una integración tipo browser, NO para mobile.

Los pasos son los siguientes:

1. Obtener el reference_id y jwt.
curl -k  -L -H 'Content-Type: application/json' -H 'Auth-Token: auth-token'
'https://ccapi-stg.shieldgate.mx/v2/3ds/init/cybersource'

Para el request previo, la respuesta es un JSON estructurado como sigue:

{
  "jwt": "eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJSZWZlcmVuY2VJZCI6ICIxIiwgImlzcyI6ICI1ZmY0NDVlZTU1ZjEwNTcwOWUyNjljODkiLCAianRpIjogIjgxZGY0MzZjLWZmMzEtNDhiNi1iMGYwLTBkM2Y1Y2NjOGEwOSIsICJleHAiOiAxNjQ2OTU5MTgxLCAiaWF0IjogMTY0Njk1MTk4MSwgIk9yZ1VuaXRJZCI6ICI1ZmY0NDVlZTA5YzUwYjJkNDA4ZjcyMDkifQ==.zHfhpRXB4u8noaHnwvvWSw2lGJHwM4Uky9FNZjRBeIc=",
  "reference_id": "1"
}
HTTP Request

GET https://ccapi-stg.shieldgate.mx/v2/3ds/init/cybersource

Respuesta
Parámetro Descripción
reference_id Id único por transacción que será ocupado tanto en backend como en front end (a través del jwt).
jwt Token para autenticarse con el servicio front end de cybersource.
2. En su front end llamar al método init. Debe escuchar el evento payments.setupComplete para saber cuándo Songbird ha terminado de inicializarse.

En front end llamar al init. Continúe solo si el metodo de inicialización ha terminado.

<script src="https://includestest.ccdc02.com/cardinalcruise/v1/songbird.js"></script>
Cardinal.setup('init', {
        jwt: jwt,
        order: {
            Consumer: {
                Account: {
                    AccountNumber: bin,
                }
            }
        }
    });

Cardinal.on('payments.setupComplete', function () {
    // this is an example
    document.getElementById('init').disabled = true;
    document.getElementById('Authenticate').disabled = false;
});


Cardinal.on('payments.validated', function (data, jwt) {
    // This event is triggered when the transaction has been finished. This is how Songbird hands back control to the merchant's webpage.
    // You can call the verify, this is an example:
   Payment.verifyTransaction(user_id, transaction_id, 'BY_CRES', '', useCases, successCallback, errorCallback);
});

El componente javascript del MPI Cybersource es el siguiente: Para mayor información

Ambiente URL
development https://includestest.ccdc02.com/cardinalcruise/v1/songbird.js
production https://songbird.cardinalcommerce.com/edge/v1/songbird.js

Los parámetros necesarios para el Init:

Parámetro Descripción
bin Los primeros 6 dígitos de la tarjeta.
jwt Token obtenido en el paso anterior, para autenticarse con el servicio front end de cybersource.
3. En su backend llamar el debit with credit card.

Ejemplo de debit with creditcard.

curl -k  -L -X POST -H 'Content-Type: application/json' -H 'Auth-Token: auth_token' -d '{
    "user": {
        "id": "4",
        "email": "user@example.com",
        "phone": "1234567890123"
    },
    "order":{
        "amount": 11.1,
        "description": "una paleta",
        "vat": 0,
        "dev_reference": "referencia",
        "installments": 4
    },
    "card": {
        "number": "4456530000001047",
        "holder_name": "citlali calderon",
        "expiry_month": 12,
        "expiry_year": 2024,
        "cvc": "123",
        "type": "vi"
    },
     "billing_address": {
        "street": "Street Test",
        "house_number": "24",
        "city": "ciudad de mexico",
        "zip": "67890",
        "state": "DF",
        "country": "MEX",
        "district": "colonia",
        "additional_address_info": ""
    },
    "extra_params": {
        "threeDS2_data": {
            "term_url": "https://your.url.com/",
            "device_type": "browser",
            "reference_id": "2"
        },
        "browser_info": {
            "ip": "88.196.25.166",
            "language": "en-US",
            "java_enabled": false,
            "js_enabled": true,
            "color_depth": 24,
            "screen_height": 1200,
            "screen_width": 1920,
            "timezone_offset": 0,
            "user_agent": "Mozilla\/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/70.0.3538.110 Safari\/537.36",
            "accept_header": "text/html"
        }
    }
}' 'https://ccapi-stg.shieldgate.mx/v2/transaction/debit_cc'

Observaciones sobre algunos parámetros:

Parámetro Descripción
extra_params.threeDS2_data.term_url El url del merchant al cual se regresará.
extra_params.threeDS2_data.device_type Solo es posible browser.
extra_params.threeDS2_data.reference_id El reference_id obtenido en el paso 1.
billing_address La dirección de facturación es obligatoria para el MPI de CyberSource.

En la respuesta vendrá información necesaria para el siguiente paso:

Parámetro Descripción
3ds.browser_response.challenge_request Corresponde al AcsUrl.
3ds.browser_response.transaction_id Corresponde al TransactionId de CyberSource.
3ds.browser_response.pareq Corresponde al Payload.
4. Si el status_detail obtenido en el paso anterior fue 36, en su front end llamar el método continue.

En front end, llamar el continue.

<script src="https://includestest.ccdc02.com/cardinalcruise/v1/songbird.js"></script>
Cardinal.continue('cca',
        {
            "AcsUrl": browser_response.challenge_request,
            "Payload": browser_response.pareq,
        },
        {
            "OrderDetails": {
                "TransactionId": browser_response.transaction_id
            }
        }
    );

Los parámetros necesarios para el continue son: AcsUrl, TransactionId y Payload, recibidos en el paso anterior.

5. Si fue necesario el paso 4, procederá a llamar en su banckend al verify BY_CRES.

Ejemplo de verify BY_CRES:

curl -k  -L -X POST -H 'Content-Type: application/json' -H 'Auth-Token: auth-token' -d '{
  "user": {
    "id": "4"
  },
  "transaction": {
    "id": "RB-340"
  },
  "type": "BY_CRES",
  "value": "",
  "more_info": true

}' 'https://ccapi-stg.shieldgate.mx/v2/transaction/verify'

En este caso se mandará una cadena vacía en el value.

Tarjetas para probar diferentes escenarios:
Tarjeta Escenario
5200000000001096 challenge
5200000000001005 frictionless

Autorizar

Caso a) Enviando solo el card.token

curl -k  -L -X POST -H 'Content-Type: application/json' -H 'Auth-Token: auth_token' -d '{
    "user": {
        "id": "4",
        "email": "user@example.com"
    },
    "order": {
        "dev_reference": "referencia",
        "amount": 99.0,
        "description": "pozole",
        "vat": 0.00
    },
    "card": {
        "token": "6221308792087238335"
    }
}' 'https://ccapi-stg.shieldgate.mx/v2/transaction/authorize/'

Para el request previo, la respuesta es un JSON estructurado como sigue:

{
  "transaction": {
    "status": "success",
    "payment_date": "2017-09-26T21:03:04",
    "amount": 99.0,
    "authorization_code": "148177",
    "installments": 1,
    "dev_reference": "referencia",
    "message": "Operation Successful",
    "carrier_code": "4",
    "id": "CI-490",
    "status_detail": 0
  },
  "card": {
    "bin": "453254",
    "status": "valid",
    "token": "10135134879450157925",
    "expiry_year": "2020",
    "expiry_month": "9",
    "transaction_reference": "CI-490",
    "type": "vi",
    "number": "8311",
    "origin": "ORIGIN"
  }
}

Caso b) Enviando toda la información de la tarjeta (comercios pci)

curl -k  -L -X POST -H 'Content-Type: application/json' -H 'Auth-Token: auth_token' -d '{
    "user": {
        "id": "4",
        "email": "user@example.com"
    },
    "order": {
        "dev_reference": "referencia",
        "amount": 99.0,
        "description": "pozole",
        "vat": 0.00
    },
    "card": {
            "number": "4507000397186651",
            "holder_name": "citlali calderon",
            "expiry_month": 9,
            "expiry_year": 2020,
            "cvc": "123",
            "type": "vi"
    }
}' 'https://ccapi-stg.shieldgate.mx/v2/transaction/authorize/'

Para el request previo, la respuesta es un JSON estructurado como sigue:

{
  "transaction": {
    "status": "success",
    "payment_date": "2017-09-26T21:02:04",
    "amount": 99.0,
    "authorization_code": "148177",
    "installments": 1,
    "dev_reference": "referencia",
    "message": "Operation Successful",
    "carrier_code": "4",
    "id": "CI-491",
    "status_detail": 0
  },
  "card": {
    "bin": "450700",
    "expiry_year": "2020",
    "expiry_month": "9",
    "transaction_reference": "CI-491",
    "type": "vi",
    "number": "6651"
  }
}

Este endpoint envía para autorización una transacción de Tarjeta de Crédito (solo para Cielo (BRL), Prosa (MXN), Procesos y Visanet (PEN))

Si desea autorizar con la autenticación 3D Secure 2, hay dos formas posibles:

  1. Autorización directa con Shieldgate by Afirme. Esto incluirá parámetros adicionales en la solicitud, que se utilizan para la autenticación (Revise objetos para autenticación)

  2. Realizando la autenticación llamando el endpoint adecuado Sección Authentication 3DS 2, antes de realizar la autorización.

HTTP Request

POST https://ccapi-stg.shieldgate.mx/v2/transaction/authorize/

Parámetros URL
Parámetro Tipo Requerido Descripción
session_id String No Parámetro utilizado para el anti fraude. Hash numérico de longitud 32.
order.amount Number Yes Monto a cobrar. Formato: decimal con dos dígitos de fracción.
order.description String Yes Descripción de la orden a ser comprada. Formato: (Longitud Máxima 250)
order.dev_reference String Yes Referencia de la orden en el comercio. Usted identificará esta compra utilizando esta referencia
order.vat Number Yes Importe del impuesto sobre las ventas, incluido en el costo del producto. Formato: decimal con dos dígitos de fracción.
order.installments Number No El número de cuotas para el pago, solo para COP, MXN, BRL, PEN, CLP y USD (Ecuador).
order.installments_type Number No Solo disponible para Ecuador y México. Revise los valores permitidos
order.months_grace Number No Solo disponible para México y Ecuador (Medianet), el número de meses de gracia para un pago diferido.
user.id String Yes Identificador del cliente. Este es el identificador que usa dentro de su aplicación.
user.first_name String No Nombre del Usuario.
user.last_name String No Apellido del Usuario.
user.email String Yes Correo electrónico del comprador, con formato de correo válido.
user.phone String No Numero de teléfono del comprador.
user.ip_address String No Direccion IP del usuario. Formato: IP v4 válida.
card.token String No (*) Identificador de tarjeta. Este código es único entre todas las tarjetas. Formato: Long Integer.
card.number String No Un número de tarjeta de crédito válido.
card.holder_name String No (*) El nombre del titular de la tarjeta de crédito.
card.expiry_month Number No (*) El mes de expiración de la tarjeta de crédito.
card.expiry_year Number No (*) El año de caducidad de la tarjeta de crédito.
card.cvc String No (*) El número de seguridad de la tarjeta de crédito.
card.type String No (*) Tipo de tarjeta abreviado. Revise las opciones válidas
extra_params Json No Parámetros opcionales (objetos 3DS 2 incluídos) utilizados para algunos comercios en formato Json. Por favor, póngase en contacto con su ejecutivo comercial para más detalles.
billing_address Json No Objeto con la dirección de facturación de la tarjeta, vea las especificaciones para la dirección.
shipping_address Json No Objeto con la dirección de envió del pedido, vea las especificaciones para la dirección.
airline Json No Objecto con datos de aerolínea, Vea las especificaciones para aerolínea.
hotel Json No Objeto con datos de hotel, Vea las especificaciones para hotel.
Respuesta

Ver Objetos en la respuesta

Captura

curl -k  -L -X POST -H 'Content-Type: application/json' -H 'Auth-Token: auth_token' -d '{
    "transaction": {
        "id": "CI-325"
    }
}' 'https://ccapi-stg.shieldgate.mx/v2/transaction/capture/'

Para el request previo, la respuesta es un JSON estructurado como sigue:

{
  "transaction": {
    "status": "success",
    "payment_date": "2017-09-26T21:03:04",
    "amount": 99.0,
    "authorization_code": "148177",
    "installments": 1,
    "dev_reference": "referencia",
    "message": "Operation Successful",
    "carrier_code": "6",
    "id": "CI-490",
    "status_detail": 3
  },
  "card": {
    "bin": "453254",
    "status": "valid",
    "token": "10135134879450157925",
    "expiry_year": "2020",
    "expiry_month": "9",
    "transaction_reference": "CI-490",
    "type": "vi",
    "number": "8311"
  }
}

Este endpoint captura o cierra una transacción autorizada (solo para Cielo (BRL), Prosa (MXN) Procesos y VisaNet (PEN))

HTTP Request

POST https://ccapi-stg.shieldgate.mx/v2/transaction/capture/

Parámetros URL
Parámetro Tipo Requerido Descripción
transaction.id String Yes Identificador de la transacción. Este código es único entre todas las transacciones.
order.amount Number No El monto del pedido a capturar, puede ser mayor o menor que el original (Prosa MXN) o solo menor (Cielo BRL, Procesos y VisaNet (PEN)). Formato: decimal con dos dígitos de fracción. Si no se proporciona, se capturará el monto total de la autorización original.
Respuesta

Ver Objetos en la respuesta

Verificar

curl -k  -L -X POST -H 'Content-Type: application/json' -H 'Auth-Token: auth_token' -d '{
    "user": {
        "id": "4"
    },
    "transaction": {
        "id": "CI-316"
    },
    "type": "BY_AMOUNT",
    "value": "99.99"

}' 'https://ccapi-stg.shieldgate.mx/v2/transaction/verify'

Para el request previo, la respuesta es un JSON estructurado como sigue:

{
  "status": 1,
  "payment_date": "2017-09-26T21:16:00",
  "amount": 99.0,
  "transaction_id": "CI-491",
  "status_detail": 3,
  "message": ""
}

Para el caso cuando se mande more_info = true, este es un ejemplo:

{
  "transaction": {
    "status": "failure",
    "payment_date": null,
    "amount": 11.1,
    "authorization_code": null,
    "installments": 1,
    "dev_reference": "referencia",
    "message": null,
    "carrier_code": null,
    "id": "RB-5969",
    "status_detail": 37
  },
  "card": {
    "bin": "401600",
    "status": "",
    "token": "",
    "expiry_year": "2020",
    "expiry_month": "9",
    "transaction_reference": "RB-5969",
    "type": "vi",
    "number": "0051",
    "origin": "ORIGIN"
  },
  "3ds": {
    "sdk_response": {
      "acs_trans_id": "00000000-0005-5a5a-8000-016ab2e4246c",
      "acs_signed_content": null,
      "acs_reference_number": "JCB0002"
    },
    "authentication": {
      "status": "U",
      "return_message": "U-status/Challenge authentication via ACS: ",
      "version": null,
      "xid": "MDAwMDAwMDAwMDAwMDAwMDAyMDg=",
      "reference_id": "ffffffff-9002-51a3-8000-0000000345a2",
      "cavv": null,
      "return_code": "5",
      "eci": null
    },
    "browser_response": {
      "hidden_iframe": "",
      "challenge_request": ""
    }
  }
}

Después de haber realizado una transacción, haya sido a través de Agregar una Tarjeta, un Cobro con token, un Cobro con tarjeta o una *Autorización, si el status en la respuesta de la transacción es pending, este endpoint debe llamarse después de eso.

A veces, al agregar una tarjeta o al realizar un cobro, la transacción podría necesitar verificarse, con un código de la entidad financiera que realiza el cargo en la tarjeta. Otro caso que necesita verificación es cuando el emisor de la tarjeta envía un OTP al usuario para continuar con la transacción, o después de que el comprador haya sido desafiado en una transacción 3DS 2.

Cuando el comprador obtiene el código de verificación de su banco, o cuando el comprador obtiene el SMS con el OTP, o cuando el comerciante obtiene el resultado de la respuesta de desafío, es posible verificar la operación haciendo una solicitud para:

HTTP Request

POST https://ccapi-stg.shieldgate.mx/v2/transaction/verify

Parámetros URL
Parámetro Tipo Requerido Descripción
transaction.id String Yes Identificador de la transacción. Este código es único entre todas las transacciones.
user.id String Yes Identificador del cliente. Este es el identificador que usa dentro de su aplicación.
type String Yes El tipo de valor que se enviará en la solicitud. Cadenas válidas "BY_AMOUNT", "BY_AUTH_CODE", "BY_OTP", "BY_CRES" y "AUTHENTICATION_CONTINUE".
value String Yes Podría ser el código de autorización proporcionado por la entidad financiera al comprador, el monto de la transacción, la contraseña de un solo uso (OTP), la respuesta de desafío (CRES) o una cadena vacía en el caso de AUTHENTICATION_CONTINUE.
more_info Boolean No true o false para determinar si la respuesta incluirá más información sobre la transacción.
Respuesta
Parámetro Descripción
status El estado de la transacción, para más información status detail
payment_date En ambiente de pruebas la fecha estará en UTC, de lo contrario dependerá del Procesador.
amount El importe de la transacción.
transaction_id Identificador de la transacción. Este código es único entre todas las transacciones.
status_detail El detalle del estado de la transacción, para más información, detalle del estado.
message Si el tipo de verificación fue "BY_OTP", el mensaje de respuesta en caso de falla.

Si envía more_info con el valor true: Ver Objetos en la respuesta

Moneda Monto total
COP 256
CRC 256
CLP 256
USD 2.56
BRL 2.56
PEN 2.56
SGD 2.56
MXN 25.6
HNL 25.6
NIO 25.6
UYU 25.6
ARS 128

Reembolso

curl -k  -L -X POST -H 'Content-Type: application/json' -H 'Auth-Token: auth_token' -d '{
    "transaction": {
        "id": "CI-311"
    }
}' 'https://ccapi-stg.shieldgate.mx/v2/transaction/refund/'

Para el request previo, la respuesta es un JSON estructurado como sigue:

{
  "status": "success",
  "detail": "Completed"
}

Ejemplo de reembolso con monto parcial

curl -k  -L -X POST -H 'Content-Type: application/json' -H 'Auth-Token: auth_token' -d '{
    "transaction": {
        "id": "CI-311"
    },
    "order": {
        "amount": 11.10
    }
}' 'https://ccapi-stg.shieldgate.mx/v2/transaction/refund/'

Ejemplo de request con reference_label. Para QR Colombia unicamente.

curl -k  -L -X POST -H 'Content-Type: application/json' -H 'Auth-Token: auth_token' -d '{
    "transaction": {
        "reference_label": 1234567891011141618
    }
}' 'https://ccapi-stg.shieldgate.mx/v2/transaction/refund/'

Ejemplo de request, con el parámetro 'more_info'

curl -k  -L -X POST -H 'Content-Type: application/json' -H 'Auth-Token: auth_token' -d '{
    "transaction": {
        "id": "PR-11"
    },
    "order": {
        "amount": 8.00
    },
    "more_info": true
}' 'https://ccapi-stg.shieldgate.mx/v2/transaction/refund/'

Ejemplo de respuesta con more info

{
  "status": "success",
  "transaction": {
    "status": "success",
    "payment_date": "2020-02-11T00:39:58.477",
    "authorization_code": "TEST00",
    "refund_amount": 8.0,
    "dev_reference": "referencia",
    "carrier_code": null,
    "status_detail": 34,
    "amount": 11.1,
    "installments": 1,
    "message": "Reverse by mock",
    "id": "PR-11"
  },
  "detail": "Completed partial refunded with 8.0",
  "card": {
    "bin": "400000",
    "status": "",
    "token": "",
    "expiry_year": "2020",
    "expiry_month": "9",
    "transaction_reference": "PR-11",
    "type": "vi",
    "number": "0077",
    "origin": "ORIGIN"
  }
}

Este endpoint se utiliza para reembolsar una transacción.

HTTP Request

POST https://ccapi-stg.shieldgate.mx/v2/transaction/refund/

Parámetros URL
Parámetro Tipo Requerido Descripción
transaction.id String Yes (*) Identificador de la transacción. Este código es único entre todas las transacciones.
transaction.reference_label Number Yes (*) Únicamente para QR Colombia. Referencia de una transacción.
order.amount Number No El importe del pedido a reembolso. Formato: decimal con dos dígitos de fracción. Si no se proporciona, el importe total de la transacción. Funciona con Cielo (BRL), Prosa (MXN), Credibanco y Redeban (COP) (**).
more_info Boolean No true o false para determinar si la respuesta incluirá más información sobre la transacción.
Respuesta
Parámetro Descripción
status Podría ser uno de los siguientes: success, pending o failure
detail Si es success pudiera ser Completed o Completed partial refunded with NN.NN donde NN.NN es el monto del reembolso parcial. Si es failure puede ser Error: Not completed, Transaction already refunded o Invalid Status. Si es pending, Waiting gateway confirmation o Waiting gateway confirmation for partial refund with NN.NN.

Void

curl -k  -L -X POST -H 'Content-Type: application/json' -H 'Auth-Token: auth_token' -d '{
    "transaction": {
        "id": "PR-11"
    },
}' 'https://ccapi-stg.shieldgate.mx/v2/transaction/void/'

Para el request previo, la respuesta es un JSON estructurado como sigue:

{
  "transaction": {
    "status": "success",
    "payment_date": "2022-08-11T18:52:32",
    "amount": 99.0,
    "authorization_code": "148177",
    "installments": 1,
    "dev_reference": "referencia",
    "message": "Operation Successful",
    "carrier_code": null,
    "id": "PR-11",
    "status_detail": 29
  },
  "card": {
    "bin": "453254",
    "status": "valid",
    "token": "10135134879450157925",
    "expiry_year": "2025",
    "expiry_month": "10",
    "transaction_reference": "PR-11",
    "type": "vi",
    "number": "8311"
  }
}

Este endpoint cancela una transacción autorizada (solo Prosa (MXN))

HTTP Request

POST https://ccapi-stg.shieldgate.mx/v2/transaction/void/

Parámetros URL
Parámetro Tipo Requerido Descripción
transaction.id String Yes (*) Identificador de la transacción. Este código es único entre todas las transacciones.
Respuesta

Ver Objetos en la respuesta

Información de la Trasacción

curl -k  -L -H 'Content-Type: application/json' -H 'Auth-Token: auth_token'
 'https://ccapi-stg.shieldgate.mx/v2/transaction/<transaction_id>/'

Para el request previo, la respuesta es un JSON estructurado como sigue:

{
  "transaction": {
    "status": "pending",
    "payment_date": "2018-01-26T23:49:51.100Z",
    "amount": 10,
    "authorization_code": "",
    "installments": 1,
    "dev_reference": "",
    "status_detail": 0,
    "carrier_code": "",
    "message": "",
    "id": ""
  },
  "card": {
    "bin": "400552",
    "holder_name": "First Dev",
    "number": "4821",
    "expiry_year": "2020",
    "expiry_month": "12",
    "type": "vi",
    "origin": "ORIGIN"
  }
}

Este endpoint es usado para obtener información de la transacción

HTTP Request

GET https://ccapi-stg.shieldgate.mx/v2/transaction/<transaction_id>

Parámetros URL
Parámetro Tipo Requerido Descripción
transaction_id String Yes Shieldgate by Afirme transaction_id
Respuesta
Parámetro Descripción
transaction.status Puede ser success, failure, pending, expired* o **canceled.
transaction.payment_date En ambiente de pruebas la fecha estará en UTC, de lo contrario dependerá del Procesador.
transaction.amount El importe de la transacción.
transaction.authorization_code En caso de éxito el código de autorización que respondió el Procesador.
transaction.installments El número de cuotas para el pago.
transaction.dev_reference Referencia de la orden del comerciante.
transaction.message El mensaje devuelto por el Procesador o el sistema de análisis de fraude.
transaction.carrier_code El código devuelto del Procesador.
transaction.id Identificador de la transacción. Este código es único entre todas las transacciones.
transaction.status_detail El detalle del estado de la transacción, para más información, detalle del estado.
card.bin El BIN de la tarjeta (primeros seis dígitos de la tarjeta).
card.expiry_year El año en que expira la tarjeta.
card.expiry_month El mes de expiración de la tarjeta.
card.transaction_reference Si se regresa será un transaction.id
card.type Abreviatura del tipo de tarjeta. Revise las opciones válidas
card.number Los últimos cuatro dígitos de la tarjeta.
card.origin El origen de la tarjeta de crédito. Podría ser uno de los siguientes: Shieldgate, VisaCheckout, Masterpass.

Marcas de tarjetas

Internacionales

Tipo de Tarjeta Marca Logotipo
vi Visa
mc Mastercard
ax American Express
di Diners
dc Discover
ms Maestro

México

Tipo de Tarjeta Marca Logotipo
cn Carnet

LinkToPay

En esta plataforma, podemos generar un enlace de pago, que se puede completar con cualquiera de los métodos de pago asignados a las credenciales de acceso.

Generar un enlace

Ejemplo de request para generar un enlace.

curl --request POST
  --url https://noccapi-stg.shieldgate.mx/linktopay/init_order/
  --header 'auth-token: auth-token'
  --header 'content-type: application/json'
  --data '{
    "user": {
        "id": "117",
        "email": "dummy@foo.com",
        "name": "Gabriel",
        "last_name": "Cruz"
    },
    "order": {
        "dev_reference": "1",
        "description": "Product description",
        "amount": 1000,
        "installments_type": 0,
        "currency": "COP"
    },
    "configuration": {
        "partial_payment": true,
        "expiration_days": 1,
        "allowed_payment_methods": ["All"],
        "success_url": "https://url-to-success.com",
        "failure_url": "https://url-to-failure.com",
        "pending_url": "https://url-to-pending.com",
        "review_url": "https://url-to-review.com"
    }
}'

Ejemplo de request para generar un enlace con datos de dirección (billing_address)

curl --request POST
  --url https://noccapi-stg.shieldgate.mx/linktopay/init_order/
  --header 'auth-token: auth-token'
  --header 'content-type: application/json'
  --data '{
    "user": {
        "id": "117",
        "email": "dummy@foo.com",
        "name": "Gabriel",
        "last_name": "Cruz"
    },
    "order": {
        "dev_reference": "1",
        "description": "Product description",
        "amount": 1000,
        "installments_type": 0,
        "currency": "COP"
    },
    "configuration": {
        "partial_payment": true,
        "expiration_days": 1,
        "allowed_payment_methods": ["Card"],
        "success_url": "https://url-to-success.com",
        "failure_url": "https://url-to-failure.com",
        "pending_url": "https://url-to-pending.com",
        "review_url": "https://url-to-review.com"
    },
   "billing_address": {
         "street": "Calle 1 Sur",
         "city": "Chia",
         "country": "COL",
         "district": "Chia",
         "zip": "#5",
         "state": "CU",
         "house_number": "179",
         "additional_address_info": "Casa 53"
 }
}'

Para el request previo, la respuesta es un JSON estructurado como sigue:

{
    "success": true,
    "detail": "Operation completed successfully.",
    "data": {
        "user": {
            "id": "117",
            "email": "dummy@foo.com"
        },
        "order": {
            "id": "8REV4qMyevlR4xGm3OL",
            "status": "Init",
            "dev_reference": "1",
            "description": "Product description",
            "currency": "COP",
            "amount": 1000.0,
            "taxes": [
                {
                    "type": "vat",
                    "amount": 0
                },
                {
                    "type": "inc",
                    "amount": 0
                }
            ],
            "additional_amounts": [
                {
                    "type": "tip",
                    "amount": 0
                }
            ]
        },
        "configuration": {
            "expiration_date": "2022-11-19 18:45:39",
            "partial_payment": true,
            "allowed_payment_methods": [
                "All"
            ],
            "allow_retry": true
        },
        "payment": {
            "payment_url": "https://link-stg.shieldgate.mx./checkout/8REV4qMyevlR4xGm3OL",
            "payment_qr": "iVBORw0KGgoAAAANSUhEUgAAAZoAAAGaAQAAAAAefbjOAAADC0lEQVR4nO2cXa7aMBBGz9SReDRSF8BSzA7ukq66s2Q
                           pLAApeURK9PXBdhJoVaniFigZP6Ak5Ahbsebnmwkm/np03/6eAYcccsghhxxy6D0hK6PJRzCYme2Bbjk1Mzs+ZXoOPR
                           5KkqQe1MYRO0aJ1E9GkmRHgiRJ19DjpufQ46GhGoB02kk/9kBnO2VDAWBmzfOm59DDoObm3IgXUzoZAvh9bvria3LoS6
                           HUgx0JotsDMJnaf/JLDr0kVG1EFDDUq90+YGAIQrYTa2vx4mty6AugzmpywbATqQdSH2THocGOTFaSkOdMz6FH24hfwo
                           V4MbrDxej2WLEgz5ieQw+HyFllkoplII4lGW1v7ozlPrUvviaH7oHqjuhB0ojUl8CB1AdJGoFYNkhWJXxHvDNUHrL6UL
                           ZFG8e6NyTV0+ujF1+TQ/dAV15D8+iD1BJUnMhsLdxrvD1UdkQOEuo+qB5iBLgxHr4j3hyac42pUXcYsSTKR/5i+I6KVh
                           W8rrEBqMYR2R5QPES7MhnMX3hkuQUo2wgjnlH3cc6GAoByFM+NuiNopVq8+Jocuh/KUWQ67QRDg332U9Uns4QZZLafXL
                           PcALT2GqlmEyWUJJSeCVXByr3GZqBuHwTDrjz4FlgkzGIe4ngDPW56Dj3BRix6xFgz0jyCFtXK9Yj3h2aXUPOKlGXrpb
                           hRXMf62ouvyaF7oLmuEVTLF+FKq4ql1uFxxEagqlANIAZDSQDxYsVtDA10HyMkTbW95sXX5NA90NxnOZmIgu7jPGsUPU
                           Y8N5ZjTNcsNwTV9qm5SyqHFZNlPaJ0WLkesQVolWssGcZS5FIbrzQKjyM2Ai3vdOUYs6vvZtiRoBJMHFyP2AK06o/IKc
                           Xy0UaJXA3Pt3g1fAvQqquupKCrnJN1k533WW4TUhsvOZ4029f6Vs41hqbI2//bmhy6C0qnhlLDiCNqo2qThNc1NgXND7
                           47jNjnqUFtTUbNDvO2eNL0HHoYdFvVysHE3FiZrxGvimEeR7wzZL9/+/uPw/+ZzCGHHHLIIYccAvgJATB20GiZw/kAAA
                           AASUVORK5CYII="
        }
    }
}

Para generar un enlace para pagar, se requiere cierta información, esto permite consumir cualquier método de pago provisto por Shieldgate by Afirme

HTTP Request

POST https://noccapi-stg.shieldgate.mx/linktopay/init_order/

Parámetros URL
Parámetro Tipo Requerido Descripción
user.id String Yes Identificador del comprador. Longitud máxima 250 caracteres.
user.email String Yes Correo electrónico del comprador, con formato de correo electrónico válido. Longitud máxima 250 caracteres.
user.name String Yes Nombre del comprador. Longitud máxima 100 caracteres.
user.last_name String Yes Nombre del comprador. Longitud máxima 100 caracteres.
user.fiscal_number_type String No Indica el tipo de número fiscal (identificación del usuario).
user.fiscal_number String No Número fiscal (número de identificación) dado por el usuario. Longitud máxima 100 caracteres.
order.dev_reference String Yes Identificación del comercio para identificar el pedido. Longitud máxima 100 caracteres.
order.description String Yes La descripción del pedido. Longitud máxima 250 caracteres.
order.amount Number Yes Importe total a pagar. Formato: decimal con dos dígitos de fracción.
order.installments_type Number Yes Para Ecuador y México Revise los tipos válidos. Para el resto de los países, 0 para permitir cuotas, -1 en caso contrario. Sólo disponible para pago con tarjeta.
order.vat Number Yes Impuesto sobre las ventas, incluido en el importe del pedido. Formato: decimal con dos dígitos de fracción.
order.inc Number No Impuesto nacional al consumo, incluido en el importe del pedido. Formato: decimal con dos dígitos de fracción.
order.tip Number No Solo disponible para Pago con código Qr. La Propina, adicional al importe del pedido. Formato: Decimal con dos digitos de fracción.
order.taxable_amount Number No Solo disponible para Ecuador y Colsubsidio. El importe imponible es el total de todos los items imponibles o gravables excluyendo el iva. Si no se envía, se calcula sobre el total. Formato: decimal con dos dígitos de fracción.
order.tax_percentage Number No Solo disponible para Ecuador y Colsubsidio. La tasa de impuesto que se aplicará a este pedido. Debe de ser 0 o 12.
order.currency String Yes Moneda de la orden Revise los tipos válidos.
configuration.partial_payment Boolean Yes Indica si el pago parcial está permitido.
configuration.expiration_days Number No(*) Número de días en que vence el enlace a pagar.
configuration.expiration_time Number No(*) Tiempo en segundos que tardará en vencer el enlace para pagar.
configuration.allowed_payment_methods Array (String) No Indica los métodos de pago permitidos. 'All' es el valor predeterminado. Revise los tipos válidos.
configuration.currency_exchange String No Moneda en la cual se pagará la orden Revise los tipos válidos.
configuration.success_url String Yes URL para redireccionar cuando la transacción es exitosa.
configuration.failure_url String Yes URL para redireccionar cuando la transacción falla.
configuration.pending_url String Yes URL para redireccionar cuando la transacción está pendiente.
configuration.review_url String Yes URL para redireccionar cuando se revisa la transacción.
billing_address.street String No El nombre de la calle.
billing_address.city String Yes El nombre de la ciudad, máximo de 50 caracteres.
billing_address.state String No El estado. Formato 3166-2 código de 2 caracteres en caso de transacciones que se autenticarán con 3DS, formato libre en otro caso.
billing_address.district String No El distrito.
billing_address.zip String Yes Código Postal, máximo de 50 caracteres.
billing_address.house_number String No El número de la casa.
billing_address.country String Yes País en formato ISO 3166-1 alpha-3, por ejemplo: COL, MEX, ECU.
billing_address.additional_address_info String No Información adicional, sin formato.
Respuesta
Parámetro Descripción
user.id Identificador del comprador.
user.email Correo electrónico del comprador registrado en el pedido.
order.dev_reference Referencia del comercio.
order.amount Importe total a pagar.
order.description Descripción del pedido.
configuration.expiration_date Fecha límite para pagar.
configuration.partial_payment Indica si el pago parcial está permitido.
configuration.allowed_payment_methods Indica los métodos de pago permitidos.
payment.payment_url Link Para Pagar, URL al cual redireccionar.
payment.payment_qr Code Qr base64, URL al cual redireccionar.

Monedas

Monedas permitidas.

Moneda País
COP Colombia
USD Ecuador, El Salvador, Panamá
BRL Brasil
MXN México
ARS Argentina
CLP Chile
PEN Perú
GTQ Guatemala
HNL Honduras
NIO Nicaragua
CRC Costa Rica

Métodos de pago permitidos

Métodos de pago permitidos por país:

Llave Descripción
All Todos los métodos de pago
Card Sólo método de pago con tarjeta (Todos los países)
BankTransfer Sólo método de pago transferencia bancaria (Colombia)
Cash Sólo pago en efectivo ó pago por referencia (Colombia, México, Ecuador)
Colsubsidio Sólo colsubsidio en Colombia
EWallet Sólo pago por monedero electrónico (Colombia)
Qr Sólo método de pago con código Qr(Colombia)
Pix Sólo método de pago Pix(con código Qr para Brazil)
Rappi Sólo método de pago Paga con Rappi (Colombia)

Integraciones de terceros

VTEX

Contamos con implementación en la plataforma de eCommerce VTEX.

Para mayor información visite el siguiente manual.

Tarjetas de Prueba

Usted puede utilizar las siguientes tarjetas para sus pruebas. Para añadir una tarjeta o realizar un cobro directo en ambiente staging:

Tarjeta Código de retorno Escenarios
4111111111111111, 36417002140808 valid Cargo exitoso
5119159076977991, 370236553676505 review El cargo se encuentra en revisión
4242424242424242, 347763907473248 rejected No autorizado
4520121813132351, 378196561987405 rejected Rechazado por el sistema antifraude
375953548754701, 376337093362277 rejected Tarjeta en black list

Para cualquier tarjeta que no se encuentre en la lista previa, el sistema dejará la tarjeta como válida. Una vez que usted añada una tajeta válida en la plataforma, podrá probar el cobro con token utilizando una descripción específica, como sigue:

order.description Resultado
Approved transaction status = success, status_detail = 3
Denied transaction status = failure, status_detail = 9
Reviewed transaction status = pending, status_detail = 1
Rejected by fraud system transaction status = failure, status_detail = 11
Card in black list status = failure, status_detail = 12

Usted puede utilizar ya sea las tarjetas de prueba o las descripciones para probar, pero no ambas.

WebHook

El siguiente es el JSON regresado en el WebHook:

{
  "transaction": {
     "status": "1",
     "order_description": "ORDER #1507155336536",
     "authorization_code": "113310",
     "status_detail": "3",
     "date": "04/10/2017 22:15:37",
     "message": "Operation Successful",
     "id": "CI-502",
     "dev_reference": "1507155336536",
     "carrier_code": "6",
     "amount": "10.5",
     "paid_date": "04/10/2017 19:15:00",
     "installments": "1",
     "ltp_id": "LeNgJbx57Vnj9Rnq",
     "stoken": "e03f67eba6d730d8468f328961ac9b2e",
     "application_code": "AndroidTest",
     "terminal_code": "12334"
  },
  "user": {
     "id": "4",
     "email": "user@example.com"
  },
  "card": {
     "bin": "411111",
     "holder_name": "Martin Mucito",
     "type": "vi",
     "number": "1111",
     "origin": "ORIGIN",
     "fiscal_number": "2365448809"
  }
}

Ejemplo de la generación de stoken (python):


transaction_id = 123
app_code = HF
user_id = 123456
app_key = 2GYx7SdjmbucLKE924JVFcmCl8t6nB
for_md5 = “123_HF_123456_2GYx7SdjmbucLKE924JVFcmCl8t6nB”
stoken = hashlib.md5(for_md5).hexdigest()

Entonces el stoken para este ejemplo es e242e78ae5f1ed162966f0eacaa0af01

El siguiente es un ejemplo del JSON regresado para el caso de Split de Pagos:

{
  "transaction": {
     "status": "1",
     "order_description": "ORDER #1507155336536",
     "authorization_code": "113310",
     "status_detail": "3",
     "date": "04/10/2017 22:15:37",
     "stoken": "e03f67eba6d730d8468f328961ac9b2e",
     "application_code": "AndroidTest",
     "status": "1",
     "paid_date": "04/10/2017 22:15:37",
     "amount": "19000.0",
     "authorization_code": "615246",
     "installments": "1",
     "dev_reference": "11372",
     "message": "Aprobado",
     "carrier_code": "00",
     "id": "RB-37",
     "status_detail": "3"
  },
  "split": {
    "transactions": [
      {
        "installments": "1",
        "amount": "10000.0",
        "id": "RB-37-1",
        "application_code": "App2",
        "authorization_code": "615246"
      },
      {
        "installments": "1",
        "amount": "9000.0",
        "id": "RB-37-2",
        "application_code": "App1",
        "authorization_code": "580705"
      }
    ]
  },
  "card": {
    "bin": "377813",
    "holder_name": "Martin Mucito",
    "type": "ax",
    "number": "9063",
    "origin": "ORIGIN"
  }
}

El siguiente es un ejemplo del JSON regresado para el caso de pago con Efectivo o Transferencia Bancaria

{
  "transaction": {
     "status": "1",
     "order_description": "ORDER #1507155336536",
     "status_detail": "3",
     "date": "04/01/2020 22:15:37",
     "id": "PSE-1000",
     "payment_method_type": "2",
     "dev_reference": "1507155336536",
     "amount": "10.5",
     "paid_date": "04/10/2017 19:15:00",
     "ltp_id": "LeNgJbx57Vnj9Rnq",
     "stoken": "e03f67eba6d730d8468f328961ac9b2e",
     "application_code": "AndroidTest",
     "terminal_code": "12334"
  },
  "user": {
     "id": "4",
     "email": "user@example.com"
  }
}

Cada vez que una transacción sea aprobada o cancelada usted recibirá un HTTP POST request de Shieldgate by Afirme, a su callback_url (debe proporcionar esta url a nuestro personal). El POST incluye los siguientes campos:

Parámetro Descripción
transaction.status El estado de la transacción, para mayor información: status
transaction.order_description Descripción de la orden a ser comprada. Formato: (Longitud Máxima 250)
transaction.authorization_code En caso de éxito el código de autorización que respondió el Procesador.
transaction.status_detail El detalle del estado de la transacción, para más información, detalle del estado.
transaction.date Fecha de la transacción (dato usado para estadísticas en Dashboard).
transaction.message El mensaje devuelto por el Procesador o el sistema de análisis de fraude.
transaction.id Identificador de la transacción. Este código es único entre todas las transacciones.
transaction.dev_reference Referencia de la orden del comerciante.
transaction.carrier_code El código devuelto del Procesador.
transaction.amount El importe de la transacción.
transaction.paid_date Fecha de pago de la transacción (dato usado para estadísticas en Dashboard).
transaction.installments El número de cuotas para el pago.
transaction.stoken Hash MD5 de [transaction_id]_[application_code]_[user_id]_[app_key]
transaction.ltp_id Código de referencia del Link de Pago con el que se realizó el Pago.
transaction.application_code La transacción se realizó con este código de aplicación.
transaction.payment_method_type Tipo de método de pago de la transacción, para mas información payment_method_types
transaction.terminal_code Terminal id de la transacción.
user.id Identificador del cliente. Este es el identificador que usa dentro de su aplicación.
user.email Correo electrónico del comprador, con formato de correo válido.
card.bin El BIN de la tarjeta (primeros seis dígitos de la tarjeta).
card.holder_name El nombre del titular de la tarjeta de crédito.
card.type Abreviatura del tipo de tarjeta. Revise las opciones válidas
card.number Los últimos cuatro dígitos de la tarjeta.
card.origin El origen de la tarjeta de crédito. Podría ser uno de los siguientes: Shieldgate, VisaCheckout, Masterpass.
card.fiscal_number Número fiscal del pagador de la transacción.

Para cada transacción debe regresar un HTTP status, este status es usado para determinar si usted recibió correctamente la información:

Estado Caso
200 exito
203 error con el token

Usted necesita generar el stoken y compararlo con el que recibe, para cerciorarse de que el POST provenga de Shieldgate by Afirme . Usted debe de guardar esta información proveniente de todas las transacciones, en su base de datos, y siempre verificar el transaction.id para evitar duplicidades.

Si su servidor no responde con el mensaje HTTP 200 se seguirá reintentando durante 48 horas, con períodos de tiempo incrementales, es decir primer reintento se realizará a los 5 min aprox, segundo reintento a los 10 min aprox y así sucesivamente. En caso de recibir cualquier status HTTP >= 500 se dejará de intentar.

Adicionalmente para transacciones aprobadas, también enviamos la información cuando fueron canceladas (si aplica), para este caso la diferencia radicará en el valor del estado, que será de 2. En este caso usted deberá responder con un 200 (para que no enviemos la información nuevamente) y deberá actualizar la transacción para asegurar que su información coincida con la de Shieldgate by Afirme

Detalle de los estados

La API de Shieldgate by Afirme utiliza los siguientes Estados y Detalles de Estado:

Estado Significado
0 Pendiente
1 Aprobada
2 Cancelada
4 Rechazada
5 Expirada
Detalle del Estado Significado
0 Esperando para ser Pagada.
1 Se requiere verificación, por favor revise la sección de Verificar
2 Pagada Parcialmente
3 Pagada
4 En Disputa
5 Sobrepagada
6 Fraude
7 Reverso
8 Contracargo
9 Rechazada por el procesador
10 Error en el sistema
11 Fraude detectado por Shieldgate by Afirme
12 Blacklist de Shieldgate by Afirme
13 Tiempo de tolerancia
14 Expirada por Shieldgate by Afirme
15 Expirado por el carrier
16 Rechazado por Shieldgate by Afirme
17 Abandonada por Shieldgate by Afirme
18 Abandonada por el cliente
19 Código de autorización invalido
20 Código de autorización expirado
21 Fraude Shieldgate by Afirme - Reverso pendiente
22 AuthCode Inválido - Reverso pendiente
23 AuthCode Expirado - Reverso pendiente
24 Fraude Shieldgate by Afirme - Reverso solicitado
25 AuthCode Inválido - Reverso solicitado
26 AuthCode Expirado - Reverso solicitado
27 Comercio - Reverso pendiente
28 Comercio - Reverso solicitado
29 Anulada
30 Transacción asentada (solo para Ecuador)
31 Esperando OTP
32 OTP validado correctamente
33 OTP no validado
34 Reverso parcial
35 Método 3DS solicitado, esperando para continuar
36 Desafío 3DS solicitado, esperando el CRES
37 Rechazada por 3DS

Errores

La API de Shieldgate by Afirme utiliza los siguientes códigos de error:

Código de Estado Significado
400 Petición errada -- Por ejemplo el objeto json mal formado, tipos de datos o parámetros faltantes.
401 Sin autorización -- Su auth_token esta mal construido o ya expiró.
403 Prohibido -- Puede ser por muchas razones, por ejemplo tarjeta inválida, tarjeta ya añadida, procesador no configurado u operación no permitida.
404 No encontrado -- El recurso no existe.
409 Conflicto -- Puede ser por muchas razones, por ejemplo transacción no pudo ser creada, una mala configuración, servicio de terceros responde con error.
500 Error en el Servidor -- Tuvimos un problema con nuestro servidor. Intenta otra vez más tarde.
503 Servicio no disponible -- Estamos temporalmente fuera de línea por mantenimiento. Por favor intente más tarde.

Respuesta en caso de error

Un ejemplo de error, regresa un JSON estructurado de la siguiente manera:

{
  "error": {
    "type": "Invalid Token",
    "help": "Auth-Token: should have a format like b64encode(application_code;unix_timestamp;token)",
    "description": "{}"
  }
}
Parámetro Descripción
error.type Tipo del error.
error.help En algunos casos ayuda útil para el desarrollador.
error.description Una descripción del error.

Tipos de Métodos de Pago

Estos son los significados de los distintos tipos de métodos de pago.

Código para Tipo de Método de Pago Significado
0 Tarjeta de Crédito
1 Boleto (Bank Ticket)
5 Tarjeta de Vales
7 Tarjeta de Débito
8 Tarjeta Prepagada
shell python php