Saltar al contenido principal

Endpoints

Creación de link de pago (POST) /paymentlink/checkout​

Descripción​

Este endpoint permite generar un link de pago para realizar un cobro a través de CheckoutLink.

tip

Si necesitas escuchar eventos de la orden, puedes configurar tu Webhhok

Request Body Schema​

{
  "orderReference": "string",
  "orderName": "string",
  "orderDescription": "string",
  "amount": 0,
  "lineItems": [
    {
      "sku": "string",
      "product": {
        "name": "string",
        "price": 0,
        "imageUrl": "string",
        "requiresShipping": true
      },
      "quantity": 0
    }
  ],
  "successUrl": "string",
  "cancelUrl": "string",
  "locationCode": "string",
  "metadata": [
    {
      "name": "string",
      "value": "string"
    }
  ],
  "expirationMinutes": 0
}

  • orderReference: string|required(false)|length(255) - Referencia del pedido. Ejemplo: “RFC-1234”

  • orderName: string|required(false)|length(255)|default-value(PaymentLink Order) - Nombre del pedido. Ejemplo: "Pizza Integration"

  • orderDescription: string*|*required(false)|length(2048)|default-value(null) - Descripción del pedido. Ejemplo: "A delicious pizza order"

  • amount: decimal|required-conditionally - Monto total del pedido cuando no se especifican lineItems (requerido solo para el Metodo 2). Ejemplo: 10.50 (ajustar según el monto total del pedido)

  • lineItems: array|required-conditionally - Lista de productos con detalles cuando no se especifica amount (requerido solo para el Método 1).

    Ejemplo:

    • LineItem:
      • sku: string|required-conditionally - valor del stock-keeping unit del producto creado en el portal de comercios cuando no se especifica el objeto product. Ejemplo: "PIZZA-001"
      • product: object|required-conditionally - estructura del producto de un solo uso cuando no se especifica sku.
        • product.name: string|required(true) - Ejemplo: "Pizza Italiana"
        • product.price: decimal|required(true) - Ejemplo: 15.00
        • product.imageUrl: string|required(false)|length(512) - Ejemplo: "https://www.test.com/image.png"
        • product.requiresShipping: boolean|required(false) - Ejemplo: true
      • quantity: int|required(true) - Ejemplo: 2

  • successUrl: string|required(false) - URL a la que redirigir en caso de éxito. Ejemplo: "https://www.my-website.com/checkout/success"

  • cancelUrl: string|required(false) - URL a la que redirigir en caso de cancelación. Ejemplo: "https://www.my-website.com/shopping-cart"

  • locationCode: string|required(false) - Código de sucursal (puede ajustarse según tus necesidades, si no se pasa, se utiliza la sucursal predeterminada de la tienda). Ejemplo: "LC-001"

    note

    Para obtener el código de sucursal, puedes consultar la lista de sucursales en el portal de comercios.

  • metadata: array|required(false) - Datos adicionales. Ejemplo:

    • name string|required(true): "clientId"
    • value string|required(true): "1234"

  • expirationMinutes: int|required(false)|default-value(1440) - Minutos de expiración del enlace de pago. Ejemplo: 30

Response Body Schema​

200 OK - Response Body​

{
  "orderCode": "string",
  "orderId": 0,
  "paymentLinkUrl": "string"
}

Fields

  • orderCode: string - Código del pedido en n1co business. Ejemplo: "PL-001"
  • orderId: integer - Id del pedido en n1co business. Ejemplo: 1
  • paymentLinkUrl: string - url del enlace de pago. Ejemplo: https://pay.example.com/PL-001

Example

{
    "orderCode": "ABC123",
    "orderId": 21566,
    "paymentLinkUrl": "https://pay.n1cco.shop/ABC123"
}

400 Bad Request - Response Body​

{
    "type": "string",
    "title": "string",
    "status": 0,
    "errors": {
        "field": [
            "string"
        ]
    }
}

Fields

  • type: string - Una URL que identifica el tipo de error. Generalmente, esta URL se refiere a una especificación que describe el tipo de error. En este caso, apunta a la sección 6.5.1 de RFC 7231, que trata sobre los códigos de estado de respuesta HTTP.
  • title: string - Un título breve que describe la naturaleza del error. Este campo suele contener un mensaje genérico que resume el problema.
  • status: integer - Un código de estado HTTP que indica el tipo de error. En este caso, 400 representa un "Bad Request", lo que significa que el servidor no pudo procesar la solicitud debido a un error aparente del cliente.
  • errors: object - Un objeto que contiene detalles específicos sobre los errores. Este objeto puede tener múltiples campos, cada uno representando un aspecto diferente del error. Los nombres de los campos y su estructura pueden variar según la implementación de la API.

Example

{
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "errors": {
        "amount": [
            "El monto debe ser mayor a 0."
        ]
    }
}

500 Internal Server Error - Response Body​

{
    "type": "string",
    "title": "string",
    "status": 0
}

Fields

  • type: string - Una URL que identifica el tipo de error. Generalmente, esta URL se refiere a una especificación que describe el tipo de error. En este caso, apunta a la sección 6.6.1 de RFC 7231, que trata sobre los códigos de estado de respuesta HTTP.
  • title: string - Un título breve que describe la naturaleza del error. Este campo suele contener un mensaje genérico que resume el problema.
  • status: integer - Un código de estado HTTP que indica el tipo de error. En este caso, 500 representa un error del lado del servidor (Internal Server Error).

Example

{
    "type": "https://tools.ietf.org/html/rfc7231#section-6.6.1",
    "title": "An error occurred while processing your request.",
    "status": 500
}

Casos de uso​

Crear Enlace de Pago (Productos) - Método 1​

Esta solicitud permite crear un enlace de pago utilizando una lista detallada de productos y cantidades.

cURL​
curl -X 'POST' \
  '{{API_BASE_URL}}/paymentlink/checkout' \
  -H "Authorization: Bearer {{ YOUR_SECRET_KEY }}" \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "orderName": "Pizza Integration",
  "orderDescription": "A delicious pizza order",
  "lineItems": [
    {
      "product": {
        "name": "Pizza Italiana",
        "price": 15
      },
      "quantity": 2
    },
    {
      "product": {
        "name": "Pizza Romana",
        "price": 20
      },
      "quantity": 3
    }
  ],
  "successUrl": "https://www.google.hn",
  "cancelUrl": "https://www.youtube.com",
  "metadata": [
    {
      "name": "clientId",
      "value": "1234"
    }
  ]
}'
JS​
const paymentLinkDTO = {
  "orderName": "Pizza Integration",
  "orderDescription": "A delicious pizza order",
  "lineItems": [
    {
      "product": {
        "name": "Pizza Italiana",
        "price": 15
      },
      "quantity": 2
    },
    {
      "product": {
        "name": "Pizza Romana",
        "price": 20
      },
      "quantity": 3
    }
  ],
  "successUrl": "https://www.google.hn",
  "cancelUrl": "https://www.youtube.com",
  "metadata": [
    {
      "name": "clientId",
      "value": "1234"
    }
  ]
};

const endpointURL = '{{API_BASE_URL}}/paymentlink/checkout';

const authToken = '{{ YOUR_SECRET_KEY }}';

fetch(endpointURL, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${authToken}`,
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify(paymentLinkDTO)
})
  .then(response => response.json())
  .then(data => console.log('Respuesta:', data))
  .catch(error => console.error('Error al realizar la solicitud:', error.message));

Crear Enlace de Pago (Solo Monto) - Método 2​

Esta solicitud permite crear un enlace de pago utilizando un monto total en lugar de una lista detallada de productos.

cURL​
curl -X 'POST' \
  '{{API_BASE_URL}}/paymentlink/checkout' \
  -H "Authorization: Bearer {{ YOUR_SECRET_KEY }}" \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "orderName": "Pizza Integration",
  "orderDescription": "A delicious pizza order",
  "amount": 25,
  "successUrl": "https://www.google.hn",
  "cancelUrl": "https://www.youtube.com",
  "metadata": [
    {
      "name": "clientId",
      "value": "1234"
    }
  ]
}'
JS​
const paymentLinkDTO = {
  "orderName": "Pizza Integration",
  "orderDescription": "A delicious pizza order",
  "amount": 25,
  "successUrl": "https://www.google.hn",
  "cancelUrl": "https://www.youtube.com",
  "metadata": [
    {
      "name": "clientId",
      "value": "1234"
    }
  ]
};

const endpointURL = '{{API_BASE_URL}}/paymentlink/checkout';

const authToken = '{{ YOUR_SECRET_KEY }}';

fetch(endpointURL, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${authToken}`,
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  },
  body: JSON.stringify(paymentLinkDTO)
})
  .then(response => response.json())
  .then(data => console.log('Respuesta:', data))
  .catch(error => console.error('Error al realizar la solicitud:', error.message));

Obtener detalle de orden (GET) /paymentlink/order/{orderCode}​

Descripción​

Este endpoint permite obtener el detalle de una orden de pago a través de su código.

Response Body Schema​

{
  "orderId": 0,
  "orderCode": "string",
  "orderReference": "string",
  "name": "string",
  "description": "string",
  "lineItems": [
    {
      "productId": 0,
      "sku": "string",
      "name": "string",
      "price": 0,
      "promoPrice": 0,
      "quantity": 0,
      "imageUrl": "string",
      "subTotal": 0
    }
  ],
  "orderStatus": "string",
  "subtotal": 0,
  "totalDetails": {
    "shippingAmount": 0,
    "discountAmount": 0,
    "surchargeAmount": 0
  },
  "total": 0,
  "metadata": [
    {
      "name": "string",
      "value": "string"
    }
  ],
  "paymentLinkUrl": "string",
  "successUrl": "string",
  "cancelUrl": "string",
  "store": {
    "name": "string",
    "countryCode": "string",
    "currencyCode": "string",
    "currencySymbol": "string",
    "locale": "string",
    "timezone": "string"
  },
  "payment": {
    "authorizationCode": "string",
    "voucherUrl": "string",
    "buyer": {
      "name": "string",
      "phone": "string",
      "email": "string"
    }
  },
  "created": "2024-05-14T13:44:23.133Z"
}

Fields

  • orderId: integer - Id de la orden en n1co business. Ejemplo: 1

  • orderCode: string - Código de la orden en n1co business. Ejemplo: "PL-001"

  • orderReference: string - Referencia de la orden. Ejemplo: "RFC-1234"

  • name: string - Nombre de la orden. Ejemplo: "Pizza Integration"

  • description: string - Descripción de la orden. Ejemplo: "A delicious pizza order"

  • lineItems: array - Lista de productos de la orden.

    Ejemplo:

    • LineItem:
      • productId: integer - Id del producto en n1co business. Ejemplo: 1
      • sku: string - valor del stock-keeping unit del producto. Ejemplo: "PIZZA-001"
      • name: string - Nombre del producto. Ejemplo: "Pizza Italiana"
      • price: decimal - Precio unitario del producto. Ejemplo: 15.00
      • promoPrice: decimal - Precio promocional del producto. Ejemplo: 10.00
      • quantity: int - Cantidad del producto. Ejemplo: 2
      • imageUrl: string - URL de la imagen del producto. Ejemplo: "https://www.test.com/image.png"
      • subTotal: decimal - Subtotal del producto. Ejemplo: 30.00

  • orderStatus: string - Estado de la orden. [ PENDING, PAID, CANCELLED, FINALIZED ]

  • subtotal: decimal - Subtotal de la orden. Ejemplo: 30.00

  • totalDetails: object - Detalles del total de la orden.

    Ejemplo:

    • shippingAmount: decimal - Monto de envío. Ejemplo: 5.00
    • discountAmount: decimal - Monto de descuento. Ejemplo: 0.00
    • surchargeAmount: decimal - Monto de recargo. Ejemplo: 0.00

  • total: decimal - Total de la orden. Ejemplo: 35.00

  • metadata: array - Datos adicionales.

    Ejemplo:

    • name string: "clientId"
    • value string: "1234"

  • paymentLinkUrl: string - URL del enlace de pago. Ejemplo: https://pay.example.com/PL-001

  • successUrl: string - URL de redirección en caso de éxito. Ejemplo: "https://www.my-website.com/checkout/success"

  • cancelUrl: string - URL de redirección en caso de cancelación. Ejemplo: "https://www.my-website.com/shopping-cart"

  • store: object - Detalles de la tienda.

    Ejemplo:

    • name: string - Nombre de la tienda. Ejemplo: "Pizza Shop"
    • countryCode: string - Código de país de la tienda. Ejemplo: "HN"
    • currencyCode: string - Código de moneda de la tienda. Ejemplo: "HNL"
    • currencySymbol: string - Símbolo de moneda de la tienda. Ejemplo: "L"
    • locale: string - Configuración regional de la tienda. Ejemplo: "es_HN"
    • timezone: string - Zona horaria de la tienda. Ejemplo: "America/Tegucigalpa"

  • payment: object - Detalles del pago.

    Ejemplo:

    • authorizationCode: string - Código de autorización del pago. Ejemplo: "ABC123"

    • voucherUrl: string - URL del comprobante de pago. Ejemplo: "https://pay.example.com/voucher/ABC123"

    • buyer: object - Detalles del comprador.

      Ejemplo:

      • name: string - Nombre del comprador. Ejemplo: "John Doe"
      • phone: string - Teléfono del comprador. Ejemplo: "+504 9999-9999"
      • email: string - Correo electrónico del comprador. Ejemplo: "

  • created: string - Fecha de creación de la orden. Ejemplo: "2024-05-14T13:44:23.133Z"