NAV
shell python php

Introducción

El API GlobalPay Redeban 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 GlobalPay Redeban integraciones@globalpay.com.co 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.globalpay.com.co
production https://dashboard.globalpay.com.co

Usted puede cambiar su password si lo olvida, utilizando la opción forgot password para recuperarla. En el sistema de administración de GlobalPay Redeban 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.globalpay.com.co
production https://ccapi.globalpay.com.co
Ambiente URL
development https://noccapi-stg.globalpay.com.co
production https://noccapi.globalpay.com.co

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 GlobalPay Redeban
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 GlobalPay Redeban

Una vez que tenga el UNIQ-TOKEN, debe aplicar el sha264 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.globalpay.com.co/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.globalpay.com.co/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
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 refrencia
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 GlobalPay Redeban
transaction.url_reference Detalle imprimible de la transaction.reference

Procesadores

Procesador Campos en la respuesta necesarios para pagar
payvalida transaction.amount, transaction.agreement y transaction.reference
PagoEfectivo transaction.url_reference (el formato imprimible) o transaction.amount y transaction.reference (*).
oxxo transaction.reference que debe de ser convertido en un código de barras.

Campos necesarios para cada procesador de pagos en Efectivo

Procesador Campos necesarios en extra_params
PagoEfectivo user.name, user.last_name, user.phone (formato: código de país + número ejem. +52111111111111) order.hours (opcional, si tiene algún valor, la referencia durará horas)
oxxo user.name, user.last_name

PSE/ACH

Los usuarios hacen una transferencia bancaria desde su cuenta bancaria. La aprobación puede tardar hasta 72 horas.

Para realizar una transferencia bancaria primero, debe obtener la lista de todos los bancos y luego crear la referencia de transferencia.

Obtener los Bancos

curl --request GET \
--url https://noccapi-stg.globalpay.com.co/banks/PSE/ \
--header 'auth-token: auth-token' \
--header 'content-type: application/json'


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

{
"banks": [
  {
    "name": "BANCO AV VILLAS",
    "code": "1052"
  },
  {
    "name": "BANCO CAJA SOCIAL",
    "code": "1032"
  },
  {
    "name": "BANCO COLPATRIA",
    "code": "1019"
  },
  {
    "name": "BANCO CORPBANCA S.A",
    "code": "1006"
  },
  {
    "name": "BANCO DAVIVIENDA",
    "code": "1051"
  },
  {
    "name": "BANCO DE BOGOTA",
    "code": "1001"
  },
  {
    "name": "BANCO DE OCCIDENTE",
    "code": "1023"
  },
  {
    "name": "BANCO FALABELLA ",
    "code": "1062"
  },
  {
    "name": "BANCO GNB SUDAMERIS",
    "code": "1012"
  },
  {
    "name": "BANCO PICHINCHA S.A.",
    "code": "1060"
  },
  {
    "name": "BANCO POPULAR",
    "code": "1002"
  },
  {
    "name": "BANCO PROCREDIT",
    "code": "1058"
  },
  {
    "name": "BANCOLOMBIA",
    "code": "1007"
  },
  {
    "name": "BANCOOMEVA S.A.",
    "code": "1061"
  },
  {
    "name": "BBVA COLOMBIA S.A.",
    "code": "1013"
  },
  {
    "name": "CITIBANK ",
    "code": "1009"
  },
  {
    "name": "HELM BANK S.A.",
    "code": "1014"
  },
  {
    "name": "HSBC COLOMBIA ",
    "code": "1010"
  }
  ]
}

Para la transferencia bancaria, deberá listar los bancos disponibles para mostrarlos al pagador y permitirle seleccionar el banco donde se debitará el dinero.

HTTP Request

GET https://noccapi-stg.globalpay.com.co/banks/<carrier>/

Parámetros URL
Parámetro Tipo Requerido Descripción
carrier_id String Yes Indica el procesador de donde se obtendrá la lista.Revise la lista de procesadores
Respuesta

La lista de los bancos

Parámetro Descripción
bank.name Nombre del banco
bank.code Código del banco

Crear transferencia bancaria

Este es un ejemplo de un request para transferencia bancaria

  curl --request POST \
  --url https://noccapi-stg.globalpay.com.co/order/ \
  --header 'auth-token: auth-token' \
  --header 'content-type: application/json' \
  --data '{
    "carrier":{
      "id": "PSE",
      "extra_params": {
        "bank_code": "1022",
        "response_url": "https://example.your_url/",
        "user": {
          "name": "User full name",
          "fiscal_number": 12312312313,
          "type": "N",
          "type_fis_number": "CC",
          "ip_address": "201.0.90.12"
        }
      }
    },
    "user": {
      "id": "sdf",
      "email": "user@example.com"
    },
    "order": {
      "country": "COL",
      "currency": "COP",
      "dev_reference": "1",
      "amount": 5001.00,
      "vat": 250.00,
      "description": "description"
    }
  }'

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


  {
    "application": {
      "code": "AbiColApp"
    },
    "commerce": {
      "merchant_id": "example"
    },
    "user": {
      "name": "User full name",
      "email": "test@example.com",
      "id": "sdf"
    },
    "transaction": {
      "currency": "COP",
      "country": "COL",
      "dev_reference": "1",
      "amount": 5001.0,
      "paid_date": null,
      "description": "description",
      "status": "pending",
      "id": "PSE-10",
      "bank_url": "https://noccapi-stg.globalpay.com.co/pse/order-pay/PSE-10/",
      "status_bank": "PENDING",
      "trazability_code": 7501,
      "ticket_id": 10
    }
  }

Éste es un ejemplo de petición de H2H:

  curl --request POST \
  --url https://noccapi-stg.globalpay.com.co/order/ \
  --header 'auth-token: auth-token' \
  --header 'content-type: application/json' \
  --data '{
    "carrier": {
      "id": "H2H",
      "extra_params": {
        "debit_type": "1",
        "service_code": "PROH",
        "sub_service_code": "PROH",
        "origin_account": {
          "application_code": "APP_CODE",
          "account_number": "098100958259",
          "account_type": "CC",
          "account_nit": "9004531884",
          "account_bank_code": "000051",
        },
        "destination_account": {
          "account_number": "099700018692",
          "account_type": "CA",
          "account_identification": "79845632",
          "account_identification_type": "CDC",
          "account_bank_code": "000051"
        }
       }
    },
    "user": {
      "id": "uid117",
      "email": "jhon@doe.com"
    },
    "order": {
      "country": "COL",
      "currency": "COP",
      "dev_reference": "123123_Payment",
      "amount": 5500,
      "vat": 0,
      "description": "Destination account in request"
    }
  }'

Éste es un ejemplo de respuesta obtenida de H2H:

{
  "application": {
    "code": "GaboColApp"
  },
  "commerce": {
    "merchant_id": "1234567"
  },
  "user": {
    "email": "gcruz@test.com",
    "id": "117"
  },
  "transaction": {
    "id": "H2H-83",
    "status": "pending",
    "dev_reference": "117",
    "total_amount": 600.0,
    "description": "Pago de Davivienda CC a Bancolombia",
    "currency": "COP",
    "country": "COL",
    "paid_date": null,
    "authorization_code": null
  }
}

HTTP Request

POST https://noccapi-stg.globalpay.com.co/order/

Parámetros URL
Parámetro Tipo Requerido Descripción
carrier.id String Yes Indica el método por el cuál la transferencia será creada. Revisa la lista de procesadores
carrier.extra_params.debit_type String No (*) Tipo de débito. Opciones
carrier.extra_params.bank_code String Yes (*) Código de Banco.
carrier.extra_params.response_url String Yes (*) Una vez que el cliente termine el pago, response_url será la URL donde se esperas que el cliente llegue, ahí se deberá disparar la consulta de estado de la transacción y se deberá de mostrar el estado final de la transacción al cliente.
carrier.extra_params.service_code String No (*) Código de servicio. Opciones
carrier.extra_params.sub_service_code String No (*) Código de subservicio. Opciones
carrier.extra_params.origin_account.application_code String Yes (*) Aplicación previamente configurada con los datos de la cuenta de origen
carrier.extra_params.origin_account.account_number String Yes (*) Número de cuenta origen
carrier.extra_params.origin_account.account_type String Yes (*) Tipo de cuenta origen. Opciones
carrier.extra_params.origin_account.account_nit String Yes (*) NIT de la cuenta origen
carrier.extra_params.destination_account.account_number String Yes (*) Número de la cuenta de destino
carrier.extra_params.destination_account.account_type String Yes (*) Tipo de la cuenta destino. Opciones
carrier.extra_params.destination_account.account_identification String Yes (*) Identificador de la cuenta destino
carrier.extra_params.destination_account.account_identification_type String Yes (*) Tipo de identificador de la cuenta destino
carrier.extra_params.destination_account.account_bank_code String Yes (*) Codigo del banco de la cuenta destino
carrier.extra_params.user.name String Yes (*) Nombre del usuario.
carrier.extra_params.user.type String Yes (*) Tipo de usuario, puede ser N para persona natural o J para persona jurídica.
carrier.extra_params.user.type_fis_number String Yes (*) Indica el tipo de Número Fiscal (Nit) (Indentificación 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.ip_address String Yes (*) Dirección IP del usuario. Formato: una dirección IP v4 válida.
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 Idenficador proporcionado por el comercio para identificar la orden. Formato: String. Para PSE en ambiente de pruebas se pueden usar los siguientes valores, pending, rejected, failure, approved, con estos valores las transacciones quedarán con los estados indicados
order.amount Number Yes Monto total a pagar. Formato: Decimal con dos digitos de fracción
order.vat Number No Importe del impuesto sobre las ventas, incluido en el costo del producto. Formato: decimal con dos dígitos de fracción.
order.description String Yes Descripción de la orden.
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.

Respuesta
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.paid_date Fecha de pago de la transacción
transaction.description Descripción de la orden
transaction.status El estado del pago, podría ser: pending, approved, cancelled, failure.
transaction.id Id generado por
transaction.bank_url La URL a donde usted deberá de redireccionar al cliente. Nota: El URL retornado en el ambiente de pruebas(staging) es una simulación.
transaction.status_bank El estado de la transacción en el banco.
transaction.trazability_code Número de referencia.
transaction.ticket_id El ID de la transacción con PSE.

Estado de la transferencia

  curl --request GET \
  --url https://noccapi-stg.globalpay.com.co/pse/order/<transaction_id>/ \
  --header 'auth-token: auth-token' \
  --header 'content-type: application/json'

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

{
  "application": {
    "code": "AbiColApp"
  },
  "commerce": {
    "merchant_id": "example"
  },
  "user": {
    "name": "User Test",
    "email": "test@example.com",
    "id": "sdf"
  },
  "transaction": {
    "currency": "COP",
    "country": "COL",
    "dev_reference": "1",
    "amount": 5001.00,
    "paid_date": "2018-12-12 10:30:00",
    "description": "description",
    "status": "approved",
    "id": "PSE-10",
    "bank_url": "https://noccapi-stg.globalpay.com.co/pse/order-pay/PSE-10/",
    "status_bank": "SUCCESS",
    "trazability_code": "72692",
    "ticket_id": 10
  }
}

HTTP Request

GET https://noccapi-stg.globalpay.com.co/<carrier>/order/<transaction_id>

Parámetros URL
Parámetro Tipo Requerido Descripción
transaction_id String Yes El transaction Id devuelto por GlobalPay Redeban
Respuesta
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.paid_date Fecha de pago de la transacción
transaction.description Descripción de la transacción
transaction.bank_url La url donde el banco tiene el estado. Nota: La url devuelto en el entorno de ensayo es un simulacro.
transaction.status_bank El estado devuelto por el banco.
transaction.status El estado del pago, podría ser: pending, approved, cancelled, failure.
transaction.id Id generado por
transaction.trazability_code Número de referencia.
transaction.ticket_id El ID de la transacción con PSE.

Procesadores

Campos necesarios para todo proveedor

Procesador Campos necesitados en extra_params
PSE bank_code, response_url, user.name, user.type, user.type_fis_num, user.fiscal_number, user.ip_address
H2H extra_params.origin_account, extra_params.destination_account

Tipos de números Fiscales

Tipo Descripción
CC Cédula de ciudadanía.
CE Cédula de extranjería.
NIT Número de identificación tributario.
TI Tarjeta de identidad.
PP Pasaporte.
IDC Identificador único de cliente, para el caso de ID's únicos de clientes/usuarios de servicios públicos.
CEL (*) En caso de identificarse a través de la línea del móvil.
RC Registro civil de nacimiento.
DE Documento de identificación extranjero.
SE_NIT (**) Sociedad Extranjera sin Nit.
FIDE (**) Fideicomiso.
NIT_M (**) Nit Menores.
RIF_V (**) RIF Venezuela.
NIT_E (**) Nit Extranjería.
NIT_N (**) Nit Persona Natural.
C_DIP (**) Carnet Diplomático.
RUT (**) RUT.

Tipos de cuenta

Tipo Descripción
CC Cuenta Corriente.
CA Cuenta de Ahorros.

Tipos de débito

Tipo Descripción
0 Aplique lo de la contratación.
1 Débito 1 a 1.
2 Débito 1 a varios.

Códigos de servicio

Tipo Descripción
NOMH Pago de Nómina.
PROH Pago de Proveedores.
TCLH Transferencia cuenta en lote.

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.globalpay.com.co/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 es un ejemplo de respuesta de un request hecho con una tarjeta Tuya:

{
    "card": {
        "bin": "590309",
        "status": "pending",
        "token": "11069986367052940589",
        "message": "{\"Mail\": \"user@example.com\", \"Result\": \"TRANSACCION EXITOSA\"}",
        "expiry_year": "0",
        "expiry_month": "0",
        "transaction_reference": "TY-919",
        "type": "ex",
        "number": "5282",
        "origin": "ORIGIN"
    }
}

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

HTTP Request

POST https://ccapi-stg.globalpay.com.co/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.nip String No Nip de la tarjeta. Solo disponible para tarjetas Tuya (Exito, Alkosto).
card.card_auth String No Tipo de autenticación, disponible solo para tarjeta Tuya (Exito, Alkosto). Cadenas válidas: "AUTH_CVC", "AUTH_NIP" y "AUTH_OTP".
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.
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, para las Tarjetas Tuya, el mensaje incluirá los campos incrustados: Result, Mail, Phone si el usuario tiene esos parámetros configurados.
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: GlobalPay, VisaCheckout, Masterpass.

Obtener todas las tarjetas

curl \
-k -L -H 'Content-Type: application/json' \
-H 'Auth-Token: auth_token' \
'https://ccapi-stg.globalpay.com.co/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.globalpay.com.co/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.globalpay.com.co/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.globalpay.com.co/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.

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.globalpay.com.co/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
  },
  "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 hecho con una tarjeta Tuya:


{
  "transaction": {
    "status": "pending",
    "payment_date": null,
    "amount": 15.99,
    "authorization_code": null,
    "installments": 1,
    "dev_reference": "referencia",
    "message": "{\"Phone\": \"313*****55\", \"Result\": \"\"TRANSACCION EXITOSA\"\", \"Mail\": \"user@example.com\"}",
    "carrier_code": "000",
    "id": "TY-925",
    "status_detail": 31
  },
  "card": {
    "bin": "590309",
    "expiry_year": "0",
    "expiry_month": "0",
    "transaction_reference": "TY-925",
    "type": "ex",
    "number": "5282",
    "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, hay dos formas posibles:

  1. Compra con GlobalPay Redeban. En el request serán incluidos parámetros adiciones(extra_params), que serán utilizados para autenticar. (Revise objetos para autenticación).

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

HTTP Request

POST https://ccapi-stg.globalpay.com.co/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, BRL, PEN, CLP y USD (Ecuador).
order.installments_type Number No Sólo disponible para Ecuador. 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.tip Number No Solo disponible para Tarjetas Tuya ('ex', ak'). La Propina. Formato: Decimal con dos digitos de fracció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.
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.
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, en el caso de las Tarjetas Tuya, el mensaje incluirá los campos incrustados: Result, Mail, Phone si el usuario tiene configurados esos parámetros.
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: GlobalPay, 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.
3ds.authentication.reference_id ID de transacción del servidor 3DS.
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.
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.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.
extra_params.auth_data.xid String Yes 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 de transacción del servidor 3DS.
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
Tipos de Diferidos

Los tipos de diferidos son sólo permitidos para Ecuador. 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.globalpay.com.co/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.globalpay.com.co/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, 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, en el caso de las Tarjetas Tuya, el mensaje incluirá los campos incrustados: Result, Mail, Phone si el usuario tiene configurados esos parámetros.
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: GlobalPay, 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.globalpay.com.co/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.globalpay.com.co/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, 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.
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.globalpay.com.co/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
  },
  "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.globalpay.com.co/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.globalpay.com.co/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, hay dos formas posibles:

  1. Compra con GlobalPay Redeban. En el request serán incluidos parámetros adiciones(extra_params), que serán utilizados para autenticar. (Revise objetos para autenticación).

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

HTTP Request

POST https://ccapi-stg.globalpay.com.co/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, BRL, PEN, CLP y USD (Ecuador).
order.installments_type Number No Solo disponible para Ecuador. 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.tip Number No Solo disponible para Tarjetas Tuya ('ex', ak'). La Propina. Formato: Decimal con dos digitos de fracció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.
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.
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.globalpay.com.co/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.globalpay.com.co/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, 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, en el caso de las Tarjetas Tuya, el mensaje incluirá los campos incrustados: Result, Mail, Phone si el usuario tiene configurados esos parámetros.
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: GlobalPay, 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

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.globalpay.com.co/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.globalpay.com.co/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 GlobalPay Redeban. 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.globalpay.com.co/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 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, 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.
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.
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.globalpay.com.co/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.globalpay.com.co/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.globalpay.com.co/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.globalpay.com.co/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
USD 2.56
BRL 2.56
MXN 2.56
PEN 2.56
CLP 256

Reembolso

curl -k  -L -X POST -H 'Content-Type: application/json' -H 'Auth-Token: auth_token' -d '{
    "transaction": {
        "id": "CI-311"
    }
}' 'https://ccapi-stg.globalpay.com.co/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.globalpay.com.co/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.globalpay.com.co/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.globalpay.com.co/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.globalpay.com.co/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.

Información de la Trasacción

curl -k  -L -H 'Content-Type: application/json' -H 'Auth-Token: auth_token'
 'https://ccapi-stg.globalpay.com.co/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.globalpay.com.co/v2/transaction/<transaction_id>

Parámetros URL
Parámetro Tipo Requerido Descripción
transaction_id String Yes GlobalPay Redeban 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, en el caso de las Tarjetas Tuya, el mensaje incluirá los campos incrustados: Result, Mail, Phone si el usuario tiene configurados esos parámetros.
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: GlobalPay, VisaCheckout, Masterpass.

Marcas de tarjetas

Internacionales

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

Colombia

Tipo de Tarjeta Marca Logotipo
ex Exito
ak Alkosto
cd Codensa
sx Sodexo
ol Olimpica
ep EPM

México

Tipo de Tarjeta Marca Logotipo
cn Carnet

Ecuador

Tipo de Tarjeta Marca Logotipo
cs Credisensa
so Solidario
up Union Pay

Brasil

Tipo de Tarjeta Marca Logotipo
el Elo
jc JCB
au Aura
sx Sodexo

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

curl --request POST
  --url https://noccapi-stg.globalpay.com.co/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", "Cash", "BankTransfer", "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"
    }
}'

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

{
   "success": true,
   "detail": "Order created successfully.",
   "data": {
      "user": {
         "id": "117",
         "email": "dummy@foo.com"
      },
      "order": {
         "dev_reference": "1",
         "description": "Product description",
         "amount": 1000
      },
      "configuration": {
         "expiration_date": null,
         "partial_payment": true,
         "allowed_payment_methods": [
            "All"
         ]
      },
      "payment": {
         "payment_url": "https://noccapi-stg.globalpay.com.co/linktopay/pay/pLbOak7"
      }
   }
}

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

HTTP Request

POST https://noccapi-stg.globalpay.com.co/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).Revise los tipos válidos.
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 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.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.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.
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.

Monedas

Monedas permitidas.

Moneda País
COP Colombia
USD Ecuador
BRL Brasil
MXN México
ARS Argentina
CLP Chile
PEN Perú

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)

Autenticación 3DS 2

3D Secure 2 es una nueva generación en la tecnología de la autenticación introducida por EMVCo y las marcas de tarjetas más grandes, proveyendo una capa adicional de verificación para las transacciones con tarjeta no presente.

El objetivo es reducir el riesgo de fraude sin dañar la tasa de conversión. Esta nueva versión analiza varias viariables utilizadas como criterio para determinar la autenticidad del titula de la tarjeta, lo que permite en algunos casos disminuir las interacciones de autenticación del titular de la tarjeta (desafíos), sin arriesgar el cambio de responsabilidad del comerciante.

En 3D Secure 2, la autenticación se realiza dentro de su aplicación o formulario de pago. La identidad del comprador puere verificarse mediante el enfoque de autenticación pasiva, biométrica y de dos factores. Una transacción puede pasar por un flujo de autenticación sin fricción o un desafío.

3D Secure 2 es soportado por las siguientes marcas de tarjetas:

Cómo Funciona

En 3D Secure 2, el flujo del navegador y el flujo móvil se tratan por separado.

Para el flujo del navegador los pasos son los siguientes:

  1. La página de pago coloca los valores de entrada en el endpoint de authenticate 3DS de GlobalPay Redeban y lo envía.
  2. El MPI contacta al directorio y devuelve ya sea la respuesta final, continúa con la autenticación y realiza el método 3DS o finaliza con el HTML al que hay que redirigir al usuario que incluye el mensaje de CReq y la URL el ACS de la página de la aplicación de pagos.
  3. Si se inscribió al titular de la tarjeta y/o se solicitó la autenticación por desafío, la página de pago redirige el navegador del usuario al ACS enviándo el PAReq/CReq del adquiriente desde el MPI.
  4. ACS autentica.
  5. La página de pago recibe el id de la transacción de autenticación de GlobalPay Redeban y el CRes del ACS.
  6. La página de pago envía el CRes a GlobalPay Redeban en el endpoint verify_auth.
  7. GlobalPay Redeban devolverá el resultado de la verificación del CRes.

Para el caso de SDK, los pasos son los siguientes:

  1. La aplicación movil recolecta el sdk_info necesario y lo envía al backend del comercio (SDK initialization / getSdkInfo). El backend del comercio reúne toda la información para enviarla a través del endpoint authenticate.
  2. El MPI contacta al directorio y regresa ya sea la respuesta final, o la información necesaria (sdk_response) para completar el desafío.
  3. ACS autentica.
  4. La aplicación movil obtiene el resultado de la autenticación directamente del ACS.
  5. Si la transacción fue autenticada exitosamente, el backend del comercio deberá realizar un request al endpoint `verify_auth para obtener todos los parametros de respuesta resultantes de la autenticación.
  6. GlobalPay Redeban regresa el resultado de la verificación (los parámetros de autenticación).

Autentica

curl -k  -L -X POST -H 'Content-Type: application/json' -H 'Auth-Token: auth_token' -d '{
    "user": {
        "id": "4",
        "email": "test@email.com"
    },
    "order":{
        "amount": 11.10,
        "description": "una paleta",
        "dev_reference": "ref_123"
    },
    "card": {
        "number": "4016000000002",
        "holder_name": "citlali calderon",
        "expiry_month": 9,
        "expiry_year": 2023
    },
    "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"
    },
    "term_url": "http://your.url.com/YOUR_3DS_NOTIFICATION_URL",
    "device_type": "browser"
}' 'https://ccapi-stg.globalpay.com.co/v2/3ds/authenticate/'

Ejemplo de un request de app/sdk:

curl -k  -L -X POST -H 'Content-Type: application/json' -H 'Auth-Token: auth_token' -d '{
    "user": {
        "id": "4",
        "email": "test@email.com"
    },
    "order":{
        "amount": 11.10,
        "description": "una paleta",
        "dev_reference": "ref_123"
    },
    "card": {
        "number": "4016000000002",
        "holder_name": "citlali calderon",
        "expiry_month": 9,
        "expiry_year": 2023
    },
    "sdk_info": {
        "trans_id": "a24a5d87-b1a1-4aef-a37b-2f30b91274e6",
        "reference_number": "3DSSDK74332823FF",
        "app_id": "a24a5d87-b1a1-4aef-a37b-2f30b91554e6",
        "enc_data": "....",
        "max_timeout": 5,
        "options_IF": 6,
        "options_UI": "01,02,03",
        "ephem_pub_key": "P-256;EC;Kq9_QSrfw_D089BefP2dqVW70BbqiWSb219zvk1Ch80;d4SwfWFPb5_fMUwElfk-CRSyJvzkh75yZhlSjVwyJjk"
    },
    "term_url": "http://your.url.com/YOUR_3DS_NOTIFICATION_URL",
    "device_type": "SDK"
}' 'https://ccapi-stg.globalpay.com.co/v2/3ds/authenticate/'

Para el request previo, la respuesta es un JSON estructurado como sigue: (case A)

{
  "authentication": {
    "status": "Y",
    "xid": "MDAwMDAwMDAwMDAwMDAwMDAxMDg=",
    "return_code": "1",
    "eci": "05",
    "return_message": "Authenticated",
    "version": "2.1.0",
    "cavv": "QUNTRU1VOSJUQD9OSyc4Wmx7XXM=",
    "reference_id": "00000000-463b-5424-8000-000000033f52"
  },
  "transaction": {
    "dev_reference": "ref_123",
    "id": "AU-108"
  },
  "browser_response": {
    "challenge_request": "",
    "hidden_iframe": ""
  },
  "sdk_response": {
    "acs_trans_id": "00000000-0005-5a5a-8000-016ab2e4246c",
    "acs_signed_content": null,
    "acs_reference_number": "JCB0002"
  }
}

Para el request previo, la respuesta es un JSON estructurado como sigue: (case B)

{
  "authentication": {
    "status": "-",
    "xid": "MDAwMDAwMDAwMDAwMDAwMDAxMDc=",
    "return_code": "50",
    "eci": null,
    "return_message": "3DS method requested before enrollment",
    "version": null,
    "cavv": null,
    "reference_id": null
  },
  "transaction": {
    "dev_reference": "ref_12",
    "id": "AU-107"
  },
  "browser_response": {
    "challenge_request": "",
    "hidden_iframe": "<iframe>...</iframe><form>...</form><script type='text/javascript' xmlns='http://www.w3.org/1999/xhtml'>document.getElementById('tdsMmethodForm').submit();</script>"
  },
  "sdk_response": {
    "acs_trans_id": "00000000-0005-5a5a-8000-016ab2e4246c",
    "acs_signed_content": null,
    "acs_reference_number": "JCB0002"
  }
 }

Para el request previo, la respuesta es un JSON estructurado como sigue: (case C)

{
  "authentication": {
    "status": null,
    "xid": "MDAwMDAwMDAwMDAwMDAwMDAxMDk=",
    "return_code": "9",
    "eci": null,
    "return_message": "To be redirected to acs",
    "version": null,
    "cavv": null,
    "reference_id": null
  },
  "transaction": {
    "dev_reference": "ref_1234",
    "id": "AU-109"
  },
  "browser_response": {
    "challenge_request": "<!DOCTYPE html SYSTEM 'about:legacy-compat'><html>.....</html>",
    "hidden_iframe": ""
  },
  "sdk_response": {
    "acs_trans_id": "00000000-0005-5a5a-8000-016ab2e4246c",
    "acs_signed_content": null,
    "acs_reference_number": "JCB0002"
  }
}

Este endpont inicia el flujo de autenticación con 3DS 2.

HTTP Request

POST https://ccapi-stg.globalpay.com.co/v2/3ds/authenticate/

Parámetros URL
Parámetro Tipo Requerido Descripción
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.
device_type String Yes Tipo de dispositivo. Cadenas válidas: browser, SDK.
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.mobile_phone String No Teléfono celular del usuario. Formato: 1-3 dígitos para el código del país - número. Ejemplo: 52-1234567890
user.home_phone String No Teléfono de casa del usuario. Formato: 1-3 dígitos para el código del país - número. Ejemplo: 52-1234567890
user.work_phone String No Teléfono de oficina del usuario. Formato: 1-3 dígitos para el código del país - número. Ejemplo: 52-1234567890
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.installments Number No El número de cuotas para el pago, solo para COP, BRL, PEN, CLP y USD (Ecuador).
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.
browser_info.ip String No* Dirección IP del usuario. Dirección IP v4 válida.
browser_info.language String No* Idioma del navegador.
browser_info.java_enabled Boolean No* Si Java está habilitado en el navegador.
browser_info.js_enabled Boolean No* Si JavaScript está habilitado en el navegador.
browser_info.color_depth Number No* Profundidad de color del navegador.
browser_info.screen_height Number No* Altura de la pantalla del navegador.
browser_info.screen_width Number No* Ancho de pantalla del navegador.
browser_info.timezone_offset Number No* Desplazamiento de zona horaria.
browser_info.user_agent String No* Agente de usuario.
browser_info.accept_header String No* Aceptar encabezado.
sdk_info.trans_id UUID N/R UUID generado en el móvil.
sdk_info.reference_number String N/R Número de referencia. Formato: 1-32 caracteres.
sdk_info.app_id UUID N/R UUID del app
sdk_info.enc_data String N/R Datos encriptados. Formato: 1-64000 caracteres.
sdk_info.max_timeout Number N/R Tiempo máximo de espera. Formato: mayor que 5 menos que 99
sdk_info.options_IF Number N/R Opciones para la interfaz del dispositivo. Formato: mayor que 0 menos que 99
sdk_info.options_UI String N/R Opciones de renderizado del dispositivo UI. Formato: longitud de valores numéricos separados por comas: 1-20. Ejemplo: 01,02,03
sdk_info.ephem_pub_key String N/R Llave pública. Formato: JSON separados por punto y coma: crv;kty;x;y.
billing_address.city String No Ciudad. Formato: (Longitud máxima 50)
billing_address.country String No País. Formato: ISO 3166-1 alpha-3 ejemplo: 'USA', 'MEX', 'COL', 'ECU', 'ARG', 'BRA', 'CRI', 'CHL', 'PER'
billing_address.line1 String No Información adicional de la dirección (Longitud máxima 50)
billing_address.line2 String No Información adicional de la dirección (Longitud máxima 50)
billing_address.line3 String No Información adicional de la dirección (Longitud máxima 50)
billing_address.postal_code String No Código postal (Longitud máxima 16)
billing_address.state String No Estado. Formato: ISO 3166-2 código de subdivisión de país, ejemplo: 'DF' para Ciudad de México
shipping_address.city String No Ciudad. Formato: (Longitud máxima 50)
shipping_address.country String No País. Formato: ISO 3166-1 alpha-3 ejemplo: 'USA', 'MEX', 'COL', 'ECU', 'ARG', 'BRA', 'CRI', 'CHL', 'PER'
shipping_address.line1 String No Información adicional de la dirección (Longitud máxima 50)
shipping_address.line2 String No Información adicional de la dirección (Longitud máxima 50)
shipping_address.line3 String No Información adicional de la dirección (Longitud máxima 50)
shipping_address.postal_code String No Código postal (Longitud máxima 16)
shipping_address.state String No Estado. Formato: ISO 3166-2 código de subdivisión de país, ejemplo: 'DF' para Ciudad de México
risk_indicator.ship_indicator Number No Formato: 2 números
risk_indicator.delivery_time_frame Number No Longitud 1-2
risk_indicator.delivery_email_addr String No Una dirección email válida
risk_indicator.reorder_items_ind Number No Longitud 1-2
risk_indicator.pre_order_purchase Number No Longitud 1-2
risk_indicator.pre_order_date String No Fecha. Formato: YYYYMMDD
risk_indicator.gift_card_amount Number No Formato: Decimal con dos dígitos de fracción
risk_indicator.gift_card_curr String No Moneda de la tarjeta de regalo, por ejemplo: COP, MXN, PEN, BRL, CLP
risk_indicator.gift_card_count Number No Formato: 2 números

Respuesta
Parámetro Descripción
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.
authentication.xid Identificador de transacción enviado al MPI.
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
authentication.eci Indicador de comercio electrónico, con tarjetas de visa, el valor que se debe pasar en el mensaje de Autorización.
authentication.return_message Descripción del código de retorno.
authentication.version Versión de mensaje 3DS utilizada.
authentication.cavv Valor de verificación de autenticación del titular de la tarjeta, determinado por ACS.
authentication.reference_id ID de transacción del servidor 3DS.
transaction.dev_reference Id de referencia del comercio.
transaction.id Identificador de la transacción. Este código es único entre todas las transacciones.
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.
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.
sdk_response.acs_trans_id ID de la transacción en el ACS
sdk_response.acs_signed_content Contenido firmado por el ACS
sdk_response.acs_reference_number Número de referencia de ACS

Estado de la autenticación

Código Descripción
Y Autentificación / verificación de cuenta exitosa.
N No autenticado / cuenta no verificada. Transacción denegada.
U No se pudo realizar la autenticación.
A La autenticación / verificación se intentó pero no se pudo verificar.
C Desafío requerido. Se requiere autenticación adicional usando un desafío.
R Autenticación / Verificación de cuenta rechazada por el Emisor.

Códigos de respuesta del MPI

Código Descripción
0 No autenticado, no continuar la transacción
1 Completamente autenticado, continuar la transacción
2 No registrada
3 Caché no inscrito
4 Intento
5 U-recibido
6 Error recibido (del Directorio o ACS)
9 Pendiente
50 Ejecutar el método 3DS y continuar con la autenticación.
80 Se salta caso de dispositivo (no se realizo método 3DS, dispositivo no es capaz)
91 Error de red
92 Error de directorio (tiempo de espera de lectura)
93 Error de configuración
95 No se ha encontrado un directorio para PAN / tipo de tarjeta
96 No se ha encontrado directorio version 2 para PAN/ tipo de tarjeta
100 Error de comunicación 3DS

Continuar la autenticación

curl -k  -L -X POST -H 'Content-Type: application/json' -H 'Auth-Token: auth_token' -d '{
    "transaction": {
        "id": "AU-107"
    }
}' 'https://ccapi-stg.globalpay.com.co/v2/3ds/auth_continue/'

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

{
  "authentication": {
    "status": "Y",
    "xid": "MDAwMDAwMDAwMDAwMDAwMDAxMDc=",
    "return_code": "1",
    "eci": "05",
    "return_message": "Authenticated",
    "version": "2.1.0",
    "cavv": "QUNTRU1VTUVyS3FqRFlwQ05YIiE=",
    "reference_id": "00000000-463b-5424-8000-000000033f52"
  },
  "transaction": {
    "dev_reference": "ref_12",
    "id": "AU-107"
  },
  "browser_response": {
    "challenge_request": "",
    "hidden_iframe": ""
  },
  "sdk_response": {
    "acs_trans_id": "00000000-0005-5a5a-8000-016ab2e4246c",
    "acs_signed_content": null,
    "acs_reference_number": "JCB0002"
  }
}

Si el código de retorno de autenticación es 50, este endpoint debe invocarse después de haber renderizado el iframe y haber esperado durante 5 segundos.

HTTP Request

POST https://ccapi-stg.globalpay.com.co/v2/3ds/auth_continue/

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
Parámetro Descripción
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.
authentication.xid Identificador de transacción enviado al MPI.
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
authentication.eci Indicador de comercio electrónico, con tarjetas de visa, el valor que se debe pasar en el mensaje de Autorización.
authentication.return_message Descripción del código de retorno.
authentication.version Versión de mensaje 3DS utilizada.
authentication.cavv Valor de verificación de autenticación del titular de la tarjeta, determinado por ACS.
authentication.reference_id ID de transacción del servidor 3DS.
transaction.dev_reference Id de referencia del comercio.
transaction.id Identificador de la transacción. Este código es único entre todas las transacciones.
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.
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.
sdk_response.acs_trans_id ID de la transacción en el ACS
sdk_response.acs_signed_content Contenido firmado por el ACS
sdk_response.acs_reference_number Número de referencia de ACS

Verificar autenticación

curl -k  -L -X POST -H 'Content-Type: application/json' -H 'Auth-Token: auth_token' -d '{
    "transaction": {
        "id": "AU-109"
    },
    "cres": "ewogICAiYWNzUmVmZXJlbmNlTnVtYmVyIiA6ICJBQ1NFbXUyIiwKICAgImFjc1RyYW5zSUQiIDog\r\nIjAwMDAwMDAwLTAwMDUtNWE1YS04MDAwLTAxNmEyM2RhODI3YyIsCiAgICJtZXNzYWdlVHlwZSIg\r\nOiAiQ1JlcyIsCiAgICJtZXNzYWdlVmVyc2lvbiIgOiAiMi4xLjAiLAogICAidGhyZWVEU1NlcnZl\r\nclRyYW5zSUQiIDogImZmZmZmZmZmLWJhMGItNTM5Zi04MDAwLTAwMDAwMDAzMmUwZSIsCiAgICJ0\r\ncmFuc1N0YXR1cyIgOiAiWSIKfQ=="
}' 'https://ccapi-stg.globalpay.com.co/v2/3ds/auth_verify/'

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

{
  "authentication": {
    "status": "Y",
    "xid": "MDAwMDAwMDAwMDAwMDAwMDAxMTA=",
    "return_code": "1",
    "eci": "05",
    "return_message": "Y-status/Challenge authentication via ACS: https://dsx.modirum.com:443/dstests/ACSEmu2",
    "version": null,
    "cavv": "QUNTRU1VOlFmJCRoQm9EaGxKdFk=",
    "reference_id": "00000000-463b-5424-8000-000000033f52"
  },
  "transaction": {
    "dev_reference": "ref_1234",
    "id": "AU-109"
  },
  "browser_response": {
    "challenge_request": "",
    "hidden_iframe": ""
  },
  "sdk_response": {
    "acs_trans_id": "00000000-0005-5a5a-8000-016ab2e4246c",
    "acs_signed_content": null,
    "acs_reference_number": "JCB0002"
  }
}

Si el desafió fue solicitado, este endpoint debe de ser invocado para obtener la respuesta del desafío.

HTTP Request

POST https://ccapi-stg.globalpay.com.co/v2/3ds/auth_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.
cres String Yes for browser Respuesta a la solicitud de desafío que fue recibida en el term_url. Formato: base64 url encoded. Solo si el dispositivo usado fue navegador, es obligatorio.
Respuesta
Parámetro Descripción
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.
authentication.xid Identificador de transacción enviado al MPI.
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
authentication.eci Indicador de comercio electrónico, con tarjetas de visa, el valor que se debe pasar en el mensaje de Autorización.
authentication.return_message Descripción del código de retorno.
authentication.version Versión de mensaje 3DS utilizada.
authentication.cavv Valor de verificación de autenticación del titular de la tarjeta, determinado por ACS.
authentication.reference_id ID de transacción del servidor 3DS.
transaction.dev_reference Id de referencia del comercio.
transaction.id Identificador de la transacción. Este código es único entre todas las transacciones.
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.
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.
sdk_response.acs_trans_id ID de la transacción en el ACS
sdk_response.acs_signed_content Contenido firmado por el ACS
sdk_response.acs_reference_number Número de referencia de ACS

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 valid Cargo exitoso
5119159076977991 review El cargo se encuentra en revisión
4242424242424242 rejected No autorizado
4520121813132351 rejected Rechazado por el sistema antifraude
375953548754701 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.

Tarjetas Tuya

Para la integración con Tuya, usted puede utilizar las siguientes tarjetas de prueba, para pruebas en el ambiente staging.

Tipo Tarjeta Cédula OTP Clave
Éxito sin OTP 5704230012199650 1234010129 1478
Éxito con OTP 5903098000000332 70323463 012345 1478
Alkosto sin OTP 5903120012199650 1234010129 1478
Alkosto con OTP 5903128000000332 70323463 012345 1478

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,
     "stoken": "e03f67eba6d730d8468f328961ac9b2e",
     "application_code": "AndroidTest"
  },
  "user": {
     "id": "4",
     "email": "user@example.com"
  },
  "card": {
     "bin": "411111",
     "holder_name": "Martin Mucito",
     "type": "vi",
     "number": "1111",
     "origin": "ORIGIN"
  }
}

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",
     "stoken": "e03f67eba6d730d8468f328961ac9b2e",
     "application_code": "AndroidTest"
  },
  "user": {
     "id": "4",
     "email": "user@example.com"
  }
}

Cada vez que una transacción sea aprobada o cancelada usted recibirá un HTTP POST request de GlobalPay Redeban, a su callback_url (configurado en el panel del admin). 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 Maxima 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, en el caso de las Tarjetas Tuya, el mensaje incluirá los campos incrustados: Result, Mail, Phone si el usuario tiene configurados esos parámetros.
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.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
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: GlobalPay, VisaCheckout, Masterpass.

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 GlobalPay Redeban . 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 GlobalPay Redeban

Detalle de los estados

La API de GlobalPay Redeban 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
3 Pagada
6 Fraude
7 Reverso
8 Contracargo
9 Rechazada por el procesador
10 Error en el sistema
11 Fraude detectado por GlobalPay Redeban
12 Blacklist de GlobalPay Redeban
13 Tiempo de tolerancia
14 Expirada por GlobalPay Redeban
15 Expirado por el carrier
19 Código de autorización invalido
20 Código de autorización expirado
21 Fraude GlobalPay Redeban - Reverso pendiente
22 AuthCode Inválido - Reverso pendiente
23 AuthCode Expirado - Reverso pendiente
24 Fraude GlobalPay Redeban - 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 GlobalPay Redeban 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.
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)
3 E-wallet (Billetera electrónica)
5 Tarjeta de Vales
6 Transferencia Bancaria
7 Tarjeta de Débito
8 Tarjeta Prepagada