NAV
shell python php

Introduction

The GlobalPay Redeban 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 Paymentez Server Credentials in any public website's client-side code.

To start the integration you will need to request to GlobalPay Redeban Team integraciones@globalpay.com.co 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.globalpay.com.co
production https://dashboard.globalpay.com.co

You can change you account password or if you forget it you can always use the forgot password option to recover it. In the GlobalPay Redeban 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.globalpay.com.co
production https://ccapi.globalpay.com.co
Environment URL
development https://noccapi-stg.globalpay.com.co
production https://noccapi.globalpay.com.co

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

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.globalpay.com.co/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

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

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

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

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

PSE/ACH

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.globalpay.com.co/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.globalpay.com.co/banks/<carrier>/

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

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

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

  curl --request POST \
  --url https://noccapi-stg.globalpay.com.co/order/ \
  --header 'auth-token: auth-token' \
  --header 'content-type: application/json' \
  --data '{
    "carrier":{
      "id": "PSE",
      "extra_params": {
        "bank_code": "1022",
        "response_url": "https://example.your_url/",
        "user": {
          "name": "User full name",
          "fiscal_number": 12312312313,
          "type": "N",
          "type_fis_number": "CC",
          "ip_address": "201.0.90.12"
        },
        "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.globalpay.com.co/pse/order-pay/PSE-10/",
      "status_bank": "PENDING",
      "trazability_code": 7501,
      "ticket_id": 10
    }
  }

This is an example of a request for H2H:

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

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

HTTP Request

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

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.
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.
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
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.ticket_id Id transaction with PSE.

Get status transfer

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

HTTP Request

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

URL Parameters
Parameter Type Required Description
transaction_id String Yes The transaction id returned from GlobalPay Redeban
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
transaction.trazability_code Reference number.
transaction.ticket_id Id transaction with PSE.

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
PSE SPLIT bank_code, response_url, user.name, user.type, user.type_fis_num, user.fiscal_number, user.ip_address, split.transactions.application_code, split.transactions.amount, split.transactions.vat
H2H extra_params.origin_account, extra_params.destination_account

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.

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",
        "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": {
            "specific_cards": [
                "MC",
                "VI"
            ],
        "something": "else"
        }
    }

}' 'https://ccapi-stg.globalpay.com.co/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.globalpay.com.co/v2/qr/generate/

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 No If needed the extra parameters needed for the carrier.
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.globalpay.com.co/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.globalpay.com.co/v2/qr/<qr_id>/

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.globalpay.com.co/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.globalpay.com.co/v2/qr/<qr_id>/update/

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.

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.globalpay.com.co/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 in an example of response of a request made with a Tuya Card:

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

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

HTTP Request

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

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.
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.nip String No Nip of the card. Only available for Tuya Cards (Exito, Alkosto).
card.card_auth String No Type of authentication. Only available for Tuya Cards (Exito, Alkosto). Valid strings: "AUTH_CVC", "AUTH_NIP" and "AUTH_OTP".
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, for Tuya Cards the message will contain embedded the fields: Result, Mail, Phone if the user has those parameters configured.
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: GlobalPay, VisaCheckout, Masterpass.

Get all Cards

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

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.globalpay.com.co/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.globalpay.com.co/v2/card/delete/

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.

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.globalpay.com.co/v2/transaction/debit/'

The above request returns JSON structured like this:

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

This in an example of response of a request made with a Tuya Card:


{
  "transaction": {
    "status": "pending",
    "payment_date": null,
    "amount": 15.99,
    "authorization_code": null,
    "installments": 1,
    "dev_reference": "referencia",
    "message": "{\"Phone\": \"313*****55\", \"Result\": \"\"TRANSACCION EXITOSA\"\", \"Mail\": \"user@example.com\"}",
    "carrier_code": "000",
    "id": "TY-925",
    "status_detail": 31
  },
  "card": {
    "bin": "590309",
    "expiry_year": "0",
    "expiry_month": "0",
    "transaction_reference": "TY-925",
    "type": "ex",
    "number": "5282",
    "origin": "ORIGIN"
  }
}

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

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

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:

  1. Direct debit with GlobalPay Redeban. This will include extra_params in the request, that are used for authentication (See objects for authentication)

  2. 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.globalpay.com.co/v2/transaction/debit/

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. 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. The tax rate to be applied to this order. Should be 0 or 12.
order.months_grace Number No Only available for Mexico, the number of months of grace for a deferred payment.
order.tip Number No Only available for Tuya Cards ('ex', ak'). The tip. Format: Decimal with two fraction digits.
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.
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.
Response
Parameter Description
transaction.status Could be success, failure or pending.
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, in case of Tuya Cards the message will contain embedded the fields: Result, Mail, Phone if the user has those parameters configured.
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: GlobalPay, 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.
3ds.authentication.reference_id 3DS Server 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.
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.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.
extra_params.auth_data.xid String Yes 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 3DS Server 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.globalpay.com.co/v2/transaction/debit_cc'

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

Parameter Type Required Description
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.
Installments Type

The installments type are only available for Ecuador and Mexico. 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.globalpay.com.co/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.globalpay.com.co/v2/transaction/debit/

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, in case of Tuya Cards the message will contain embedded the fields: Result, Mail, Phone if the user has those parameters configured.
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: GlobalPay, 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.globalpay.com.co/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.globalpay.com.co/v2/transaction/debit/

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.
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.globalpay.com.co/v2/transaction/debit_cc'

The above request returns JSON structured like this:

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

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.globalpay.com.co/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.globalpay.com.co/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:

  1. Direct debit with GlobalPay Redeban. This will include extra_params in the request, that are used for authentication (See objects for authentication)

  2. 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.globalpay.com.co/v2/transaction/debit_cc/

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. 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. The tax rate to be applied to this order. Should be 0 or 12.
order.months_grace Number No Only available for Mexico, the number of months of grace for a deferred payment.
order.tip Number No Only available for Tuya Cards ('ex', ak'). The tip. Format: Decimal with two fraction digits.
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.
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
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.
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.globalpay.com.co/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.globalpay.com.co/v2/transaction/debit_cc/

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, in case of Tuya Cards the message will contain embedded the fields: Result, Mail, Phone if the user has those parameters configured.
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: GlobalPay, 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

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.globalpay.com.co/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.globalpay.com.co/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:

  1. Direct authorization with GlobalPay Redeban. This will include extra params in the request, that are used for authentication (See objects for authentication)

  2. 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.globalpay.com.co/v2/transaction/authorize/

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, 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.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.
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.globalpay.com.co/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.globalpay.com.co/v2/transaction/capture/

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.globalpay.com.co/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.globalpay.com.co/v2/transaction/verify

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.
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.globalpay.com.co/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.globalpay.com.co/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.globalpay.com.co/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.globalpay.com.co/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.globalpay.com.co/v2/transaction/refund/

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.

Transaction Info

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

URL Parameters
Parameter Type Required Description
transaction_id String Yes GlobalPay Redeban 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, in case of Tuya Cards the message will contain embedded the fields: Result, Mail, Phone if the user has those parameters configured.
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: GlobalPay, VisaCheckout, Masterpass.

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

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

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.

curl --request POST
  --url https://noccapi-stg.globalpay.com.co/linktopay/init_order/
  --header 'auth-token: auth-token'
  --header 'content-type: application/json'
  --data '{
    "user": {
        "id": "117",
        "email": "dummy@foo.com",
        "name": "Gabriel",
        "last_name": "Cruz"
    },
    "order": {
        "dev_reference": "1",
        "description": "Product description",
        "amount": 1000,
        "installments_type": 0,
        "currency": "COP"
    },
    "configuration": {
        "partial_payment": true,
        "expiration_days": 1,
        "allowed_payment_methods": ["All", "Cash", "BankTransfer", "Card", "Qr"],
        "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"
    }
}'

The above request returns JSON structured like this:

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

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

POST https://noccapi-stg.globalpay.com.co/linktopay/init_order/

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 Colsubsidio. 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 Colsubsidio. The tax rate to be applied to this order. 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.success_url String Yes URL to redirect when transaction is success.
configuration.failure_url String Yes URL to redirect when transaction is failure.
configuration.pending_url String Yes URL to redirect when transaction is pending.
configuration.review_url String Yes URL to redirect when transaction is in review.
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 Lin To Pay. URL to do redirect.

Allowed currencies:

Currency Country
COP Colombia
USD Ecuador
BRL Brazil
MXN Mexico
ARS Argentina
CLP Chile
PEN Peru

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)

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:

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:

  1. The payment page places GlobalPay Redeban input values into 3DS authenticate endpoint and post it.
  2. 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.
  3. 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.
  4. ACS authenticates.
  5. Payment page application receives the GlobalPay Redeban transaction id and CRes back from the ACS.
  6. Payment page application submits the ACS response CRes to GlobalPay Redeban in the verify_auth endpoint.
  7. GlobalPay Redeban return the result of the verification of the CRes.

For the SDK flow the steps are the following:

  1. 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.
  2. The MPI contacts directory and returns either final response, or the information needed (sdk_response) to fulfill the challenge request.
  3. ACS authenticates.
  4. The app obtain the authentication result from the ACS.
  5. If authenticated the commerce backend submits the verify_auth endpoint to get the authentication result params.
  6. GlobalPay Redeban 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
    },
    "browser_info": {
        "ip": "88.196.25.166",
        "language": "en-US",
        "java_enabled": false,
        "js_enabled": true,
        "color_depth": 24,
        "screen_height": 1200,
        "screen_width": 1920,
        "timezone_offset": 0,
        "user_agent": "Mozilla\/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/70.0.3538.110 Safari\/537.36",
        "accept_header": "text/html"
    },
    "term_url": "http://your.url.com/YOUR_3DS_NOTIFICATION_URL",
    "device_type": "browser"
}' 'https://ccapi-stg.globalpay.com.co/v2/3ds/authenticate/'

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
    },
    "sdk_info": {
        "trans_id": "a24a5d87-b1a1-4aef-a37b-2f30b91274e6",
        "reference_number": "3DSSDK74332823FF",
        "app_id": "a24a5d87-b1a1-4aef-a37b-2f30b91554e6",
        "enc_data": "....",
        "max_timeout": 5,
        "options_IF": 6,
        "options_UI": "01,02,03",
        "ephem_pub_key": "P-256;EC;Kq9_QSrfw_D089BefP2dqVW70BbqiWSb219zvk1Ch80;d4SwfWFPb5_fMUwElfk-CRSyJvzkh75yZhlSjVwyJjk"
    },
    "term_url": "http://your.url.com/YOUR_3DS_NOTIFICATION_URL",
    "device_type": "SDK"
}' 'https://ccapi-stg.globalpay.com.co/v2/3ds/authenticate/'

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

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

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

This endpoint initiates the flow of authentication with 3DS 2

HTTP Request

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

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

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.
authentication.reference_id 3DS Server 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.

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

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.globalpay.com.co/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"
  }
}

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.globalpay.com.co/v2/3ds/auth_continue/

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.
authentication.reference_id 3DS Server 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.

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.globalpay.com.co/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"
  }
}

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

HTTP Request

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

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.
authentication.reference_id 3DS Server 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.

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 valid Charge succeeds
5119159076977991 review Charge is under Review
4242424242424242 rejected Not Authorized
4520121813132351 rejected Rejected by Fraud System
375953548754701 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.

Tuya cards

In case of integration with Tuya you can use the following testing cards in staging environment:

Type Card Fiscal number OTP Clave
Éxito sin OTP 5704230012199650 1234010129 1478
Éxito con OTP 5903098000000332 70323463 012345 1478
Alkosto sin OTP 5903120012199650 1234010129 1478
Alkosto con OTP 5903128000000332 70323463 012345 1478

WebHook

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

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

Every time a transaction gets approved or cancelled you will get an HTTP POST request from GlobalPay Redeban 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, in case of Tuya Cards the message will contain embedded the fields: Result, Mail, Phone if the user has those parameters configured.
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.application_code The transaction belongs to this application code.
transaction.payment_method_type Payment method of the transaction, for more information payment_method_types
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: GlobalPay, VisaCheckout, Masterpass.

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

Status details

The GlobalPay Redeban 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.
3 Paid.
6 Fraud.
7 Refund.
8 Chargeback
9 Rejected by carrier.
10 System error.
11 GlobalPay Redeban fraud.
12 GlobalPay Redeban blacklist.
13 Time tolerance.
14 Expired by GlobalPay Redeban
15 Expired by carrier.
19 Invalid Authorization Code.
20 Authorization code expired.
21 GlobalPay Redeban Fraud - Pending refund.
22 Invalid AuthCode - Pending refund.
23 AuthCode expired - Pending refund.
24 GlobalPay Redeban 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.

Errors

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