Skip to main content

Endpoints

Create Payment Link (POST) /paymentlink/checkout​

Description​

This endpoint allows generating a payment link to collect payments through CheckoutLink.

tip

If you need to listen to order events, you can configure your 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) - Order reference. Example: “RFC-1234”

  • orderName: string|required(false)|length(255)|default-value(PaymentLink Order) - Order name. Example: "Pizza Integration"

  • orderDescription: string|required(false)|length(2048)|default-value(null) - Order description. Example: "A delicious pizza order"

  • amount: decimal|required-conditionally - Total order amount when lineItems are not specified (required only for Method 2). Example: 10.50 (adjust according to the total order amount)

  • lineItems: array|required-conditionally - List of products with details when amount is not specified (required only for Method 1).

    Example:

    • LineItem:
      • sku: string|required-conditionally - Value of the stock-keeping unit of the product created in the merchant portal when the product object is not specified. Example: "PIZZA-001"
      • product: object|required-conditionally - One-time product structure when sku is not specified.
        • product.name: string|required(true) - Example: "Italian Pizza"
        • product.price: decimal|required(true) - Example: 15.00
        • product.imageUrl: string|required(false)|length(512) - Example: "https://www.test.com/image.png"
        • product.requiresShipping: boolean|required(false)|default-value(false) - Example: true
      • quantity: int|required(true) - Example: 2

  • successUrl: string|required(false) - URL to redirect to in case of success. Example: "https://www.my-website.com/checkout/success"

  • cancelUrl: string|required(false) - URL to redirect to in case of cancellation. Example: "https://www.my-website.com/shopping-cart"

  • locationCode: string|required(false) - Branch code (can be adjusted according to your needs; if not passed, the default store branch is used). Example: "LC-001"

    note

    To obtain the branch code, you can check the branch list in the merchant portal.

  • metadata: array|required(false) - Additional data. Example:

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

  • expirationMinutes: int|required(false)|default-value(1440) - Expiration time in minutes for the payment link. Example: 30

Response Body Schema​

200 OK - Response Body​

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

Fields

  • orderCode: string - Order code in n1co business. Example: "PL-001"
  • orderId: integer - Order ID in n1co business. Example: 1
  • paymentLinkUrl: string - URL of the payment link. Example: 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 - A URL that identifies the type of error. Generally, this URL refers to a specification describing the error type. In this case, it points to section 6.5.1 of RFC 7231, which deals with HTTP response status codes.
  • title: string - A brief title describing the nature of the error. This field usually contains a generic message summarizing the issue.
  • status: integer - An HTTP status code indicating the type of error. In this case, 400 represents a "Bad Request," meaning the server could not process the request due to an apparent client error.
  • errors: object - An object containing specific details about the errors. This object can have multiple fields, each representing a different aspect of the error. The field names and structure can vary depending on the API implementation.

Example

{
    "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
    "title": "One or more validation errors occurred.",
    "status": 400,
    "errors": {
        "amount": [
            "The amount must be greater than 0."
        ]
    }
}

500 Internal Server Error - Response Body​

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

Fields

  • type: string - A URL that identifies the type of error. Generally, this URL refers to a specification describing the error type. In this case, it points to section 6.6.1 of RFC 7231, which deals with HTTP response status codes.
  • title: string - A brief title describing the nature of the error. This field usually contains a generic message summarizing the issue.
  • status: integer - An HTTP status code indicating the type of error. In this case, 500 represents a server-side error (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
}

Use Cases​

Create Payment Link (Products) - Method 1​

This request allows creating a payment link using a detailed list of products and quantities.

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": "Italian Pizza",
        "price": 15
      },
      "quantity": 2
    },
    {
      "product": {
        "name": "Roman Pizza",
        "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": "Italian Pizza",
        "price": 15
      },
      "quantity": 2
    },
    {
      "product": {
        "name": "Roman Pizza",
        "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('Response:', data))
  .catch(error => console.error('Error making request:', error.message));

Create Payment Link (Amount Only) - Method 2​

This request allows creating a payment link using a total amount instead of a detailed list of products.

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": 100,
  "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": 100,
  "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('Response:', data))
  .catch(error => console.error('Error making request:', error.message));

Get Order Details (GET) /paymentlink/order/{orderCode}​

Description​

This endpoint allows you to get the details of a payment order through its code.

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 - Order ID in n1co business. Example: 1

  • orderCode: string - Order code in n1co business. Example: "PL-001"

  • orderReference: string - Order reference. Example: "RFC-1234"

  • name: string - Order name. Example: "Pizza Integration"

  • description: string - Order description. Example: "A delicious pizza order"

  • lineItems: array - List of order products.

    Example:

    • LineItem:
      • productId: integer - Product ID in n1co business. Example: 1
      • sku: string - Stock-keeping unit value of the product. Example: "PIZZA-001"
      • name: string - Product name. Example: "Italian Pizza"
      • price: decimal - Unit price of the product. Example: 15.00
      • promoPrice: decimal - Promotional price of the product. Example: 10.00
      • quantity: int - Product quantity. Example: 2
      • imageUrl: string - Product image URL. Example: "https://www.test.com/image.png"
      • subTotal: decimal - Product subtotal. Example: 30.00

  • orderStatus: string - Order status. [ PENDING, PAID, CANCELLED, FINALIZED ]

  • subtotal: decimal - Order subtotal. Example: 30.00

  • totalDetails: object - Order total details.

    Example:

    • shippingAmount: decimal - Shipping amount. Example: 5.00
    • discountAmount: decimal - Discount amount. Example: 0.00
    • surchargeAmount: decimal - Surcharge amount. Example: 0.00

  • total: decimal - Order total. Example: 35.00

  • metadata: array - Additional data.

    Example:

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

  • paymentLinkUrl: string - Payment link URL. Example: https://pay.example.com/PL-001

  • successUrl: string - Redirect URL in case of success. Example: "https://www.my-website.com/checkout/success"

  • cancelUrl: string - Redirect URL in case of cancellation. Example: "https://www.my-website.com/shopping-cart"

  • store: object - Store details.

    Example:

    • name: string - Store name. Example: "Pizza Shop"
    • countryCode: string - Store country code. Example: "HN"
    • currencyCode: string - Store currency code. Example: "HNL"
    • currencySymbol: string - Store currency symbol. Example: "L"
    • locale: string - Store locale. Example: "es_HN"
    • timezone: string - Store timezone. Example: "America/Tegucigalpa"

  • payment: object - Payment details.

    Example:

    • authorizationCode: string - Payment authorization code. Example: "ABC123"

    • voucherUrl: string - Payment voucher URL. Example: "https://pay.example.com/voucher/ABC123"

    • buyer: object - Buyer details.

      Example:

      • name: string - Buyer name. Example: "John Doe"
      • phone: string - Buyer phone. Example: "+504 9999-9999"
      • email: string - Buyer email. Example: "[email protected]"

  • created: string - Order creation date. Example: "2024-05-14T13:44:23.133Z"