Introduction

The Nuvei API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. JSON is returned by all API responses, including errors, although our API libraries convert responses to appropriate language-specific objects.

You should never expose your Server Credentials in any public website's client-side code.

To start the integration you will need to request to Nuvei Team integrations@paymentez.com for a Development/Sandbox account. Please send us your e-mail to identify you as a developer and the name of your company.

We will create an Application and give you the application code. From now this will be the identifier for your Application in the whole integration. We also give you a developer account based on the e-mail you provided. We will send you the password via e-mail to access to your developer account. You can access to this configuration here:

Environment	URL
development	https://dashboard-stg.paymentez.com
production	https://dashboard.paymentez.com

You can change you account password or if you forget it you can always use the forgot password option to recover it. In the Nuvei admin system you will see your transactions, application settings (including application URLs and application key) and so more.

Configurations have to be done for the application in development environment and production environment, URLs and application key are different for every environment. Development environment will be always available for tests even after launching your application to production.

Environments

In order to use the API, you need to use one of the following base URLs depending of the environment:

Cards payment method

Environment	URL
development	https://ccapi-stg.paymentez.com
production	https://ccapi.paymentez.com

Cash / Bank Transfer / Wallets / Link To Pay payment methods

Environment	URL
development	https://noccapi-stg.paymentez.com
production	https://noccapi.paymentez.com

Authentication

To build the auth_token, you can use this code:

#!/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";
?>

All the requests must have the header Auth-Token: . This is a base64 encoded string, the string should be created as follows(consider the ; between each one):

APPLICATION-CODE;UNIXTIMESTAMP;UNIQ-TOKEN

Element	Description
APPLICATION-CODE	Ask the Nuvei team for it.
UNIXTIMESTAMP	This must be created at the same time as the request, be aware that the time is in UTC and in SECONDS, you will have 15 seconds before you need to create a new one, or your request will be rejected (error.type: Invalid timestamp).
UNIQ-TOKEN	Is the hexa representation of a hash sha256 generate from the string “secret-key”+”timestamp”, the secret-key is given by Nuvei team.

Once you have the UNIQ-TOKEN you need to apply the sha256 and the hexa convertion, you can use the next python example, just add your server_application_code and server_app_key:

You must replace server_application_code and server_app_key with your personal Nuvei Server Credentials.

Payment Methods

Cash

In this platform we can generate a reference to pay with cash.

Generate a reference

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

The above request returns JSON structured like this:

{
    "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"
    }
}

Cash transactions generates a payment reference through a carrier

HTTP Request

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

You must replace the base64 encoded string auth_token in the header, with your personal auth_token. how to build token

URL Parameters

Parameter	Type	Required	Description
carrier.id	String	Yes	Indicates the method by which the reference will be created. See carrier list
carrier.extra_params.user.name	String	Yes (*)	User name.
carrier.extra_params.user.last_name	String	Yes (*)	User last name.
carrier.extra_params.user.phone	String	Yes (*)	User phone.
carrier.extra_params.user.fiscal_number	String	Yes (*)	The fiscal number (identification number) given by the user.
carrier.extra_params.user.address	Json	Yes (*)	Object with user address, see the specification of address.
user.id	String	Yes	Buyer identifier.
user.email	String	Yes	Buyer email, with valid e-mail format.
order.dev_reference	String	Yes	Id from commerce to identify the order.
order.amount	Number	Yes	Total amount to pay. Format: Decimal with two fraction digits.
order.expiration_days	Number	No	Number of days in which the payment reference expires. Default 2.
order.recurrent	Boolean	No	To indicate if the pay is recurrent or not.
order.description	String	Yes	The order description.
order.hours	Number	No	Optional. If there is value, the reference will last hours.
order.country	String	Optional	Country where payment will be made. By default the credential settings will be used.
order.currency	String	Optional	Currency to be used for payment. By default the credential settings will be used.

Response

Parameter	Description
application.code	Identifier of the application.
commerce.merchant_id	Identifier of the commerce.
user.email	Buyer email registered to order.
user.id	Buyer identifier.
transaction.currency	Currency of the transaction.
transaction.country	Country where the transaction has made.
transaction.dev_reference	Reference from commerce.
transaction.amount	Total amount to pay.
transaction.expiration	Limit date to pay the reference.
transaction.recurrent	Show if the transaction will be recurrent.
transaction.reference	Reference to make the pay in a store.
transaction.agreement	Json object with all agreements to pay (For payvalida).
transaction.status	The status of payment (pending, approved, cancelled).
transaction.id	Id generated by Nuvei
transaction.url_reference	Detailed printable view of the transaction.reference.

Carriers

Carrier	Response fields needed to pay
payvalida	transaction.amount, transaction.agreement and transaction.reference
PagoEfectivo	transaction.url_reference (the printable view) or transaction.amount and transaction.reference (*).
oxxo	transaction.reference that must be converted in a barcode.
bradesco	transaction.url_reference this send the printable view

Fields needed for every cash carrier

Carrier	Fields needed in extra_params
PagoEfectivo	user.name, user.last_name, user.phone (format country code + number eg. +52111111111111) order.hours (optional if there is value the reference will last hours)
oxxo	user.name, user.last_name
bradesco	user.name, user.last_name, user.fiscal_number, user.address

Address

In case you are sending address, this is the Json Object Format:

This is an example of request with Address Object:

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

Parameter	Type	Required	Description
state	String	No	The state: ISO 3166-2 country subdivision code
city	String	No	The city, max length of 30 characters.
zip_code	String	No	The zip or postal code. Max length allowed of 30 characters.
street	String	No	The name of the street.
house_number	String	No	The house number
district	String	No	The district.
additional_address_info	String	No	Additional address info, without format.

Bank transfer

Users make a wire transfer from their bank account. Approval may take up to 72 hours.

To make a bank transfer first you need to get the list of all the banks, then create the transfer reference.

Get Banks

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

The above request returns JSON structured like this:

{
"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"
  }
  ]
}

For bank transfer you will need to list the available banks, in order to show them to the payer and allow him to select the bank where the money will be debited.

HTTP Request

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

You must replace the base64 encoded string auth_token in the header, with your personal auth_token. how to build token

URL Parameters

Parameter	Type	Required	Description
carrier_id	String	Yes	Indicates the carrier from where the list will be obtained. See carrier list

Response

A list of banks

Parameter	Description
bank.name	The name of the bank
bank.code	The code of the bank

Create bank transfer

This is an example of a request for bank transfer

  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"
    }
  }'

The above request returns JSON structured like this:


  {
    "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"
    }
  }

This is an example of a request for Split Bank Transfer:

  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"
    }
  }'

This is an example of response obtained from a Split Bank Transfer:


  {
    "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"
    }
  }

This is an example of a request for 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"
    }
  }'

This is an example of response obtained from a 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
  }
}

This is a example of a request for 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"
              }
          }'

This is a example of response obtained from 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."
            }
        ]
    }
}

This is an example of a request for 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"
   }
}'

This is an example of response obtained from a 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/

You must replace the base64 encoded string auth_token in the header, with your personal auth_token. how to build token
To do full flow test, use bank_code 1022

URL Parameters

Parameter	Type	Required	Description
carrier.id	String	Yes	Indicates the method by which the reference will be created. See carrier list
carrier.extra_params.debit_type	String	No (*)	Debit type. Options
carrier.extra_params.bank_code	String	Yes (*)	Bank code.
carrier.extra_params.response_url	String	Yes (*)	Once the client finishes the payment, response_url will be the URL where the client is expected to arrive, there the transaction status query should be triggered and the final transaction status should be shown to the client.
carrier.extra_params.service_code	String	No (*)	Service code. Options
carrier.extra_params.sub_service_code	String	No (*)	Subservice code. Options
carrier.extra_params.origin_account.application_code	String	Yes (*)	Application previously configured with the origin account data
carrier.extra_params.origin_account.account_number	String	Yes (*)	Origin account number
carrier.extra_params.origin_account.account_type	String	Yes (*)	Origin account type. Options
carrier.extra_params.origin_account.account_nit	String	Yes (*)	Origin account NIT
carrier.extra_params.destination_account.account_number	String	Yes (*)	Destination account number
carrier.extra_params.destination_account.account_type	String	Yes (*)	Destination account type. Options
carrier.extra_params.destination_account.account_identification	String	Yes (*)	Destination account identification
carrier.extra_params.destination_account.account_identification_type	String	Yes (*)	Destination account identification type
carrier.extra_params.destination_account.account_bank_code	String	Yes (*)	Destination account bank code
carrier.extra_params.user.name	String	Yes (*)	User name.
carrier.extra_params.user.type	String	Yes (*)	Type of user, could be N for persona natural or J for persona jurídica.
carrier.extra_params.user.type_fis_number	String	Yes (*)	Indicates the type of fiscal number (user identification).
carrier.extra_params.user.fiscal_number	String	Yes (*)	The fiscal number (identification number) given by the user.
carrier.extra_params.user.ip_address	String	Yes (*)	User IP address. Valid v4 IP address.
carrier.extra_params.split.transactions	String	Yes (*)	Array with the information of how the payment will be divided (commerce/amounts)
carrier.extra_params.split.transactions.application_code	String	Yes (*)	Application that has the account to which a partial amount will be sent
carrier.extra_params.split.transactions.amount	String	Yes (*)	Partial amount of payment
carrier.extra_params.split.transactions.vat	String	Yes (*)	Sales tax amount, included in partial amount. Format: Decimal with two fraction digits.
user.id	String	Yes	Buyer identifier.
user.email	String	Yes	Buyer email, with valid e-mail format.
user.phone_number	String	No	Buyer number phone, required for carrier pse.
user.adress	String	No	Object with user address, see the specification of address.
order.dev_reference	String	Yes	Id from commerce to identify the order. Format: String. For PSE in environment staging could use the next values, pending, rejected, failure, approved, with these values the transactions will have the indicated status
order.amount	Number	Yes	Total amount to pay. Format: Decimal with two fraction digits.
order.vat	Number	No	Sales tax amount, included in order amount. If not sent default 0. Format: Decimal with two fraction digits.
order.description	String	Yes	The order description. Format: (100 characters max)
order.country	String	Optional	Country where payment will be made. By default the credential settings will be used.
order.currency	String	Optional	Currency to be used for payment. By default the credential settings will be used.

Response

Parameter	Description
application.code	Identifier of the application.
commerce.merchant_id	Identifier of the commerce.
user.email	Buyer email registered to order.
user.id	Buyer identifier.
transaction.currency	Currency of the transaction.
transaction.country	Country where the transaction has made.
transaction.dev_reference	Reference from commerce.
transaction.amount	Total amount to pay.
transaction.paid_date	Payment date of the transaction.
transaction.description	Transaction description.
transaction.status	The status of payment (pending, approved, cancelled, failure).
transaction.id	Id generated by Nuvei
transaction.bank_url	The URL where you have to redirect the customer. Note: The url returned in staging environment is a mock.
transaction.status_bank	The status of transaction in the bank.
transaction.trazability_code	Reference number.
transaction.pse_cycle	Cycle number where the transaction was created (only for PSE).
transaction.ticket_id	Id transaction with PSE.
transaction.qr.code	Base64 code for render (only for pix carrier).
transaction.qr.content	plain text content in code (only for pix carrier).

Get status transfer

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

The above request returns JSON structured like this:

{
  "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>

You must replace the base64 encoded string auth_token in the header, with your personal auth_token. how to build token

URL Parameters

Parameter	Type	Required	Description
transaction_id	String	Yes	The transaction id returned from Nuvei

Response

Parameter	Description
application.code	Identifier of the application.
commerce.merchant_id	Identifier of the commerce.
user.email	Buyer email registered to order.
user.id	Buyer identifier.
transaction.currency	Currency of the transaction.
transaction.country	Country where the transaction has made.
transaction.dev_reference	Reference from commerce.
transaction.amount	Total amount to pay.
transaction.paid_date	Payment date of the transaction.
transaction.description	Description of the transaction
transaction.bank_url	The url where the bank has the status. Note: The url returned in staging environment is a mock.
transaction.status_bank	The status returned from the bank
transaction.status	The status of payment (pending, approved, cancelled, failure).
transaction.id	Id generated by Nuvei
transaction.trazability_code	Reference number.
transaction.pse_cycle	Cycle number where the transaction was created (only for PSE).
transaction.ticket_id	Id transaction with PSE.
transaction.qr.code	Base64 code for render (only for pix carrier).
transaction.qr.content	plain text content in code (only for pix carrier).

Refund

Example of refund with total amount:

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

Example of refund with partial amount:

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

Example of response refund:

{
    "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"
    }
}

Example of refund response with partial amount:

{
    "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"
    }
}

Example of fail refund:

{
    "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"
    }
}

This endpoint is used to refund a transaction

HTTP Request

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

You must replace the base64 encoded string auth_token in the header, with your personal auth_token. how to build token

URL Parameters

Parameter	Type	Required	Description
transaction.id	String	Yes (*)	Transaction identifier. This code is unique among all transactions.
order.amount	Number	No	The order amount to refund. Format: Decimal with two fraction digits. If not provided, get the full amount of the transaction. Works with pix-koin

Response

Parameter	Description
status	Could be success or failure
detail	If success could be Completed If failure could be Refund could not be process
transaction.id	Id generated by Nuvei
transaction.status	The status of payment (pending, approved, cancelled, failure).
transaction.status_detail	The status detail of the transaction, for more information status detail
transaction.dev_reference	Reference from commerce.
transaction.amount	Total amount to pay.
transaction.refund_amount	Total refund amount
transaction.currency	Currency of the transaction.
transaction.country	Country where the transaction has made.
transaction.paid_date	Payment date of the transaction.

Cancel

Example of cancel

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'

Example of cancel response

{
    "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
    }
}

Example of fail cancel response

{
    "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"
    }
}

This endpoint allow to update the status of a order, from pending to cancelled, this order don't allow payment

HTTP Request

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

You must replace the base64 encoded string auth_token in the header, with your personal auth_token. how to build token

URL Parameters

Parameter	Type	Required	Description
transaction.id	String	Yes (*)	Transaction identifier. This code is unique among all transactions.

Response

Parameter	Description
status	Could be success or failure
detail	If success could be Completed If failure could be Cancellation could not be applied
transaction.id	Id generated by Nuvei
transaction.status	The status of payment (pending, approved, cancelled, failure).
transaction.status_detail	The status detail of the transaction, for more information status detail
transaction.dev_reference	Reference from commerce.
transaction.amount	Total amount to pay.
transaction.currency	Currency of the transaction.
transaction.country	Country where the transaction has made.
transaction.paid_date	Payment date of the transaction.
transaction.qr.code	Base64 code for render (only for pix carrier).
transaction.qr.content	plain text content in code (only for pix carrier).

Carriers

Fields needed for every carrier

Carrier	Fields needed in 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

Address

Buyer address this is the Json Object Format

Parameter	Type	Required	Description
street	String	No	Street name, max size 100
number	String	No	House number
district	String	No	District name
city	String	No	City name
state	String	No	State name
zip	String	No	Zip code

Fiscal number types

Type	Description
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.

Account types

Type	Description
CC	Cuenta Corriente.
CA	Cuenta de Ahorros.

Debit types

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

Service codes

Type	Description
NOMH	Pago de Nómina.
PROH	Pago de Proveedores.
TCLH	Transferencia cuenta en lote.

QR EMVCo

Through this platform you can create QR codes in order to pay with a wallet, that internally will call the method Debit with QR to make the payment.

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

The above request returns JSON structured like this:

{
  "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
  }
}

In case of error throw in the carrier, the request return a JSON structured like this:

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

This endpoint allow to generate QR codes that the payment method will show in order that the final client will read it

HTTP Request

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

You must replace the base64 encoded string auth_token in the header, with your personal auth_token. how to build token

Body Parameters

Parameter	Type	Required	Description
qr.type	String	Yes	QR type, could be 'STA' for static, or 'DIN' for dynamic.
qr.expiration_time	Number	Yes	Time in seconds it will take to expire the QR to make a payment.
order.amount	Number	Yes	The total amount to pay, tip not included.
order.description	String	Yes	Order description
order.currency	String	No	Order currency see the valid types.
order.country	String	No	Country where the QR will be use, for default the setting in the credentials is used.
cost_breakdown	Array	Yes	Array with one or more objects of amounts, included in order.amount See object amount details.
additional_amounts	Array	Yes	Array with one or more objects that are NOT included in order.amount See object amount details.
carrier.id	String	Yes	Indicates the method by which the QR will be created. For example: 'redeban'
carrier.extra_params	Json	Yes	Extra parameters needed for the carrier.payer is required

Payer object detail.

Parameter	Type	Required	Description
id	String	Yes	Payer id.
name	String	Yes	Payer name.
email	String	Yes	Payer email.
fiscal_number	String	No*	The fiscal number (identification number) given by the payer. Only for pix Brazil.
fiscal_number_type	String	No*	CPF or CNPJ only for pix Brazil.
ip_address	String	No*	IP address from the payer. Only for pix Brazil.

Amount object detail

Parameter	Type	Required	Description
type	String	Yes	Amount type, could be 'vat', 'inc' for INC in Colombia, 'taxable_amount', 'tip'.
amount	Number	Yes	The amount.
calculation_type	String	Yes	'01'- Wallet, '02' - Commerce and '03' - Percentage. Note: IF percentage is selected the amount should be a percentage between 0 and 99.

Response

Parameter	Description
qr.id	Qr identifier. This id is unique in this platform.
qr.code	QR in base 64. String with the information needed to generate the image of the QR.
qr.rows	If more than 0, number of rows in the QR.
qr.error_code	If returned, the error code from the carrier.
qr.error_desc	If returned, the error description from the carrier.

Consult 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'

The above request returns JSON structured like this:

{
  "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"
      }
    ]
  }
}

After the generation of a QR code, the process of authorization will begin once the QR had been read. The consult is needed in order to know the status of the payment intent.

HTTP Request

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

You must replace the base64 encoded string auth_token in the header, with your personal auth_token. how to build token

URL Parameters

Parameter	Type	Required	Description
qr_id	String	Yes	Qr identifier. This id is unique in this platform.
transaction_date	String	No	In case that the payment apply after the creation date, you should specify the transaction date in the following format: YYYY-MM-DD

Response

Parameter	Description
transaction.status	Could be success, pending or failure.
transaction.current_status	Could be PENDING, APPROVED, CANCELLED, INITIATED, REJECTED or EXPIRED.
transaction.payment_date	If staging environment the date will be in UTC, otherwise will depend on carrier.
transaction.amount	The amount of the transaction.
transaction.authorization_code	If success the authorization code responded from carrier.
transaction.installments	The number of installments for the payment.
transaction.dev_reference	For QR empty string
transaction.message	The returned message from carrier.
transaction.carrier_code	The returned code from carrier.
transaction.id	Transaction identifier. This code is unique among all transactions.
transaction.status_detail	The status detail of the transaction, for more information status detail
card.bin	The BIN of the card (First six digits of the card).
card.expiry_year	The expiry year of the card.
card.expiry_month	The expiry month of the card.
card.type	Abbreviated card type. See the valid options
card.number	The last four digits of the card.
card.origin	Channel where the transaction was originated.
qr.terminal	Terminal ID.
qr.commerce	Commerce ID.
qr.additional_amount_info	Array of objects that contains amount and type, where type could be one of the followings: vat, inc or tip.

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

The above request returns JSON structured like this:

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

This endpoint allow to update the status of a QR code, from active to inactive, enabling that a QR code don't has more than one payment.

HTTP Request

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

You must replace the base64 encoded string auth_token in the header, with your personal auth_token. how to build token

URL Parameters

Parameter	Type	Required	Description
qr_id	String	Yes	Qr identifier. This id is unique in this platform.

Body Parameters

Parameter	Type	Required	Description
status	String	Yes	Could be active or inactive

Response

Parameter	Description
response.description	Description of the code returned.
response.code	OK if success case. E01, E02 or E09 otherwise.

Wallets

Through this platform you can make payments with electronic wallets such as DaviPlata in Colombia. Two steps are needed:

Generate an order
If was a successful one verify the order

Generate an order

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

The above request returns JSON structured like this:

{
  "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
  }
}

Generate a purchase order in the wallet. For example: 'daviplata'

HTTP Request

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

You must replace the base64 encoded string auth_token in the header, with your personal auth_token. how to build token

URL Parameters

Parameter	Type	Required	Description
carrier.id	String	Yes	Indicates the method where the order will be created.
carrier.extra_params.user.type_fis_number	String	Yes (*)	Indicates the type of fiscal number (user identification).
carrier.extra_params.user.fiscal_number	String	Yes (*)	The fiscal number (identification number) given by the user.
user.id	String	Yes	Buyer identifier.
user.email	String	Yes	Buyer email, with valid e-mail format.
order.dev_reference	String	Yes	Id from commerce to identify the order.
order.amount	Number	Yes	Total amount to pay. Format: Decimal with two fraction digits.
order.description	String	Yes	The order description. Format: (100 characters max)
order.country	String	Optional	Country where payment will be made. By default the credential settings will be used.
order.currency	String	Optional	Currency to be used for payment. By default the credential settings will be used.

Response

Parameter	Description
application.code	Identifier of the application.
commerce.merchant_id	Identifier of the commerce.
user.email	Buyer email registered to order.
user.id	Buyer identifier.
transaction.currency	Currency of the transaction.
transaction.country	Country where the transaction has made.
transaction.dev_reference	Reference from commerce.
transaction.amount	Total amount to pay.
transaction.status	The status of the payment could be pending, failure or approved
transaction.id	Id generated by Nuvei
transaction.date	Transaction date returned by carrier.
transaction.authorization_code	Authorization code returned by carrier.

Verify the order

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

The above request returns JSON structured like this:

{
  "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"
  }
}

Only if the order generated before is with status pending, you need to verify the order.

HTTP Request

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

You must replace the base64 encoded string auth_token in the header, with your personal auth_token. how to build token

URL Parameters

Parameter	Type	Required	Description
transaction.id	String	Yes	Payment Id returned in the generation of an order.
type	String	Yes	The type of value that is going to be sent in the request. Valid strings "BY_OTP".
value	String	Yes	The OTP (One Time Password) sent to the client.

Response

The same kind of response of generate an order.

Cards

In this platform we can securely store the sensitive credit card data.

This data is transformed into an encrypted code called token, which can be stored in a database. With the platform, the store will be able to offer features like “One click buy” and “Retry transaction”, always preserving the integrity and the confidentiality of the information.

Add a Card

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'

The above request returns JSON structured like this:

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

This endpoint add a card to the platform related to a user.

HTTP Request

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

You must replace the base64 encoded string auth_token in the header, with your personal auth_token. how to build token

URL Parameters

Parameter	Type	Required	Description
session_id	String	No	Fraud related parameter. 32-length numeric hash.
user.id	String	Yes	Customer identifier. This is the identifier you use inside your application. Max length allowed 100 characters
user.email	String	Yes	Buyer email, with valid e-mail format.
user.phone	String	No	Buyer phone.
user.ip_address	String	No	User IP address. Valid v4 IP address.
user.fiscal_number	String	No	The fiscal number given by the buyer Note: For card types ex, ak, vr, sx, ol, ep and cd this field is mandatory.
card.number	String	Yes	A valid credit card number.
card.holder_name	String	Yes	The credit card holder name.
card.expiry_month	Number	Yes	The credit card expiry month.
card.expiry_year	Number	Yes	The credit card expiry year.
card.cvc	String	Yes	The credit card security number.
card.type	String	No	Abbreviated card type. See the valid options
card.account_type	String	No	The corresponding values for: Credit, Checking and Savings accounts are: C, R and A respectively. This field is mandatory for QR Colombia.
extra_params	Json	No	Optional params (3DS 2 objects included) used for some commerce in Json format. Please contact your commercial executive for more details.
billing_address	Json	No	Object with the billing address, see the specification of address.

Response

Parameter	Description
card.bin	The BIN of the card (First six digits of the card).
card.status	Either of the following status: valid, review, pending and rejected. If the response is "review" or "pending", the transaction associated to the attempt to add a card (transaction_reference) needs to be verified by the user, to set this card as valid.
card.token	New card identifier. This code is unique among all cards, only returned if status is valid or review, "" otherwise.
card.message	If any, would be the message of the carrier for example in case of rejected by carrier.
card.expiry_year	The expiry year of the card.
card.expiry_month	The expiry month of the card.
card.transaction_reference	The transaction.id that origin the addition of the card (only if it was sent to review, by the anti-fraud system, null otherwise).
card.type	Abbreviated card type. See the valid options
card.number	The last four digits of the card.
card.origin	The origin of the credit card. Could be one of the following: Paymentez, VisaCheckout, Masterpass.

Get all Cards

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

The above request returns JSON structured like this:

{
    "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
}

This endpoint retrieves all Cards related to a user.

HTTP Request

GET https://ccapi-stg.paymentez.com/v2/card/list

You must replace the base64 encoded string auth_token in the header, with your personal auth_token. how to build token

URL Parameters

Parameter	Type	Required	Description
uid	String	Yes	Customer identifier. This is the identifier you use inside your application.

Response

A list of cards

Parameter	Description
result_size	Number of items of the list of cards.
card.bin	The BIN of the card (First six digits of the card).
card.status	Either of the following status: valid, review, pending and rejected. If the response is "review" or "pending", the transaction associated to the attempt to add a card (transaction_reference) needs to be verified by the user, to set this card as valid.
card.token	Card identifier. This code is unique among all cards
card.holder_name	The credit card holder name.
card.expiry_year	The expiry year of the card.
card.expiry_month	The expiry month of the card.
card.transaction_reference	The transaction.id that origin the addition of the card (only if it was sent to review, by the anti-fraud system, null otherwise).
card.type	Abbreviated card type. See the valid options
card.number	The last four digits of the card.

Delete a Card

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

The above request returns JSON structured like this:

{
  "message": "card deleted"
}

This endpoint delete a Card related to a user

HTTP Request

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

You must replace the base64 encoded string auth_token in the header, with your personal auth_token. how to build token

URL Parameters

Parameter	Type	Required	Description
card.token	String	Yes	Card Identifier. This code is unique among all cards. Format: Long Integer.
user.id	String	Yes	Customer identifier. This is the identifier you use inside your application.

Init a Reference

This is an example of basic request for init reference

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

This is an example of request with all parameters for init reference

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

The above request returns JSON structured like this:

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

This endpoint is used for initialize a reference for checkout.

HTTP Request

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

You must replace the base64 encoded string auth_token in the header, with your personal auth_token. how to build token

URL Parameters

Parameter	Type	Required	Description
locale	String	Yes	User's preferred language (es, en, pt). English will be used by default.
session_id	String	No	Fraud related parameter. 32-length numeric hash.
antifraud	Json	No	Object with antifraud data, see the specification of antifraud.
order.amount	Number	Yes	Amount to debit. Format: Decimal with two fraction digits.
order.description	String	Yes	Description of the order to be purchase. Format: (Maximum Length 250)
order.vat	Number	Yes	Sales tax amount, included in product cost. Format: Decimal with two fraction digits.
order.dev_reference	String	Yes	Merchant order reference. You will identify this purchase using this reference.
order.installments_type	Number	No	Only available for Ecuador and Mexico. See the valid values
conf	Json	No	Object with data for conf , see the specification for conf.
billing_address	Json	No	Object with the billing address, see the specification of address.
user.id	String	Yes	Customer identifier. This is the identifier you use inside your application.
user.email	String	Yes	Buyer email, with valid e-mail format.

Response

Parameter	Description
checkout_url	Checkout URL, use for render checkout
reference	Reference, use for render checkout, is required a reference for render.

Data for conf

Required from conf, when integration is API

Parameter	Type	Required	Description
conf.allowed_card_brands	String	No	Allowed card brands to this operation. See the valid options
conf.allowed_card_types	String	No	Allowed card types
conf.invalid_card_type_message	String	No	Define a custom message to show for invalid card types.
conf.theme	JSON	No	Data for custom checkout color's

Debit with token

Base Case

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

The above request returns JSON structured like this:

{
  "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"
  }
}

This is an example of response for 3DS 2 with objects for authentication:

{
  "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": ""
    }
  }
}

This endpoint creates a debit transaction with a stored credit card. If you want to debit with 3D Secure 2 authentication, there are two possible ways:

Direct debit with Nuvei. This will include extra_params in the request, that are used for authentication (See objects for authentication)
By Performing a 3D Secure 2 authentication calling the proper endpoint Authentication 3DS 2 section, before calling the debit.

HTTP Request

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

You must replace the base64 encoded string auth_token in the header, with your personal auth_token. how to build token

URL Parameters

Parameter	Type	Required	Description
session_id	String	No	Fraud related parameter. 32-length numeric hash.
order.amount	Number	Yes	Amount to debit. Format: Decimal with two fraction digits.
order.description	String	Yes	Description of the order to be purchase. Format: (Maximum Length 250)
order.dev_reference	String	Yes	Merchant order reference. You will identify this purchase using this reference.
order.vat	Number	Yes	Sales tax amount, included in product cost. Format: Decimal with two fraction digits.
order.installments	Number	No	The number of installments for the payment, only for COP, MXN, BRL, PEN, CLP and USD (Ecuador).
order.installments_type	Number	No	Only available for Ecuador and Mexico. See the valid values
order.taxable_amount	Number	No	Only available for Ecuador and Colombia. The taxable amount is the total amount of all taxable items excluding tax. If not sent, it's calculated on the total. Format: Decimal with two fraction digits.
order.tax_percentage	Number	No	Only available for Ecuador and Colombia. The tax rate to be applied to this order. For Ecuador should be 0 or 12.
order.months_grace	Number	No	Only available for Mexico and Ecuador (Medianet), the number of months of grace for a deferred payment.
user.id	String	Yes	Customer identifier. This is the identifier you use inside your application.
user.first_name	String	No	User name.
user.last_name	String	No	User last name.
user.email	String	Yes	Buyer email, with valid e-mail format.
user.phone	String	No	Buyer phone.
user.ip_address	String	No	User IP address. Valid v4 IP address.
user.fiscal_number	String	No	The fiscal number given by the buyer Note: For card types ex, ak, vr, sx, ol, ep and cd this field is mandatory.
card.token	String	No	Card Identifier. This code is unique among all cards. Format: Long Integer.
card.cvc	String	No	The credit card security number.
wallet.type	String	No	Type of wallet, the valid are : 'VisaCheckout', 'Masterpass' and 'CyberSource'.
wallet.key	String	No	The id of the wallet (either callid, transactionId or subscriptionID ).
extra_params	Json	No	Optional params (3DS 2 objects included) used for some commerce in Json format. Please contact your commercial executive for more details.
shipping_address	Json	No	Object with the shipping address, see the specification of address.
airline	Json	No	Object with airline data, see the specification of airline.
hotel	Json	No	Object with hotel data, see the specification of hotel.

Response

Parameter	Description
transaction.status	Could be success, failure or pending.
transaction.current_status	Could be PENDING, APPROVED, CANCELLED, INITIATED, REJECTED or EXPIRED.
transaction.payment_date	If staging environment the date will be in UTC, otherwise will depend on carrier.
transaction.amount	The amount of the transaction.
transaction.authorization_code	If success the authorization code responded from carrier.
transaction.installments	The number of installments for the payment.
transaction.dev_reference	Merchant order reference.
transaction.message	The returned message from carrier or fraud analysis system.
transaction.carrier_code	The returned code from carrier.
transaction.id	Transaction identifier. This code is unique among all transactions.
transaction.status_detail	The status detail of the transaction, for more information status detail
transaction.installments_type	Only available for Ecuador and Mexico. See the valid values
transaction.payment_method_type	Payment method of the transaction, type string. For more information payment_method_types
transaction.product_description	Order description.
transaction.trace_number	Only available for Ecuador and Mexico.
transaction.lot_number	Only available for Ecuador.
card.bin	The BIN of the card (First six digits of the card).
card.expiry_year	The expiry year of the card.
card.expiry_month	The expiry month of the card.
card.transaction_reference	If any, the transaction.id
card.type	Abbreviated card type. See the valid options
card.number	The last four digits of the card.
card.origin	The origin of the credit card. Could be one of the following: Paymentez, VisaCheckout, Masterpass.

In case of transactions that were authenticated with 3DS 2, the response will include:

Parameter	Description
3ds.sdk_response.acs_trans_id	Transaction ID from ACS.
3ds.sdk_response.acs_signed_content	Signed content from ACS.
3ds.sdk_response.acs_reference_number	ACS reference number.
3ds.authentication.status	Authentication status, could be: "Y", "N", "U", "A", "R", "C" or "-" if value not available due errors or not enrolled, for more information authentication_status.
3ds.authentication.xid	Transaction identifier sent to MPI.
3ds.authentication.return_code	Returned code from MPI, that provides all the information that is needed to determine how to manage the transaction, for more information return code mpi
3ds.authentication.eci	Electronic Commerce Indicator, with visa cards, the value to be passed in Authorization message.
3ds.authentication.return_message	Description of the return_code.
3ds.authentication.version	3DS message version used.
3ds.authentication.cavv	Cardholder Authentication Verification Value, determined by ACS. Format: base64
3ds.authentication.reference_id	DS Transaction Id.
3ds.browser_response.challenge_request	If cardholder was enrolled and or challenge authentication requested, payment page application must redirects the user browser to the ACS. If this field is not empty, it will contain the html to redirect.
3ds.browser_response.hidden_iframe	If this field is not empty, the content should be render into an intermediate page into an invisible iframe and wait about 5 seconds.
3ds.service	The name of the MPI that has authenticated the transaction.

Objects for authentication

Before perform a payment whether through a debit with token, a debit with card or an authorization, it is possible to first perform a 3D Secure authentication, sending this objects in extra_params:

Object name	Description
threeDS2_data	If authentication will be performed directly in debit/authorization this object is required.
browser_info	Required for device_type browser.
auth_data	Use this object if you performed the authentication first.
risk_indicator	Additional risk fields for 3DS 2. Include this in your request whenever available.

Parameter	Type	Required	Description
extra_params.threeDS2_data.term_url	String	Yes	Merchant page url, where ACS will post (via user browser) CRes message after authentication.
extra_params.threeDS2_data.device_type	String	Yes	Device type. Valid strings: browser, SDK.
extra_params.threeDS2_data.process_anyway	Boolean	No	Process anyway, ie. no matter the result of the authentication, perform the debit/authorize. If not provided default false.
extra_params.threeDS2_data.reference_id	String	Yes*	Mandatory only for MPI CyberSource, the id used to build the jwt sent in the init method in front end.
extra_params.browser_info.ip	String	C	User IP address. Valid v4 IP address.
extra_params.browser_info.language	String	C	Language of the browser.
extra_params.browser_info.java_enabled	Boolean	C	If java is enabled in the browser.
extra_params.browser_info.js_enabled	Boolean	C	If Java Script is enabled in the browser.
extra_params.browser_info.color_depth	Number	C	Color depth of the browser.
extra_params.browser_info.screen_height	Number	C	Screen height of the browser.
extra_params.browser_info.screen_width	Number	C	Screen width of the browser.
extra_params.browser_info.timezone_offset	Number	C	Time Zone Offset.
extra_params.browser_info.user_agent	String	C	User agent.
extra_params.browser_info.accept_header	String	C	Accept header.
extra_params.auth_data.cavv	String	Yes	Cardholder Authentication Verification Value, determined by ACS. Format: base64
extra_params.auth_data.xid	String	No	Transaction identifier sent to MPI.
extra_params.auth_data.eci	String	Yes	Electronic Commerce Indicator, with visa cards, the value to be passed in Authorization message.
extra_params.auth_data.version	String	Yes	3DS message version used.
extra_params.auth_data.reference_id	UUID	Yes	DS Transaction Id.
extra_params.auth_data.status	String	Yes	Authentication status, could be: "Y", "N", "U", "A", "R" or "C", for more information authentication_status

Address

This is an example of request with Billing Address Object:

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'

In case you are sending the billing or shipping address, this is the Json Object Format:

Parameter	Type	Required	Description
first_name	String	No	Address owner name
last_name	String	No	Address owner last name
street	String	No	The name of the street.
city	String	No	The city, max length of 50 characters.
state	String	No	The state: ISO 3166-2 country subdivision code in case of 3DS authentication, free format otherwise
district	String	No	The district.
zip	String	No	The zip or postal code. Max length allowed of 50 characters.
house_number	String	No	The house number
country	String	No	Country in ISO 3166-1 alpha-3 format, for example: COL, MEX, ECU.
additional_address_info	String	No	Additional address info, without format.

Hotel Data

This is an example of request with hotel data.

 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'

In case you are sending airline hotel, this is the Json Object Format.

Parameter	Type	Required	Description
booking_reference	String	Yes	Booking reference.
booking_country	String	No	Country booking, Format: ISO 3166-2.
issue_date	String	Yes	Reservation date in the following format:YYYY-MM-DD HH:MM:SS.
name	String	Yes	Hotel name.
code	String	Yes	Hotel code.
arrival_date	String	Yes	Arrival date in the following format:YYYY-MM-DD HH:MM:SS.
departure_date	String	Yes	Departure date in the following format:YYYY-MM-DD HH:MM:SS.
payer_in	Boolean	No	True if payer is in booking.
country	String	Yes	Hotel country, Format: ISO 3166-2.
numbers_child	Number	Yes	Total child.
numbers_adt	Number	Yes	Total adult.
transportation_include	Boolean	No	True if include transportation.
transport_name	String	No	Transport name.

Airline Data

This is an example of request with airline data.

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'

In case you are sending airline data, this is the Json Object Format.

Parameter	Type	Required	Description
flight_legs	Array	Yes	Array with one or more objects of flight leg.see the specification of flight_leg.
passengers	Array	Yes	Array with one or more objects of passenger.see the specification of passenger
reservation.airline_code	String	Yes	Airline code.
reservation.booking_reference	String	Yes	Booking reference.
reservation.document_type	String	Yes	Document type can be ELECTRONIC_TICKET or OTHER.
reservation.issue_date	Date Time	Yes	Reservation date in the following format:YYYY-MM-DD HH:MM:SS.
reservation.ticket_number	String	No	Ticket number.
reservation.travel_agent_code	String	Yes	Travel agent code.
reservation.travel_agent_name	String	Yes	Travel agent name.
reservation.itinerary_type	String	No	Itinerary type can be MULTI_DESTINATION, ONE_WAY, ROUND_TRIP.
reservation.complete_route	String	No	Complete route example: SFO-JFK:JFK-LHR:LHR-CDG.
reservation.frequent_flyer	String	No	Frequent flyer code, split with _.
reservation.delta_days	Number	No	Delta days.
reservation.city_departure	String	No	Departure city.
reservation.city_arrival	String	No	Arrival City.

Flight leg object detail.

Parameter	Type	Required	Description
carrier_code	String	Yes	Carrier code.
departure_airport	String	Yes	Departure airport.
departure_date	Date Time	Yes	Departure date in the following format:YYYY-MM-DD HH:MM:SS.
destination_airport	String	Yes	Destination airport
arrival_date	Date Time	Yes	Arrival date in the following format:YYYY-MM-DD HH:MM:SS.
flight_number	String	Yes	Flight number.
stopover_allowed	Boolean	No	Allow stopover.

Passenger object detail.

Parameter	Type	Required	Description
id	String	No	User id.
first_name	String	Yes	First name passenger.
last_name	String	Yes	Last name passenger.
middle_name	String	No	Middle name passenger.
title	String	Yes	Title passenger.
email	String	No	Passenger email.
type	String	No	Passenger type : ADT, INF ó CHD.
phone	String	No	Passenger phone.
amount	Number	No	Amount for passenger. Format: Decimal with two fraction digits.

Installments Type

The installments type are only available for Ecuador and Mexico. For this countries if you send installments, then the installments_type are mandatory. The valid values are:

Type	Description
0	Revolving credit (rotativo).
1	Revolving and deferred without interest (The bank will pay to the commerce the installment, month by month).
2	Deferred with interest.
3	Deferred without interest.
7	Deferred with interest and months of grace.
6	Deferred without interest pay month by month. *()**
9	Deferred without interest and months of grace.
10	Deferred without interest promotion bimonthly. *()**
21	For Diners Club exclusive, deferred with and without interest.
22	For Diners Club exclusive, deferred with and without interest.
30	Deferred with interest pay month by month. *()**
50	Deferred without interest promotions (Supermaxi). *()**
51	Deferred with interest (Cuota fácil). *()**
52	Without interest (Rendecion Produmillas). *()**
53	Without interest sale with promotions. *()**
70	Deferred special without interest. *()**
72	Credit without interest (cte smax). *()**
73	Special credit without interest (smax). *()**
74	Prepay without interest (smax). *()**
75	Deffered credit without interest (smax). *()**
90	Without interest with months of grace (Supermaxi). *()**

Split payment

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

The above request returns JSON structured like this:

{
  "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"
  }
}

This endpoint is used to make payments that enables to split the order amount between different applications (Available only for Colombia).

HTTP Request

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

You must replace the base64 encoded string auth_token in the header, with your personal auth_token. how to build token

URL Parameters

Parameter	Type	Required	Description
session_id	String	No	Fraud related parameter. 32-length numeric hash.
order.amount	Number	Yes	Total amount to pay. Format: Decimal with two fraction digits.
order.description	String	Yes	The order description.
order.dev_reference	String	Yes	Id from commerce to identify the order.
order.vat	Number	Yes	Sales tax amount, included in product cost. Format: Decimal with two fraction digits.
order.installments	Number	No	The number of installments for the payment, only for COP, MXN, BRL, PEN, CLP and USD (Ecuador).
user.id	String	Yes	Buyer identifier.
user.email	String	Yes	Buyer email registered to order.
user.phone	String	No	Numero de teléfono del comprador.
user.ip_address	String	No	User IP address. Valid v4 IP address.
user.fiscal_number	String	No	The fiscal number given by the buyer Note: For card types ex, ak, vr, sx, ol, ep and cd this field is mandatory.
card.token	String	Yes	Card Identifier. This code is unique among all cards. Format: Long Integer.
extra_params	Json	Yes	Required params to generate a split transaction See split params

Split params

Parameter	Type	Required	Description
split.transactions	Array	Yes	Array with the information of how the payment will be divided (commerce/amounts)
split.transactions.application_code	String	Yes	Application that has the account to which a partial amount will be sent
split.transactions.amount	Number	Yes	Partial amount of payment
split.transactions.installments	Number	Yes	The number of installments for the partial amount

Split response

Parameter	Description
transaction.status	Could be success, failure, pending, expired or canceled.
transaction.payment_date	If staging environment the date will be in UTC, otherwise will depend on carrier.
transaction.amount	The amount of the transaction.
transaction.authorization_code	If success the authorization code responded from carrier.
transaction.installments	The number of installments for the payment.
transaction.dev_reference	Merchant order reference.
transaction.message	The returned message from carrier or fraud analysis system.
transaction.carrier_code	The returned code from carrier.
transaction.id	Transaction identifier. This code is unique among all transactions.
transaction.status_detail	The status detail of the transaction, for more information status detail
card.bin	The BIN of the card (First six digits of the card).
card.expiry_year	The expiry year of the card.
card.expiry_month	The expiry month of the card.
card.transaction_reference	If any, the transaction.id
card.type	Abbreviated card type. See the valid options
card.number	The last four digits of the card.
card.origin	The origin of the credit card. Could be one of the following: Paymentez, VisaCheckout, Masterpass.
split.transactions	Array containing authorized transactions on split payment
split.transactions.application_code	Application that corresponds to that payment
split.transactions.amount	Partial amount of the total order
split.transactions.id	Transaction identifier of split payment
split.transactions.installments	The number of installments for the partial amount
split.transactions.authorization_code	Split transaction authorization code

Debit with 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/'

This endpoint creates a debit transaction with a QR code, only for Colombia (COP).

This is a solution that allow to pay throw a QR code generated in the dataphone or mobile application that is scaned from the mobile wallet of the client.

HTTP Request

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

You must replace the base64 encoded string auth_token in the header, with your personal auth_token. how to build token

URL Parameters

Parameter	Type	Required	Description
session_id	String	No	Fraud related parameter. 32-length numeric hash.
order.amount	Number	Yes	Total amount to pay. Format: Decimal with two fraction digits.
order.description	String	Yes	The order description.
order.dev_reference	String	Yes	Id from commerce to identify the order.
order.vat	Number	Yes	Sales tax amount, included in product cost. Format: Decimal with two fraction digits.
order.installments	Number	No	The number of installments for the payment, only for COP, MXN, BRL, PEN, CLP and USD (Ecuador).
user.id	String	Yes	Buyer identifier.
user.email	String	Yes	Buyer email registered to order.
user.phone	String	No	Numero de teléfono del comprador.
user.ip_address	String	No	User IP address. Valid v4 IP address.
user.fiscal_number	String	No	The fiscal number given by the buyer Note: For card types ex, ak, vr, sx, ol, ep and cd this field is mandatory.
user.fiscal_number_type	String	No	Fiscal number type
card.token	String	Yes	Card Identifier. This code is unique among all cards. Format: Long Integer.
card.account_type	String	No	The corresponding values for: Credit, Checking and Savings accounts are: C, R and A respectively.
extra_params.qr_data	Json	Yes	Json returned in the SDK.

Response

See Objects in response

Debit with credit card

Base Case


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'

The above request returns JSON structured like this:

{
  "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"
  }
}

An example of request with 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'

This is an example of request making the request with 3ds 2 objects for authentication:


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'

This endpoint creates a debit transaction with a credit card.

If you want to debit with 3D Secure 2 authentication, there are two possible ways:

Direct debit with Nuvei. This will include extra_params in the request, that are used for authentication (See objects for authentication)
By Performing a 3D Secure 2 authentication calling the proper endpoint Authentication 3DS 2 section, before calling the debit.

HTTP Request

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

You must replace the base64 encoded string auth_token in the header, with your personal auth_token. how to build token

URL Parameters

Parameter	Type	Required	Description
session_id	String	No	Fraud related parameter. 32-length numeric hash.
order.amount	Number	Yes	Amount to debit. Format: Decimal with two fraction digits.
order.description	String	Yes	Description of the order to be purchase. Format: (Maximum Length 250)
order.dev_reference	String	Yes	Merchant order reference. You will identify this purchase using this reference.
order.vat	Number	Yes	Sales tax amount, included in product cost. Format: Decimal with two fraction digits.
order.installments	Number	No	The number of installments for the payment, only for COP, MXN, BRL, PEN, CLP and USD (Ecuador).
order.installments_type	Number	No	Only available for Ecuador and Mexico. See the valid values
order.taxable_amount	Number	No	Only available for Ecuador and Colombia. The taxable amount is the total amount of all taxable items excluding tax. If not sent, it's calculated on the total. Format: Decimal with two fraction digits.
order.tax_percentage	Number	No	Only available for Ecuador and Colombia. The tax rate to be applied to this order. For Ecuador should be 0 or 12.
order.months_grace	Number	No	Only available for Mexico and Ecuador (Medianet), the number of months of grace for a deferred payment.
user.id	String	Yes	Customer identifier. This is the identifier you use inside your application.
user.first_name	String	No	User name.
user.last_name	String	No	User last name.
user.email	String	Yes	Buyer email, with valid e-mail format.
user.phone	String	No	Buyer phone.
user.ip_address	String	No	User IP address. Valid v4 IP address.
user.fiscal_number	String	No	The fiscal number given by the buyer Note: For card types ex, ak, vr, sx, ol, ep and cd this field is mandatory.
user.fiscal_number_type	String	No	Fiscal number type
card.number	String	Yes	A valid credit card number.
card.holder_name	String	Yes	The credit card holder name.
card.expiry_month	Number	Yes	The credit card expiry month.
card.expiry_year	Number	Yes	The credit card expiry year.
card.cvc	String	Yes	The credit card security number.
card.type	String	No	Abbreviated card type. See the valid options
extra_params	Json	No	Optional params (3DS 2 objects included) used for some commerce in Json format. Please contact your commercial executive for more details.
billing_address	Json	No	Object with the billing address, see the specification of address.
shipping_address	Json	No	Object with the shipping address, see the specification of address.
airline	Json	No	Object with airline data, see the specification of airline.
hotel	Json	No	Object with hotel data, see the specification of hotel.

Response

See Objects in response

Split payment

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'

The above request returns JSON structured like this:

{
    "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"
    }
}

This endpoint is used to make payments that enables to split the order amount between different applications (Available only for Colombia).

HTTP Request

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

You must replace the base64 encoded string auth_token in the header, with your personal auth_token. how to build token

URL Parameters

Parameter	Type	Required	Description
session_id	String	No	Fraud related parameter. 32-length numeric hash.
order.amount	Number	Yes	Total amount to pay. Format: Decimal with two fraction digits.
order.description	String	Yes	The order description.
order.dev_reference	String	Yes	Id from commerce to identify the order.
order.vat	Number	Yes	Sales tax amount, included in product cost. Format: Decimal with two fraction digits.
order.installments	Number	No	The number of installments for the payment, only for COP, MXN, BRL, PEN, CLP and USD (Ecuador).
user.id	String	Yes	Buyer identifier.
user.email	String	Yes	Buyer email registered to order.
user.phone	String	No	Numero de teléfono del comprador.
user.ip_address	String	No	User IP address. Valid v4 IP address.
user.fiscal_number	String	No	The fiscal number given by the buyer Note: For card types ex, ak, vr, sx, ol, ep and cd this field is mandatory.
card.number	String	Yes	A valid credit card number.
card.holder_name	String	Yes	The credit card holder name.
card.expiry_month	Number	Yes	The credit card expiry month.
card.expiry_year	Number	Yes	The credit card expiry year.
card.cvc	String	Yes	The credit card security number.
card.type	String	No	Abbreviated card type. See the valid options
extra_params	Json	Yes	Required params to generate a split transaction See split params

Split params

Parameter	Type	Required	Description
split.transactions	Array	Yes	Array with the information of how the payment will be divided (commerce/amounts)
split.transactions.application_code	String	Yes	Application that has the account to which a partial amount will be sent
split.transactions.amount	Number	Yes	Partial amount of payment
split.transactions.installments	Number	Yes	The number of installments for the partial amount

Split response

Parameter	Description
transaction.status	Could be success, failure, pending, expired or canceled.
transaction.payment_date	If staging environment the date will be in UTC, otherwise will depend on carrier.
transaction.amount	The amount of the transaction.
transaction.authorization_code	If success the authorization code responded from carrier.
transaction.installments	The number of installments for the payment.
transaction.dev_reference	Merchant order reference.
transaction.message	The returned message from carrier or fraud analysis system.
transaction.carrier_code	The returned code from carrier.
transaction.id	Transaction identifier. This code is unique among all transactions.
transaction.status_detail	The status detail of the transaction, for more information status detail
card.bin	The BIN of the card (First six digits of the card).
card.expiry_year	The expiry year of the card.
card.expiry_month	The expiry month of the card.
card.transaction_reference	If any, the transaction.id
card.type	Abbreviated card type. See the valid options
card.number	The last four digits of the card.
card.origin	The origin of the credit card. Could be one of the following: Paymentez, VisaCheckout, Masterpass.
split.transactions	Array containing authorized transactions on split payment
split.transactions.application_code	Application that corresponds to that payment
split.transactions.amount	Partial amount of the total order
split.transactions.id	Transaction identifier of split payment
split.transactions.installments	The number of installments for the partial amount
split.transactions.authorization_code	Split transaction authorization code

Debit with 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'

The above request returns JSON structured like this:

{
  "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"
  }
}

This endpoint creates a debit transaction with a credit card through a token.

HTTP Request

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

You must replace the base64 encoded string auth_token in the header, with your personal auth_token. how to build token

URL Parameters

Parameter	Type	Required	Description
order.amount	Number	Yes	Total amount to pay. Format: Decimal with two fraction digits.
order.description	String	Yes	The order description.
order.dev_reference	String	Yes	Id from commerce to identify the order.
order.vat	Number	Yes	Sales tax amount, included in product cost. Format: Decimal with two fraction digits.
order.installments	Number	No	The number of installments for the payment, only for COP, MXN, BRL, PEN, CLP and USD (Ecuador).
user.id	String	Yes	Buyer identifier.
user.email	String	Yes	Buyer email registered to order.
user.phone	String	No	Numero de teléfono del comprador.
user.ip_address	String	No	User IP address. Valid v4 IP address.
user.fiscal_number	String	No	The fiscal number given by the buyer Note: For card types ex, ak, vr, sx, ol, ep and cd this field is mandatory.
card.number	String	Yes	Token number that seems like a real card number.
card.holder_name	String	Yes	The credit card holder name.
card.expiry_month	Number	Yes	The token expiry month.
card.expiry_year	Number	Yes	The token expiry year.
card.wallet_token.type	String	Yes	Type of the token (Applepay)
card.wallet_token.cryptogram	Number	Yes	Cryptogram generated by the token provider
card.wallet_token.requestor_id	Number	Yes	Id token requestor

Response

See Objects in response

Authorize

Case a) sending only the 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/'

The above request returns JSON structured like this:

{
  "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"
  }
}

Case b) sending all the information of the card (pci commerce)

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

The above request returns JSON structured like this:

{
  "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"
  }
}

This endpoint send for authorization a transaction of Credit Card (Only for Cielo (BRL), Prosa (MXN) Procesos and Visanet (PEN))

If you want to authorize with 3D Secure 2 authentication, there are two possible ways:

Direct authorization with Nuvei. This will include extra params in the request, that are used for authentication (See objects for authentication)
By Performing a 3D Secure 2 authentication calling the proper endpoint Authentication 3DS 2 section, before calling the authorize.

HTTP Request

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

You must replace the base64 encoded string auth_token in the header, with your personal auth_token. how to build token

URL Parameters

Parameter	Type	Required	Description
session_id	String	No	Fraud related parameter. 32-length numeric hash.
order.amount	Number	Yes	Amount to debit. Format: Decimal with two fraction digits.
order.description	String	Yes	Description of the order to be purchase. Format: (Maximum Length 250)
order.dev_reference	String	Yes	Merchant order reference. You will identify this purchase using this reference.
order.vat	Number	Yes	Sales tax amount, included in product cost. Format: Decimal with two fraction digits.
order.installments	Number	No	The number of installments for the payment, only for COP, MXN, BRL, PEN, CLP and USD (Ecuador).
order.installments_type	Number	No	Only available for Ecuador and Mexico. See the valid values
order.months_grace	Number	No	Only available for Mexico and Ecuador (Medianet), the number of months of grace for a deferred payment.
user.id	String	Yes	Customer identifier. This is the identifier you use inside your application.
user.first_name	String	No	User name.
user.last_name	String	No	User last name.
user.email	String	Yes	Buyer email, with valid e-mail format.
user.phone	String	No	Buyer phone.
user.ip_address	String	No	User IP address. Valid v4 IP address.
card.token	String	No (*)	Card Identifier. This code is unique among all cards. Format: Long Integer.
card.number	String	No	A valid credit card number.
card.holder_name	String	No (*)	The credit card holder name.
card.expiry_month	Number	No (*)	The credit card expiry month.
card.expiry_year	Number	No (*)	The credit card expiry year.
card.cvc	String	No (*)	The credit card security number.
card.type	String	No (*)	Abbreviated card type. See the valid options
extra_params	Json	No	Optional params (3DS 2 objects included) used for some commerce in Json format. Please contact your commercial executive for more details.
billing_address	Json	No	Object with the billing address, see the specification of address.
shipping_address	Json	No	Object with the shipping address, see the specification of address.
airline	Json	No	Object with airline data, see the specification of airline.
hotel	Json	No	Object with hotel data, see the specification of hotel.

Response

See Objects in response

Capture

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

The above request returns JSON structured like this:

{
  "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"
  }
}

This endpoint capture an authorized transaction (Only for Cielo (BRL), Prosa (MXN) Procesos and VisaNet (PEN))

HTTP Request

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

You must replace the base64 encoded string auth_token in the header, with your personal auth_token. how to build token

URL Parameters

Parameter	Type	Required	Description
transaction.id	String	Yes	Transaction identifier. This code is unique among all transactions.
order.amount	Number	No	The order amount to capture, could be greater o lower than original (Prosa MXN), or only lower (Cielo, BRL Procesos and VisaNet (PEN)). Format: Decimal with two fraction digits. If not provided, the full amount of the original authorize will be captured.

Response

See Objects in response

Verify

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'

The above request returns JSON structured like this:

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

In case of more_info = true, this is an example:

{
  "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": ""
    }
  }
}

After have been performed a transaction, whether through an add card, a debit with token, a debit with card or an authorization, if the response transaction status is pending, this end point should be posted after that.

Sometimes an add card or debit transaction would need to be verified with a code from the financial entity that charges the card. Another case that needs verification is when the card issuer send a OTP to the user in order to continue with the transaction, or after the buyer have been challenged in a 3DS 2 transaction.

When the buyer gets the verification code from his bank, or when the buyer obtain the SMS with the OTP, or when the merchant gets the result of the challenge response, its possible to verify the operation making a request to:

HTTP Request

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

You must replace the base64 encoded string auth_token in the header, with your personal auth_token. how to build token

URL Parameters

Parameter	Type	Required	Description
transaction.id	String	Yes	Transaction identifier. This code is unique among all transactions.
user.id	String	Yes	Customer identifier. This is the identifier you use inside your application. Max length allowed 100 characters
type	String	Yes	The type of value that is going to be sent in the request. Valid strings "BY_AMOUNT", "BY_AUTH_CODE", "BY_OTP", "BY_CRES" and "AUTHENTICATION_CONTINUE".
value	String	Yes	Could be the authorization code provided by the financial entity to the buyer, the transaction amount, the One Time Password (OTP), the Challenge Response (CRES), or empty string in case of AUTHENTICATION_CONTINUE.
more_info	Boolean	No	true or false to determine if the response will include more info about the transaction.

Response

Parameter	Description
status	The status of the transaction, for more information status detail
payment_date	If staging environment the date will be in UTC, otherwise will depend on carrier.
amount	The amount of the transaction.
transaction_id	Transaction identifier. This code is unique among all transactions.
status_detail	The status detail of the transaction, for more information status detail
message	If the type of verification was "BY_OTP", the response message in case of failure.

If you send more_info with value true: See Objects in response

Currency	Amount
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

Refund

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

The above request returns JSON structured like this:

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

Example of refund with partial amount

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

Example of request with reference_label. For QR Colombia only.

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

Example of request, with param '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/'

Example of response with 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"
  }
}

This endpoint is used to refund a transaction

HTTP Request

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

You must replace the base64 encoded string auth_token in the header, with your personal auth_token. how to build token

URL Parameters

Parameter	Type	Required	Description
transaction.id	String	Yes (*)	Transaction identifier. This code is unique among all transactions.
transaction.reference_label	Number	Yes (*)	Only for QR Colombia. ID Reference for a QR transaction.
order.amount	Number	No	The order amount to refund. Format: Decimal with two fraction digits. If not provided, the full amount of the transaction. Works with Cielo (BRL), Prosa (MXN), Credibanco and Redeban (COP) (**).
more_info	Boolean	No	true or false to determine if the response will include more info about the transaction.

Response

Parameter	Description
status	Could be one of the following: success, pending or failure
detail	If success could be Completed or Completed partial refunded with NN.NN where NN.NN is the amount of the partial refund. If failure could be Error: Not completed, Transaction already refunded or Invalid Status. If pending, Waiting gateway confirmation or 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/'

The above request returns JSON structured like this:

{
  "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"
  }
}

This endpoint cancels an authorized transaction (Prosa (MXN))

HTTP Request

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

URL Parameters

You must replace the base64 encoded string auth_token in the header, with your personal auth_token. how to build token

Parameter	Type	Required	Description
transaction.id	String	Yes (*)	Transaction identifier. This code is unique among all transactions.

Response

See Objects in response

Transaction Info

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

The above request returns JSON structured like this:

{
  "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"
  }
}

This endpoint is used to obtain transaction info

HTTP Request

GET https://ccapi-stg.paymentez.com/v2/transaction/<transaction_id>

You must replace the base64 encoded string auth_token in the header, with your personal auth_token. how to build token

URL Parameters

Parameter	Type	Required	Description
transaction_id	String	Yes	Nuvei transaction_id

Response

Parameter	Description
transaction.status	Could be success, failure, pending, expired or canceled.
transaction.payment_date	If staging environment the date will be in UTC, otherwise will depend on carrier.
transaction.amount	The amount of the transaction.
transaction.authorization_code	If success the authorization code responded from carrier.
transaction.installments	The number of installments for the payment.
transaction.dev_reference	Merchant order reference.
transaction.message	The returned message from carrier or fraud analysis system.
transaction.carrier_code	The returned code from carrier.
transaction.id	Transaction identifier. This code is unique among all transactions.
transaction.status_detail	The status detail of the transaction, for more information status detail
card.bin	The BIN of the card (First six digits of the card).
card.expiry_year	The expiry year of the card.
card.expiry_month	The expiry month of the card.
card.transaction_reference	If any, the transaction.id
card.type	Abbreviated card type. See the valid options
card.number	The last four digits of the card.
card.origin	The origin of the credit card. Could be one of the following: 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/'

The above request returns JSON structured like this:

{
  "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"
  }
}

Allows performing a payout (a transfer of funds from the merchant to the consumer) with no connection to a previous transaction.

HTTP Request

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

You must replace the base64 encoded string auth_token in the header, with your personal auth_token. how to build token

URL Parameters

Parameter	Type	Required	Description
order.amount	Number	Yes	The transaction amount. Decimal with two fraction digits.
order.currency	String	Yes	Three letter ISO currency code, example PEN.
order.dev_reference	String	Yes	Merchant order reference. Max length 50.
card.number	String	Yes	A valid credit card number.
card.holder_name	String	Yes	The credit card holder name.
card.expiry_month	Number	Yes	The credit card expiry month.
card.expiry_year	Number	Yes	The credit card expiry year.
user.first_name	String	Yes	First name beneficiary. Max length 30.
user.last_name	String	Yes	Last name beneficiary. Max length 40.
user.address	String	Yes	Address of beneficiary. Max length 50.
user.phone	String	Yes	Phone number beneficiary. Max length 18.
user.zip	String	Yes	Zip beneficiary. Max length 10.
user.city	String	Yes	City of beneficiary. Max length 30.
user.country	String	Yes	Three letter ISO county code, example PER.
user.state	String	No	The state of the beneficiary. Max length 3.
user.email	String	Yes	Card holder valid email.
user.identification	String	Yes	This represents the customer’s identification number in their respective country. Max length 15.
device.device_type	String	Yes	Supported device types include: DESKTOP, SMARTPHONE, TABLET, TV, UNKNOWN
device.ip_address	String	No	Valid IP address.

Response

Parameter	Description
application.code	The application_code that throw the request.
commerce.merchant_id	The merchant id where the funds were obtained.
beneficiary.first_name	First name beneficiary. Max length 30.
beneficiary.last_name	Last name beneficiary. Max length 40.
beneficiary.email	Card holder valid email.
beneficiary.card_bin	The BIN of the card (First six digits of the card).
beneficiary.card_number	The last four digits of the card.
transaction.id	Transaction identifier. This code is unique among all transactions.
transaction.dev_reference	Merchant order reference.
transaction.amount	The amount of the transaction.
transaction.authorization_code	The authorization code responded by carrier.
transaction.authorization_date	The date of the authorization in UTC.
transaction.error_code	The returned code from carrier.
transaction.error_description	The returned message from carrier.
transaction.status_detail	The status detail of the transaction, for more information status detail
transaction.current_status	Could be PENDING, APPROVED, CANCELLED, INITIATED, REJECTED or EXPIRED.

Card Brands

Internationals

Card type	Brand	Logo
vi	Visa
mc	Mastercard
ax	American Express
di	Diners
dc	Discover
ms	Maestro

Colombia

Card type	Brand	Logo
ex	Exito
ak	Alkosto
cd	Codensa
sx	Sodexo
ol	Olimpica
ep	EPM
csd	Colsubsidio
bbva	BBVA
cmr	Falabella

Mexico

Card type	Brand	Logo
cn	Carnet

Ecuador

Card type	Brand	Logo
cs	Credisensa
so	Solidario
up	Union Pay

Brazil

Card type	Brand	Logo
el	Elo
jc	JCB
au	Aura
sx	Sodexo
hpc	Hipercard

LinkToPay

In this platform, we can generate a payment link, which can be completed with any of the payment methods assigned to the access credentials.

Generate a link

Example of request to generate link.

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"
    }
}'

Example of request to generate a link with 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"
 }
}'

The above request returns JSON structured like this:

{
    "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="
        }
    }
}

To generate a link to pay, certain information is required, this allows to consume any payment method provided by Nuvei

HTTP Request

POST https://noccapi-stg.paymentez.com/linktopay/init_order/

You must replace the base64 encoded string auth_token in the header, with your personal auth_token. how to build token

URL Parameters

Parameter	Type	Required	Description
user.id	String	Yes	Buyer identifier. Max length 250 characters.
user.email	String	Yes	Buyer email, with valid e-mail format. Max length 250 characters.
user.name	String	Yes	Buyer name. Max length 100 characters.
user.last_name	String	Yes	Buyer name. Max length 100 characters.
user.fiscal_number_type	String	No	Indicates the type of fiscal number (user identification).See the valid types.
user.fiscal_number	String	No	Fiscal number (identification number) given by the user. Max length 100 characters.
order.dev_reference	String	Yes	Id from commerce to identify the order. Max length 100 characters.
order.description	String	Yes	The order description. Max length 250 characters.
order.amount	Number	Yes	Total amount to pay. Format: Decimal with two fraction digits.
order.installments_type	Number	Yes	Only available Ecuador and Mexico see the valid types. For the rest of the countries, 0 to allow installments, -1 otherwise. Only available to card payment method.
order.vat	Number	Yes	Sales tax amount, included in order amount. Format: Decimal with two fraction digits.
order.inc	Number	No	National consumption tax, included in order amount. Format: Decimal with two fraction digits.
order.tip	Number	No	Only available for pay with Qr code . Tip, not included in order amount. Format: Decimal with two fraction digits.
order.taxable_amount	Number	No	Only available for Ecuador and Colombia. The taxable amount is the total amount of all taxable items excluding tax. If not sent, it's calculated on the total. Format: Decimal with two fraction digits.
order.tax_percentage	Number	No	Only available for Ecuador and Colombia. The tax rate to be applied to this order. For Ecuador should be 0 or 12.
order.currency	String	Yes	Order currency see the valid types.
configuration.partial_payment	Boolean	Yes	Indicates if the partial payment is allowed.
configuration.expiration_days	Number	No(*)	Number of days in which the link to pay expires.
configuration.expiration_time	Number	No(*)	Time in seconds it will take for the link to pay to expire.
configuration.allowed_payment_methods	Array (String)	No	Indicates allowed payment methods. 'All' is the default. See the valid types.
configuration.currency_exchange	String	No	Currency in which the link to pay will be paid see the valid types.
configuration.success_url	String	Yes	URL to redirect when transaction is success. (max 500)
configuration.failure_url	String	Yes	URL to redirect when transaction is failure. (max 500)
configuration.pending_url	String	Yes	URL to redirect when transaction is pending. (max 500)
configuration.review_url	String	Yes	URL to redirect when transaction is in review. (max 500)
configuration.card.capture_cellphone	Boolean	No	Indicates if it is required or not to ask for the phone number in card payment (By default is True).
billing_address.street	String	No	The name of the street.
billing_address.city	String	Yes	The city, max length of 50 characters.
billing_address.state	String	No	The state: ISO 3166-2 country subdivision code in case of 3DS authentication, free format otherwise
billing_address.district	String	No	The district.
billing_address.zip	String	Yes	The zip or postal code. Max length allowed of 50 characters.
billing_address.house_number	String	No	The house number
billing_address.country	String	Yes	Country in ISO 3166-1 alpha-3 format, for example: COL, MEX, ECU.
billing_address.additional_address_info	String	No	Additional address info, without format.

Response

Parameter	Description
user.id	Buyer identifier.
user.email	Buyer email registered to order.
order.dev_reference	Reference from commerce.
order.amount	Total amount to pay.
order.description	Order description.
configuration.expiration_date	Date limit to pay.
configuration.partial_payment	Indicates if the partial payment is allowed.
configuration.allowed_payment_methods	Indicates allowed payment methods.
payment.payment_url	Link To Pay, URL to do redirect.
payment.payment_qr	Code Qr base64, URL to do redirect.

Currencies

Allowed currencies:

Currency	Country
COP	Colombia
USD	Ecuador, El Salvador, Panama
BRL	Brazil
MXN	Mexico
ARS	Argentina
CLP	Chile
PEN	Peru
GTQ	Guatemala
HNL	Honduras
NIO	Nicaragua
CRC	Costa Rica

Allowed payment methods

Allowed payment methods by country:

Key	Description
All	All payment methods
Card	Only card payment method (All countries)
BankTransfer	Only bank transfer method (Colombia)
Cash	Only cash / reference payment method (Colombia, Mexico, Ecuador)
Colsubsidio	Only colsubsidio for Colombia
EWallet	Only E-wallet payment method (Colombia)
Qr	Only Qr code payment method (Colombia)
Pix	Only Pix (Qr code) payment method (Brazil)

Authentication 3DS 2

3D Secure 2 is the new generation of authentication technology introduced by EMVCo and major card schemes, providing an additional layer of verification on Card Not Present (CNP) transactions.

The goal is to reduce the risk of fraud without harming the conversion rate. This new version analyzes several variables used as a criteria to determine the cardholder authenticity, allowing in some cases decreased cardholder authentication interactions (challenges), without risking the merchant’s Liability Shift.

In 3D Secure 2, the authentication is performed within your app or payment form. The shopper's identity may be verified by using passive, biometric, and two-factor authentication approach. A transaction may go through a frictionless or a challenge authentication flow.

3D Secure 2 is supported by the following card schemes:

Visa
Mastercard
Discover / Diners
JCB
UnionPay
American Express

How it works

In 3D Secure 2, the browser flow and mobile flow are treated separately.

For the browser flow the steps are the following:

The payment page places Nuvei input values into 3DS authenticate endpoint and post it.
The MPI contacts directory and returns either final response, continue with authentication and perform 3DS method or finalized HTML redirect form with included formatted CReq message and ACS URL to the payment page application.
If cardholder was enrolled and or challenge authentication requested, payment page application redirects the user browser to the ACS with posting the PAReq/CReq from acquired from MPI.
ACS authenticates.
Payment page application receives the Nuvei transaction id and CRes back from the ACS.
Payment page application submits the ACS response CRes to Nuvei in the verify_auth endpoint.
Nuvei return the result of the verification of the CRes.

For the SDK flow the steps are the following:

The app collect the sdk_info needed and send to the commerce backend (SDK initialization / getSdkInfo). The commerce backed gather all the information an places input values into 3ds `authenticate endpoint and post it.
The MPI contacts directory and returns either final response, or the information needed (sdk_response) to fulfill the challenge request.
ACS authenticates.
The app obtain the authentication result from the ACS.
If authenticated the commerce backend submits the verify_auth endpoint to get the authentication result params.
Nuvei return the result of the verification.

Authenticate

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

Example of app/sdk request:

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

The above request returns JSON structured like this: (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"
}

The above request returns JSON structured like this: (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"
 }

The above request returns JSON structured like this: (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"
}

This endpoint initiates the flow of authentication with 3DS 2

HTTP Request

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

You must replace the base64 encoded string auth_token in the header, with your personal auth_token. how to build token

URL Parameters

Parameter	Type	Required	Description
term_url	String	Yes	Merchant page url, where ACS will post (via user browser) CRes message after authentication.
device_type	String	Yes	Device type. Valid strings: browser, SDK.
user.id	String	Yes	Customer identifier. This is the identifier you use inside your application. Max length allowed 100 characters
user.email	String	Yes	Buyer email, with valid e-mail format.
user.mobile_phone	String	No	User mobile phone Format: 1-3 digits for country code - number. Example: 52-1234567890
user.home_phone	String	No	User home phone Format: 1-3 digits for country code - number. Example: 52-1234567890
user.work_phone	String	No	User work phone Format: 1-3 digits for country code - number. Example: 52-1234567890
order.amount	Number	Yes	Amount to debit. Format: Decimal with two fraction digits.
order.description	String	Yes	Description of the order to be purchase. Format: (Maximum Length 250)
order.dev_reference	String	Yes	Merchant order reference. You will identify this purchase using this reference.
order.installments	Number	No	The number of installments for the payment, only for COP, MXN, BRL, PEN, CLP and USD (Ecuador).
card.number	String	Yes	A valid credit card number.
card.holder_name	String	Yes	The credit card holder name.
card.expiry_month	Number	Yes	The credit card expiry month.
card.expiry_year	Number	Yes	The credit card expiry year.
card.type	String	Yes	Abbreviated card type. See the valid options
browser_info.ip	String	No*	User IP address. Valid v4 IP address.
browser_info.language	String	No*	Language of the browser.
browser_info.java_enabled	Boolean	No*	If java is enabled in the browser.
browser_info.js_enabled	Boolean	No*	If Java Script is enabled in the browser.
browser_info.color_depth	Number	No*	Color depth of the browser.
browser_info.screen_height	Number	No*	Screen height of the browser.
browser_info.screen_width	Number	No*	Screen width of the browser.
browser_info.timezone_offset	Number	No*	Time Zone Offset.
browser_info.user_agent	String	No*	User agent.
browser_info.accept_header	String	No*	Accept header.
sdk_info.trans_id	UUID	N/R	UUID generated in the mobile.
sdk_info.reference_number	String	N/R	Reference number. Format: 1-32 characters.
sdk_info.app_id	UUID	N/R	UUID of the app.
sdk_info.enc_data	String	N/R	Encrypted data. Format: 1-64000 characters.
sdk_info.max_timeout	Number	N/R	Maximum timeout. Format: greater than 5 less than 99
sdk_info.options_IF	Number	N/R	Device render options interface. Format: greater than 0 less than 99
sdk_info.options_UI	String	N/R	Device render options UI. Format: comma separated numeric values length: 1-20. Example: 01,02,03
sdk_info.ephem_pub_key	String	N/R	Public key. Format: semicolon separated JSON Web Key components: crv;kty;x;y.
billing_address.city	String	No	City Format: (Maximum Length 50)
billing_address.country	String	No	Country, format: ISO 3166-1 alpha-3 example: 'USA', 'MEX', 'COL', 'ECU', 'ARG', 'BRA', 'CRI', 'CHL', 'PER'
billing_address.line1	String	No	Extra address info (Maximum Length 50)
billing_address.line2	String	No	Extra address info (Maximum Length 50)
billing_address.line3	String	No	Extra address info (Maximum Length 50)
billing_address.postal_code	String	No	Zip Code (Maximum Length 16)
billing_address.state	String	No	State, format: ISO 3166-2 country subdivision code, example 'DF' for Ciudad de México
shipping_address.city	String	No	City Format: (Maximum Length 50)
shipping_address.country	String	No	Country, format: ISO 3166-1 alpha-3 example: 'USA', 'MEX', 'COL', 'ECU', 'ARG', 'BRA', 'CRI', 'CHL', 'PER'
shipping_address.line1	String	No	Extra address info (Maximum Length 50)
shipping_address.line2	String	No	Extra address info (Maximum Length 50)
shipping_address.line3	String	No	Extra address info (Maximum Length 50)
shipping_address.postal_code	String	No	Zip Code (Maximum Length 16)
shipping_address.state	String	No	State, format: ISO 3166-2 country subdivision code, example 'DF' for Ciudad de México
risk_indicator.ship_indicator	Number	No	Format 2 numeric
risk_indicator.delivery_time_frame	Number	No	Length 1-2
risk_indicator.delivery_email_addr	String	No	A valid e-mail address
risk_indicator.reorder_items_ind	Number	No	Length 1-2
risk_indicator.pre_order_purchase	Number	No	Length 1-2
risk_indicator.pre_order_date	String	No	Date, format: YYYYMMDD
risk_indicator.gift_card_amount	Number	No	Format: Decimal with two fraction digits
risk_indicator.gift_card_curr	String	No	Gift card currency, example: COP, MXN, PEN, BRL, CLP
risk_indicator.gift_card_count	Number	No	Format 2 numeric

* If you send the browser_info, you must send all the parameters related to the browser.

N/R sdk_info is required if device_type is SDK.

Response

Parameter	Description
authentication.status	Authentication status, could be: "Y", "N", "U", "A", "R", "C" or "-" if value not available due errors or not enrolled, for more information authentication_status.
authentication.xid	Transaction identifier sent to MPI.
authentication.return_code	Returned code from MPI, that provides all the information that is needed to determine how to manage the transaction, for more information return code mpi
authentication.eci	Electronic Commerce Indicator, with visa cards, the value to be passed in Authorization message.
authentication.return_message	Description of the return_code.
authentication.version	3DS message version used.
authentication.cavv	Cardholder Authentication Verification Value, determined by ACS. Format: base64
authentication.reference_id	DS Transaction Id.
transaction.dev_reference	Id reference from commerce.
transaction.id	Transaction identifier. This code is unique among all transactions.
browser_response.challenge_request	If cardholder was enrolled and or challenge authentication requested, payment page application must redirects the user browser to the ACS. If this field is not empty, it will contain the html to redirect.
browser_response.hidden_iframe	If this field is not empty, the content should be render into an intermediate page into an invisible iframe and wait about 5 seconds.
sdk_response.acs_trans_id	Transaction ID from ACS.
sdk_response.acs_signed_content	Signed content from ACS.
sdk_response.acs_reference_number	ACS reference number.
service	The name of the MPI that has authenticated the transaction.

The browser_response only apply when device browser, sdk_response only apply when device SDK. But both are returned.

Authentication Status

Code	Description
Y	Authentication / Account verification successful.
N	Not Authenticated / Account not verified. Transaction denied.
U	Authentication / Account verification could not be performed.
A	Authentication / Verification was attempted but could not be verified.
C	Challenge Required. Additional authentication is required using a Challenge.
R	Authentication /Account verification rejected by the Issuer.

Return Code MPI (This apply for Modirum MPI only)

Code	Description
0	Not Authenticated, do not continue transaction
1	Fully Authenticated, continue transaction
2	Not enrolled
3	Not enrolled cache
4	Attempt
5	U-received
6	Error received (from Directory or ACS)
9	Pending
50	Execute 3DS method and continue to authentication
80	Skip device case (no 3DS performed as device known not well capable)
91	Network error
92	Directory error (read timeout)
93	Configuration error
95	No directory found for PAN/cardtype
96	No version 2 directory found for PAN/cardtype
100	3DS Communication Error

Continue Authentication

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

The above request returns JSON structured like this:

{
  "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"
}

If in the authentication return code is 50, this end point should be posted after had been render the iframe and had waited during 5 seconds.

HTTP Request

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

You must replace the base64 encoded string auth_token in the header, with your personal auth_token. how to build token

URL Parameters

Parameter	Type	Required	Description
transaction.id	String	Yes	Transaction identifier. This code is unique among all transactions.

Response

Parameter	Description
authentication.status	Authentication status, could be: "Y", "N", "U", "A", "R", "C" or "-" if value not available due errors or not enrolled, for more information authentication_status.
authentication.xid	Transaction identifier sent to MPI.
authentication.return_code	Returned code from MPI, that provides all the information that is needed to determine how to manage the transaction, for more information return code mpi
authentication.eci	Electronic Commerce Indicator, with visa cards, the value to be passed in Authorization message.
authentication.return_message	Description of the return_code.
authentication.version	3DS message version used.
authentication.cavv	Cardholder Authentication Verification Value, determined by ACS. Format: base64
authentication.reference_id	DS Transaction Id.
transaction.dev_reference	Id reference from commerce.
transaction.id	Transaction identifier. This code is unique among all transactions.
browser_response.challenge_request	If cardholder was enrolled and or challenge authentication requested, payment page application must redirects the user browser to the ACS. If this field is not empty, it will contain the html to redirect.
browser_response.hidden_iframe	If this field is not empty, the content should be render into an intermediate page into an invisible iframe and wait about 5 seconds.
sdk_response.acs_trans_id	Transaction ID from ACS.
sdk_response.acs_signed_content	Signed content from ACS.
sdk_response.acs_reference_number	ACS reference number.

The browser_response only apply when device browser, sdk_response only apply when device SDK. But both are returned.

Verify Authentication

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

The above request returns JSON structured like this:

{
  "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"
}

If a challenge was requested, this end point has to be requested to validate the Challenge response.

HTTP Request

POST https://ccapi-stg.paymentez.com/v2/3ds/auth_verify/

You must replace the base64 encoded string auth_token in the header, with your personal auth_token. how to build token

URL Parameters

Parameter	Type	Required	Description
transaction.id	String	Yes	Transaction identifier. This code is unique among all transactions.
cres	String	Yes for browser	Challenge request response received in the term_url. Format: base64 url encoded. Only for device type browser is mandatory

Response

Parameter	Description
authentication.status	Authentication status, could be: "Y", "N", "U", "A", "R", "C" or "-" if value not available due errors or not enrolled, for more information authentication_status.
authentication.xid	Transaction identifier sent to MPI.
authentication.return_code	Returned code from MPI, that provides all the information that is needed to determine how to manage the transaction, for more information return code mpi
authentication.eci	Electronic Commerce Indicator, with visa cards, the value to be passed in Authorization message.
authentication.return_message	Description of the return_code.
authentication.version	3DS message version used.
authentication.cavv	Cardholder Authentication Verification Value, determined by ACS. Format: base64
authentication.reference_id	DS Transaction Id.
transaction.dev_reference	Id reference from commerce.
transaction.id	Transaction identifier. This code is unique among all transactions.
browser_response.challenge_request	If cardholder was enrolled and or challenge authentication requested, payment page application must redirects the user browser to the ACS. If this field is not empty, it will contain the html to redirect.
browser_response.hidden_iframe	If this field is not empty, the content should be render into an intermediate page into an invisible iframe and wait about 5 seconds.
sdk_response.acs_trans_id	Transaction ID from ACS.
sdk_response.acs_signed_content	Signed content from ACS.
sdk_response.acs_reference_number	ACS reference number.

The browser_response only apply when device browser, sdk_response only apply when device SDK. But both are returned.

Third party integrations

Spreedly

Example of (1) Add an gateway in 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'

Example of (2.a) Create payment method in 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'

Example of (2.b) Create payment method in 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'

Example of (3) Store credit card

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'

Example of (4.a) Purchase in 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 is one of the payment gateways Spreedly supports.

This is a quick guide to integrate Paymentez through Spreedly:

Add a gateway in your environment
Collect Payment Information (Create a payment_method in spreedly):

a. For card that have been created in Paymentez in the past No need to store again.

b. For new cards
In order to store the new credit card is mandatory that retain_on_success: true will be included at the Spreedly request.

c. In case of a direct purchase Without storing the card in Paymentez or Spreedly
Store credit card in Paymentez through Spreedly
Is always mandatory to send the user.id and user.email information, the email is sent in the payment_method of spreedly.
Use the payment_method token returned after store or 2a to complete the purchase in paymentez.
Depending of the country complete the purchase:
To make a purchase in Paymentez is mandatory to send the order.description and user.email, be awere that this fields are not listed in the "gateway_specific_fields" at Spreedly.
Despite that user.ip_address is optional to send to Paymentez, if you are using Spreedly that will be become a mandatory field.

a. Purchase

b. Authorize

c. Capture
In case of refund needed

Spoonity

For further information visit: Spoonity web page

VTEX

We have implementation in the eCommerce VTEX platform.

For further information visit the following manual.

Test Cards

You can use the following cards for your tests. For adding a card or direct purchase in staging environment:

Card	Return Code	Scenarios
4111111111111111, 36417002140808	valid	Charge succeeds
5119159076977991, 370236553676505	review	Charge is under Review
4242424242424242, 347763907473248	rejected	Not Authorized
4520121813132351, 378196561987405	rejected	Rejected by Fraud System
375953548754701, 376337093362277	rejected	Card in black list

For a card not listed above, the system will leave the card as valid. Once you add a valid card in the platform you can prove the debit using a specific description as follow:

order.description	Result
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

You can use either the test cards or the description to prove, but not both.

OTP Diners

In case of integration with OTP Diners (only Ecuador) you can use the following testing cards in staging environment:

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

3DS with nuvei MPI

The following cards are for testing in the staging environment, you should change the order.description depending on the test case

Scenario	Card	order.description	order.amount
Challenge	2221008123677736	3DS Challenge	151
Frictionless	4000020951595032	3DS FrictionLess	>= 150

WebHook

The above is the JSON returned in the 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"
  }
}

Example of stoken generation (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()

So the stoken for this example is e242e78ae5f1ed162966f0eacaa0af01

The above is an example of JSON returned for the case of Split Payment:

{
  "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"
  }
}

The following is an example of returned JSON for the case of payment with Cash or Bank Transfer:

{
  "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"
  }
}

Every time a transaction gets approved or cancelled you will get an HTTP POST request from Nuvei to your callback_url (you need to provide this url to our staff). The POST includes the following fields:

Parameter	Description
transaction.status	The status of the transaction, for more information status
transaction.order_description	Description of the order to be purchase. Format: (Maximum Length 250)
transaction.authorization_code	If success the authorization code responded from carrier.
transaction.status_detail	The status detail of the transaction, for more information status detail
transaction.date	Transaction date (used for approved numbers in the Dashboard).
transaction.message	The returned message from carrier or fraud analysis system.
transaction.id	Transaction identifier. This code is unique among all transactions.
transaction.dev_reference	Merchant order reference.
transaction.carrier_code	The returned code from carrier.
transaction.amount	The amount of the transaction.
transaction.paid_date	Transaction paid date (used for approved numbers in the Dashboard).
transaction.installments	The number of installments for the payment.
transaction.stoken	MD5 hash of [transaction_id]_[application_code]_[user_id]_[app_key]
transaction.ltp_id	Reference to the link to pay used to pay.
transaction.application_code	The transaction belongs to this application code.
transaction.payment_method_type	Payment method of the transaction, type string. For more information payment_method_types
transaction.terminal_code	Terminal id of the transaction.
user.id	Customer identifier. This is the identifier you use inside your application.
user.email	Buyer email, with valid e-mail format.
card.bin	The BIN of the card (First six digits of the card).
card.holder_name	The credit card holder name.
card.type	Abbreviated card type. See the valid options
card.number	The last four digits of the card.
card.origin	The origin of the credit card. Could be one of the following: Paymentez, VisaCheckout, Masterpass.
card.fiscal_number	Fiscal number of the payer of the transaction.

For every transaction you must return an HTTP status, this status is only used to know that you received correctly the call:

Status	Case
200	success
203	token error

You just need to generate the stoken and match the token against the one you receive to be sure that the POST came from Nuvei . You must store this information from all transactions in your database and always check the transaction.id to make sure you are not getting a duplicated POST.

If your server doesn’t respond with an HTTP 200 OK message, the POST will be retrying until get an status HTTP 200, this during 48 hours, with incremental period of time in each retry, first retry will be at 5 min aprox., second retry at 10 min aprox. and so on. In case of receiving any HTTP status >= 500 we will stop trying.

Additionally to approve transactions we also send you those approved transactions that get cancelled, this time the only difference is the status value, which will be 2. In this case you should answer with 200 (so we don’t send it again) and should update the transaction status so you ensure your data and accounting matches with Nuvei

Status details

The Nuvei API uses the following status and status details:

Status	Meaning
0	Pending
1	Approved
2	Cancelled
4	Rejected
5	Expired

Status Detail	Meaning
0	Waiting for Payment.
1	Verification required, please see Verification section.
2	Paid Partially
3	Paid.
4	In Dispute.
5	Overpaid.
6	Fraud.
7	Refund.
8	Chargeback
9	Rejected by carrier.
10	System error.
11	Nuvei fraud.
12	Nuvei blacklist.
13	Time tolerance.
14	Expired by Nuvei
15	Expired by carrier.
16	Rejected by Nuvei
17	Abandoned by Nuvei
18	Abandoned by Customer
19	Invalid Authorization Code.
20	Authorization code expired.
21	Nuvei Fraud - Pending refund.
22	Invalid AuthCode - Pending refund.
23	AuthCode expired - Pending refund.
24	Nuvei Fraud - Refund requested.
25	Invalid AuthCode - Refund requested.
26	AuthCode expired - Refund requested.
27	Merchant - Pending refund.
28	Merchant - Refund requested.
29	Annulled.
30	Transaction seated (only Ecuador).
31	Waiting for OTP.
32	OTP successfully validated.
33	OTP not validated.
34	Partial refund.
35	3DS method requested, waiting to continue.
36	3DS challenge requested, waiting CRES.
37	Rejected by 3DS.
47	Failure cpf validation
48	Authenticated by 3DS

Errors

The Nuvei API uses the following error codes:

Http Status Code	Meaning
400	Bad Request -- For example json not well formatted, data type or parameters missing.
401	Unauthorized -- Your auth_token is wrong or expired.
403	Forbidden -- For several reasons, for example invalid card, card already added, carrier not configured or operation not allowed.
404	Not found -- The resource does not exist.
409	Conflict -- For several reasons, for example transaction could not be created, a miss configuration, the response from third party service response with error.
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

Response in case of error

An example of an error returns JSON structured like this:

{
  "error": {
    "type": "Invalid Token",
    "help": "Auth-Token: should have a format like b64encode(application_code;unix_timestamp;token)",
    "description": "{}"
  }
}

Parameter	Description
error.type	Type of error.
error.help	In some cases a useful help for the developers.
error.description	A description of the error.

Payment Method Types

These are the meanings of the different payment method types.

Payment Method Type Code	Meaning
0	Credit Card
1	Boleto (Bank Ticket)
3	E-wallet
5	Vouchers Card
6	Bank Transfer
7	Debit Card
8	Prepaid Card