NAV Navbar
shell python php
  • Introduction
  • Environments
  • Authentication
  • Payment Methods
  • Wallet
  • Third party integrations
  • Test Cards
  • WebHook
  • Status details
  • Errors
  • Migration from API v1 to v2
  • Introduction

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

    To start the integration you will need to request to Paymentez Team integrations@paymentez.com for a Development/Sandbox account. Please send us your e-mail to identify you as a developer and the name of your company. We suggest you have an integration e-mail i.e. paymentez@yourcompanydomain.com, if it is not possible any e-mail would be fine.

    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://paymentez.herokuapp.com/
    production https://secure.paymentez.com/

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

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

    Environments

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

    Cards payment method

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

    Cash / Bank Transfer payment methods

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

    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 '#########################################################'
    paymentez_server_application_code = ''
    paymentez_server_app_key = ''
    unix_timestamp = str(int(time.time()))
    print 'UNIX TIMESTAMP: %s' % unix_timestamp
    uniq_token_string = paymentez_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' % (paymentez_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 '#########################################################'
    paymentez_server_application_code = ''
    paymentez_server_app_key = ''
    unix_timestamp = str(int(time.time()))
    print 'UNIX TIMESTAMP: %s' % unix_timestamp
    uniq_token_string = paymentez_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' % (paymentez_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";
    
    $paymentez_server_application_code = API_LOGIN_DEV;
    $paymentez_server_app_key = API_KEY_DEV ;
    $date = new DateTime();
    $unix_timestamp = $date->getTimestamp();
    // $unix_timestamp = "1546543146";
    $uniq_token_string = $paymentez_server_app_key.$unix_timestamp;
    $uniq_token_hash = hash('sha256', $uniq_token_string);
    $auth_token = base64_encode($paymentez_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 Paymentez team for it.
    UNIXTIMESTAMP This must be created at the same time as the request, be aware that the time is in UTC, 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 Paymentez team.

    Once you have the UNIQ-TOKEN you need to apply the sha264 and the hexa convertion, you can use the next python example, just add you paymentez_server_application_code and paymentez_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": "amontiel@paymentez.com"
        },
        "order": {
            "dev_reference": "prueba_stg_2",
            "amount": 50001,
            "expiration_days": 5,
            "recurrent": false,
            "description": "Esto es una prueba desde rest client"
        }
    }' 'https://noccapi-stg.paymentez.com/order/'
    
    

    The above request returns JSON structured like this:

    {
        "application": {
            "code": "AbiColApp"
        },
        "commerce": {
            "merchant_id": "paymentez"
        },
        "user": {
            "email": "amontiel@paymentez.com",
            "id": "sadfasdf"
        },
        "transaction": {
            "currency": "COP",
            "country": "COL",
            "dev_reference": "prueba_stg_2",
            "amount": 50001.0,
            "expiration_date": "2018-07-01",
            "recurrent": false,
            "description": "Esto es una prueba desde rest client",
            "reference": "69193",
            "agreement": {
              "baloto": 95715,
              "efecty": 110342,
              "dimonex": 110342,
              "puntored": 113042,
              "redservi": 761
            },
            "status": "pending",
            "id": "PV-0000000000021"
        }
    }
    

    Cash transactions generates a payment reference through a carrier

    HTTP Request

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

    Url Parameter

    Parameter Type Required Description
    carrier.id String Yes Indicates the method by which the reference will be created. See carrier list
    carrier.extra_params.bank_code String Yes (*) Bank code.
    carrier.extra_params.response_url String Yes (*) Response URL. Format: (Maximum Length 255)
    carrier.extra_params.user.name String Yes (*) Full user name.
    carrier.extra_params.user.last_name String Yes (*) User last name.
    carrier.extra_params.user.phone String Yes (*) User phone.
    carrier.extra_params.user.type String Yes (*) Type of user, could be N for persona natural or J for persona jurídica.
    carrier.extra_params.user.type_fis_num String Yes (*) Indicates the type of fiscal number (user identification). See the valid types
    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.
    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.

    Response

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

    Bank transfer

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

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

    Get Banks

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

    The above request returns JSON structured like this:

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

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

    HTTP Request

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

    Url Parameter

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

    Response

    A list of banks

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

    Create bank transfer

    This is an example of a request for bank transfer

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

    This is an example of response obtained from a bank transfer

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

    HTTP Request

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

    Url Parameter

    Parameter Type Required Description
    carrier.id String Yes Indicates the method by which the reference will be created. See carrier list
    carrier.extra_params.bank_code String Yes (*) Bank code.
    carrier.extra_params.response_url String Yes (*) Response URL.
    carrier.extra_params.user.name String Yes (*) Full 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). See the valid types
    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.
    user.id String Yes Buyer identifier.
    user.email String Yes Buyer email, with valid e-mail format.
    order.dev_reference Number Yes Id from commerce to identify the order. Format: Integer.
    order.amount Number Yes Total amount to pay. Format: Decimal with two fraction digits.
    order.vat Number Yes Sales tax amount, included in order amount. Format: Decimal with two fraction digits.
    order.description String Yes The order description.

    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 paymentez.
    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.paymentez.com/pse/order/<transaction_id>/ \
      --header 'auth-token: auth-token' \
      --header 'content-type: application/json'
    
    

    The above request returns JSON structured like this:

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

    HTTP Request

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

    Url Parameter

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

    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 of the country
    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 paymentez
    transaction.trazability_code Reference number.
    transaction.ticket_id Id transaction with PSE.

    Bank transfer 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

    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.

    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@paymentez.com"
        },
        "card": {
            "number": "5119159076977991",
            "holder_name": "citlali calderon",
            "expiry_month": 9,
            "expiry_year": 2020,
            "cvc": "123",
            "type": "vi"
        }
    }' 'https://ccapi-stg.paymentez.com/v2/card/add'
    
    

    The above request returns JSON structured like this:

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

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

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

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

    HTTP Request

    POST https://ccapi-stg.paymentez.com/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 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".

    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 sended to review, by the anti-fraud system, null otherwise).
    card.type Abbreviated card type. See the valid options
    card.number The last four digits of the card.
    card.origin The origin of the credit card. Could be one of the following: Paymentez, VisaCheckout, Masterpass.

    Get all Cards

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

    The above request returns JSON structured like this:

    {
        "cards": [
            {
                "bin": "511915",
                "status": "review",
                "token": "17121538682542236138",
                "holder_name": "citlali calderon",
                "expiry_year": "2020",
                "expiry_month": "9",
                "transaction_reference": "CI-473",
                "type": "vi",
                "number": "7991"
            },
            {
                "bin": "422023",
                "status": "valid",
                "token": "15363681013452573066",
                "holder_name": "citlali calderon",
                "expiry_year": "2020",
                "expiry_month": "9",
                "transaction_reference": null,
                "type": "mc",
                "number": "8431"
            },
            {
                "bin": "453254",
                "status": "valid",
                "token": "10135134879450157925",
                "holder_name": "citlali calderon",
                "expiry_year": "2020",
                "expiry_month": "9",
                "transaction_reference": null,
                "type": "vi",
                "number": "8311"
            }
        ],
        "result_size": 3
    }
    

    This endpoint retrieves all Cards related to a user.

    HTTP Request

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

    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 New 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 sended to review, by the anti-fraud system, or is pending, null otherwise).
    card.type Abbreviated card type. See the valid options
    card.number The last four digits of the card.

    Delete a Card

    curl -k  -L -X POST -H 'Content-Type: application/json' -H 'Auth-Token: auth_token' -d '{
       "card": {
            "token": "2293795539132514250"
        },
        "user": {
            "id": "4"
        }
    }' 'https://ccapi-stg.paymentez.com/v2/card/delete/'
    

    The above request returns JSON structured like this:

    {
      "message": "card deleted"
    }
    
    

    This endpoint delete a Card related to a user

    HTTP Request

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

    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

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

    The above request returns JSON structured like this:

    {
      "transaction": {
        "status": "success",
        "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": "Paymentez"
      }
    }
    
    

    This is an example of response making the request 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\": \"dev@paymentez.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": "Paymentez"
        }
    }
    
    

    This endpoint make a debit transaction with a stored credit card

    HTTP Request

    POST https://ccapi-stg.paymentez.com/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.discount Number No Amount to be discounted. This field is informative only, doesn't affect the final amount. Format: Decimal with two fraction digits.
    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, BRL and USD (Datafast).
    order.installments_type Number No Only available for Datafast (Equador). See the valid values
    order.taxable_amount Number No Only available for Datafast (Equador). The taxable amount, if it is zero, it is calculated on the total. Format: Decimal with two fraction digits.
    order.tax_percentage Number No Only available for Datafast (Equador). The tax percentage to be applied to this order.
    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 vr, sx this field is mandatory.
    card.token String No Card Identifier. This code is unique among all cards. Format: Long Integer.
    wallet.type String No Type of wallet, the valids are : 'VisaCheckout' 'Masterpass'.
    wallet.key String No The id of the wallet (either callid or transactionId)
    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: Paymentez, VisaCheckout, Masterpass.

    Installments Type

    The installments type are only available for Equador. 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). (*)

    Debit with credit card

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

    The above request returns JSON structured like this:

    {
      "transaction": {
        "status": "success",
        "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": "Paymentez"
      }
    }
    
    

    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": "test@paymentez.com"
        },
        "order":{
            "amount": 11.1,
            "description": "una paleta",
            "vat": 0,
            "dev_reference": "referencia"
        },
        "card": {
            "number": "4507000397186651",
            "holder_name": "citlali calderon",
            "expiry_month": 9,
            "expiry_year": 2020,
            "cvc": "123",
            "type": "vi"
        },
        "extra_params": {
            "config_01": "value_01",
            "config_02": {"name_01": "name_v01"}
        }
    }' 'https://ccapi-stg.paymentez.com/v2/transaction/debit_cc'
    

    This endpoint make a debit transaction with a credit card.

    HTTP Request

    POST https://ccapi-stg.paymentez.com/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.discount Number No Amount to be discounted. This field is informative only, doesn't affect the final amount. Format: Decimal with two fraction digits.
    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, BRL and USD (Datafast).
    order.installments_type Number No Only available for Datafast (Equador). See the valid values
    order.taxable_amount Number No Only available for Datafast (Equador). The taxable amount, if it is zero, it is calculated on the total. Format: Decimal with two fraction digits.
    order.tax_percentage Number No Only available for Datafast (Equador). The tax percentage to be applied to this order.
    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 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 No The credit card security number.
    card.type String No Abbreviated card type. See the valid options
    extra_params Json No Optional params used for some commerce in Json format. Please contact your commercial executive for more details, in most of the cases not needed.

    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": "test@paymentez.com"
        },
        "order": {
            "dev_reference": "referencia",
            "amount": 99.0,
            "description": "pozole",
            "vat": 0.00
        },
        "card": {
            "token": "6221308792087238335"
        }
    }' 'https://ccapi-stg.paymentez.com/v2/transaction/authorize/'
    

    The above request returns JSON structured like this:

    {
      "transaction": {
        "status": "success",
        "payment_date": "2017-09-26T21:03:04",
        "amount": 99.0,
        "authorization_code": "148177",
        "installments": 1,
        "dev_reference": "referencia",
        "message": "Operation Successful",
        "carrier_code": "4",
        "id": "CI-490",
        "status_detail": 0
      },
      "card": {
        "bin": "453254",
        "status": "valid",
        "token": "10135134879450157925",
        "expiry_year": "2020",
        "expiry_month": "9",
        "transaction_reference": "CI-490",
        "type": "vi",
        "number": "8311"
      }
    }
    
    

    Case b) sending all the information of the card

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

    The above request returns JSON structured like this:

    {
      "transaction": {
        "status": "success",
        "payment_date": "2017-09-26T21:02:04",
        "amount": 99.0,
        "authorization_code": "148177",
        "installments": 1,
        "dev_reference": "referencia",
        "message": "Operation Successful",
        "carrier_code": "4",
        "id": "CI-491",
        "status_detail": 0
      },
      "card": {
        "bin": "450700",
        "expiry_year": "2020",
        "expiry_month": "9",
        "transaction_reference": "CI-491",
        "type": "vi",
        "number": "6651"
      }
    }
    
    

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

    HTTP Request

    POST https://ccapi-stg.paymentez.com/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.discount Number No Amount to be discounted. This field is informative only, doesn't affect the final amount. Format: Decimal with two fraction digits.
    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, BRL and USD (Datafast).
    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

    Capture

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

    The above request returns JSON structured like this:

    {
      "transaction": {
        "status": "success",
        "payment_date": "2017-09-26T21:03:04",
        "amount": 99.0,
        "authorization_code": "148177",
        "installments": 1,
        "dev_reference": "referencia",
        "message": "Operation Successful",
        "carrier_code": "6",
        "id": "CI-490",
        "status_detail": 3
      },
      "card": {
        "bin": "453254",
        "status": "valid",
        "token": "10135134879450157925",
        "expiry_year": "2020",
        "expiry_month": "9",
        "transaction_reference": "CI-490",
        "type": "vi",
        "number": "8311"
      }
    }
    

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

    HTTP Request

    POST https://ccapi-stg.paymentez.com/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 and Mundipagg, BRL). Format: Decimal with two fraction digits. If not provided, the full amount of the original authorize will be captured.

    Verify

    curl -k  -L -X POST -H 'Content-Type: application/json' -H 'Auth-Token: auth_token' -d '{
        "user": {
            "id": "4"
        },
        "transaction": {
            "id": "CI-316"
        },
        "type": "BY_AMOUNT",
        "value": "99.99"
    
    }' 'https://ccapi-stg.paymentez.com/v2/transaction/verify'
    

    The above request returns JSON structured like this:

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

    Sometimes an add card or debit transaction would need to be verified with a code from the financial entity that charges the card. When the buyer gets the verification code from his bank, you can verify the operation making a request to:

    HTTP Request

    POST https://ccapi-stg.paymentez.com/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 sended in the request. Valid strings "BY_AMOUNT", "BY_AUTH_CODE" and "BY_OTP".
    value String Yes Could be the authorization code provided by the financial entity to the buyer, the transaction amount or the OTP.

    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.
    Currency Amount
    COP 256
    USD 2.56
    BRL 2.56
    MNX 25.6

    Refund

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

    The above request returns JSON structured like this:

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

    Example of refund with partial amount

    curl -k  -L -X POST -H 'Content-Type: application/json' -H 'Auth-Token: auth_token' -d '{
        "transaction": {
            "id": "CI-311"
        },
        "order": {
            "amount": 11.10
        }    
    }' 'https://ccapi-stg.paymentez.com/v2/transaction/refund/'
    

    This endpoint is used to refund a transaction

    HTTP Request

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

    URL Parameters

    Parameter Type Required Description
    transaction.id String Yes Transaction identifier. This code is unique among all transactions.
    order.amount Number No The order amount to refund. Format: Decimal with two fraction digits. If not provided, the full amount of the transaction. Works with Cielo, Mundipagg (BRL), Prosa (MXN), Credibanco and Redeban (COP) (**).

    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 or Transaction already refunded. If pending, Waiting gateway confirmation or Waiting gateway confirmation for partial refund with NN.NN.

    Card Brands

    Card type Brand Logo
    vi Visa
    mc Mastercard
    ax American Express
    di Diners
    dc Discover
    el Elo
    cs Credisensa
    so Solidario
    ex Exito
    ak Alkosto
    cd Codensa
    sx Sodexo
    vr VRBeneficios
    jc JCB
    au Aura

    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.paymentez.com/linktopay/init_order/ \
      --header 'auth-token: auth-token' \
      --header 'content-type: application/json' \
      --data '{
        "user": {
            "id": "117",
            "email": "dummy@foo.com",
            "name": "Gabriel",
            "last_name": "Cruz"
        },
        "order": {
            "dev_reference": "1",
            "description": "Product description",
            "amount": 1000,
            "installments_type": 0,
            "currency": "COP"
        },
        "configuration": {
            "partial_payment": true,
            "expiration_days": 1,
            "allowed_payment_methods": ["All", "Cash", "BankTransfer", "Card"],
            "success_url": "https://url-to-success.com",
            "failure_url": "https://url-to-failure.com",
            "pending_url": "https://url-to-pending.com",
            "review_url": "https://url-to-review.com"
        }
    }'
    

    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.paymentez.com/linktopay/pay/pLbOak7"
          }
       }
    }
    

    To generate a link to pay, certain information is requiered, this allows to consume any payment method provided by Paymentez.

    HTTP Request

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

    Url Parameter

    Parameter Type Required Description
    user.id String Yes Buyer identifier. Max lenght 250 characters.
    user.email String Yes Buyer email, with valid e-mail format. Max lenght 250 characters.
    user.name String No Buyer name. Max lenght 100 characters.
    user.last_name String No Buyer name. Max lenght 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 lenght 100 characters.
    order.dev_reference String Yes Id from commerce to identify the order. Max lenght 100 characters.
    order.description String Yes The order description. Max lenght 250 characters.
    order.amount Number Yes Total amount to pay. Format: Decimal with two fraction digits.
    order.installments_type Number Yes For Equador 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.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.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 review.

    Response

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

    Currencies

    Allowed currencies

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

    Allowed payment methods

    Allowed payment methods by country

    Key Description
    All All payment methods
    Card Only card payment method (All countries)
    BankTransfer Only bank transfer method (Colombia)
    Cash Only cash / reference payment method (Colombia, Mexico, Ecuador)

    Wallet

    The Wallets are repositories of cards and payment data for online consumers. The digital wallets allow a consumer to register their payment data, thus streamlining the purchase process in authorized stores in their purchases for having only one registration.

    To use wallets in the API Paymentez, the merchant must have the wallets integrated in their checkout.

    Info from wallet

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

    The above request returns JSON structured like this:

    {
      "getPaymentDataResponse": {
        "partialShippingAddress": {
          "postalCode": "111221",
          "countryCode": "CO"
        },
        "paymentInstrument": {
          "cardFirstName": "citlali",
          "cardArts": {
            "cardArt": {
              "width": "164",
              "baseImageFileName": "https://sandbox.secure.checkout.visa.com/VmeCardArts/Q6aJy2SMaiq7UBkmtFhw8_cQMIIyJCkt0DLfPTb__os.png",
              "height": "105"
            }
          },
          "issuerBid": "14",
          "lastFourDigits": "2958",
          "verificationStatus": "VERIFIED",
          "paymentType": {
            "cardBrand": "VISA",
            "cardType": "DEBIT"
          },
          "expirationDate": {
            "year": "2020",
            "month": "12"
          },
          "billingAddress": {
            "city": "Bogotá",
            "countryCode": "CO",
            "firstName": "citlali",
            "personName": "citlali de anda",
            "lastName": "de anda",
            "line2": "sss",
            "line1": "55-33 Carrera 15",
            "phone": "3059870741",
            "default": "false",
            "postalCode": "111221",
            "stateProvinceCode": "Bogotá"
          },
          "binSixDigits": "462294",
          "expired": "false",
          "id": "mKfgw45aQIDmaTYwiNjfLt7BYrYCpzF38dKRuC7aaPo=",
          "nameOnCard": "citlali de anda",
          "cardLastName": "de anda"
        },
        "userData": {
          "userName": "ccalderon+cop@paymentez.com",
          "userEmail": "ccalderon+cop@paymentez.com",
          "userFullName": "citlali de anda",
          "userFirstName": "citlali",
          "encUserId": "U7NDAtp8IoRF0Q+00lOFVt2yTZLV9hrbv1w84p1HezM=",
          "userLastName": "de anda"
        },
        "paymentRequest": {
          "currencyCode": "COP",
          "total": "9",
          "subtotal": "9"
        },
        "shippingAddress": {
          "city": "Bogotá",
          "countryCode": "CO",
          "firstName": "citlali",
          "personName": "citlali de anda",
          "lastName": "de anda",
          "verificationStatus": "NOT_VERIFIED",
          "line2": "sss",
          "line1": "55-33 Carrera 15",
          "id": "IRjK90UbuHBfi7PGoc7SI8hPEZ9gRVzpZNsF3Arm6VU=",
          "phone": "3059870741",
          "default": "false",
          "postalCode": "111221",
          "stateProvinceCode": "Bogotá"
        },
        "riskData": {
          "avsResponseCode": "0",
          "advice": "UNAVAILABLE",
          "score": "0",
          "cvvResponseCode": "0",
          "ageOfAccount": "4"
        },
        "externalClientId": "rapiapp",
        "visaCheckoutGuest": "false",
        "creationTimeStamp": "2018-03-02T16:44:27.146Z",
        "walletInfo": {
          "walletName": "VISA_CHECKOUT"
        }
      }
    }
    

    This endpoint is used to obtain transaction info

    HTTP Request

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

    URL Parameters

    Parameter Type Required Description
    transaction_id String Yes The wallet_key either callid or transactionId.
    type String Yes The type of the transaction, could be 'VisaCheckout.

    VisaCheckout

    
    Example of debit with wallet for VisaCheckout
    
    curl -k  -L -X POST -H 'Content-Type: application/json' -H 'Auth-Token: auth_token' -d '{
        "user": {
            "id": "4",
            "email": "test@paymentez.com"
        },
        "order": {
            "amount": 99.0,
            "description": "pozole",
            "dev_reference": "referencia",
            "vat": 0.00
        },
        "wallet": {
            "type": "VisaCheckout",
            "key": "callid"
        }
    }' 'https://ccapi-stg.paymentez.com/v2/transaction/debit/'
    
    

    Two steps are needed to complete a purchase with VisaCheckout.

    1. Obtain the information of the card

    2. Make a purchase

    In the web hook the merchant will obtain the information of the origin of the credit card, the transactions made with this wallet will be marked as origin: VisaCheckout

    Masterpass

    
    Example of debit with wallet for Masterpass
    
    curl -k  -L -X POST -H 'Content-Type: application/json' -H 'Auth-Token: auth_token' -d '{
        "user": {
            "id": "4",
            "email": "test@paymentez.com"
        },
        "order": {
            "amount": 99.0,
            "description": "pozole",
            "dev_reference": "referencia",
            "vat": 0.00
        },
        "wallet": {
            "type": "Masterpass",
            "key": "transaction_id"
        }
    }' 'https://ccapi-stg.paymentez.com/v2/transaction/debit/'
    
    

    For this case you only need to Make a purchase with the appropriate parameters.

    In the web hook the merchant will obtain the information of the origin of the credit card, the transactions made with this wallet will be marked as origin: Masterpass

    Third party integrations

    Spreedly

    Example of (1) Add an gateway in spreedly

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

    Example of (2.a) Create payment method in spreedly

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

    Example of (2.b) Create payment method in spreedly

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

    Example of (3) Store credit card

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

    Example of (4.a) Purchase in spreedly

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

    Paymentez is one of the payment gateways Spreedly supports.

    This is a quick guide to integrate Paymentez through Spreedly:

    1. Add a gateway in your environment

    2. Collect Payment Information (Create a payment_method in spreedly):

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

      b. For new cards

      c. In case of a direct purchase Without storing the card in Paymentez or Spreedly

    3. Store credit card in Paymentez through Spreedly

    4. Depending of the country complete the purchase:

      a. Purchase

      b. Authorize

      c. Capture

    5. In case of refund needed

    VTEX

    We have the solution eCommerce VTEX + Paymentez implemented.

    For further information visit: This manual

    Spoonity

    For further information visit: Spoonity web page

    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 = failure, 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.

    WebHook

    The above is the JSON sended 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": "dev@paymentez.com"
      }, 
      "card": {
         "bin": "411111",
         "holder_name": "Martin Mucito",
         "type": "vi",
         "number": "1111",
         "origin": "Paymentez"
      }
    }
    

    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

    Every time a transaction gets approved or cancelled you will get an HTTP POST request from Paymentez to your callback_url (configured using the admin cpanel). 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.
    transaction.authorization_code The authorization code of the transaction sent from the 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 Return message from the carrier or the platform.
    transaction.id Transaction identifier. This code is unique among all transactions.
    transaction.dev_reference Merchant order reference. You will identify this purchase using this reference.
    transaction.carrier_code The return message code.
    transaction.amount Amount to debit.
    transaction.paid_date Transaction paid date (used for approved numbers in the Dashboard).
    transaction.installments The number of installments for the payment, only for COP, BRL and USD (Datafast).
    transaction.stoken MD5 hash of [transaction_id]_[application_code]_[user_id]_[app_key]
    transaction.application_code The transaction belongs to this application code.
    user.id Customer identifier. This is the identifier you use inside your application.
    user.email Buyer email.
    card.bin The credit card bin.
    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 credit card.
    card.origin The origin of the credit card. Could be one of the following: Paymentez, 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
    201 product_id error
    202 user_id error
    203 token error
    204 transaction_id already received

    You just need to generate the stoken and match the token against the one you receive to be sure that the POST came from Paymentez. If your server doesn’t respond with an HTTP 200 OK message, the POST will be retried until get and HTTP 204 status. 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.

    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 204 (so we don’t send it again) and should update the transaction status so you ensure your data and accounting matches with Paymentez.

    Status details

    The Paymentez API uses the following status and status details:

    Status Meaning
    0 Pending
    1 Approved
    2 Cancelled
    4 Rejected
    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 Paymentez fraud.
    12 Paymentez blacklist.
    13 Time tolerance.
    19 Invalid Authorization Code.
    20 Authorization code expired.
    21 Paymentez Fraud - Pending refund.
    22 Invalid AuthCode - Pending refund.
    23 AuthCode expired - Pending refund.
    24 Paymentez Fraud - Refund requested.
    25 Invalid AuthCode - Refund requested.
    26 AuthCode expired - Refund requested.
    27 Merchant - Pending refund.
    28 Merchant - Refund requested.
    30 Transaction seated (only Datafast).
    31 Waiting for OTP.
    32 OTP successfully validated.
    33 OTP not validated.
    34 Partial refund

    Errors

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

    Migration from API v1 to v2

    You can use the same app_code you were using, building the auth_token with the new method: how to build token.

    In case you are a no PCI merchant you will need another app_code (that will end with CLIENT) in order to add a card in Paymentez, that could be achieved with the SDK for iOS, the SDK for Android, or SDK Javascript.

    All the cards you have registered in the past with us can be accessed with API v2.