GUÍA PARA DESARROLLADORES -API DE DINEROMAIL-

Transcripción

1 GUÍA PARA DESARROLLADORES -API DE DINEROMAIL- DMAPI 1

2 Objetivos Este documento servirá como guía para aquellos desarrolladores que quieran implementar la API de DineroMail. Consideraciones Iniciales Qué es una API? El término API viene del inglés application programming interface (interfaz de programación de aplicaciones), y es el conjunto de funciones y procedimientos que ofrece cierta biblioteca para ser utilizado por otro software como una capa de abstracción. Qué permite la API? A través de la API de DineroMail, podrás desde tu sitio web, plataforma, móvil, sistema de facturación y otros diferentes escenarios, de los más simples a los más complejos, realizar operaciones que van desde ingresar a tu cuenta, obtener el saldo, realizar y recibir pagos, recibir información o dirigir acciones de distinto tipo. Desde donde quieras, podrás consumir la API y, en un espacio e programación, a través de las variables que el documento solicita, realizar todo tipo de operaciones sin necesidad de acceder al sitio web de DineroMail. La API te ofrecerá posibilidades ilimitadas donde encontrarás una riqueza de servicios para programar. Podrás crear desde una pequeña aplicación para recibir pagos en una red social o en una nómina de pagos hasta atender al contexto en el cual el negocio está interactuando con el consumidor. Cuáles son los beneficios de la API? No es necesario entrar al sitio web de DineroMail. Podrás conectar aplicaciones, automatizar procesos y crear cadenas paralelas. Podrás integrar DineroMail a las necesidades del sistema del comercio y su flujo de pago. Podrás programar servicios de pagos en tus propias aplicaciones. Qué necesitas para utilizar la API? No podrás utilizar la API si no eres un usuario avanzado con conocimientos sobre programación. Además, es necesario tener una Credencial válida. Esta Credencial está compuesta por un usuario y contraseña. Si quieres solicitar tu Credencial, envía un a integration@dineromail.com Encriptación Los datos de la API viajarán con una encriptación del tipo TripleDES y aplicando como llave una clave secreta cuyo valor debe setear el usuario en DineroMail, de la Credencial DMAPI 2

3 La Credencial es la tarjeta de acceso a la API de DineroMail. La misma está especificada de la siguiente manera: APIUserName APIPassword Requerido. Tipo string. Usuario para utilización de la API Requerido. Tipo string Password para utilización de la API Todos los métodos publicados de la API reciben como primer parámetro la Credential, para poder validar si el usuario que intenta consumir la API es un usuario válido. Métodos publicados de la API GetBalance Permite realizar Consultas de saldo. Recibe: Credential Crypt UniqueID Hash Requerido. Tipo Credential. Identificación del usuario (ver definición de Credential) Boolean. True si los datos viajan encriptados o no. Opcional. Tipo string. Identificador de transacción generada por el comercio, utilizada para consultas vía IPN 3.0 o notificaciones IPN3.0. Requerido. Tipo string. Identificador único de mensaje, no puede repetirse en futuras conexiones. Requerido. Tipo string. Hash MD5 del mensaje, ver calculo de verificación de integridad de mensajes. Retorna: Balance Status TransactionId Lista de saldos del usuario. Estado de la operación actual. Ver tabla de posibles valores para Status. Identificador de transacción generado por DineroMail. Opcional. Tipo string. Identificador de transacción generada por el comercio, utilizada para consultas vía IPN 3.0 o notificaciones IPN3.0. Opcional. Tipo string. En caso de existir, devuelve la descripción del error. Descripcion de Balance Currency Amount String que identifica la moneda del saldo. Importe del saldo. Valores posibles para Status: OK La operación se realizó correctamente. ERROR Hubo un error, no se pudo realizar la operación. DENIED La operación ha sido rechazada. DMAPI 3

4 Valor del parámetro hash: Debe realizarse el cálculo MD5 de los valores de los siguientes parámetros en orden especificado. Cadena = + UniqueID + Clave Secreta Invocación con cifrado: Cadena = Base64(TDES() + TDES(UniqueID) + Clave Secreta) Los parámetros y UniqueID viajan cifrados, y codificados en Base64 SendMoney Nos da la posibilidad de hacer un Envío de dinero. Recibe: Credential Crypt Currency Amount To PayOff Subject UniqueID Hash Retorna: TransaccionId Status Requerido. Tipo Credential. Identificación del usuario (ver definición de Credential) Boolean. True si los datos viajan encriptados o no. Requerido. Tipo string. Moneda del importe a enviar Requerido. Tipo string. Importe a enviar. El separador de decimales es. (punto) Requerido. Tipo string. del usuario que recibe el dinero. Requerido. Tipo string. Identifica el origen del envío de dinero, ver tabla de valores posibles para PayOff Opcional. Tipo string. Concepto del envio de dinero. Opcional. Tipo string. Mensaje al usuario destinatario del dinero. Opcional. Tipo string. Identificador de transacción generada por el comercio, utilizada para consultas vía IPN 3.0 o notificaciones IPN3.0. Opcional. Tipo string. Identificador único de mensaje, no puede repetirse en futuras conexiones. Requerido. Tipo string. Hash MD5 del mensaje, ver calculo de verificación de integridad de mensajes. Id de transacción generado por DineroMail. Estado de la operación. Ver tabla de valores posibles para Status. Opcional. Tipo string. Identificador de transacción generada por el comercio, utilizada para consultas vía IPN 3.0 o notificaciones IPN3.0. Opcional. Tipo string. En caso de existir, devuelve la descripción del error. Valores posibles para PayOff: PRODUCT Pago de producto. SERVICE Pago de servicio. ITEM_PAYMENT Pago de ítem en Subasta. DMAPI 4

5 Valores posibles para Status: COMPLETED La operación se realizó correctamente. ERROR Hubo un error, no se pudo realizar la operación. DENIED La operación ha sido rechazada por proceso de validación o por fondos insuficientes. PENDING La operación se realizo correctamente, se encuentra pendiente. IPN 3.0 enviará al comercio una notificación cuando la operación haya cambiado de estado, el usuario puede consultar, cuando lo desee (IPN3.0), cual es el estado actual de la operación. Valor del parámetro hash: Debe realizarse el cálculo MD5 de los valores de los siguientes parámetros en orden especificado. Cadena = + UniqueID + Currency + Amount + To + PayOff + Subject + + Clave Secreta Invocación con cifrado (Opcional): Cadena = Base64( TDES() + TDES(UniqueID) + TDES(Currency) + TDES(Amount) + TDES(To ) + TDES(PayOff) + TDES(Subject) + TDES() + (Clave Secreta)) Los parámetros, UniqueID, Currency, Amount, To , PayOff, Subject y viajan cifrados con TripleDES aplicando como llave la clave secreta del usuario configurada en DineroMail, y codificados en Base64 DoPaymentWithReference Permite Realizar pago de Botón o Carrito de compras, con códigos de barra. Recibe: Credential Crypt MerchantTransaccionId Items Buyer Provider Subject UniqueID Requerido. Tipo Credential. Identificación del usuario (ver definición de Credential) Boolean. True si los datos viajan encriptados o no. Opcional. Tipo string. Identificador de transacción generado por el comercio requerido para consultas a IPN 3.0. Requerido. Tipo List<Item> ver especificación de Item. Lista de los ítems del carro de compras, en caso de ser un botón se enviará una lista de un solo ítem. Requerido. Tipo Buyer. Ver especificación de Buyer. Datos del comprador Requerido. Tipo string. Identifica el proveedor con el cual se desea realizar el pago. Ver tabla de valores posibles para Provider. Opcional. Tipo string. Concepto o asunto del comprador hacia el vendedor. Opcional. Tipo string. Mensaje del comprador hacia el vendedor. Opcional. Tipo string. Identificador único de mensaje, no puede repetirse en DMAPI 5

6 Hash Retorna: TransaccionId Status VoucherUrl BarcodeImageUrl BarcodeDigits de Items: Amount Code Currency Description Name Quantity de Buyer: Name LastName Address Phone Country City futuras conexiones. Requerido. Tipo string. Hash MD5 del mensaje, ver calculo de verificación de integridad de mensajes. Id de transacción generado por DineroMail. Estado de la operación. Ver tabla de valores posibles para Status. Url donde el comercio puede redireccionar al comprador para que imprima el voucher de pago. Url desde donde el comercio puede descargar la imagen del código de barras. El código de barras en sí, para poder personalizarlo o renderizarlo con un proceso propio del comercio. Opcional. Tipo string. Identificador de transacción generada por el comercio, utilizada para consultas vía IPN 3.0 o notificaciones IPN3.0. Opcional. Tipo string. En caso de existir, devuelve la descripción del error. Requerido. Tipo string. Importe del ítem. El separador de decimales es. (punto) Opcional. Tipo string. Identificador generado por el comercio. Requerido. Tipo string. Identificador de la moneda para el ítem. Opcional. Tipo string. Descripcion del ítem. Requerido. Tipo string. o titulo del ítem. Requerido. Tipo string. Cantidad del ítem. Requerido. Tipo string. del comprador. Requerido. Tipo string. Apellido del comprador. Requerido. Tipo string. del comprador. Opcional. Tipo string. Dirección del comprador. Opcional. Tipo string. Teléfono del comprador. Opcional. Tipo string. País del comprador. Opcional. Tipo string. Ciudad o provincia del comprador. Valores posibles para Provider: rapipago Argentina. pagofacil Argentina. bapro Argentina. cobroexpress Argentina. seveneleven Código de Barras 7-Eleven México. oxxo Código de Barras Oxxo México. servipag Chile. Ixe México. Depósitos referenciados. scotia Scotiabank México. Depósitos referenciados. banamex Banamex México. Depósitos referenciados. santander Santander México. Depósitos referenciados. bancomer Bancomer México. Depósitos referenciados. DMAPI 6

7 bajio hsbc Bajio México. Depósitos referenciados. Hsbc México. Depósitos referenciados. Valores posibles para Status: COMPLETED La operación se realizó correctamente. La venta generada se encuentra Pendiente. ERROR Hubo un error, no se pudo realizar la operación. DENIED La operación ha sido rechazada. Valor del parámetro hash: Debe realizarse el cálculo MD5 de los valores de los siguientes parámetros en orden especificado. CadenaItemsConcats = Amount Item 1 + Code item 1 + Currency Item 1 + Description item 1 + Name item 1 + Quantity item 1 (esta concatenación debe repetirse por cada item de la colección Items ) CadenaBuyerConcats = Name + LastName + + Address + Phone + Country + City Cadena = + UniqueID + CadenaItemsConcats + CadenaBuyerConcats + Provider + Subject + + Clave Secreta Invocación con cifrado(opcional): Cadena = Base64(TDES() + TDES(UniqueID) + TDES(CadenaItemsConcats) + TDES(CadenaBuyerConcats) + TDES(Provider) + TDES(Subject) + TDES() + Clave Secreta) Los parámetros = + UniqueID + CadenaItemsConcats + CadenaBuyerConcats + Provider + Subject + viajan cifrados con TripleDES aplicando como llave la clave secreta del usuario configurada en DineroMail, y codificados en Base64 GetPaymentTicket Permite obtener un cupón de pago de cualquier proveedor de código de barras y lo asigna al comercio. Recibe: Credential Crypt Currency Amount Provider Requerido. Tipo Credential. Identificación del usuario (ver definición de Credential) Boolean. True si los datos viajan encriptados o no. Requerido. Tipo string. Moneda del importe a enviar Requerido. Tipo string. Importe a enviar. El separador de decimales es. (punto) Requerido. Tipo string. Identifica el proveedor con el cual se desea realizar el pago. Ver tabla de valores posibles para Provider del método DoPayWithReference. DMAPI 7

8 MerchantTransaccionId UniqueID Hash Retorna: TransaccionId Status VoucherUrl BarcodeUrl BarcodeDigits Valores posible para Status: COMPLETED ERROR DENIED Opcional. Tipo string. Identificador de transacción generado por el comercio requerido para consultas a IPN 3.0. Opcional. Tipo string. Identificador único de mensaje, no puede repetirse en futuras conexiones. Requerido. Tipo string. Hash MD5 del mensaje, ver calculo de verificación de integridad de mensajes. Id de transacción generado por DineroMail. Estado de la operación. Ver tabla de valores posibles para Status. Url donde el comercio puede redireccionar al comprador para que imprima el voucher de pago. Url desde donde el comercio puede descargar la imagen del código de barras. El código de barras en sí, para poder personalizarlo o renderizarlo con algún proceso propio del comercio. Opcional. Tipo string. Identificador de transacción generada por el comercio, utilizada para consulas vía IPN 3.0 o notificaciones IPN3.0. Opcional. Tipo string. En caso de existir, devuelve la descripción del error. La operación se realizó correctamente. Hubo un error, no se pudo realizar la operación. La operación ha sido rechazada. Valor del parámetro hash: Debe realizarse el cálculo MD5 de los valores de los siguientes parámetros en orden especificado. Cadena = + UniqueID + Currency + Amount + Provider + Clave Secreta Invocación con cifrado: Cadena = Base64(TDES() + TDES(UniqueID) + TDES(Currency) + TDES(Amount) + TDES(Provider) + Clave Secreta) Los parámetros = + UniqueID + Currency + Amount + Provider viajan cifrados con TripleDES aplicando como llave la clave secreta del usuario configurada en DineroMail, y codificados en Base64 DoWithDraw Realiza Retiro de fondos de la cuenta de DineroMail. Recibe: DMAPI 8

9 Credential Crypt MerchantTransaccionId Method Currency Amount AddressDetail BankAccountDetail UniqueID Hash Retorna: TransaccionId Status Requerido. Tipo Credential. Identificación del usuario (ver definición de Credential) Boolean. True si los datos viajan encriptados o no. Opcional. Tipo string. Identificador de transacción generado por el comercio requerido para consultas a IPN 3.0. Requerido. Tipo string. Identificador del método a utilizar para el retiro de fondos. Ver valores posibles para Method Requerido. Tipo string. Moneda del importe a enviar Requerido. Tipo string. Importe a retirar. El separador de decimales es. (punto) Requerido en caso de que Method sea CHECK o POSTAL. Detalla la dirección de entrega. Ver especificación de AddressDetail. Requerido en caso de que Method sea BANK. Detalla la cuenta bancaria destino de los fondos. Si se omite se toma por defaul la cuenta bancaria asociada al usuario. Ver especificación de BankAccount. Opcional. Tipo string. Identificador único de mensaje, no puede repetirse en futuras conexiones. Requerido. Tipo string. Hash MD5 del mensaje, ver calculo de verificación de integridad de mensajes. Id de transacción generado por DineroMail. Estado de la operación. Ver tabla de valores posibles para Status. Opcional. Tipo string. Identificador de transacción generada por el comercio, utilizada para consultas vía IPN 3.0 o notificaciones IPN3.0. Opcional. Tipo string. En caso de existir, devuelve la descripción del error. Valores posibles para Method: BANK Retiro de fondos en la cuenta bancaria default del usuario. CHECK Retiro de fondos por checke, debe enviar los datos de la dirección de entrega. POSTAL Retira los fondos por giro postal en Correo Argentino (Solo AR) de AddressDetail: Street Requerido. Tipo sring. Calle donde recibirá el checke. Number Requerido. Tipo sring. Altura de la calle donde recibirá el checke. Floor Opcional. Tipo sring.piso en caso de vivir en edificio. Appartment Opcional. Requerido si Floor no está vacío. Tipo string. Departamento. Zip Requerido. Tipo sring. Codigo postal. City Requerido. Tipo sring. Identificador de Ciudad, ver tabla de ciudades por país. State Requerido. Tipo sring. Identificador de Estado o provincia, ver tabla de provincias por país. de BankAccountDetail: Bank Requerido. Tipo string. Identificador del banco, ver tabla de bancos. BankNumber Requerio. Tipo string. Número de la cuenta bancaria (CBU, Clabe,.). Type Opcional. Tipo string. Identifica el tipo de cuenta bancaria, ver tabla de DMAPI 9

10 Name LastName DocumentType DocumentNumber Branch Valores posibles para Type: CA CC CV valores posibles. Requerido. Tipo string. del titular de la cuenta bancaria. Requerido. Tipo string. Apellido del titular de la cuenta bancaria. Requerido. Tipo string, Tipo de documento del titular. Ver tabla Tipo de Documento. Requerido. Tipo string, Nro de documento del titular. Solamente necesario en Brasil. Por defecto enviar 0 cero. Caja de ahorro. Cuenta corriente. Cuenta vista. Valores posibles para DocumentType CUIT Clave Unica de Identificación Laboral. Usado en Argentina CUIL Clave Unica de Identificación Tributaria. Usado en Argentina RUT Registro Unico Tributario. Usado en Chile CNPJ Cadastro Nacional de Pessoas Jurídicas. Usado en Brasil CPF Cadastro de Pessoas Físicas. Usado en Brasil RFC Registro Federal de Contribuyentes. Usado en México Valores posibles para Status: COMPLETED ERROR DENIED PENDING PROCESING La operación se realizó correctamente. Este valor será notificado por IPN 3.0 puesto que un retiro de fondos nunca es instantáneo. Hubo un error, no se pudo realizar la operación. La operación ha sido rechazada. La operación se realizo, está pendiente. Se está procesando el retiro de fondos, se realizo la solicitud al banco destino o está en proceso con el correo. Valor del parámetro hash: Debe realizarse el cálculo MD5 de los valores de los siguientes parámetros en orden especificado. CadenaAddressDetailConcat = Street + Number + Floor + Appartment + Zip + City + State CadenaBankAccountDetail = Bank + BankNumber + Type + Name + LastName + DocumentType + DocumentNumber + Branch Cadena = + UniqueID + Method + Currency + Amount + CadenaAddressDetailConcat + CadenaBankAccountDetail + Clave Secreta Invocación con cifrado: Cadena = Base64(TDES() + TDES(UniqueID) + TDES(Method) + TDES(Currency) + TDES(Amount) + TDES(CadenaAddressDetailConcat ) + TDES(CadenaBankAccountDetail) + Clave Secreta) DMAPI 10

11 Los parámetros = Street, Number, Floor, Appartment, Zip, City, State, Bank, BankNumber, Type, Name, LastName, DocumentType, DocumentNumber,, UniqueID, Method, Currency y Amount viajan cifrados con TripleDES aplicando como llave la clave secreta del usuario configurada en DineroMail, y codificados en Base64 GetOperations Obtiene la descripción de una o varias operaciones de DineroMail por parte de los vendedores. Recibe: Credential Crypt MerchantTransaccionId OperationId StartDate EndDate UniqueID Hash Retorna: Operations Status para Operations: Id Date State Number Buyer Amount NetAmount PaymentMethod Shares Items Seller para Buyer: Requerido. Tipo Credential. Identificación del usuario (ver definición de Credential) Boolean. True si los datos viajan encriptados o no. Opcional. Tipo string. Identificador de transacción generado por el comercio requerido para consultas a IPN 3.0. Opcional. Tipo string, Identificador de la operación en DineroMail Opcional. Tipo datetime. Para traer operaciones en un rango de fecha. Este campo indica la fecha inicial Opcional. Tipo datetime. Para traer operaciones en un rango de fecha. Este campo indica la fecha final Opcional. Tipo string. Identificador único de mensaje, no puede repetirse en futuras conexiones. Requerido. Tipo string. Hash MD5 del mensaje, ver calculo de verificación de integridad de mensajes. Lista de Operaciones. Ver formato en la tabla. Estado de la operación. Ver tabla de valores posibles para Status. Opcional. Tipo string. Identificador de transacción generada por el comercio, utilizada para consultas vía IPN 3.0 o notificaciones IPN3.0. Opcional. Tipo string. En caso de existir, devuelve la descripción del error. Tipo String. Identificador de la operación. DateTime. Fecha de la operación Tipo String. Estado de la operación. Ver tabla adjunta Tipo String. Número de la operación Tipo Buyer. Comprador. Ver tabla adjunta Tipo decimal. Monto de la operación. Tipo decimal. Monto neto de la operación. String. del método de pago. String. de la cantidad de cuotas. Tipo Item. Descipción de los ítems de la compra. Ver tabla adjunta. Vendedor. Ver tabla adjunta. String. del comprador DMAPI 11

12 Address Comments Name LastName Phone DocumentType DocumentNumber para Seller: Name LastName Phone DocumentType DocumentNumber para Item: Descripcion Currency UnitPrice Quantity Valores posible para Status: COMPLETED ERROR DENIED String. Dirección del comprador. String. Comentarios de la compra. String. del comprador String. Apellido del comprador. String. Teléfono del comprador. String. Tipo de documento. String. Numero de documento String. del comprador String. del comprador String. Apellido del comprador. String. Teléfono del comprador. String. Tipo de documento. String. Numero de documento String. de la compra String. Moneda. Decimal. Precio Unitario. Entero. Cantidad La operación se realizó correctamente. Hubo un error, no se pudo realizar la operación. La operación ha sido rechazada. Valor del parámetro hash: Debe realizarse el cálculo MD5 de los valores de los siguientes parámetros en orden especificado. Cadena = + UniqueID + OperationId + StartDate + EndDate + Clave Secreta Invocación con cifrado: Cadena = Base64(TDES() + TDES(UniqueID) + TDES(OperationId) + TDES(StartDate) + TDES(EndDate) + Clave Secreta) Los parámetros + UniqueID + OperationId + StartDate + EndDate viajan cifrados con TripleDES aplicando como llave la clave secreta del usuario configurada en DineroMail, y codificados en Base64 DMAPI 12

13 Cómo consumir la API? Este es un ejemplo para poder consumir la API desde.net con C#: 1) Referenciamos al WebServices: 2) Instanciamos a la API: DMAPI oapi = new DMAPI(); 3) Creamos la credencial de la siguiente manera: Credential ocredential = new Credential(); ocredential.apipassword = "test"; ocredential.apiusername = "test"; 4) Creamos una instancia de la respuesta del método a imbocar: ResultGetBalance obalance = new ResultGetBalance(); 5) Llamamos al método: obalance = oapi.getbalance(ocredential, "trxid12345", "umid12345", MD5("trxid12345" + "umid12345" )); Direcciones urls del servicio: Ambiente de homologación y pruebas Credential de pruebas: APIUserName = "TEST"; APIPassword = "TEST-TEST-TEST-TEST-TEST"; Modo de uso de la API de test Todos los métodos de la API reciben como primer parámetro el objeto Credential, en caso de que los datos de la misma no sean los especificados en el punto Credential de pruebas, el valor de retorno en la propiedad Status de los métodos será DENIED. Para testear los distintos retornos de los métodos existe una lógica basada en el parámetro de todos los métodos, se explica a continuacion: GetBalance : Valor de retorno en Status 1 OK Distinto de 1 ERROR SendMoney: Valor de retorno en Status 1 COMPLETED DMAPI 13

14 2 DENIED 3 ERROR 4 PENDING DoPaymentWithReference: Valor de retorno en Status 1 COMPLETED 2 DENIED 3 ERROR DoPaymentWithReference: Valor de retorno en Status 1 COMPLETED 2 DENIED 3 ERROR GetPaymentTicket: Valor de retorno en Status 1 COMPLETED 2 DENIED 3 ERROR DoWithDraw: Valor de retorno en Status 1 COMPLETED 2 DENIED 3 ERROR 4 PENDING 5 PROCESING DMAPI 14

15 GetOperations: Valor de retorno en Status 1 OK 2 DENIED 3 ERROR Ambiente productivo DMAPI 15