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

Pago en Efectivo/ Transferencia Bancaria / Billetera Electrónica / Link To Pay

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:

Usted debe remplazar server_application_code and server_app_key con sus credenciales tipo Server de Nuvei

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.

HTTP Request

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

Usted debe remplazar la cadena codificada base64 auth_token en el encabezado, con su auth_token personal. Cómo construir token.

Parámetros URL

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.

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.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>/

Usted debe remplazar la cadena codificada base64 auth_token en el encabezado, con su auth_token personal. Cómo construir token.

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/

Usted debe remplazar la cadena codificada base64 auth_token en el encabezado, con su auth_token personal. Cómo construir token.
Para realizar un flujo completo de prueba, utilize el bank_code 1022

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>

Usted debe remplazar la cadena codificada base64 auth_token en el encabezado, con su auth_token personal. Cómo construir token.

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/

Usted debe remplazar la cadena codificada base64 auth_token en el encabezado, con su auth_token personal. Cómo construir token.

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>

Usted debe remplazar la cadena codificada base64 auth_token en el encabezado, con su auth_token personal. Cómo construir token.

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/

Usted debe remplazar la cadena codificada base64 auth_token en el encabezado, con su auth_token personal. Cómo construir token.

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

Usted debe remplazar la cadena codificada base64 auth_token en el encabezado, con su auth_token personal. Cómo construir token.

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/

Usted debe remplazar la cadena codificada base64 auth_token en el encabezado, con su auth_token personal. Cómo construir token.

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:

Generar una orden
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/

Usted debe remplazar la cadena codificada base64 auth_token en el encabezado, con su auth_token personal. Cómo construir token.

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/

Usted debe remplazar la cadena codificada base64 auth_token en el encabezado, con su auth_token personal. Cómo construir token.

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

Usted debe remplazar la cadena codificada base64 auth_token en el encabezado, con su auth_token personal. Cómo construir token.

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. (Longitud Maxima 100)
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

Usted debe remplazar la cadena codificada base64 auth_token en el encabezado, con su auth_token personal. Cómo construir token.

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/

Usted debe remplazar la cadena codificada base64 auth_token en el encabezado, con su auth_token personal. Cómo construir token.

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/

Usted debe remplazar la cadena codificada base64 auth_token en el encabezado, con su auth_token personal. Cómo construir token.

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:

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).
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/

Usted debe remplazar la cadena codificada base64 auth_token en el encabezado, con su auth_token personal. Cómo construir token.

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/

Usted debe remplazar la cadena codificada base64 auth_token en el encabezado, con su auth_token personal. Cómo construir token.

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/

Usted debe remplazar la cadena codificada base64 auth_token en el encabezado, con su auth_token personal. Cómo construir token.

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:

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).
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/

Usted debe remplazar la cadena codificada base64 auth_token en el encabezado, con su auth_token personal. Cómo construir token.

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/

Usted debe remplazar la cadena codificada base64 auth_token en el encabezado, con su auth_token personal. Cómo construir token.

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

Cobro con Wallet

curl -k  -L -X POST -H 'Content-Type: application/json' -H 'Auth-Token: auth_token' -d '{
    "user": {
        "id": "1",
        "email": "user1@example.com",
        "fiscal_number": "80265579"
    },
    "order": {
        "amount": 200.0,
        "description": "Product description",
        "dev_reference": "referencia",
        "vat": 0.0
    },
    "card": {
        "number": "5196330685797445",
        "holder_name": "john noe",
        "expiry_month": 1,
        "expiry_year": 2026,
        "wallet_token": {
            "type": "ApplePay",
            "cryptogram": "AJWGMLI/vbrpABAVn4tuAoABFA==",
            "requestor_id": "50110030273"
        }
    }
}' 'https://ccapi-stg.paymentez.com/v2/transaction/debit_cc'

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

{
  "transaction": {
    "id": "RB-MA-1826",
    "status": "success",
    "current_status": "APPROVED",
    "status_detail": 3,
    "payment_date": "2024-03-04T16:16:44.271",
    "amount": 200.0,
    "installments": 1,
    "carrier_code": "00",
    "message": "Response by mock",
    "authorization_code": "bMSLxK",
    "dev_reference": "referencia",
    "carrier": "Redeban",
    "product_description": "Product description",
    "payment_method_type": "0"
  },
  "card": {
    "number": "7445",
    "bin": "519633",
    "type": "mc",
    "transaction_reference": "RB-MA-1826",
    "expiry_year": "2026",
    "expiry_month": "1",
    "origin": "localhost:8080",
    "fiscal_number": "80265579"
  }
}

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

HTTP Request

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

Usted debe remplazar la cadena codificada base64 auth_token en el encabezado, con su auth_token personal. Cómo construir token.

Parámetros URL

Parámetro	Tipo	Requerido	Descripción
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	Número del token el cual tiene un aspecto muy similar al de una tarjeta real.
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 del token.
card.expiry_year	Number	Yes	El año de caducidad del token.
card.wallet_token.type	String	Yes	Tipo del token (Applepay)
card.wallet_token.cryptogram	Number	Yes	Criptograma generado por el proveedor del token
card.wallet_token.requestor_id	Number	Yes	Id del solicitante del token generado por el proveedor

Respuesta

Ver Objetos en la respuesta

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:

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)
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/

Usted debe remplazar la cadena codificada base64 auth_token en el encabezado, con su auth_token personal. Cómo construir token.

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/

Usted debe remplazar la cadena codificada base64 auth_token en el encabezado, con su auth_token personal. Cómo construir token.

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

Usted debe remplazar la cadena codificada base64 auth_token en el encabezado, con su auth_token personal. Cómo construir token.

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. (Longitud Maxima 100)
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/

Usted debe remplazar la cadena codificada base64 auth_token en el encabezado, con su auth_token personal. Cómo construir token.

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

Usted debe remplazar la cadena codificada base64 auth_token en el encabezado, con su auth_token personal. Cómo construir token.

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>

Usted debe remplazar la cadena codificada base64 auth_token en el encabezado, con su auth_token personal. Cómo construir token.

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.

Payout

curl -k  -L -X POST -H 'Content-Type: application/json' -H 'Auth-Token: auth_token' -d '{
   {
    "order": {
        "amount": 200,
        "currency": "PEN",
        "dev_reference": "123456789"
    },
    "card": {
        "number": "4051421834258061",
        "holder_name": "Jonh Doe",
        "expiry_month": 3,
        "expiry_year": 2030

    },
    "user":{
        "first_name": "Jonh",
        "last_name": "Doe",
        "address": "4533 Loveland",
        "phone": "123456789",
        "zip": "12345",
        "city": "Lima",
        "country": "PER",
        "email": "user@example.com",
        "identification": "10422866472"
    },
    "device": {
        "device_type": "DESKTOP",
        "ip_address": "127.0.0.1"
    }
  }
}' 'https://ccapi-stg.paymentez.com/v3/card/payout/'

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

{
  "application": {
    "code": "CiEquApp"
  },
  "commerce": {
    "merchant_id": "456879852"
  },
  "beneficiary": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "user@example.com",
    "card_bin": "405142",
    "card_number": "8061"
  },
  "transaction": {
    "id": "PP-MA-49",
    "dev_reference": "123456789",
    "amount": 200.0,
    "currency": "PEN",
    "authorization_code": "222752",
    "authorization_date": "2020-04-20 18:34:33",
    "error_code": "00",
    "error_description": "Approved and completed successfully",
    "status_detail": 3,
    "current_status": "APPROVED"
  }
}

Permite realizar un deposito (una transferencia de fondos desde el comercio hacia el consumidor) sin tener una transacción previa

HTTP Request

POST https://ccapi-stg.paymentez.com/v3/card/payout/

Usted debe remplazar la cadena codificada base64 auth_token en el encabezado, con su auth_token personal. Cómo construir token.

Parámetros URL

Parámetro	Tipo	Requerido	Descripción
order.amount	Number	Yes	El monto de la transacción. Decimal con dos decimales.
order.currency	String	Yes	Código de moneda ISO de tres letras, por ejemplo PEN.
order.dev_reference	String	Yes	Referencia del comercio. Longitud máx 50.
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.
user.first_name	String	Yes	Nombre del beneficiario. Longitud máx 30.
user.last_name	String	Yes	Apellido del beneficiario. Longitud máx 40.
user.address	String	Yes	Dirección del beneficiario. Longitud máx 50.
user.phone	String	Yes	Número de teléfono del beneficiario. Longitud máx 18.
user.zip	String	Yes	Código postal del beneficiario. Longitud máx 10.
user.city	String	Yes	Ciudad del beneficiario. Longitud máx 30.
user.country	String	Yes	Código ISO de tres letras para país. por ejemplo PER.
user.state	String	No	El estado donde habita beneficario. Longitud máx 3.
user.email	String	Yes	Correo electrónico del tarjetahabiente.
user.identification	String	Yes	Número de identificación del consumidor en su respectivo país. Longitud máx 15.
device.device_type	String	Yes	Tipo de dispositivos soportados: DESKTOP, SMARTPHONE, TABLET, TV, UNKNOWN
device.ip_address	String	No	Dirección IP válida.

Respuesta

Parámetro	Descripción
application.code	El application_code que lanzó la petición.
commerce.merchant_id	El id del merchant del cual se obtuvieron los fondos para el pago.
beneficiary.first_name	Nombre del beneficiario. Longitud máx 30.
beneficiary.last_name	Apellido del beneficiario. Longitud máx 40.
beneficiary.email	Correo electrónico del tarjetahabiente.
beneficiary.card_bin	El BIN de la tarjeta (primeros seis dígitos de la tarjeta).
beneficiary.card_number	Los últimos cuatro dígitos de la tarjeta.
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.amount	El importe de la transacción.
transaction.authorization_code	El código de autorización que respondió el procesador de pagos.
transaction.authorization_date	Fecha de la autorización en UTC.
transaction.error_code	El código devuelto del Procesador.
transaction.error_description	El mensaje que retorno el procesodor de pagos
transaction.status_detail	El detalle del estado de la transacción, para más información, detalle del estado.
transaction.current_status	Puede ser PENDING, APPROVED, CANCELLED, INITIATED, REJECTED or EXPIRED.

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
cmr	Falabella

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/

Usted debe remplazar la cadena codificada base64 auth_token en el encabezado, con su auth_token personal. Cómo construir token.

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 Brasil)

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:

Visa
Mastercard
Discover / Diners
JCB
UnionPay
American Express

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:

La página de pago coloca los valores de entrada en el endpoint de authenticate 3DS de Nuvei y lo envía.
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.
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.
ACS autentica.
La página de pago recibe el id de la transacción de autenticación de Nuvei y el CRes del ACS.
La página de pago envía el CRes a Nuvei en el endpoint verify_auth.
Nuvei devolverá el resultado de la verificación del CRes.

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

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.
El MPI contacta al directorio y regresa ya sea la respuesta final, o la información necesaria (sdk_response) para completar el desafío.
ACS autentica.
La aplicación movil obtiene el resultado de la autenticación directamente del ACS.
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.
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/

Usted debe remplazar la cadena codificada base64 auth_token en el encabezado, con su auth_token personal. Cómo construir token.

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. (Longitud Maxima 100)
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

* Si envía browser_info, debe enviar todos los parámetros relacionados con el navegador.

N/R sdk_info es obligatorio si device_type es SDK.

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.

El browser_response solo aplica cuando la autenticación se realiza desde un navegador, sdk_response solo se aplica cuando la autenticación se realiza con el SDK para dispositivos móviles. Pero ambos son devueltos.

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/

Usted debe remplazar la cadena codificada base64 auth_token en el encabezado, con su auth_token personal. Cómo construir token.

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/

Usted debe remplazar la cadena codificada base64 auth_token en el encabezado, con su auth_token personal. Cómo construir token.

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:

Añade una pasarele a tu ambiente
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
Para almacenar la nueva tarjeta es necesario que retail_on_suceess: true sea incluido en el request a Spreedly.

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
  Es obligatorio enviar el user.id y user.email, el email es enviado en el payment_method de spreedly.
  Utilice el payment_method token regresado después de haber almacenado o caso 2a para realizar un cobro en Paymentez.
Dependiendo del país finalice la compra (purchase):
Para realizar un cobro (purchase) en Paymentez es necesario enviar el order.description y user.email, mismo si estos campos no están listados en los "gateway_specific_fields" de Spreedly.
A pesar de que ** user.ip_address** es un campo opcional para Paymentez, si utiliza Spreedly será obligatorio enviarlo.

a. Cobro

b. Autorización

c. Captura
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