NAV Navbar
Logo
shell java php

Introducción

Bienvendo al API de PayValida la forma más sencilla de registrar tus órdenes de compra y recibir el pago de tus productos y servicios a través de todos los medios de recaudo que podemos ofrecerte.

Tenemos códigos de ejemplo en shell, php y Java.

Para más información visita PayValida.

Ordenes de compra

Obtener una Orden de Compra

  curl -i -X GET \
 'https://api-test.payvalida.com/api/v3/porders/1496953766724?merchant=testmerchant_co&checksum=eef0c07f779252b735c67df2c1945b68ca93f72100ece73dac778964aca909184cbcb16bd698527ee5738a88e809202284fec8df640a9e12e90f11f4ddb4f3a8'
  try {
            // Sandbox
            String urlAPI = "https://api-test.payvalida.com/api/v3/porders/";
            // Production
            // String urlAPI = "https://api.payvalida.com/api/v3/porders/";

            //Change orderID by you order
            String orderID = "1500037122481";

            //Change merchantID by you merchant
            String merchantID = "testmerchant_co";

            //Calculate checksum = SHA512(order + merchant + FIXED_HASH)
            String checksum = "547c85b4575b2a9188e0677d38147941aab3be14d45b87393f4339ffd415017bf2af78653968f920d546c2e67e6ae8d40601dba82019349109b4e0ae0603b592";

            URL url = new URL(urlAPI + orderID + "?merchant=" + merchantID + "&checksum=" + checksum);

            HttpURLConnection conn = (HttpURLConnection) url.openConnection();
            if (conn.getResponseCode() != 200) {
                throw new RuntimeException("Failed : HTTP error code : " + conn.getResponseCode());
            }

            BufferedReader br = new BufferedReader(new InputStreamReader((conn.getInputStream())));

            String output;
            System.out.println("Output from Server .... \n");
            while ((output = br.readLine()) != null) {
                System.out.println(output);
            }

            conn.disconnect();

        } catch (MalformedURLException e) {
            e.printStackTrace();
        } catch (IOException e) {
            e.printStackTrace();
        }

<?php

    /**
        You need activarte curl support in your PHP
        If you're on Windows:
            Go to your php.ini file and remove the ; mark from the beginning of the following line:
            ;extension=php_curl.dll
            After you have saved the file you must restart your HTTP server software (e.g. Apache) before this can take effect.
        If you're on Linux:
            In a terminal type the following to install it and do not forgot to restart server.
            sudo apt-get install php-curl
    **/

    // Sandbox
    $urlAPI = "https://api-test.payvalida.com/api/v3/porders/";

    // Production
    //$service_url = "https://api.payvalida.com/api/v3/porders/";

    //Change orderID by you order
    $orderID = "1500037122481";

    //You must change merchantID by you merchant
    $merchantId = "testmerchant_co";

    //Calculate checksum = SHA512(order + merchant + FIXED_HASH)
    $checksum  = "eef0c07f779252b735c67df2c1945b68ca93f72100ece73dac778964aca909184cbcb16bd698527ee5738a88e809202284fec8df640a9e12e90f11f4ddb4f3a8";

    $service_url = $urlAPI.$orderID."?merchant=".$merchantId."&checksum=".$checksum;

    $curl = curl_init($service_url);
    curl_setopt($curl, CURLOPT_HTTPHEADER, ["Content-Type:application/json"]);  
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
    $curl_response = curl_exec($curl);
    curl_close($curl);

    var_dump($curl_response);
    ?>

La ejecución, retorna un JSON estructurado de esta manera:

{  
   "CODE":"0000",
   "DATA":[  
      {  
         "CURRENCY":"COP",
         "NOTIFICATION_RESPONSE":"Notificacion no enviada al comercio: URL de Notificacion en NULL",
         "UPDATE_DATE":"2017-07-22 12:18:26",
         "CREATION_DATE":"2017-07-14 08:35:32",
         "STATE":"VENCIDA",
         "PAYMENT_METHOD":"tc",
         "EMAIL":"[email protected]_co.com",
         "LIFETIME":"200h",
         "RECURRENCY":false,
         "ORDER":"1500039330728",
         "CODE":95124,
         "AMOUNT":"20,000.00",
         "DESCRIPTION":"Prueba Link de Pago",
         "REFERENCE":"1500037122481",
         "checkout":"checkout.payvalida.com/?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJNRVJDSEFOVF9DRUwiOiIzMTc2ODI3MzQxIiwiT1JERVJfTUVUSE9EIjoiZWZlY3R5IiwiTUVSQ0hBTlRfQ09ERSI6MjU0LCJNRVJDSEFOVF9FTUFJTCI6ImhyZXN0cmVwb0BwYXl2YWxpZGEuY29tIiwiaXNzIjoiYXV0aDAiLCJNRVJDSEFOVF9MT0dPIjoiaHR0cHM6Ly9zMy5hbWF6b25hd3MuY29tL3ZhbGlkZGF3ZWIvZXZlbnRvcy9mZW5hbGNvYnJhLnBuZyIsIk1FUkNIQU5UX1VSTF9SRVRVUk4iOiJ3d3cucGludmFsaWRkYS5jb20uY28iLCJNRVJDSEFOVF9OQU1FIjoiSGVybmFuIFJwbyAoQ09MKSIsIk9SREVSX0JSSUVGIjoiVGVzdCBSRVNUZnVsbCBQdXJjaGFzZSBPcmRlciBQT1NUIiwiTUVSQ0hBTlRfVEVMIjoiMjg4MDUzOSIsIk9SREVSX0NVUlJFTkNZIjoiQ09QIiwiT1JERVJfQU1PVVQiOiIxMCwwMDAuMDAiLCJleHAiOjE1MzA0MDE1MzgsIk9SREVSX1JFRkVSRU5DRSI6IjQyMzEzIn0.QVsZwm-2BIkK-5RgrAX2NuwGqmHSNHD_zw91i1hcSc8"
      }
   ],
   "DESC":"Resultado exitoso"
}

Con esta opcion se obtiene el detalle de una Orden de Compra

HTTP Request

Sandbox:
GET https://api-test.payvalida.com/api/v3/porders/<order>
Producción:
GET https://api.payvalida.com/api/v3/porders/<order>

Parametros Query

Nombre Requerido Descripción Tipo Longitud
merchant si Identificacion del comercio en Payvalida Alfanummérico 50 caracteres
checksum si Cadena de comprobación calculada con SHA512(order + merchant + FIXED_HASH) Alfanumérico 512 caracteres

Parametro PATH

Nombre Requerido Descripción Tipo Longitud
order si Número de la orden Alfanumérico 200 caracteres

Registrar una orden de compra

  curl -i -X POST \
   -H "Content-Type:application/json" \
   -d \
'{
  "country":343,
  "email":"[email protected]",
  "merchant":"testmerchant_co",
  "order":"p0000101",
  "reference":"989898101",
  "money":"COP",
  "amount":"45000",
  "description":"Test RESTfull Purchase Order POST",
  "language":"es",
  "recurrent":false,
  "expiration":"30/08/2017",
  "method":"baloto",
  "iva":"0.02",
  "checksum":"71ff0ca3ffa49f0d13c7de5c661c6f8fddcab38004a195718e3d89d330005ee34623959e93893cc2ff5f451b89b43dcc514c5767a2415066578adecbd4ef8242"
}' \
 'https://api-test.payvalida.com/api/v3/porders'
        try {
            // Sandbox
            String urlAPI = "https://api-test.payvalida.com/api/v3/porders/";
            // Production
            // String urlAPI = "https://api.payvalida.com/api/v3/porders/";

            URL url = new URL(urlAPI);


            String data = "{\"country\":343,\"email\":\"[email protected]\",\"merchant\":\"testmerchant_co\",\"order\":\"p0000101\",\"reference\":\"989898001\",\"money\":\"COP\",\"amount\":\"45000\",\"description\":\"Test RESTfull service\",\"language\":\"es\",\"recurrent\":false,\"expiration\":\"30/08/2017\",\"method\":\"baloto\",\"iva\":\"0.02\",\"checksum\":\"71ff0ca3ffa49f0d13c7de5c661c6f8fddcab38004a195718e3d89d330005ee34623959e93893cc2ff5f451b89b43dcc514c5767a2415066578adecbd4ef8242\"}";

            HttpURLConnection conn = (HttpURLConnection) url.openConnection();
            conn.setDoOutput(true);
            conn.setRequestMethod("POST");
            conn.setRequestProperty("Content-Type", "application/json");
            conn.setRequestProperty("Content-Length", Integer.toString(data.length()));
            conn.setRequestProperty("Accept", "application/json");

            try {
                OutputStream out = conn.getOutputStream();
                out.write(data.getBytes());
                out.flush();
                out.close();
            } catch (IOException ex) {
                ex.printStackTrace();
            }

            if (conn.getResponseCode() != 200) {
                throw new RuntimeException("Failed : HTTP error code : " + conn.getResponseCode());
            }

            BufferedReader br = new BufferedReader(new InputStreamReader((conn.getInputStream())));

            String output;
            System.out.println("Output from Server .... \n");
            while ((output = br.readLine()) != null) {
                System.out.println(output);
            }

            conn.disconnect();

        } catch (MalformedURLException e) {
            e.printStackTrace();
        } catch (IOException e) {
            e.printStackTrace();
        }

    <?php
    /**
        You need activarte curl support in your PHP
        If you're on Windows:
            Go to your php.ini file and remove the ; mark from the beginning of the following line:
            ;extension=php_curl.dll
            After you have saved the file you must restart your HTTP server software (e.g. Apache) before this can take effect.
        If you're on Linux:
            In a terminal type the following to install it and do not forgot to restart server.
            sudo apt-get install php-curl
    **/

    // Sandbox
    $urlAPI = "https://api-test.payvalida.com/api/v3/porders/";

    // Production
    //$service_url = "https://api.payvalida.com/api/v3/porders/";

    $data = "{\"country\":343,\"email\":\"[email protected]\",\"merchant\":\"testmerchant_co\",\"order\":\"p0000101\",\"reference\":\"989898001\",\"money\":\"COP\",\"amount\":\"45000\",\"description\":\"Test RESTfull service\",\"language\":\"es\",\"recurrent\":false,\"expiration\":\"30/08/2017\",\"method\":\"baloto\","iva":"0.02",\"checksum\":\"71ff0ca3ffa49f0d13c7de5c661c6f8fddcab38004a195718e3d89d330005ee34623959e93893cc2ff5f451b89b43dcc514c5767a2415066578adecbd4ef8242\"}";

    $service_url = $urlAPI;

    $curl = curl_init($service_url);
    curl_setopt($curl, CURLOPT_HTTPHEADER, ['Content-Type:application/json']); 
    curl_setopt($curl, CURLOPT_POSTFIELDS, $data);
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($curl, CURLOPT_POST, true);
    $curl_response = curl_exec($curl);
    curl_close($curl);

    var_dump($curl_response);

    ?>

La ejecución, retorna un JSON estructurado de esta manera:

{  
   "CODE":"0000",
   "DATA":{  
      "OrdenID":"p0000101",
      "Monto":"45000.0",
      "PVordenID":"95601",
      "Referencia":"989898101",
      "Operacion":"CREADA",
       "checkout":"checkout.payvalida.com/?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJNRVJDSEFOVF9DRUwiOiIzMTc2ODI3MzQxIiwiT1JERVJfTUVUSE9EIjoiZWZlY3R5IiwiTUVSQ0hBTlRfQ09ERSI6MjU0LCJNRVJDSEFOVF9FTUFJTCI6ImhyZXN0cmVwb0BwYXl2YWxpZGEuY29tIiwiaXNzIjoiYXV0aDAiLCJNRVJDSEFOVF9MT0dPIjoiaHR0cHM6Ly9zMy5hbWF6b25hd3MuY29tL3ZhbGlkZGF3ZWIvZXZlbnRvcy9mZW5hbGNvYnJhLnBuZyIsIk1FUkNIQU5UX1VSTF9SRVRVUk4iOiJ3d3cucGludmFsaWRkYS5jb20uY28iLCJNRVJDSEFOVF9OQU1FIjoiSGVybmFuIFJwbyAoQ09MKSIsIk9SREVSX0JSSUVGIjoiVGVzdCBSRVNUZnVsbCBQdXJjaGFzZSBPcmRlciBQT1NUIiwiTUVSQ0hBTlRfVEVMIjoiMjg4MDUzOSIsIk9SREVSX0NVUlJFTkNZIjoiQ09QIiwiT1JERVJfQU1PVVQiOiIxMCwwMDAuMDAiLCJleHAiOjE1MzA0MDE1MzgsIk9SREVSX1JFRkVSRU5DRSI6IjQyMzEzIn0.QVsZwm-2BIkK-5RgrAX2NuwGqmHSNHD_zw91i1hcSc8"
   },
   "DESC":"OK"
}

Permite registrar una Orden de Compra

HTTP Request

Sandbox:
POST https://api-test.payvalida.com/api/v3/porders
Producción:
POST https://api.payvalida.com/api/v3/porders

Parametros POST (en formato JSON)

Nombre Requerido Descripción Tipo Longitud
merchant si Identificacion del comercio en Payvalida Alfanumérico 50 caracteres
email si Email del comprador Email 100 caracteres
country si Código del país Numérico 3 caracteres
order si Codigo alfanumérico correspondiente al número de la orden generada por le comercio Alfanumérico 200 caracteres
reference no Número de referencia de pago, utilizada por el cliente para hacer el pago de la Orden de Compra Numérico 25 caracteres
money si Código de moneda de la transacción Alfabético 3 caracteres
amount si Monto de la operación Numérico N/A
description si Breve descripción de la Orden de Compra Alfanumérico 500 caracteres
method no Método seleccionado por el cliente para realizar el pago Alfanumérico 25 caracteres
language no Lenguaje de respuestas y mensajes Alfabético 2 caracteres
recurrent si Indica si la Orden de Compra es recurrente o no Booleano N/A
expiration si Fecha de expiracion de la Orden de Compra, en formato DD/MM/AAAA Fecha N/A
iva si Monto porcentual del IVA correspondiente a la orden Numérico N/A
checksum si Cadena de comprobación calculada con SHA512(email + country + order + money + amount + FIXED_HASH) Alfanumérico 512 caracteres

Notificación

El proceso de notificación, consiste en reportar al comercio aquellos Payments que han cambiado de estado.

Al momento de registrar un Payment, este se crea en estado PENDIENTE. El Payment puede cambiar de estado por diversas razones:

  1. Se ha recibido el pago correspondiente al Payment -> Cambia de PENDIENTE a APROBADA y se notifica con estatus “approved”
  2. No se ha recibido el pago correspondiente al Payment antes de la fecha de vencimiento -> Cambia de PENDIENTE a VENCIDA y se notifica con estatus “cancelled”
  3. El comercio elimina el Payment -> Cambia de PENDIENTE a CANCELADA. No se notifica
  4. El cliente realiza un reclamo de devolución del pago realizado -> Cambia de APROBADA a ANULADA y se notifica con estatus “cancelled”
  5. El comercio solicita devolución del pago de un cliente -> Cambia de APROBADA a ANULADA y se notifica con estatus “cancelled”

Nuestro sistema notifica al comercio los cambios de estado del Payment, para ello se requiere del comercio, registrar una URL que permita recibir peticiones POST desde nuestro sistema, cada notificación envía los valores asociados a los siguientes parámetros:

Parámetros POST

Nombre Descripción
pv_po_id Identificación del Payment en Payvalida
po_id Corresponde al valor “order” registrado en el Payment
status Estado actual del Payment
pv_checksum Cadena de comprobación calculada con SHA256(po_id + status + FIXED_HASH)
amount Monto del Payment
iso_currency Moneda de registro del Payment
pv_payment Medio de pago del Payment

El sistema notifica de forma automática en el momento del cambio de estado del Payment, pero es posible que exista mas de una notificación de la misma orden. Es reponsabilidad del comercio evitar entregar mas de una vez el producto adquirido por el cliente en caso de que haya mas de una notificación.

El sistema registra la respuesta obtenida al momento de la notificación, por ello es recomendable enviar como respuesta un texto adecuado al proceso de notificación, por ejemplo un “OK” en caso afirmativo y “ERROR” en caso contrario.

El comercio debe registrar la dirección a la cual desea le sean enviadas las notificaciones

Paises/Monedas

Los países soportados con sus respectivos códigos y monedas son:

Código Moneda País
343 COP Colombia
345 USD Ecuador
348 PEN Perú
314 COL Costa Rica