API

REFERENCE

P á g i n a 1 | 20

 INDICE

3. ¿Qué es una API?
3. ¿Qué es el formato JSON?
3. ¿Qué es una API REST?
4. ¿Qué son las peticiones HTTP?
5. API: Ejemplo de URL de llamada.
5. API: Referencia de parámetros de URL de llamada.
6. API: Ejemplo de respuesta.
8. API: Referencia de parámetros de respuesta.
11. API: Referencia de códigos de error.
12. Gateway de Pago: Referencia de parámetros para
GATEWAY->URL
15. Gateway de Pago: 1.- Envío de formulario por POST.
16. Gateway de Pago: 2.- Envío de formulario por POST usando
Ajax (jQuery).
18. Gateway de Pago: 3.- Con PHP – Utilizando la librería CURL.
20. Gateway de Pago: Referencia de códigos de error.

P á g i n a 2 | 20

¿Qué es una API?
Una API es un conjunto de funciones y procedimientos que cumplen una o
muchas funciones con el fin de ser utilizadas por otro software. Las siglas
API vienen del inglés Application Programming Interface. En español sería
Interfaz de Programación de Aplicaciones.
Una API permite que los desarrolladores interactúen con los datos de una
aplicación de un modo planificado y ordenado pudiendo implementar las
funciones y procedimientos de dicha aplicación sin la necesidad de
programarla de nuevo. En términos de programación, es una capa de
abstracción.

¿Qué es el formato JSON?

JSON es la abreviatura de JavaScript Object Notation, un formato que
permite la clasificación e intercambio de datos, principalmente utilizado en
bases de datos.

¿Qué es una API REST?

Una API REST es una biblioteca apoyada totalmente en el estándar HTTP.
Visto de una forma más sencilla, una API REST es un servicio que nos
provee de funciones que nos dan la capacidad de hacer uso de un servicio
web que no es nuestro, dentro de una aplicación propia, de manera segura.
Al usar una API todo el desarrollo que se quiera realizar estará limitado por
los métodos o funciones que esta incluya, es decir, no pueden ser añadidas
nuevas funcionalidades.

P á g i n a 3 | 20

¿Qué son las peticiones HTTP?
La REST API es mucho más efectiva gracias a HTTP (Hyper Text Transfer
Protocol). El motivo de que esto sea así es que este protocolo permite
compartir información entre un cliente (portátil, teléfono móvil, tableta,
etc.) y un servidor.
Para resumirlo, un escenario de petición HTTP funciona así:
1. Un cliente envía una petición HTTP a un servidor.
2. El servidor devuelve una respuesta HTTP.

P á g i n a 4 | 20

API de e-Payouts
La API de e-Payouts, es un servicio para desarrolladores que permite
acceder a toda la información de un Módulo de Pago desde un servidor
propio.
Con dicha información, es posible crear una UI personalizada con todos los
métodos de pago disponibles en el Módulo (excepto Western Union y
Transferencia Bancaria), para vender un producto o servicio directamente
desde un sitio web.

Comenzando…
Lo primero será llamar a la API mediante una URL que obtendrás desde la
sección "API de pagos".
La URL tendrá una estructura similar a la que se muestra a continuación:

Ejemplo de URL de llamada.

<!-- Use the API URL to get all Payment Module data -->
https://api.e-payouts.com/getData.php?uid=X&mid=X&cc=XX&apikey=XXXXXXXXXXXXXXXX

Referencia de parámetros de URL de llamada.

Parámetro Tipo Tipo de valor Descripción

?uid requerido INT ID único de usuario e-Payouts

&mid requerido INT ID único del módulo de pago

País del cual se quiere obtener la

&cc requerido Código de país en formato ISO 3166-2
información de pago. Ej: es
Clave de acceso a la API de usuario
&apikey requerido STRING
e-Payouts
Precio de venta del producto o
&price opcional FLOAT
servicio. Ej: 9.99

P á g i n a 5 | 20

Ten en cuenta que podrás acceder a la API únicamente desde un servidor
cuya IP haya sido previamente configurada al momento de crear el Módulo
de Pago.
La respuesta de la API, será un JSON con la siguiente estructura:

Ejemplo de respuesta.
{
'error': 0,
'message': "API response -> successful request.",
'data': {
'sites': {
'status': "enabled",
'url': "http://www.mywebsite.com"
},
'modules': {
'price': "2.99",
'status': "enabled",
'currency': "EUR",
'country': "XX",
'api_ip': "XX.XX.XX.XX",
'methods': {
'sms': [
{
'method': "sms",
'country': "XX",
'operator': "74801",
'name': "Ancel",
'shortcode': "8118",
'prefix': "eps",
'lcurrency': "uyu",
'price': "30.000",
'sms': 4,
'maxsms': "5"
},
{
'method': "sms",
'country': "XX",
'operator': "74807",
'name': "Movistar",
'shortcode': "8118",
'prefix': "eps",
'lcurrency': "uyu",
'price': "30.000",
'sms': 4,
'maxsms': "5"
}
P á g i n a 6 | 20

 ],
'creditcard': [
{
'method': "creditcard",
'price': "2.99",
'pmin': "1.00",
'pmax': "1000.00"
}
],
'paysafecard': [

{

'method': "paysafecard",

'country': "XX",

'price': "2.99",

'pmin': "1.00",

'pmax': "1000.00"

}
],

'astropay': [
{
'method': "astropay",
'price': "2.99",
'pmin': "1.00",
'pmax': "200.00",
'banks': {
'RE': {
'code': "RE",
'name': "Red Pagos",
'logo': "tags/79a4b0ed450b65b1ba147ef688288de0.jpg"
}
}
}
],
'epayouts': [
{
'method': "epayouts",
'price': "2.99",
'pmin': "1.00",
'pmax': "1000.00"
}
]
}
},
'gateway': {
'url': "https://api.e-payouts.com/createCode.php"
}
}
}

P á g i n a 7 | 20

Con ésta información, podrás armar tu propia UI para ofrecer a tus clientes
diferentes opciones de pago para el producto o servicio que deseas vender.
Puedes acceder a la sección "Payment Box" para tener una referencia de
cómo crear una correcta UI de pago.

Referencia de parámetros de respuesta.
JSON Key Descripción
error Codigos de error de la API

message Mensaje de respuesta de la API

data Objeto con información de pago

sites Objeto con información del sitio web

status Estado del sitio web

url URL del sitio web

modules Objeto con información del módulo de pago

price Precio del módulo de pago

status Estado del módulo de pago

currency Tipo de moneda del módulo de pago

country Código del país de acceso

api_ip IPs desde las cuales se puede acceder a la API

methods Objeto con información de los métodos de pago

sms Objeto con información del método de pago SMS

method Nombre del método de pago

country Código del país

operator Código de la operadora

name Nombre de la operadora

shortcode Número de la operadora

prefix Alias de la operadora

lcurrency Tipo de moneda local

price Precio en moneda local

P á g i n a 8 | 20

 JSON Key Descripción
sms Cantidad de SMS necesarios para el acceso

maxsms Cantidad máxima de SMS permitidos por la operadora

creditcard Objeto con información del método de pago Tarjeta de Crédito

method Nombre del método de pago

price Importe de la transacción

pmin Importe mínimo de una transacción

pmax Importe máximo de una transacción

paysafecard Objeto con información del método de pago Paysafecard

method Nombre del método de pago

country Código del país

price Importe de la transacción

pmin Importe mínimo de una transacción

pmax Importe máximo de una transacción

safetypay Objeto con información del método de pago Safetypay

method Nombre del método de pago

country Código del país

price Importe de la transacción

pmin Importe mínimo de una transacción

pmax Importe máximo de una transacción

astropay Objeto con información del método de pago Astropay

method Nombre del método de pago

price Importe de la transacción

pmin Importe mínimo de una transacción

pmax Importe máximo de una transacción

banks Objeto con información de los métodos de pago locales de Astropay

methodName Objeto con información del método de pago local

code Código del método de pago local

name Nombre del método de pago local

logo URL de la imagen del logo del método de pago local

payvalida Objeto con información del método de pago Payvalida

P á g i n a 9 | 20

 JSON Key Descripción
method Nombre del método de pago

price Importe de la transacción

pmin Importe mínimo de una transacción

pmax Importe máximo de una transacción

banks Objeto con información de los métodos de pago locales de Payvalida

methodName Objeto con información del método de pago local

code Código del método de pago local

name Nombre del método de pago local

logo URL de la imagen del logo del método de pago local

epayouts Objeto con información del método de pago e-Payouts

method Nombre del método de pago

price Importe de la transacción

pmin Importe mínimo de una transacción

pmax Importe máximo de una transacción

gateway Objeto con información del Gateway de Pago

url URL para procesar pagos

P á g i n a 10 | 20

Referencia de códigos de error.
Código Descripción
0 Respuesta exitosa

05 MID desconocido

06 UID desconocido
19 Sitio web desconocido
22 API KEY incorrecta
30 Acceso denegado
31 No hay datos para mostrar
32 Código de país desconocido

P á g i n a 11 | 20

GATEWAY DE PAGO
Se accede mediante el parámetro GATEWAY->URL devuelto desde la API y
permite iniciar un proceso de pago para generar un código de acceso a un
producto o servicio específico.
Dicho código de acceso quedará deshabilitado hasta que el cliente
complete el proceso de pago con el proveedor correspondiente.
Completado el pago, el código será habilitado para ser utilizado en la URL
que fue configurada como URL DE ACCESO en el módulo de pago.
ACLARACION: El pago por SMS queda excluído de este proceso ya que el
código de acceso es generado automáticamente por nuestra plataforma al
recibir un mensaje de texto de un cliente.

Referencia de parámetros para GATEWAY->URL.

Parámetro Tipo Tipo de valor Descripción

uid requerido INT ID único de usuario e-Payouts

mid requerido INT ID único del módulo de pago

Nombre del método de pago. Ej:

type requerido STRING
creditcard
Código de país en formato ISO
cc requerido País donde se va a realizar el pago. Ej: uy
3166-2

email requerido STRING E-mail del cliente

Clave única de acceso a la API de usuario

apikey requerido STRING
e-Payouts
Precio de venta del producto o servicio.
price opcional FLOAT
Ej: 9.99
ID del producto o servicio. Ej: PRD-
ucode opcional STRING
123456

P á g i n a 12 | 20

El parámetro type puede soportar los siguientes valores:
- creditcard
- sofort
- paysafecard
- safetypay
- astropay
- payvalida

Dependiendo del valor de type, es posible tener que enviar algunos
parámetros extras al Gateway de Pago.
Los type como astropay y payvalida ofrecen sub métodos de pago locales
(payment-type) que deben ser identificados para que el proceso de pago se
inicie de manera correcta.

TYPE: creditcard:
Param Type Value type Description

name required STRING Nombre del cliente. Ej: Juan Herrera

TYPE: astropay:
Parámetro Tipo Tipo de valor Descripción

payment-type requerido STRING Código del método de pago local

nin requerido INT Número de D.N.I del cliente

name requerido STRING Nombre del cliente. Ej: Juan Herrera

Fecha de nacimiento del cliente en formato

birthday requerido STRING
AAAA/MM/DD

P á g i n a 13 | 20

TYPE: payvalida:
Parámetro Tipo Tipo de valor Descripción

payment-type requerido STRING Código del método de pago local

TYPE: sofort:
Param Type Value type Description

name required STRING Nombre del cliente. Ej: Juan

lastname required STRING Apellido del cliente. Ej: Herrera

P á g i n a 14 | 20

Ejemplos prácticos de cómo invocar la URL del Gateway.

1.- Envío de formulario por POST.

Formulario HTML que envía los parámetros requeridos por POST al
Gateway de Pago.
Si el código de acceso es creado correctamente, se redirige
automáticamente al proveedor de pago para que el cliente complete el
proceso de pago con los datos requeridos.

Código de ejemplo (pago por sofort):

<!-- Payment form -->
<form id="e-Payouts_gateway" method="post" action="https://api.e-payouts.com/createCode.php"
enctype="application/x-www-form-urlencoded">
<!-- USER ID - Value type: integer -->
<input type="hidden" name="uid" value=ID />
<!-- PAYMENT MODULE ID - Value type: integer -->
<input type="hidden" name="mid" value=ID />
<!-- PAYMENT METHOD - Value type: string -->
<input type="hidden" name="type" value="sofort" />
<!-- COUNTRY CODE - Value format: ISO 3166-2 format -->
<input type="hidden" name="cc" value="es" />
<!-- CUSTOMER EMAIL -->
<input type="hidden" name="email" value="email@gmail.com" />
<!-- PRODUCT/SERVICE PRICE - Value type: float -->
<input type="hidden" name="price" value=2.99 />
<!-- PRODUCT/SERVICE CODE - Value type: string -->
<input type="hidden" name="ucode" value="ABC" />
<!-- CUSTOMER NAME - Value type: string -->
<input type="hidden" name="name" value="" />
<!-- CUSTOMER LASTNAME - Value type: string -->
<input type="hidden" name="lastname" value="" />
<!-- e-Payouts API KEY -->
<input type="hidden" name="apikey" value="XXXXXXXXXXXXXXXX" />
<!-- AUTOMATIC REDIRECTION TO PAYMENT PROVIDER - Value type: true/false -->
<input type="hidden" name="direct" value="true" />

<button id="submit" name="submit">PAY</button>
</form>

P á g i n a 15 | 20

2.- Envío de formulario por POST usando Ajax (jQuery).
Formulario HTML que envía los parámetros requeridos por POST al
Gateway de Pago usando Ajax con jQuery.
Se recibirá como respuesta un JSON con la siguiente información:
1. Si el código de acceso se pudo crear correctamente:
a. code: código de acceso creado.
b. price: Precio del producto o servicio.
c. error: Código de error. Siempre será 0.
d. url: URL para redirigir al cliente al proveedor de pago y así
completar proceso de pago con los datos requeridos.
2. Si el código de acceso no se pudo crear:
a. error: Código de error

Código de ejemplo (pago por tarjeta de credito):

<!-- Payment form -->
<form id="e-Payouts_gateway" method="post" action="https://api.e-payouts.com/createCode.php"
enctype="application/x-www-form-urlencoded">
<!-- USER ID - Value type: integer -->
<input type="hidden" name="uid" value=ID />
<!-- PAYMENT MODULE ID - Value type: integer -->
<input type="hidden" name="mid" value=ID />
<!-- PAYMENT METHOD - Value type: string -->
<input type="hidden" name="type" value="creditcard" />
<!-- COUNTRY CODE - Value format: ISO 3166-2 format -->
<input type="hidden" name="cc" value="es" />
<!-- CUSTOMER EMAIL -->
<input type="hidden" name="email" value="email@gmail.com" />
<!-- PRODUCT/SERVICE PRICE - Value type: float -->
<input type="hidden" name="price" value=2.99 />
<!-- PRODUCT/SERVICE CODE - Value type: string -->
<input type="hidden" name="ucode" value="ABC" />
<!-- CUSTOMER NAME - Value type: string -->
<input type="hidden" name="name" value="" />
<!-- e-Payouts API KEY -->
<input type="hidden" name="apikey" value="XXXXXXXXXXXXXXXX" />

<button id="submit" name="submit">PAY</button>
</form>

P á g i n a 16 | 20


<!-- jQuery code -->
<script type="text/javascript">
$(document).ready(function() {
$("form#e-Payouts_gateway").on("click", "button#submit", function(e) {
e.preventDefault();

var form = $(this).parents("form:first");
$.post(form.attr("action"), form.serialize(), function(callback) {
if(callback.error==0) {
// Redirect to Payment Provider FORM
location.href = callback.url;
}
else {
// Print Error code - view Error Codes reference
alert("Error code: " + callback.error);
}
},"json");
});
});
</script>

Respuesta JSON: código de acceso creado correctamente.

{
'code': "AABBCCDDEEFF",
'price': 2.99,
'error': 0,
'url': "https://api.e-
payouts.com/pay.php?uid=1&mid=1&method=paypal&country=uy&code=AABBCCDDEEFF"
}

Respuesta JSON: error al crear el código de acceso.

{
'error': 02
}

P á g i n a 17 | 20

3.- Con PHP – Utilizando la librería CURL.
CURL (librería de PHP) para enviar los parámetros requeridos por POST al
Gateway de Pago.
Se recibirá como respuesta un JSON que contendrá:
1. Si el código de acceso se pudo crear correctamente:
a. code: código de acceso creado.
b. price: Precio del producto o servicio.
c. error: Código de error. Siempre será 0.
d. url: URL para redirigir al cliente al proveedor de pago y así
completar proceso de pago con los datos requeridos.
2. Si el código de acceso no se pudo crear:
a. error: Código de error

El script convierte el objeto JSON a un array PHP para obtener una mejor
comodidad al manejar la información de respuesta.

Código de ejemplo (pago por astropay):

<?php

// Payment array
$data=Array(
"uid"=>ID, //USER ID - Value type: integer
"mid"=>ID, //PAYMENT MODULE ID - Value type: integer
"type"=>"astropay", //PAYMENT METHOD - Value type: string
"cc"=>"co", //COUNTRY CODE - Value format: ISO 3166-2 format
"email"=>"email@gmail.com", //CUSTOMER EMAIL
"price"=>2.99, //PRODUCT/SERVICE PRICE - Value type: float
"ucode"=>"ABC", //PRODUCT/SERVICE CODE - Value type: string
"payment-type"=>"", //LOCAL PAYMENT METHOD - Value type: string
"nin"=>"", //CUSTOMER NATIONAL ID NUMBER - Value type: integer
"name"=>"", //CUSTOMER NAME - Value type: string
"birthdate"=>"", //CUSTOMER BIRTHDAY - Value format: AAAA/MM/DD
"apikey"=>"XXXXXXXXXXXXXXXX" //e-Payouts API KEY
);

$fields=http_build_query($data);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL,"https://api.e-payouts.com/createCode.php");
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);

P á g i n a 18 | 20

 curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $fields);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec ($ch);
curl_close ($ch);

if($result)
{
// Decode JSON data
$data=json_decode($result);
// Convert PHP object to PHP array
if(is_object($data)) $data=(array)$data;
if(is_array($data)&&count($data))
{
if(!$data["error"]&&isset($data["url"]))
{
// Redirect to Payment Provider FORM
header("Location: {$data["url"]}");
exit;
}
// Print Error code - view Error Codes reference
die("Error: {$data["error"]}");
}
}
// Print Error message
die("Error");
?>

Array PHP: código de acceso creado correctamente.

Array (
["code"] => "C7EBX9KSN36G"
["price"] => 25.00
["error"] => 0
["url"] => "https://api.e-
payouts.com/pay.php?uid=2&mid=21&method=paypal&country=ar&code=C7EBX9KSN36G"
)

Array PHP: código de acceso no se pudo crear .

Array (
["error"] => 02
)

P á g i n a 19 | 20

Referencia de códigos de error.
Código Descripción
0 Respuesta exitosa

01 Método de pago desconocido

02 Email vacío

03 UID vacío

04 MID vacío

05 MID desconocido

06 UID desconocido

07 Cuenta deshabilitada

08 Error interno

09 No existen métodos de pago habilitados

10 El método de pago seleccionado no está habilitado

11 Datos de acceso a e-Payouts incorrectos (EP payment)

12 Saldo insuficiente (EP payment)

16 Método de pago desconocido para la API

17 Error interno de procesamiento

18 Error de configuración de cuenta

19 Sitio web desconocido

20 No hay comisión configurada

22 API KEY incorrecta

26 Referrer desconocido

27 IP deshabilitada

28 Módulo de pago deshabilitado

29 Sitio web deshabilitado

P á g i n a 20 | 20