V2.5.0 - 06.09.
2023
Integración vía API
Con nuestra integración vía API, podés habilitar pagos con Nave en tu propia
aplicación o página web. Brindá a tus usuarios la oportunidad de realizar pagos de
manera sencilla, rápida y segura desde cualquier dispositivo, utilizando pagos con
transferencia o cualquier tarjeta. Además, con Nave, los comercios recibirán los
pagos de forma inmediata y disfrutarán de comisiones bajas.
¿Qué necesitás para comenzar?
1. Credenciales de homologación y producción: Obtené un par de credenciales
que te permitirán recuperar un token de acceso necesario para comunicarte
con nuestras APIs.
2. Utilizá nuestras APIs: Aprovechá nuestros servicios para generar intenciones
de pago y recibir notificaciones de pago en tiempo real.
3. Opciones de visualización: Tenés la flexibilidad de elegir cómo presentar el
proceso de pago a tus usuarios. Podés renderizar un código QR
personalizado o simplemente redirigirlos a nuestro checkout.
2
Configuración inicial
Como parte del proceso de configuraciones iniciales, es necesario informar los
siguientes datos:
Atributo Descripción Tipo Requerido
store_id ID del store. Puede existir más de uno String Sí
Punto de venta donde se acreditarán
pos_id String Sí
los pagos
email Email del comercio String Sí
Dominio desde donde se consumen
domain String Sí
los servicios
Endpoint donde se reciben las
notification_url String Sí
notificaciones de pago
platform Nombre de la plataforma String Sí
Ejemplo:
JavaScript
{
"store_id": "IJgEegwyxaLXgotf1g1calhxdxZoJVSo",
"pos_id": "2a3d18d2-88d5-4a50-95ef-9d99496ec0cb",
"email": "[email protected]",
"domain": "platform.com.ar",
"notification_url": "https://api.com/payment/notification/nave",
"platform": "platform_name",
}
⚠️ ️Esta información podrá enviarse por cualquier medio.
3
Autenticación
Para realizar interacciones HTTPS con nuestros servicios, se requiere un Bearer
Token. Las credenciales necesarias para obtener este token se proporcionarán una
vez que avances con la integración.
Base URL
Testing
JavaScript
POST
https://homoservices.apinaranja.com/security-ms/api/security/auth0/b2b/m2ms
Producción
JavaScript
POST
https://services.apinaranja.com/security-ms/api/security/auth0/b2b/m2ms
4
Parámetros
JavaScript
{
"client_id": "eGXu7VV...LsXWylDmrE",
"client_secret": "BAdRFax_McS...JLBTH-n",
"audience": "https://na...rchants/api",
"cache": true
}
Atributo Descripción Tipo Requerido
client_id Identificación del cliente String Sí
client_secret Clave secreta String Sí
audience Audiencia provista String Sí
cache Cache de token String Sí
⚠️ ️ Recordá que esta información es privada. No la compartas con nadie. El
equipo de Nave nunca te pedirá esta información.
5
Respuesta
JavaScript
{
"access_token": "eyJhbGciOiJS...1A",
"scope": "read... write...",
"expires_in": 86400,
"token_type": "Bearer"
}
Atributo Descripción Tipo
access_token Token generado String
scope Permisos habilitados String
expires_in Tiempo de vida expresado en segundos String
token_type Tipo de token String
6
Ejemplo
JavaScript
curl --location --request POST
'https://homoservices.apinaranja.com/security-ms/api/security/aut
h0/b2b/m2ms' \
--header 'Content-Type: application/json' \
--data-raw '{
"client_id": "eGXu7VVi...rE",
"client_secret": "BAdRFax_McS4...rkkJLBTH-n",
"audience": "https://n...nts/api",
"cache": true
}'
JavaScript
{
"access_token":
"eyJhbGciOiJSUzI1NiIs.k56aEVPVGN4TmtaRE5EWkZOREUzTVRWQ05URXdNakkx
UkRjeU5EQTJPUSJ9.eyJodHRwczovL2.HdyaXRlLnFyX3.m1A",
"scope": "read:ecommerce-api write:ecommerce-api",
"expires_in": 86400,
"token_type": "Bearer"
}
7
─
Intención de pago
Cuando un usuario decide realizar una compra, es necesario generar la intención de
pago. Esta actúa como una solicitud o autorización formal para completar la
transacción. Al generar la intención de pago, se establecen todos los detalles
necesarios, como el monto a pagar, la información de los productos y los datos
relevantes del comprador.
Base URL
Testing
JavaScript
POST https://e3-api.ranty.io/ecommerce/payment_request/external
Producción
JavaScript
POST
https://api.ranty.io/ecommerce/payment_request/external
8
Parámetros
Headers
Header Tipo Valor
Authorization Bearer Token Token generado
Body
JavaScript
{
"store_id": "112233",
"platform": "uba",
"callback_url": "https://uba.com/order/123",
"order_id": 9546,
"mobile": false,
"payment_request": {
"transactions": [
{
"products": [
{
"id": "883627",
"name": "CURSO 1",
"description": "CURSO 1",
"quantity": 2,
"unit_price": {
"currency": "ARS",
"value": "1000.00"
}
9
}
],
"amount": {
"currency": "ARS",
"value": "2000.00"
}
}
],
"buyer": {
"user_id": "nachocabrera",
"doc_type": "DNI",
"doc_number": "39032555",
"user_email": "[email protected]",
"name": "Nacho Cabrera",
"phone": "N/A",
"billing_address": {
"street_1": "Nueva Cordoba",
"street_2": "N/A",
"city": "1409",
"region": "Córdoba",
"country": "AR",
"zipcode": "5000"
}
}
}
}
10
Atributo Descripción Tipo Requerido
store_id Identificación del comercio String Sí
platform Identificación de la plataforma String Sí
callback_url URL de redirección luego del pago String Sí
order_id Identificación de la orden Number Sí
mobile Identificación del dispositivo Boolean Sí
payment_request Información de la transacción Object Sí
buyer Información del comprador Object Sí
11
Respuesta
JavaScript
{
"status": "PENDING",
"message": "Payment request created",
"data": {
"transaction_id": "c559cd47-4415-4b85-8570-36109052f966",
"qr_data": "00020101021244160012..bfbf81786304E788",
"payment_request_id": "46458184-3cd9..a558bfbf8178",
"checkout_url": "https://checkout.ranty.io/nave/..",
"redirect_to": "https://www.modo.com.ar/pagar/?qr=.."
}
}
Atributo Descripción Tipo
transaction_id Identificación de la transacción String
qr_data Código QR de la intención de pago String
payment_request_id Identificación de la intención de pago String
checkout_url Link de pago String
redirect_to Redirección a aplicaciones para pago mobile String
⚠️ ️ Si la transacción se está llevando a cabo en un dispositivo móvil, es posible
realizar una redirección al atributo "redirect_to" devuelto al crear la intención de
pago. Esto permitirá al usuario realizar el pago utilizando aplicaciones bancarias o
MODO. Proceso incorporado también en nuestro checkout.
12
Ejemplo
JavaScript
curl --location --request POST
'https://e3-api.ranty.io/ecommerce/payment_request/external' \
--header 'Authorization: Bearer eyJraWQiOiJKOFw..' \
--header 'Content-Type: application/json' \
--data-raw '{
"store_id": "112233",
"platform": "uba",
"callback_url": "https://uba.com/order/9546",
"order_id": 9546,
"mobile": true,
"payment_request": {
"transactions": [
{
"products": [
{
"id": "883627",
"name": "CURSO",
"description": "CURSO",
"quantity": 2,
"unit_price": {
"currency": "ARS",
"value": "1000.00"
}
}
],
"amount": {
13
"currency": "ARS",
"value": "2000.00"
}
}
],
"buyer": {
"user_id": "nachocabrera",
"doc_type": "N/A",
"doc_number": "N/A",
"user_email": "[email protected]",
"name": "Angel Quezada",
"phone": "N/A",
"billing_address": {
"street_1": "Nueva Cordoba",
"street_2": "N/A",
"city": "1409",
"region": "Córdoba",
"country": "AR",
"zipcode": "5000"
}
}
}
}'
14
Notificación de pago
Cuando ocurra un evento relacionado con una intención de pago u orden
específica, se enviará una notificación mediante una solicitud POST a la URL de
notificación que se especificó durante el proceso de integración. Mediante esta
notificación recibirás información en tiempo real sobre el evento ocurrido, lo que te
permitirá tomar las acciones correspondientes en tu aplicación o sistema. Es
importante asegurarse de que la URL de notificación esté correctamente
configurada y sea capaz de recibir y procesar las notificaciones entrantes de manera
adecuada.
Parámetros
Body que deberá permitir el endpoint de notificación.
JavaScript
{
"payment_method": {
"type": "wallet",
"id": "wallet"
},
"status": "APPROVED",
"amount": {
"value": "3000.00",
"currency": "ARS"
},
"order_id": "9557",
"happened_at": "2023-05-22T16:04:07.606Z",
}
15
Atributo Descripción Tipo
Identificación del método de pago. Valores
payment_method Object
posibles: wallet, credit_card o debit_card
Estado del pago. Valores posibles:
status String
APPROVED o REJECTED
amount Monto pagado por el usuario Object
order_id Identificación de la orden String
happened_at Fecha y hora del pago String
Para confirmar que la notificación se ha recibido correctamente, es necesario
responder con un código de estado 200. Si se responde con un código de estado
diferente, la notificación se volverá a procesar y se realizarán hasta cinco intentos
adicionales de notificación.
Esquema de reintentos
Intento Frecuencia
Primero 10 segundos
Segundo 70 segundos
Tercero 490 segundos
Cuarto 3430 segundos
Quinto 24010 segundos
16
Renderización de QR
Si es necesario utilizar un desarrollo personalizado para mostrar el código QR, se
puede optar por una solución disponible a nivel de frontend. Esto proporciona una
experiencia mejorada para el usuario, ya que evita redireccionamientos a otros
sitios o páginas externas. Al mostrar el código QR directamente en el frontend, se
puede mantener al usuario dentro de la interfaz de la aplicación o página web, lo
que resulta en una experiencia más fluida y coherente.
JavaScript
e3-ecommerce.ranty.io/tienda_negocio/nave/checkout?
payment_request_id=…&qr_data=…
Atributo Descripción Tipo
id Identificación de la intención de pago String
qr_data Código QR de la intención de pago String
Ejemplo
JavaScript
https://e3-ecommerce.ranty.io/tienda_negocio/nave/checkout?id=e9e16deb-5
373-49c1-8570-05444c82ef70&qr_data=00020101021244160012com.naranjax5
01500113066300584352041520530303254072000.%20005809Argentina5913tie
nda%20test%2016006ABASTO62400536e9e16deb-5373-49c1-8570-05444c82e
f706304C39C
17
Casos de uso
El caso más común implica desarrollar un iframe que muestre la URL mencionada
anteriormente. Esta aplicación se conecta a nuestros servicios a través de
WebSockets para recibir actualizaciones en tiempo real sobre el estado del pago.
