¿Cómo usar el Api de pago con tarjeta? V2.0

El api de pago con tarjeta permite a los establecimientos PayPhone instalar pasarelas de pago en sus aplicaciones móviles, páginas web o sistemas empresariales, y cobrar directamente a los usuarios Para implementar el botón de pagos debes cumplir ciertos requisitos que dividimos en dos categorías: Requisitos Comerciales y Requisitos de Desarrollo.

Requisitos Comerciales:

  • El establecimiento que va a recibir los pagos tiene que estar registrado en PayPhone como una tienda habilitada. Para iniciar el registro como PayPhone Business puedes hacer click aquí.
  • Con la tienda activa y lista para transaccionar, debes crear un usuario de tipo “desarrollador“, el cual te explicaremos más adelante.

Requisitos de Desarrollo:

  • Debes configurar en nuestro sitio web «PayPhone Developer» tu ambiente de desarrollo en donde podrás obtener todas tus credenciales, tokens y llaves con las que podrás identificarte en nuestros servicios y añadir la seguridad respectiva al proceso.

Crear usuario desarrollador

Ingresa en tu página PayPhone Business, e inicia sesión con el ruc, correo y contraseña, (si no tienes acceso el administrador de la empresa puede entrar y crear tu usuario) y dirígete a la sección de «Usuarios» a continuación selecciona «Crear Usuario»:

Ingresa todos los datos del desarrollador en el formulario, no olvides que en el campo «Roles» debes ingresar «Desarrollador». (El administrador debe entregar al desarrollador el correo electrónico y la contraseña ingresadas)

Selecciona la tienda o sucursal que recibirá los pagos y presiona el botón Guardar:

Con este proceso listo, el usuario desarrollador puede iniciar la implementación.

Configuración de ambiente

Configurar el ambiente de desarrollo te permite tener un control total sobre las transacciones efectuadas a través de PayPhone. Por favor sigue los siguientes pasos:

1. Iniciar sesión como desarrollador

Ingresa en la página https://appdeveloper.payphonetodoesposible.com/ e inicia sesión con las credenciales de tu usuario desarrollador (Ruc, correo y contraseña).

2. Crear Aplicación PayPhone:

Las aplicaciones de desarrollo PayPhone te permiten configurar los parámetros de implementación, como la plataforma, permisos o usuarios de prueba, y te ayuda a obtener tus credenciales de autenticación como el token.

Para crear tu aplicación haz click en  el “+”  de la parte superior:

Se abrirá un formulario donde debes ingresar los campos informativos, y completar completar principalmente:

  • Dominio web: La url de tu página web que se conectará al botón de PayPhone. SOLO EL DOMINIO WEB TIENE ACCESO AL BOTÓN DE PAGO, si no abres el Express checkout desde tu dominio web, no te dará acceso.
  • Url de respuesta: Es la url donde se notificará el estado de la transacción.

Por último selecciona tu tipo de aplicación como API

Con la aplicación configurada puedes obtener tu token de autenticación. En el menú superior haz click en credenciales, y tendrás el botón para copiar tu token.

Implementación del Api:

Para las llamadas al api debes proporcionar tu token de autenticación en la cabecera de la llamada en un campo de tipo «Authorization» con contenido «Bearer TUTOKEN».En este enlace puedes conocer más sobre este tipo de autenticación El pago con tarjeta se compone de dos métodos:

  1. Create: Con este método debes enviar los datos de la tarjeta del cliente y el valor  a cobrar para que se genere la transacción, recuerda enviar el número de teléfono en formato internacional con su código de país e iniciando con un ‘+’. El número de tarjeta, fecha de expiración, el código cvv y el nombre del titular deben ser enviados en un objeto json codificado en AES 256 CBC sin vector de inicialización, posteriormente la cadena generada se codifica en Base64 y se adjunta al parámetro «data» del modelo de consumo del servicio. Debes hacer una llamada POST a la siguiente URL: https://pay.payphonetodoesposible.com/api/v2/transaction/Create

Los datos de la tarjeta del cliente deben enviarse en un objeto Json.

Para el método de codificación AES 256 CBC sin vector de inicialización es requerida una contraseña, esta se obtiene desde tu plataforma de PayPhone Developer en la configuración de tu aplicación:


Recuerda que la contraseña de codificación y el token deben pertenecer a la misma aplicación.

Para usar AES debes importar la librería aes.js:
https://cdnjs.cloudflare.com/ajax/libs/crypto-js/3.1.2/rollups/aes.js

A continuación puedes ver un ejemplo de cómo se codifica AES 256 CBC sin vector de inicialización usando Javascript:


var datos = {cardNumber: string, expirationMonth: string, expirationYear: string, 
             holderName: string, securityCode: string};

var key = CryptoJS.enc.Utf8.parse('AQUI-TU-CONTRASEÑA-DE-CODIFICACIÓN');
var iv = CryptoJS.enc.Utf8.parse(''); 
var encrypted = CryptoJS.AES.encrypt(JSON.stringify(datos), key,{ iv: iv });

var codificado = encrypted.ciphertext.toString(CryptoJS.enc.Base64); 


//Usando la librería: BouncyCastle

var inputBytes = Encoding.UTF8.GetBytes(input);
var keyC = Encoding.UTF8.GetBytes(password);

var cipher = new PaddedBufferedBlockCipher(new CbcBlockCipher(new AesEngine()));
var keyParamWithIV = new ParametersWithIV(new KeyParameter(keyC), new byte[16]);

cipher.Init(true, keyParamWithIV);
var outputBytes = new byte[cipher.GetOutputSize(inputBytes.Length)];
var length = cipher.ProcessBytes(inputBytes, outputBytes, 0);
cipher.DoFinal(outputBytes, length);
return Convert.ToBase64String(outputBytes); 

Cómo vimos en el ejemplo anterior la variable «codificado» es la que tiene la trama que debe ser enviada al Api en el parámetro Data.

El modelo para el objeto de consumo Json de servicio web es el siguiente:

{
Data (string): Datos de tarjeta codificados según el ejemplo anterior.
Email (string): 
     Correo del usuario que paga la transacción, 
PhoneNumber (string): 
     Número de teléfono del usuario que paga la transacción.
DocumentId (string): 
     CI del usuario que paga la transacción ,
Amount (integer): 
     El valor total de la factura a cobrar, este valor es la suma de 
     "AmountWithTax" más "AmountWithoutTax" más "Tax" más "Tip" más "Service".
AmountWithTax (integer, optional): 
     Subtotal del valor de los productos que gravan iva, sin el iva incluido. Solo se usa cuando el 
     tipo de facturación es con Iva o mixto.
AmountWithoutTax (integer, optional): 
     Subtotal del valor de los productos con tarifa 0% de iva. Solo se usa cuando el tipo de facturación
     es tarifa 0% o mixto.
Tax (integer, optional): 
     Suma de los impuestos o valor del iva. Solo se usa cuando el tipo de facturación es con Iva o mixto.
Service (integer, optional): 
     En caso de cobrar servicios, valor de los servicios.
Tip (integer, optional): 
     Total de la propina a cobrar
ClientTransactionId (string): 
     Identificador de la transacción proporcionado por la aplicación del cliente
StoreId (string, optional): 
     El campo StoreID  solo se envía cuando se manejan diferentes tiendas 
     o sucursales, si no se usan diferentes tiendas se puede omitir. 
     Para especificar que tienda hace el cobro el storeID se obtiene desde 
     la página web de PayPhone Developer, en la sección solicitud de compañía, 
     columna Acciones, Listado de tiendas.
TerminalId (string, optional): 
     El id del terminal usado en la transacción.
Currency (string, optional): 
     Código ISO de la moneda de la transacción.
DeferredType (string): 
     Tipo de diferido a cobrar (Se obtienen con el método Deferred explicado
     en la parte inferior de este artículo).
OptionalParameter (string, optional): 
     Parametro opcional
}

El modelo de respuesta sería el siguiente:

{
"CardToken": "string",                  // Token de tarjeta
"AuthorizationCode": "string",          // Código de autorización
"Message": "string",                    // Mensaje de respuesta
"MessageCode": 0,                       // Código de mensaje
"Status": "string",                     // Estado 
"StatusCode": 0,                        // Código de estado
"TransactionId": 0,                     // Id de transacción
"ClientTransactionId": "string"         // Id de transacción de cliente
}

Para verificar el estado de la transacción, PayPhone te entrega siempre dos campos, el Status y StatusCode, El Status te da el estado de la transacción (Approved, Canceled) y el StatusCode te entrega un número según el resultado. Si el StatusCode es igual a 3, entonces la transacción fue aprobada. Si el StatusCode es igual a 2, entonces la transacción fue rechazada por algún motivo, el cual se indicara en el campo Message.

Nota: Los valores son enteros y deben enviarse multiplicados por 100, es decir: $1 dólar = 100, $1 dólar con 50 centavos = 150.

Para una interacción más directa puedes revisar en nuestro swagger, cómo consumir el servicio web. En el siguiente artículo te enseñamos a usar el swagger, para consumir el servicio haz click aquí.

Si manejas usuarios recurrentes en tu plataforma y quieras evitarle todo el proceso de ingresar los datos de la tarjeta, la opción Create te devuelve un token de tarjeta (CardToken) el cual te permite usar la misma tarjeta nuevamente sin ingresar todos los datos, solo debes enviarnos el CardToken y el nombre del titular usando el siguiente método.

2. Pay: Como mencionamos anteriormente con este método de igual forma puedes solicitar el cobro a la tarjeta del cliente, pero sin enviar todos los parámetros, solo el token de tarjeta obtenido en la llamada anterior y el Titular de la tarjeta. (CardHolder codificado en AES 256 CBC sin vector de inicialización).

Debes hacer una llamada POST a la siguiente URL con el siguiente objeto Json: https://pay.payphonetodoesposible.com/api/v2/transaction/Pay

{
	"CardToken": "string",
        "CardHolder": "string", 
        "PhoneNumber": "string", 
        "Email": "string", 
        "OptionalParameter": "string", 
        "DocumentId": "string",  
        "Amount": 0, 
        "AmountWithTax": 0, 
        "AmountWithoutTax": 0, 
        "Tax": 0, 
        "Service": 0, 
        "Tip": 0, 
        "ClientTransactionId": "string", 
        "StoreId": "string", 
        "TerminalId": "string", 
        "Currency": "string", 
        "DeferredType": "string", 
        "ResponseUrl": "string" 
}

Reversar un cobro:

Para reversar un cobro puedes utilizar nuestro método reverse del api PayPhone, en este articulo te enseñamos a usarlo.

Cobrar con diferidos:

Con nuestro api puedes dar la opción de pagos con diferidos según los que tenga habilitados la tienda PayPhone Store, los diferidos pueden ser: 3 o 6  meses sin intereses y 3, 6, 9 y 12 meses con intereses. Para obtener los diferidos de tu tienda debes hacer una llamada POST a la siguiente dirección, con el siguiente objeto Json:

https://pay.payphonetodoesposible.com/api/transaction/Deferred

{
      "Bin": "string"
}

El valor del bin es el número de la tarjeta codificado en Base 64. Esta llamada te entregará un arreglo con todos los diferidos habilitados en la tienda y que la tarjeta proporcionada permita de la siguiente forma:

{
       "Code": "string",   // Código del diferido (se envía al solicitar el pago en el método Create o Pay)
       "Name": "string"    // Nombre del diferido, por ejemplo: "3 Meses Con intereses"
}

Por ultimo debes enviar ya sea en el método Create o en el Pay, el campo DeferredType con el código del diferido que quieras efectuar.

Leave A Comment?