NAV
shell python php

Introducción

El API Nuvei 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 Nuvei integrations@paymentez.com 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.paymentez.com
production https://dashboard.paymentez.com

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

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 Nuvei
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 Nuvei

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

Métodos de Pago

Efectivo

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

Generar una referencia

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

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

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

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
bradesco user.name, user.last_name, user.fiscal_number, user.address
Dirección

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

Ejemplo con dirección del usuario:

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

Transferencia Bancaria

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.paymentez.com/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.paymentez.com/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.paymentez.com/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",
      "phone_number": "9878987677",
      "address":{
                  "street":"calle 1",
                  "number": "10",
                  "district": "district",
                  "city":"Cartagena",
                  "state":"Bolivar",
                  "zip":"130001"
      }
    },
    "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.paymentez.com/pse/order-pay/PSE-10/",
      "status_bank": "PENDING",
      "trazability_code": 7501,
      "ticket_id": 10,
      "pse_cycle": "3"
    }
  }

Éste es un ejemplo para petición de Split de Transferencia Bancaria:

  curl --request POST \
  --url https://noccapi-stg.paymentez.com/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"
        },
        "split": {
          "transactions": [
            {
              "application_code": "TestApp",
              "amount": 15000,
              "vat": 0
            },
            {
              "application_code": "Test2App",
              "amount": 15000,
              "vat": 0
            },
            {
              "application_code": "Test2App",
              "amount": 15000,
              "vat": 0
            }
          ]
        }
      }
    },
    "user": {
      "id": "sdf",
      "email": "user@example.com"
    },
    "order": {
      "country": "COL",
      "currency": "COP",
      "dev_reference": "1",
      "amount": 45000.00,
      "vat": 0,
      "description": "description"
    }
  }'

Éste es un ejemplo de respuesta obtenida de Split de Transferencia Bancaria:


  {
    "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.paymentez.com/pse/order-pay/PSE-10/",
      "status_bank": "PENDING",
      "trazability_code": 7501,
      "ticket_id": 10,
       "pse_cycle": "3"
    }
  }

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

  curl --request POST \
  --url https://noccapi-stg.paymentez.com/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
  }
}

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

  curl --request POST \
  --url https://noccapi-stg.paymentez.com/order/ \
  --header 'auth-token: auth-token' \
  --header 'content-type: application/json' \
  --data '{
              "carrier": {
                  "id": "pix-koin",
                  "extra_params": {
                      "response_url": "https://response_url.com",
                      "user": {
                          "type_fis_num":"CPF",
                          "fiscal_number": 26658083827,
                          "name": "Leidy Cruz",
                          "ip_address": "201.0.90.12"
                      }
                  }
              },
              "user": {
                  "id": "007",
                  "email": "lcruz@mail.com"
              },
              "order": {
                  "dev_reference": "#TESTPAY-2",
                  "expiration_days": 1,
                  "amount": 5,
                  "vat": 0.0,
                  "country": "BRA",
                  "currency": "BRL",
                  "description": "Test pix"
              }
          }'

Éste es un ejemplo de respuesta obtenida de PIX:

{
    "application": {
        "code": "PM-BRA"
    },
    "user": {
        "email": "lcruz@mail.com",
        "id": "007",
        "name": "Leidy Cruz"
    },
    "commerce": {
        "merchant_id": "example"
    },
    "transaction": {
        "id": "KOI-10",
        "status": "pending",
        "status_detail": 0,
        "dev_reference": "#TESTPAY-2",
        "amount": 5.0,
        "description": "Test pix expiration",
        "currency": "BRL",
        "country": "BRA",
        "bank_url": "https://noccapi-stg.paymentez.com/qr/render/UE0tQ08tUUE7S09JLTEwOzlkN2I4NDU3M2E0M2QxOGMzYjc0NmQ2MjUxMmI1OTYzNTgzMzkzZGRkNDQxMjZlOGE3YTI5NWRiNDgzNTU2NWE=",
        "qr": {
                    "code": "iVBORw0KGgoAAAANSUhEUgAAAPoAAAD6AQAAAACgl2eQAAADCUlEQVR4Xu2XUW4cIRBE6YvA/W+Ro8BFIPWKsWU5kpWPbOVn8SaZhWep1F1dTNr5ef1q33e+rTdw1xu466+A2VqtXbuP3etMPY9zlrdjwPLnrNm1NceaNXtv426nAOliqw5K+1io3IBhoFyZsWuaE/UfgM1h0xpzTMqUBfRxXZB2ONylhy/Nej0wMe2fi+0Y4KUend1omcZHR7vufgigNMzLEDXFbL63Pj6bFQBkld57MS0KkEWfdhOg3sWAI0mYRUIJMkvGwq5VCJhWtwkwAWoXIcJvjRxw9WnL/YKQWxejPGKAxvZgEHWoBKlhErztmBhgafaMXCtqWKVDJQYc2oNndY5llncEspUDlOFFrXRA23QiUl9jwB7aPvhkoE5UGeQxBlyFLEaXCbrW+XT16wGe9Kcsk25JsH/oWgjw9PbGge+ysdAtgRAhwNm1iW+rXN5pV2oMuEaVTHlXL30iFaySXU+hAsBGpJulzAAclE3geEQGAIzCfcKrFv7VEVna3LAQMIcNyiue7lKSg1ppQ0OcAshPWWT4amNtarb4GgN8qcmwvlAk8qNRtC4GuEVKLn13fKlUUuxepQC+C9NWJ9ZlHRu5iLMUMPGrdhkZLKwLpvQfoXvXhoCDzsZP0beFgagefgkC0yWiVbxqFBmmn/Xh6tcDyxnGtUpskJ/Mb0dpDGBQnSJSJ7NKHYahaR+Fej3wWMSqMI/+Utmkmm6lgCewfICwmyPdHg4BGtRBkHp+m29VqbPyHCCPKL+pFzpJUiZIep9CBQAnOZ+nQwu3TP8bAybjqvJgkyI+DjLF07gQ4M5wXEibvtod5u0RGQDYKhhZFX3ca9hYuRID9GbDidql+kgt/eKCpYMpwGaVIAZGAaKObZyL1BygxTMgMUKXuOEXbQwBFEWaOt4tusQW/eKXQsDic0vE+17njA4SrjFg8n43XCwbZQsdfooCC4eSJJoXJVkRYJ/NSgHEOBIJ8wtYeAzQh0HpCjLop3GDeU4BtEU2kUpXR1YhQqlXDvhxvYG73sBd/wD4Df7+v4eqIoYgAAAAAElFTkSuQmCC",
                    "content": "00020101021126950014BR.GOV.BCB.PIX2573spi.dev.cloud.itau.com.br/documentos/198e49c5-2330-4ad7-9d0b-967c7b5371225204000053039865802BR5923PMD Gotham NegA cios ME6009SAO PAULO62410503***50300017BR.GOV.BCB.BRCODE01051.0.063040866"
                },
        "paid_date": null,
        "instructions": [
            {
                "step_number": 1,
                "step_instruction": "Ingrese a la Banca por Internet de su banco preferido y seleccione la opción PIX."
            },
            {
                "step_number": 2,
                "step_instruction": "Seleccione la opción de Códigos QR y con la cámara de su celular escanee el código para realizar el pago."
            },
            {
                "step_number": 3,
                "step_instruction": "Finalmente, click en confirmar pago."
            }
        ]
    }
}

Éste es un ejemplo para petición de Transbank Webpay:

  curl --request POST \
  --url https://noccapi-stg.paymentez.com/order/ \
  --header 'auth-token: auth-token' \
  --header 'content-type: application/json' \
  --data '{
   "carrier":{
      "id":"tb_webpay",
      "extra_params":{
         "response_url":"https://commerce.com"
      }
   },
   "user":{
      "id":"117",
      "email":"example@mail.com"
   },
   "order":{
      "dev_reference":11711,
      "amount":1000,
      "vat":0,
      "description":"Prueba"
   }
}'

Éste es un ejemplo de respuesta de Transbank Webpay:

{
  "application": {
    "code": "CiBraApp"
  },
  "commerce": {
    "merchant_id": 1234
  },
  "user": {
    "email": "example@mail.com",
    "id": "117"
  },
  "transaction": {
    "id": "TBWP-28",
    "status": "pending",
    "status_detail": 0,
    "dev_reference": "11711",
    "amount": 1000.0,
    "description": "Prueba",
    "currency": "CLP",
    "url_reference": "https://webpay3gint.transbank.cl/webpayserver/initTransaction?token_ws=01ab5215fb066076d815467d1b63e37e03db169036cf975335de067e12eb8468"
  }
}
HTTP Request

POST https://noccapi-stg.paymentez.com/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.
carrier.extra_params.split.transactions String Yes (*) Arreglo con la información de cómo se dividirá el pago entre los distintos comercios/aplicaciones
carrier.extra_params.split.transactions.application_code String Yes (*) Aplicación que tiene la cuenta a la cual se enviará un monto parcial
carrier.extra_params.split.transactions.amount String Yes (*) Monto parcial del total del pago
carrier.extra_params.split.transactions.vat String Yes (*) Importe del impuesto sobre las ventas, incluido en el monto parcial. Formato: decimal con dos dígitos de fracción.
user.id String Yes Identificador del comprador/usuario.
user.email String Yes Correo electrónico del comprador, un e-mail con formato válido.
user.phone_number String No Número de teléfono del comprador, requerido para pagos con PSE.
user.adress String No Objecto con la dirección del usuario, Vea la especificación para Address.
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. Formato: (Longitud Máxima 100)
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 Nuvei
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.pse_cycle Número del ciclo donde la transacción se quedó creada (solo para PSE).
transaction.ticket_id El ID de la transacción con PSE.
transaction.qr.code Código en base64 para render (solo para pix).
transaction.qr.content Texto plano del qr (solo para pix).

Estado de la transferencia

  curl --request GET \
  --url https://noccapi-stg.paymentez.com/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.paymentez.com/pse/order-pay/PSE-10/",
    "status_bank": "SUCCESS",
    "trazability_code": "72692",
    "ticket_id": 10,
    "pse_cycle": "3",
  }
}
HTTP Request

GET https://noccapi-stg.paymentez.com/order/<transaction_id>

Parámetros URL
Parámetro Tipo Requerido Descripción
transaction_id String Yes El transaction Id devuelto por Nuvei
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 Nuvei
transaction.trazability_code Número de referencia.
transaction.pse_cycle Número del ciclo donde la transacción se quedó creada (solo para PSE).
transaction.ticket_id El ID de la transacción con PSE.
transaction.qr.code Código en base64 para render (solo para pix).
transaction.qr.content Texto plano del qr (solo para pix).

Reembolso

Ejemplo de reembolso total:

curl -k  -L -X POST -H 'Content-Type: application/json' -H 'Auth-Token: auth_token' -d '{
    "transaction": {
        "id": "KOI-10"
    }
}' 'https://noccapi-stg.paymentez.com/order/refund/'

Ejemplo de reembolso con monto parcial:

curl -k  -L -X POST -H 'Content-Type: application/json' -H 'Auth-Token: auth_token' -d '{
    "transaction": {
        "id": "KOI-11"
    },
    "order": {
        "amount": 100
    }
}' 'https://noccapi-stg.paymentez.com/order/refund/'

Ejemplo de una respuesta para reembolso con monto total:

{
    "status": "success",
    "detail": "Completed",
    "transaction": {
        "id": "KOI-10",
        "status": "cancelled",
        "status_detail": 7,
        "dev_reference": "#TEST-SOFT",
        "amount": 5.0,
        "refund_amount": 5,
        "currency": "BRL",
        "country": "BRA",
        "paid_date": "2022-06-01 16:08:03"
    }
}

Ejemplo de reembolso con monto parcial:

{
    "status": "success",
    "detail": "Completed",
    "transaction": {
        "id": "KOI-15",
        "status": "cancelled",
        "status_detail": 34,
        "dev_reference": "#TEST-SOFT",
        "amount": 100.0,
        "refund_amount": 50,
        "currency": "BRL",
        "country": "BRA",
        "paid_date": "2022-06-01 16:20:03"
    }
}

Ejemplo de reembolso fallido:

{
    "status": "failure",
    "detail": "Refund could not be process status transaction: cancelled",
    "transaction": {
        "id": "KOI-684",
        "status": "cancelled",
        "status_detail": 7,
        "dev_reference": "#TEST-SOFT",
        "amount": 10.0,
        "description": "Prueba de test",
        "currency": "BRL",
        "country": "BRA",
        "bank_url": "https://noccapi-stg.paymentez.com/qr/render/TGVpZHlCcmFBcHA7S09JLTY4NDtmZWU0MTcwNmU1OTRhMjM2Y2MzYzE4MDYzMmJjNDg5NmNkNWY4N2VjMDQ4NWE5MzJlYTBhMDcwOGY4MmEwOTdm",
        "qr": {
            "code": "iVBORw0KGgoAAAANSUhEUgAAAPoAAAD6AQAAAACgl2eQAAADCUlEQVR4Xu2XUW4cIRBE6YvA/W+Ro8BFIPWKsWU5kpWPbOVn8SaZhWep1F1dTNr5ef1q33e+rTdw1xu466+A2VqtXbuP3etMPY9zlrdjwPLnrNm1NceaNXtv426nAOliqw5K+1io3IBhoFyZsWuaE/UfgM1h0xpzTMqUBfRxXZB2ONylhy/Nej0wMe2fi+0Y4KUend1omcZHR7vufgigNMzLEDXFbL63Pj6bFQBkld57MS0KkEWfdhOg3sWAI0mYRUIJMkvGwq5VCJhWtwkwAWoXIcJvjRxw9WnL/YKQWxejPGKAxvZgEHWoBKlhErztmBhgafaMXCtqWKVDJQYc2oNndY5llncEspUDlOFFrXRA23QiUl9jwB7aPvhkoE5UGeQxBlyFLEaXCbrW+XT16wGe9Kcsk25JsH/oWgjw9PbGge+ysdAtgRAhwNm1iW+rXN5pV2oMuEaVTHlXL30iFaySXU+hAsBGpJulzAAclE3geEQGAIzCfcKrFv7VEVna3LAQMIcNyiue7lKSg1ppQ0OcAshPWWT4amNtarb4GgN8qcmwvlAk8qNRtC4GuEVKLn13fKlUUuxepQC+C9NWJ9ZlHRu5iLMUMPGrdhkZLKwLpvQfoXvXhoCDzsZP0beFgagefgkC0yWiVbxqFBmmn/Xh6tcDyxnGtUpskJ/Mb0dpDGBQnSJSJ7NKHYahaR+Fej3wWMSqMI/+Utmkmm6lgCewfICwmyPdHg4BGtRBkHp+m29VqbPyHCCPKL+pFzpJUiZIep9CBQAnOZ+nQwu3TP8bAybjqvJgkyI+DjLF07gQ4M5wXEibvtod5u0RGQDYKhhZFX3ca9hYuRID9GbDidql+kgt/eKCpYMpwGaVIAZGAaKObZyL1BygxTMgMUKXuOEXbQwBFEWaOt4tusQW/eKXQsDic0vE+17njA4SrjFg8n43XCwbZQsdfooCC4eSJJoXJVkRYJ/NSgHEOBIJ8wtYeAzQh0HpCjLop3GDeU4BtEU2kUpXR1YhQqlXDvhxvYG73sBd/wD4Df7+v4eqIoYgAAAAAElFTkSuQmCC",
            "content": "00020101021126950014BR.GOV.BCB.PIX2573spi.dev.cloud.itau.com.br/documentos/198e49c5-2330-4ad7-9d0b-967c7b5371225204000053039865802BR5923PMD Gotham NegA cios ME6009SAO PAULO62410503***50300017BR.GOV.BCB.BRCODE01051.0.063040866"
        },
        "paid_date": "2022-06-01 16:15:04"
    }
}

Este endpoint se utiliza para reembolsar una transacción.

HTTP Request

POST https://noccapi-stg.paymentez.com/order/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.
order.amount Number No El importe del pedido a reembolso. Formato: decimal con dos dígitos de fracción. Si no se proporciona,se considera el importe total de la transacción. Funciona con pix-koin
Respuesta
Parámetro Descripción
status Puede ser failure
detail Si es failure Puede ser Refund could not be process
transaction.id Id generado por Nuvei
transaction.status El estado del pago, podría ser: pending, approved, cancelled, failure.
transaction.status_detail El detalle del estado de la transacción, para más información, detalle del estado.
transaction.dev_reference Referencia del comercio para identificar la orden.
transaction.amount Cantidad total a pagar.
transaction.refund_amount monto reembolsado, para identificar monto parcial reembolsado
transaction.currency Moneda de transacción.
transaction.country País donde se realizó la transacción.
transaction.paid_date Fecha de pago de la transacción.

Cancelar

Ejemplo de una cancelación

curl -k  -L -X PUT -H 'Content-Type: application/json' -H 'Auth-Token: auth_token' -d ''
 'https://noccapi-stg.paymentez.com/order/cancel/KOI-90'

Ejemplo de una respuesta de cancelación

{
    "status": "success",
    "detail": "Completed",
    "transaction": {
        "id": "KOI-687",
        "status": "cancelled",
        "status_detail": 29,
        "dev_reference": "#TEST-SOFT",
        "amount": 10.0,
        "description": "Prueba de test",
        "currency": "BRL",
        "country": "BRA",
        "bank_url": "https://noccapi-stg.paymentez.com/qr/render/TGVpZHlCcmFBcHA7S09JLTY4NztmMTA3OWE4MTRlMGNkODk0NmJiMjgzNjRhZWYyYmFlMjBlYzVlZjgyMWE1NjI5Mjg4YTg3ZDYyNzIyMDQ3M2Y5",
        "qr": {
            "code": "iVBORw0KGgoAAAANSUhEUgAAAPoAAAD6AQAAAACgl2eQAAADCUlEQVR4Xu2XUW4cIRBE6YvA/W+Ro8BFIPWKsWU5kpWPbOVn8SaZhWep1F1dTNr5ef1q33e+rTdw1xu466+A2VqtXbuP3etMPY9zlrdjwPLnrNm1NceaNXtv426nAOliqw5K+1io3IBhoFyZsWuaE/UfgM1h0xpzTMqUBfRxXZB2ONylhy/Nej0wMe2fi+0Y4KUend1omcZHR7vufgigNMzLEDXFbL63Pj6bFQBkld57MS0KkEWfdhOg3sWAI0mYRUIJMkvGwq5VCJhWtwkwAWoXIcJvjRxw9WnL/YKQWxejPGKAxvZgEHWoBKlhErztmBhgafaMXCtqWKVDJQYc2oNndY5llncEspUDlOFFrXRA23QiUl9jwB7aPvhkoE5UGeQxBlyFLEaXCbrW+XT16wGe9Kcsk25JsH/oWgjw9PbGge+ysdAtgRAhwNm1iW+rXN5pV2oMuEaVTHlXL30iFaySXU+hAsBGpJulzAAclE3geEQGAIzCfcKrFv7VEVna3LAQMIcNyiue7lKSg1ppQ0OcAshPWWT4amNtarb4GgN8qcmwvlAk8qNRtC4GuEVKLn13fKlUUuxepQC+C9NWJ9ZlHRu5iLMUMPGrdhkZLKwLpvQfoXvXhoCDzsZP0beFgagefgkC0yWiVbxqFBmmn/Xh6tcDyxnGtUpskJ/Mb0dpDGBQnSJSJ7NKHYahaR+Fej3wWMSqMI/+Utmkmm6lgCewfICwmyPdHg4BGtRBkHp+m29VqbPyHCCPKL+pFzpJUiZIep9CBQAnOZ+nQwu3TP8bAybjqvJgkyI+DjLF07gQ4M5wXEibvtod5u0RGQDYKhhZFX3ca9hYuRID9GbDidql+kgt/eKCpYMpwGaVIAZGAaKObZyL1BygxTMgMUKXuOEXbQwBFEWaOt4tusQW/eKXQsDic0vE+17njA4SrjFg8n43XCwbZQsdfooCC4eSJJoXJVkRYJ/NSgHEOBIJ8wtYeAzQh0HpCjLop3GDeU4BtEU2kUpXR1YhQqlXDvhxvYG73sBd/wD4Df7+v4eqIoYgAAAAAElFTkSuQmCC",
            "content": "00020101021126950014BR.GOV.BCB.PIX2573spi.dev.cloud.itau.com.br/documentos/198e49c5-2330-4ad7-9d0b-967c7b5371225204000053039865802BR5923PMD Gotham NegA cios ME6009SAO PAULO62410503***50300017BR.GOV.BCB.BRCODE01051.0.063040866"
        },
        "paid_date": null
    }
}

Ejemplo de una cancelación fallida

{
    "status": "failure",
    "detail": "Cancellation could not be applied, status is cancelled",
    "transaction": {
        "id": "KOI-685",
        "status": "cancelled",
        "status_detail": 34,
        "dev_reference": "#TEST-SOFT",
        "amount": 10.0,
        "description": "Prueba de test",
        "currency": "BRL",
        "country": "BRA",
        "bank_url": "https://noccapi-stg.paymentez.com/qr/render/TGVpZHlCcmFBcHA7S09JLTY4NTtkYzE5OTFiNzdmY2Y0Y2FjYWU0Mzg0ZTBkZDdjOTg2MmQxN2QzMDFjNTU1M2JiODY4Mzc4ZDNiN2JjN2I1NDg2",
        "qr": {
            "code": "iVBORw0KGgoAAAANSUhEUgAAAPoAAAD6AQAAAACgl2eQAAADCUlEQVR4Xu2XUW4cIRBE6YvA/W+Ro8BFIPWKsWU5kpWPbOVn8SaZhWep1F1dTNr5ef1q33e+rTdw1xu466+A2VqtXbuP3etMPY9zlrdjwPLnrNm1NceaNXtv426nAOliqw5K+1io3IBhoFyZsWuaE/UfgM1h0xpzTMqUBfRxXZB2ONylhy/Nej0wMe2fi+0Y4KUend1omcZHR7vufgigNMzLEDXFbL63Pj6bFQBkld57MS0KkEWfdhOg3sWAI0mYRUIJMkvGwq5VCJhWtwkwAWoXIcJvjRxw9WnL/YKQWxejPGKAxvZgEHWoBKlhErztmBhgafaMXCtqWKVDJQYc2oNndY5llncEspUDlOFFrXRA23QiUl9jwB7aPvhkoE5UGeQxBlyFLEaXCbrW+XT16wGe9Kcsk25JsH/oWgjw9PbGge+ysdAtgRAhwNm1iW+rXN5pV2oMuEaVTHlXL30iFaySXU+hAsBGpJulzAAclE3geEQGAIzCfcKrFv7VEVna3LAQMIcNyiue7lKSg1ppQ0OcAshPWWT4amNtarb4GgN8qcmwvlAk8qNRtC4GuEVKLn13fKlUUuxepQC+C9NWJ9ZlHRu5iLMUMPGrdhkZLKwLpvQfoXvXhoCDzsZP0beFgagefgkC0yWiVbxqFBmmn/Xh6tcDyxnGtUpskJ/Mb0dpDGBQnSJSJ7NKHYahaR+Fej3wWMSqMI/+Utmkmm6lgCewfICwmyPdHg4BGtRBkHp+m29VqbPyHCCPKL+pFzpJUiZIep9CBQAnOZ+nQwu3TP8bAybjqvJgkyI+DjLF07gQ4M5wXEibvtod5u0RGQDYKhhZFX3ca9hYuRID9GbDidql+kgt/eKCpYMpwGaVIAZGAaKObZyL1BygxTMgMUKXuOEXbQwBFEWaOt4tusQW/eKXQsDic0vE+17njA4SrjFg8n43XCwbZQsdfooCC4eSJJoXJVkRYJ/NSgHEOBIJ8wtYeAzQh0HpCjLop3GDeU4BtEU2kUpXR1YhQqlXDvhxvYG73sBd/wD4Df7+v4eqIoYgAAAAAElFTkSuQmCC",
            "content": "00020101021126950014BR.GOV.BCB.PIX2573spi.dev.cloud.itau.com.br/documentos/198e49c5-2330-4ad7-9d0b-967c7b5371225204000053039865802BR5923PMD Gotham NegA cios ME6009SAO PAULO62410503***50300017BR.GOV.BCB.BRCODE01051.0.063040866"
        },
        "paid_date": "2022-06-01 16:20:03"
    }
}

Este endpoint permite cancelar una orden, de tal manera que ya no se podrá realizar el pago

HTTP Request

PUT https://noccapi-stg.paymentez.com/order/cancel/<transaction_id>

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
status Puede ser success or failure
detail si es success puede ser Completed, si es failure puede ser Cancellation could not be applied
transaction.id Id generado por Nuvei
transaction.status El estado del pago, podría ser: pending, approved, cancelled, failure.
transaction.status_detail El detalle del estado de la transacción, para más información, detalle del estado.
transaction.dev_reference Referencia del comercio para identificar la orden.
transaction.amount Cantidad total a pagar.
transaction.currency Moneda de transacción.
transaction.country País donde se realizó la transacción.
transaction.paid_date Fecha de pago de la transacción.
transaction.qr.code Código en base64 para render (solo para pix).
transaction.qr.content Texto plano del qr (solo para pix).

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, user.address, user.phone_number
PSE_SPLIT bank_code, response_url, user.name, user.type, user.type_fis_num, user.fiscal_number, user.ip_address, user.address, user.phone_number, split.transactions.application_code, split.transactions.amount, split.transactions.vat
H2H extra_params.origin_account, extra_params.destination_account
safetypay bank_code, response_url, user.name, user.type, user.type_fis_num, user.fiscal_number, user.ip_address
tb_webpay response_url
pix-koin response_url, user.name, user.type, user.type_fis_num, user.fiscal_number, user.ip_address

Dirección

Dirección del comprador en formato json

Parámetro Tipo Requerido Descripción
street String No Nombre de la calle
number String No Número de casa
district String No Distrito, colonia
city String No Nombre de la ciudad
state String No Nombre del estado
zip String No Código postal

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.
CPF Registro de personas físicas (Cadastro de Pessoas Físicas).
CEDULAECU Cedula Ecuador.
CEDULACOL Cedula Colombia.

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.

QR EMVCo

A través de esta plataforma usted puede generar códigos QR que habilitará el medio de pago al ciente final. Será a través de las billeteras, que internamente llamarán al método Cobro con QR para realizar el pago.

Generar QR

curl -k  -L -X POST -H 'Content-Type: application/json' -H 'Auth-Token: auth_token' -d '{
    "qr": {
        "type": "DIN",
        "expiration_time": 12233
    },
    "order": {
        "amount": 200000,
        "description": "QR Generation",
        "dev_reference":"DE-123",
        "currency": "COP",
        "country": "COL"
    },
    "cost_breakdown": [
        {
            "type": "vat",
            "amount": 1000,
            "calculation_type": "02"
        },
        {
            "type": "inc",
            "amount": 1000,
            "calculation_type": "02"
        },
        {
            "type": "taxable_amount",
            "amount": 10100,
            "calculation_type": "01"
        }

    ],
    "additional_amounts": [
        {
            "type": "tip",
            "amount": 10,
            "calculation_type": "02"
        }
    ],
    "carrier":{
        "id": "redeban",
        "extra_params": {
            "payer": {
                "id": "123444",
                "name": "Fulanito Apellido",
                "email": "fulanito@testmail.com.mx"
            }
    }

}' 'https://ccapi-stg.paymentez.com/v2/qr/generate/'

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

{
  "qr":{
    "code": "ARQR+HpD/aw8A+you9uCt76Gr5FImeAwuzl67USKD5dt7R5fPeokUxcgbluBtORRPvWHO96G6jtu+AVVVVVVVVVVUB/+C67dgrpPVP8NRr4GyXgc1SMR25P2aZwS7Sf7s0utdwUsnYnjtmz/ai12VEDc1XlRnQdsOISzBSiLJskf2rq8NplsAsfbG3D8aACWn0o1Z4n3/9COjMVINttoxdttJieTYkw+33m6Qn32KjV4pF/qXIb3z2V4+2pSY40zt1ht6on0peVzzCXbD8RTTS+S/Bni8D9aKNGevhz1V5z2G+48vf1+UCHJAuf8DZjQCjkTo73FrsskOjlOk9XWgFaYSVWuUKbrXpO9D25cBXhARppBepAE1fJUXaWzkjXq1AZn4HFigb3sZaVkFolditJLXGlkukfWiR2SkZXVfhqxrVSquOfbl3PhVwNpmcggNsRXm4N8/wjX8GfR7o6OXuD9oLDptU1Bcl9UJh1qhoSdQ5dEaEDWy1R8BYXG99DP3ui5p39tk9ctxqc1AD120ay310dJHT3C9FCyftnSLv0wTuOc443vnUynyX3iw2+wreumvBSRZj4GfNoBmoQMMBBa54Dq41guB+q4vr7sJVDLUaPdSfb1JTrn05eBDsv0ucwBkYFPxwccSBW/uKT/VqOxjH1OGlJlZrkp1v1l9X4U2S396uw9Vsaw59cCiz/pzafFSsfVSb17Wes4NDe0jy36VVxDXKe3J7xLrT+riGUoM1vtkan8d9T++o5m0UPT40lNHzDZfNLbJKjzRtmVmjH8vl5thNp4ohX96ESsh9NPyYXbO1B8rtwVftkoxpvlbzxyen261YCr1v3sBtTstFQYfN7f75k3tuuYkz3hmFPt0DnEwS1YBf+ACLqRiO7fY6gGbflUNtVa5BRvvHCOH2+4trzuReTrBuXICbDQWioeprclc8/hGdFJLyyoAs8cCXz63ifXXrpxTM7QEVhqgtoXHr8uAQ==",
    "id": "QR-99",
    "rows": 77
  }
}

En caso de error lanzado por el carrier, el request regresa un JSON como el siguiente:

{
  "qr": {
    "id": "QR-128",
    "error_code": "E28",
    "error_desc": "Error interno del proveedor: 911-valueOfConvenienceFeePercentage debe tener un tamaño de caracteres"
  }
}

Este endpoint permite generar códigos QR que habilitará el medio de pago, para mostrarlos al cliente final.

HTTP Request

POST https://ccapi-stg.paymentez.com/v2/qr/generate/

Parámetros en Body
Parámetro Tipo Requerido Descripción
qr.type String Yes Tipo de QR a generar, puede ser 'STA' para estático o 'DIN' para dinámico.
qr.expiration_time Number Yes Tiempo en segundos que tardará en vencer el QR para pagar.
order.amount Number Yes Cantidad total a pagar, sin incluir la propina.
order.description String Yes Descripción de la orden.
order.currency String No Moneda de la orden Revise los tipos válidos.
order.country String No País donde se utilizará el QR, por defecto se usará el de la configuración de las credenciales.
cost_breakdown Array Yes Arreglo con uno o más objetos cantidad. Desglose de montos incluídos en order.amount Ver detalle del objeto cantidad.
additional_amounts Array Yes Arreglo con uno o más objetos cantidad de montos que NO están incluídos en order.amount Ver detalle del objeto cantidad
carrier.id String Yes Indica el método para el que se generará el QR. Por ejemplo: 'redeban'
carrier.extra_params Json Yes Parámetros necesarios para cada carrier.payer es requerido
Detalle del objeto payer.
Parámetro Tipo Requerido Descripción
id String Yes Identificador del pagador.
name String Yes Nombre del pagador.
email String Yes Email del pagador.
fiscal_number String No* El Número Fiscal (número de identificación) del pagador. Sólo para PIX Brasil.
fiscal_number_type String No* CPF o CNPJ solo para pix Brasil.
ip_address String No* Dirección IP del pagador. Sólo para Pix Brasil
Detalle del objeto cantidad
Parámetro Tipo Requerido Descripción
type String Yes Tipo de cantidad, puede ser 'vat' para iva, 'inc' para INC en Colombia, 'taxable_amount' para monto gravable, 'tip' para propina.
amount Number Yes La cantidad.
calculation_type String Yes '01'- Billetera, '02' - Comercio y '03' - Porcentaje. Nota: Si se selecciona porcentaje el amount deberá ser un porcentaje de 0 a 99.
Respuesta
Parámetro Descripción
qr.id Identificador del QR. Este id es único en esta plataforma.
qr.code QR en base 64. Cadena de información requerida para generar la imagen de QR.
qr.rows Si es mayor que 0, el número de renglones que tiene el QR.
qr.error_code El código de error retornado por el carrier.
qr.error_desc La descripción del error, retornada por el carrier.

Consultar QR

curl -k  -L -H 'Content-Type: application/json'
-H 'Auth-Token: auth_token'
 'https://ccapi-stg.paymentez.com/v2/qr/QR-123/?transaction_date=2021-02-26'

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

{
  "transaction": {
    "status": "success",
    "authorization_code": "542741",
    "status_detail": 3,
    "message": "Aprobado",
    "id": "QR-119",
    "payment_date": "2021-02-26T10:20:39",
    "dev_reference": "",
    "carrier_code": "00",
    "current_status": "APPROVED",
    "amount": 10100,
    "installments": 1
  },
  "card": {
    "bin": "516488",
    "origin": "BilleteraQR",
    "number": "5164",
    "expiry_year": "2020",
    "expiry_month": "12",
    "type": "mc"
  },
  "qr": {
    "terminal": "NETCOM03",
    "commerce": "10203040",
    "additional_amount_info": [
      {
        "amount": 1596,
        "type": "vat"
      },
      {
        "amount": 0,
        "type": "inc"
      },
      {
        "amount": 100,
        "type": "tip"
      }
    ]
  }
}

Posterior a la generación del QR, iniciará el proceso de autorización al leer dicho QR. Es necesario realizar la consulta para conocer el estado final del intento de pago, que se originó con la lectura del QR.

HTTP Request

GET https://ccapi-stg.paymentez.com/v2/qr/<qr_id>/

Parámetros URL
Parámetro Tipo Requerido Descripción
qr_id String Yes Identificador del QR. Este id es único en esta plataforma.
transaction_date String No En caso de que el pago se realice después de la fecha de creación del QR, deberá especificar la fecha de la transacción con el formato: AAAA-MM-DD
Respuesta
Parámetro Descripción
transaction.status Puede ser success, pending o failure.
transaction.current_status Puede ser PENDING*, **APPROVED, CANCELLED, INITIATED, REJECTED o EXPIRED.
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 En caso de QR, una cadena vacía.
transaction.message El mensaje regresado por el procesador.
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.type Abreviatura del tipo de tarjeta. Revise las opciones válidas
card.number Los últimos cuatro dígitos de la tarjeta.
card.origin Canal del origen de la transacción.
qr.terminal ID de la terminal.
qr.commerce ID del comercio.
qr.additional_amount_info Arreglo con objetos que contienen amount y type, donde type puede ser uno de los siguientes: vat (iva), inc (para colombia) o tip propina.

Actualizar QR

curl -k  -L -X PUT -H 'Content-Type: application/json' -H 'Auth-Token: auth_token' -d '{
   "status": "inactive"
}' 'https://ccapi-stg.paymentez.com/v2/qr/QR-123/update/'

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

{
  "response": {
    "description": "Actualizacion de QR realizada - QR Inactivo",
    "code": "OK"
  }
}

Este endpoint permite actualizar el estado de un código QR, de habilitado a inhabilitado, para garantizar que un QR no cuente con más de un pago realizado.

HTTP Request

PUT https://ccapi-stg.paymentez.com/v2/qr/<qr_id>/update/

Parámetros URL
Parámetro Tipo Requerido Descripción
qr_id String Yes Identificador del QR. Este id es único en esta plataforma.
Parámetros en Body
Parámetro Tipo Requerido Descripción
status String Yes Puede ser active o inactive
Respuesta
Parámetro Descripción
response.description Descripción del codigo que se regresa.
response.code OK en caso de éxito. E01, E02 o E09 en otro caso.

Billetera Electrónica

A través de esta plataforma, se podrán realizar pagos con billeteras electrónicas como DaviPlata en Colombia. Dos pasos son necesarios:

  1. Generar una orden
  2. Si fue exitosa, verficarla

Generar una orden

curl -k  -L -X POST -H 'Content-Type: application/json' -H 'Auth-Token: auth_token' -d '{
    "carrier":{
        "id": "daviplata",
        "extra_params": {
            "user": {
                "fiscal_number": 1134568011,
                "type_fis_number": "CC"
            }
        }
    },
    "user": {
        "id": "sadfasdf",
        "email": "user@example.com"
    },
    "order": {
        "country": "COL",
        "currency": "COP",
        "dev_reference": "prueba_stg_3",
        "amount": 5001,
        "description": "Esto es una prueba"
    }
}' 'https://noccapi-stg.paymentez.com/order/'

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

{
  "application": {
    "code": "CiColApp2"
  },
  "commerce": {
    "merchant_id": "0010203040"
  },
  "user": {
    "email": "user@example.com",
    "id": "sadfasdf"
  },
  "transaction": {
    "id": "DAP-11",
    "status": "pending",
    "dev_reference": "prueba_stg_3",
    "amount": 5001.0,
    "description": "Esto es una prueba",
    "currency": "COP",
    "country": "COL",
    "date": null,
    "authorization_code": null
  }
}

Genera una orden de compra en la billetera

HTTP Request

POST https://noccapi-stg.paymentez.com/order/

Parámetros URL
Parámetro Tipo Requerido Descripción
carrier.id String Yes Indica el método por el cual la orden será creada. Por ejemplo: 'daviplata'
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.
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 digitos de fracción
order.description String Yes Descripción de la orden. Formato: (Longitud Máxima 100)
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.status El estado del pago, puede ser pending, failure o approved
transaction.id Id generado por Nuvei
transaction.date Fecha de generación de la orden en el carrier.
transaction.authorization_code Código de autorización regresado por el carrier.

Verificar la orden

curl -k  -L -X POST -H 'Content-Type: application/json' -H 'Auth-Token: auth_token' -d '{
    "transaction":{
       "id": "DAP-11"
    },
    "type": "BY_OTP",
    "value": "123456"
}' 'https://noccapi-stg.paymentez.com/order/verify/'

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

{
  "application": {
    "code": "CiColApp2"
  },
  "commerce": {
    "merchant_id": "0010203040"
  },
  "user": {
    "email": "user@example.com",
    "id": "sadfasdf"
  },
  "transaction": {
    "id": "DAP-11",
    "status": "approved",
    "dev_reference": "prueba_stg_3",
    "amount": 5001.0,
    "description": "Esto es una prueba",
    "currency": "COP",
    "country": "COL",
    "date": "2020-08-10 16:59:38",
    "authorization_code": "943376"
  }
}

Sólo si la orden generada anteriormente tiene estado pending, deberá de verificar la orden.

HTTP Request

POST https://noccapi-stg.paymentez.com/order/verify/

Parámetros URL
Parámetro Tipo Requerido Descripción
transaction.id String Yes Id generado por Paymentez retornado en el servicio de generear una orden.
type String Yes El tipo de valor que será enviado en el request. Cadenas válidas: "BY_OTP".
value String Yes La contraseña de un solo uso (OTP) enviada al cliente.
Respuesta

El mismo tipo de respuesta que se obtiene al generar una orden.

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.paymentez.com/v2/card/add'

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

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

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

HTTP Request

POST https://ccapi-stg.paymentez.com/v2/card/add

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

Obtener todas las tarjetas

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

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

Inicializar una Referencia

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

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

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

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

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

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

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

HTTP Request

POST https://ccapi-stg.paymentez.com/v2/transaction/init_reference/

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

Datos para conf

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

Cobro con Token

Caso base

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

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

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

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

{
  "transaction": {
    "status": "failure",
    "current_status": "REJECTED",
    "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 Nuvei. 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.paymentez.com/v2/transaction/debit/

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

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

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

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

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

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

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

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

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

Ejemplo de request con datos de hotel.

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

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

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

Ejemplo de request con datos de aerolinea.

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

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

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

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

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

Split de pagos

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

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

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

Ver Objetos en la respuesta

Cobro con Tarjeta Crédito

Caso base


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

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

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

Este es un ejemplo de request con extra_params:


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

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

Ver Objetos en la respuesta

Split de pagos

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

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

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

Ver Objetos en la respuesta

Captura

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

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

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

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

Reembolso

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

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

Void

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

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

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

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

HTTP Request

POST https://ccapi-stg.paymentez.com/v2/transaction/void/

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

Ver Objetos en la respuesta

Información de la Transacción

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

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

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
hpc Hipercard

LinkToPay

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

Generar un enlace

Ejemplo de request para generar un enlace.

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

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

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

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

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

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

HTTP Request

POST https://noccapi-stg.paymentez.com/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 y México Revise los tipos válidos. Para el resto de los países, 0 para permitir cuotas, -1 en caso contrario. Sólo disponible para pago con tarjeta.
order.vat Number Yes Impuesto sobre las ventas, incluido en el importe del pedido. Formato: decimal con dos dígitos de fracción.
order.inc Number No Impuesto nacional al consumo, incluido en el importe del pedido. Formato: decimal con dos dígitos de fracción.
order.tip Number No Solo disponible para Pago con código Qr. La Propina, adicional al importe del pedido. Formato: Decimal con dos digitos de fracción.
order.taxable_amount Number No Solo disponible para Ecuador y Colombia. 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 Colombia. La tasa de impuesto que se aplicará a este pedido. Para Ecuador debe de ser 0 o 12.
order.currency String Yes Moneda de la orden Revise los tipos válidos.
configuration.partial_payment Boolean Yes Indica si el pago parcial está permitido.
configuration.expiration_days Number No(*) Número de días en que vence el enlace a pagar.
configuration.expiration_time Number No(*) Tiempo en segundos que tardará en vencer el enlace para pagar.
configuration.allowed_payment_methods Array (String) No Indica los métodos de pago permitidos. 'All' es el valor predeterminado. Revise los tipos válidos.
configuration.currency_exchange String No Moneda en la cual se pagará la orden Revise los tipos válidos.
configuration.success_url String Yes URL para redireccionar cuando la transacción es exitosa. (máx 500)
configuration.failure_url String Yes URL para redireccionar cuando la transacción falla. (máx 500)
configuration.pending_url String Yes URL para redireccionar cuando la transacción está pendiente. (máx 500)
configuration.review_url String Yes URL para redireccionar cuando se revisa la transacción. (máx 500)
configuration.card.capture_cellphone Boolean No Indica si se requiere pedir el número de teléfono en pago con tarjeta (Por defecto es True).
billing_address.street String No El nombre de la calle.
billing_address.city String Yes El nombre de la ciudad, máximo de 50 caracteres.
billing_address.state String No El estado. Formato 3166-2 código de 2 caracteres en caso de transacciones que se autenticarán con 3DS, formato libre en otro caso.
billing_address.district String No El distrito.
billing_address.zip String Yes Código Postal, máximo de 50 caracteres.
billing_address.house_number String No El número de la casa.
billing_address.country String Yes País en formato ISO 3166-1 alpha-3, por ejemplo: COL, MEX, ECU.
billing_address.additional_address_info String No Información adicional, sin formato.
Respuesta
Parámetro Descripción
user.id Identificador del comprador.
user.email Correo electrónico del comprador registrado en el pedido.
order.dev_reference Referencia del comercio.
order.amount Importe total a pagar.
order.description Descripción del pedido.
configuration.expiration_date Fecha límite para pagar.
configuration.partial_payment Indica si el pago parcial está permitido.
configuration.allowed_payment_methods Indica los métodos de pago permitidos.
payment.payment_url Link Para Pagar, URL al cual redireccionar.
payment.payment_qr Code Qr base64, URL al cual redireccionar.

Monedas

Monedas permitidas.

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

Métodos de pago permitidos

Métodos de pago permitidos por país:

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

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 Nuvei 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 Nuvei y el CRes del ACS.
  6. La página de pago envía el CRes a Nuvei en el endpoint verify_auth.
  7. Nuvei 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. Nuvei 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,
        "type": "vi"
    },
    "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.paymentez.com/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,
        "type": "vi"
    },
    "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.paymentez.com/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"
  },
  "service": "nuvei"
}

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"
  },
  "service": "modirum"
 }

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"
  },
  "service": "nuvei"
}

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

HTTP Request

POST https://ccapi-stg.paymentez.com/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 Máxima 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, MXN, 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.
card.type String Yes Tipo de tarjeta abreviado. Revise las opciones válidas
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. Formato: base64
authentication.reference_id Id en el server del directorio (DS transaction Id)
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
service El nombre del servicio de MPI que autenticó la transacción.

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 (Corresponden a MPI Modirum)

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.paymentez.com/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"
  },
  "service": "nuvei"
}

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.paymentez.com/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. Formato: base64
authentication.reference_id Id en el server del directorio (DS transaction Id)
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.paymentez.com/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"
  },
  "service": "nuvei"
}

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

HTTP Request

POST https://ccapi-stg.paymentez.com/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. Formato: base64
authentication.reference_id Id en el server del directorio (DS transaction Id)
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

Integraciones de terceros

Spreedly

Ejemplo de (1) Añade una pasarela en spreedly

curl -k -L -X POST -H 'Content-Type: application/json' -d '{
    "gateway": {
        "gateway_type": "paymentez",
        "application_code": "APP-CODE-PAYMENTEZ",
        "app_key": "APP-KEY-PAYMENTEZ"
    }
}' -u '7Fch4kBFxFpIvoVWdITwSCcEinm:SECRETS' 'https://core.spreedly.com/v1/gateways.json'

Ejemplo de (2.a) Genera un método de pago en spreedly

curl -k -L -X POST -H 'Content-Type: application/json' -d '{
    "payment_method": {
        "payment_method_type": "third_party_token",
        "reference": "card_token_at_paymentez",
        "gateway_type": "paymentez"
    },
    "environment_key": "THE ENV KEY"
}' -u 'WNNoyHk5OdoJIfEXLa7CMxEiQHU:SECRETS' 'https://core.spreedly.com/v1/payment_methods.json'

Ejemplo de (2.b) Genera un método de pago en spreedly

curl -k -L -X POST -H 'Content-Type: application/json' -d '{
    "payment_method": {
        "credit_card": {
            "first_name": "Citlali",
            "last_name": "Calderon de Anda",
            "number": "528851**********",
            "verification_value": "***",
            "month": "7",
            "year": "****"
        },
    "email": "ccalderon@paymentez.com"
},
"environment_key": "WNNoyHk5OdoJIfEXLa7CMxEiQHU"
}' -u 'WNNoyHk5OdoJIfEXLa7CMxEiQHU:SECRETS' 'https://core.spreedly.com/v1/payment_methods.json'

Ejemplo de (3) Almacena una tarjeta de crédito.

curl -k -L -X POST -H 'Content-Type: application/json' -d '{
    "transaction": {
        "gateway_specific_fields": {
            "paymentez": {
                "user_id": "4"
            }
        },
    "payment_method_token": "THE_PAYMENT_METHOD_TOKEN",
    "currency_code": "BRL"
    }
}' -u 'WNNoyHk5OdoJIfEXLa7CMxEiQHU:SECRETS' 'https://core.spreedly.com/v1/gateways/<Gateway_token>/store.json'

Ejemplo de (4.a) Una compra a través de spreedly

curl -k  -L -X POST -H 'Content-Type: application/json' -d '{
   "transaction": {
        "payment_method_token": "THE_PAYMENT_METHOD_TOKEN",
        "amount": 100,
        "currency_code": "MXN",
        "retain_on_success": true,
        "description": "prueba citlali",
        "email": "aquijada@paymentez.com",
        "ip": "187.189.240.46",
        "gateway_specific_fields": {
            "paymentez": {
                "vat": 0,
                "dev_reference": "ci123",
                "user_id": "abi"
            }
        }
   }
}' -u 'WNNoyHk5OdoJIfEXLa7CMxEiQHU:SECRETS' 'https://core.spreedly.com/v1/gateways/<Gateway_token>/purchase.json'

Paymentez es una de las pasarelas de pagos que Spreedly soporta.

Esta es una guía rápida de como integrar Paymentez a través de Spreedly:

  1. Añade una pasarele a tu ambiente

  2. Reune la información para el pago (Genera un payment_method en spreedly):

    a. Para una tarjeta que fue guardada en Paymentez en el pasado No es necesario almacenarla de nuevo.

    b. Para nuevas tarjetas

    c. En caso de compra directa Sin haber almacenado la tarjeta en Paymentez o en Spreedly

    1. Almacena una tarjeta de crédito en Paymentez a través de Spreedly

  3. Dependiendo del país finalice la compra (purchase):

    a. Cobro

    b. Autorización

    c. Captura

  4. En caso de que se requiera una devolución

Spoonity

Para mayor información visite: página de Spoonity

VTEX

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

Para mayor información visite el siguiente manual.

Tarjetas de Prueba

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

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

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

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

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

OTP Diners

Para la integración con Diners OTP (solo Ecuador), puede utilizar las siguientes tarjetas de prueba, para pruebas en el ambiente staging.

Tarjeta OTP
36417002140808 012345 (success result)
36417002140808 543210 (pending result)

3DS con el MPI de nuvei

Las siguientes tarjetas son para utlizarse en el ambiente de staging. Debe cambiar el order.description dependiendo del caso de prueba.

Caso de prueba Tarjeta order.description order.amount
Challenge 2221008123677736 3DS Challenge 151
Frictionless 4000020951595032 3DS FrictionLess >= 150

WebHook

El siguiente es el JSON regresado en el WebHook:

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

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


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

Entonces el stoken para este ejemplo es e242e78ae5f1ed162966f0eacaa0af01

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

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

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

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

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

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

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

Estado Caso
200 exito
203 error con el token

Usted necesita generar el stoken y compararlo con el que recibe, para cerciorarse de que el POST provenga de Nuvei . 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 Nuvei

Detalle de los estados

La API de Nuvei utiliza los siguientes Estados y Detalles de Estado:

Estado Significado
0 Pendiente
1 Aprobada
2 Cancelada
4 Rechazada
5 Expirada
Detalle del Estado Significado
0 Esperando para ser Pagada.
1 Se requiere verificación, por favor revise la sección de Verificar
2 Pagada Parcialmente
3 Pagada
4 En Disputa
5 Sobrepagada
6 Fraude
7 Reverso
8 Contracargo
9 Rechazada por el procesador
10 Error en el sistema
11 Fraude detectado por Nuvei
12 Blacklist de Nuvei
13 Tiempo de tolerancia
14 Expirada por Nuvei
15 Expirado por el carrier
16 Rechazado por Nuvei
17 Abandonada por Nuvei
18 Abandonada por el cliente
19 Código de autorización invalido
20 Código de autorización expirado
21 Fraude Nuvei - Reverso pendiente
22 AuthCode Inválido - Reverso pendiente
23 AuthCode Expirado - Reverso pendiente
24 Fraude Nuvei - 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
47 Validación de CPF fallida
48 Autenticado por 3DS

Errores

La API de Nuvei utiliza los siguientes códigos de error:

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

Respuesta en caso de error

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

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

Tipos de Métodos de Pago

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

Código para Tipo de Método de Pago Significado
0 Tarjeta de Crédito
1 Boleto (Bank Ticket)
3 E-wallet (Billetera electrónica)
5 Tarjeta de Vales
6 Transferencia Bancaria
7 Tarjeta de Débito
8 Tarjeta Prepagada
shell python php