MPI

Consumo del Partner

Estas son las operaciones que deberán ser consumidas por el partner para la integración

POST /mpi/validation/prepare
Preparar Solicitud
POST /mpi/validation/prepare

Api para preparar la ruta de redirección, a la cual deberá ir el partner para realizar la validación

Nota: la autenticación aún está en construcción, porque se está trabajando con Niubiz

Request headers

Para el valor del User-Agent, al momento de probar con postman, revisar que no esté mandando User-Agent duplicado con valores extraños propios del programa para evitar errores

User-Agent
string optional

Se necesita esta clave con el valor mencionado en el apartado de ejemplos para evitar interferencias con el WAF

Example:
Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/110.0.0.0 Safari/537.36

Request body

Object
transactionId
string required

Id generado por el partner en su sistema para la transaccion

Example:
1
partnerCode
string required

Codigo identificador del partner, Vendemás lo proporcionará

Enumeration:
001

Geopagos

card
Object required

Datos de la tarjeta

type
string required

Marca de tarjeta a validar

Enumeration:
001

Visa

002

Mastercard

003

Amex

005

Diners

expirationMonth
string required

Mes de expiración de la tarjeta

Enumeration:
01

Enero

02

Febrero

03

Marzo

04

Abril

05

Mayo

06

Junio

07

Julio

08

Agosto

09

Setiembre

10

Octubre

11

Noviembre

12

Diciembre

expirationYear
string required

Año de expiración

Example:
2025
number
string required

Número de tarjeta. Deberá enviarse encriptado con llave asimetrica y RSA 2048, la llave pública será entregada al partner por Vendemas

Example:
UmbRoVafKmTG6QLDCXfdz5Ch.................
sale
Object required

Datos de la venta

email
string required

Correo electrónico del tarjetahabiente.Deberá enviarse encriptado con llave asimetrica y RSA 2048, la llave pública será entregada al partner por Vendemas

Example:
correo@gmail.com
firstName
string required

Nombres del tarjetahabiente. Deberá enviarse encriptado con llave asimetrica y RSA 2048, la llave pública será entregada al partner por Vendemas

Example:
John
lastName
string required

Apellidos del tarjetahabiente. Deberá enviarse encriptado con llave asimetrica y RSA 2048, la llave pública será entregada al partner por Vendemas

Example:
Doe
amount
string required

Monto de la transacción, con 2 decimales(separador de decimales es “punto”, sin separador de miles

Example:
10.06
currency
string required

Moneda

Example:
PEN
notificationUrl
string required

Url de servicio web restfull que deberá ser expuesto por partner para notificar el resultado del procesamiento de la transacción

Example:
https://partner-url/notification/{idTransaction}
redirectUrl
string required

Url de redirección que deberá ser expuesta por el partner, para que Vendemás redireccione y el partner se encargue de mostrar el resultado respectivo

Example:
https://partner-url/confirm/{idTransaction}
Examples

Ejemplo de trama

{
    "transactionId": "112",
    "partnerCode": "001",
    "card": {
        "type": "001",
        "expirationMonth": "01",
        "expirationYear": "2025",
        "number": "lD8faegIIxOJ+WgORvXB3OmguW8M/P7W6fG..."
    },
    "sale": {
        "email": "MAj/wcm98p8gmeOY1CC1qcrwxikTCY9oA31Y...",
        "firstName": "JPVFLU44j76aCkdEeFOC/Gn3PnLhcBjKWfC3YDgDFjZSceG....",
        "lastName": "ZQ1VtHcUbWDv+0Q7ew5718BQqr6emRaoS565hirC....",
        "amount": "10",
        "currency": "PEN"
    },
    "notificationUrl": "https://mpi-partner.qa.vmas.com.pe/geopagos/notification/111",
    "redirectUrl": "https://mpi-partner.qa.vmas.com.pe/geopagos/confirm/111"
}

Responses

200 OK

Respuesta correcta (todos los otros responsecode se considera como errado)

Body
application/json
Object
code
string required

Código de respuesta

Example:
00
message
string required

Mensaje de respuesta

Example:
SUCCESS
data
Object nullable

Objeto de respuesta

url
string required

Url de redirección

Example:
https://mpi-url/view-to-redirect/{JWT}
Examples

Ejemplo de respuesta

{
    "code": "00",
    "message": "Operacion Exitosa",
    "data": {
        "url": "https://mpi-front.qa.vmas.com.pe/v1/setup/eyJhbGciOiJIUzUxMiJ9.eyJkYXRlIjoiMjAyMjEwMjYwNDM2MDc5NTEiLCJzdWIiOiJuaXViaXoiLCJleHAiOjE2NjY3NTk1NjcsImlhdCI6MTY2Njc1ODk2N30.YCCbPCUFtZTP-2W4ZPmJ_Z6cHDSDmI23VJZpDnx1_jjVTR8Jw5610C9CEmfG8nPDXg4_Ihxqdqhjs4reAs3big"
    }
}
400 Bad Request

Respuesta errada controlada sin error del servidor, con detalles de mensajes

Body
application/json
Object
code
string required

Código de error

Enumeration:
10

Error interno

1001

Error de Cybersource

1002

Error de token JWT

1003

Error en datos enviados del Partner

11

Request invalido

message
string required

Mensaje del error

Example:
Los campos de la solicitud no son válidos
errors
Array nullable

Detalle de los errores en forma de array

Example:
["sale.amount: no debe estar vacío","sale.currency: no debe estar vacío"]
string
Example:
sale.amount: no debe estar vacío
string
Example:
sale.currency: no debe estar vacío
Examples

Ejemplo de respuesta de trama incorrecta

{
    "code": "11",
    "message": "Los campos de la solicitud no son válidos",
    "errors": [
        "sale.amount: no debe estar vacío",
        "sale.currency: no debe estar vacío"
    ]
}
500 Internal Server Error

Respuesta errada pero con error del servidor

Body
application/json
Object
code
string required

Código de error

Enumeration:
10

Error interno

11

Request invalido

message
string required

Mensaje del error

Example:
Error en petición
Examples

Ejemplo de respuesta de error del servidor

{
    "code": "10",
    "message": "Error en petición"
}
Desarrollo del Partner

Las apis listadas en esta sección, deberán ser implementadas del lado del partner para que Vendemás pueda notificar al sistema externo

POST /partner/notification/{notificationId}
Recepción de respuesta
POST /partner/notification/{notificationId}

Esta api servirá para comunicar el resultado de la validación en MPI al partner

Consideraciones:

  1. Siempre el caso correcto de respuesta, será HTTP_STATUS = 200 y “code” = “00” (Transacción autorizada) o HTTP_STATUS = 200 y “code” = “96” (Transacción autorizada)
  2. La autenticación será con BasicAuth
  3. Dependiendo de la tarjeta, puede que en algunos casos no vengan los valores de XID,CAVV y ECI. Si alguno de esos valores faltase, entonces no enviar la clave faltante, y si faltasen los 3, no seria necesario enviar el objeto “authenticationRQ” que contiene a estas 3 claves como parte del api de autorizacion de Niubiz

Path variables

notificationId
string required

Identificador de la transacción enviado en la api de “Preparar Solicitud” en el campo “transactionId”

Request body

application/json
Object
transactionId
string required

Id generado por el partner en su sistema para la transaccion, es el que fue enviado por el partner en “Preparar Solicitud”. Este campo junto con “partnerCode” deberán ser verificados por el partner para ver si la respuesta corresponde a una transacción válida

Example:
1
partnerCode
string required

Codigo identificador del partner, es el que fue enviado por el partner en “Preparar Solicitud”. Este campo junto con “transactionId” deberán ser verificados por el partner para ver si la respuesta corresponde a una transacción válida

Enumeration:
001

Geopagos

action
string

Respuesta de entidad externa MPI, solamente se deberá enviar a transaccionar (api de autorización actual de comercio electrónico) si es que el valor es AUTHENTICATION_SUCCESSFUL

Enumeration:
AUTHENTICATION_SUCCESSFUL

Validación correcta

AUTHENTICATION_FAILED

Validación fallida

TIMEOUT

El usuario no completó el “challenge” del banco

protocolVersion
string nullable

Protocolo de la validacion. Solo si aparece esta entrada, se debe enviar al api de autorización

Example:
2.2.0
directoryServerTransactionId
string nullable

Valor Directory Server Transaction ID del proceso de Autenticación. El DS de EMV 3DS genera la ID de transacción de DS, durante la transacción de autenticación y es devuelto al comercio con los resultados de la autenticación. Solo si aparece esta entrada, se debe enviar al api de autorización

Example:
9986ce4b-6e8c-4a45-8aac-0883c858679f
xid
string nullable

Valor a usar en la api de autorización de comercio electrónico dentro del campo XID. De no recibir esta entrada, enviar al api de autorizacion el valor “null”

Example:
MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=
cavv
string nullable

Valor a usar en la api de autorización de comercio electrónico dentro del campo CAVV. De no recibir esta entrada, enviar al api de autorizacion el valor “null”

Example:
MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=
eci
string nullable

Valor a usar en la api de autorización de comercio electrónico dentro del campo ECI. De no recibir esta entrada, enviar al api de autorizacion el valor “null”

Example:
05
card
Object nullable

Objeto con los datos de la tarjeta

type
string required

Marca de tarjeta a validar

Enumeration:
001

Visa

002

Mastercard

003

Amex

005

Diners

expirationMonth
string required

Mes de expiración de la tarjeta

Example:
01
expirationYear
string required

Año de expiración

Example:
2025
number
string required

Número de tarjeta. Deberá enviarse encriptado con llave asimetrica y RSA 2048, la llave pública será entregada por el partner a Vendemas

Example:
lD8faegIIxOJ+WgORvXB3OmguW8M/P7W6fG...
Examples

Ejemplo de trama de transaccion que si hay que autorizar con Visa

{
    "transactionId": "1",
    "partnerCode": "001",
    "action": "AUTHENTICATION_SUCCESSFUL",
    "protocolVersion": "2.2.0",
    "directoryServerTransactionId": "9986ce4b-6e8c-4a45-8aac-0883c858679f",
    "xid": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=",
    "cavv": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=",
    "eci":"05"
    "card": {
        "type": "001",
        "expirationMonth": "01",
        "expirationYear": "2025",
        "number": "lD8faegIIxOJ+WgORvXB3OmguW8M/P7W6fG..."
    }
}

Ejemplo de trama de transaccion que si hay que autorizar con Mastercard (no tiene XID)

{
    "transactionId": "1",
    "partnerCode": "001",
    "action": "AUTHENTICATION_SUCCESSFUL",
    "protocolVersion": "2.2.0",
    "directoryServerTransactionId": "9986ce4b-6e8c-4a45-8aac-0883c858679f",
    "cavv": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=",
    "eci":"2"
    "card": {
        "type": "001",
        "expirationMonth": "01",
        "expirationYear": "2025",
        "number": "lD8faegIIxOJ+WgORvXB3OmguW8M/P7W6fG..."
    }
}

Ejemplo de validacion fallida, por lo tanto no debe autorizarse

{
    "transactionId": "1",
    "partnerCode": "001",
    "action": "AUTHENTICATION_FAILED",
    "card": {
        "type": "001",
        "expirationMonth": "01",
        "expirationYear": "2025",
        "number": "lD8faegIIxOJ+WgORvXB3OmguW8M/P7W6fG..."
    }
}

Ejemplo de validacion con TIMEOUT

{
    "transactionId": "1",
    "partnerCode": "001",
    "action": "TIMEOUT",
    "card": {
        "type": "001",
        "expirationMonth": "01",
        "expirationYear": "2025",
        "number": "lD8faegIIxOJ+WgORvXB3OmguW8M/P7W6fG..."
    }
}

Responses

200 OK

Estructura de la respuesta en caso de que la transacción se autorizó

Body
application/json
Object
code
string required

Código de la respuesta

Enumeration:
00

Transacción autorizada

96

Transaccion denegada

message
string required

Mensaje de detalle de la respuesta

Example:
Registro correcto
data
Object nullable

Metadata de la respuesta del partner (queda a discreción del partner los valores extra informativos a colocar aqui)

result
string required nullable

Texto con detalle del resultado

Example:
Success
Examples

Ejemplo en transacción autorizada

{
    "code": "00",
    "message": "Transacción autorizada",
    "data": {
        "result": "Success"
    }
}

Ejemplo de transacción denegada

{
    "code": "96",
    "message": "Transacción denegada",
    "data": {
        "result": "Failed"
    }
}
400 Bad Request

Estructura de la respuesta en caso de error

Body
application/json
Object
code
string required

Código de la respuesta

Enumeration:
11

Request inválido

message
string required

Mensaje de detalle de la respuesta

Example:
Error en registro
errors
Array nullable

Mensaje de detalle de la respuesta

Example:
[
    "Error en longitud de caracteres","Valor de XID no debe estar vacío"
]
string
Example:
Error en longitud de caracteres
string
Example:
Valor de XID no debe estar vacío
Examples

Ejemplo de respuesta con trama errada

{
    "code": "11",
    "message": "Error en registro",
    "errors": [
        "Error en longitud de caracteres",
        "Valor de XID no debe estar vacío"
    ]
}
500 Internal Server Error

Error en el servidor

Body
application/json
Object
code
string required

Código de la respuesta

Enumeration:
10

Error interno del servidor

message
string required

Descripción del mensaje del servidor

Example:
Error interno
Examples

Ejemplo de respuesta con error del servidor

{
    "code": "10",
    "message": "Error interno"
}