Accept Payments

With this API, you can integrate a billing system into your platform, facilitating one-time payments and refunds.

Features

Authentication and Security

To access the API, it is necessary to authenticate each request using a token, see Authentication.

📌 Generate a charge for a customer.

Base URL: https://api-sandbox.n1co.shop
Method: POST
Endpoint: /api/v3/Charges
Description: Create charge.
Required headers:
Content-Type: application/json
Authorization: Bearer {your_token}
Example:

Request
Response

{
    "customer": {
        "id": "customer114",
        "name": "Carlos Pérez",
        "email": "[email protected]",
        "phoneNumber": "+50370000000"
    },
    "order": {
        "id": "EPAY001",
        "amount": 200.9,
        "description": "Estufa eléctrica G.E modelo JJCBS631SFSS",
        "name": "Compra de cocina"
    },
    "cardId": "69167196381d34f25eb22e9d",
    "authenticationId": null,
    "billingInfo": {
        "countryCode": "US",
        "stateCode": "CA",
        "zipCode": "10002"
    },
    "locationCode": "N1C0CD001"
}

{
    "status": "SUCCEEDED",
    "message": "The payment was made successfully",
    "error": null,
    "authentication": null,
    "order": {
        "id": "50582",
        "reference": "EPAY001",
        "amount": 200.9,
        "captureAmount": 200.9,
        "currency": "USD",
        "authorizationCode": "217982"
    },
    "createdAt": "2025-12-04T17:35:48.6318771Z"
}

Create payment methods

You will need test card data →. This documentation guides you through valid test scenarios for the sandbox environment.

Before making a charge, you must create a payment method →. After creating the payment method, the ID must be used in the cardId (Required) field.

- Request Parameters

Parameter	Type	Required	Description
`customer`	object	❌	Customer information (recommended)
`customer.id`	string	❌	Unique customer identifier
`customer.name`	string	❌	Customer's full name (max. 255)
`customer.email`	string	❌	Customer's email; must be valid if sent (max. 255)
`customer.phoneNumber`	string	❌	Phone number with country code
`order`	object	✅	Order information
`order.id`	string	✅	Unique order identifier
`order.amount`	decimal	Conditional	Amount to charge, greater than 0. Required when `order.lineItems` is not sent; must be omitted when it is
`order.lineItems`	array	Conditional	Order items. Required when `order.amount` is not sent; must be omitted when it is. Repeated SKUs are not allowed
`order.lineItems[].sku`	string	Conditional	SKU of a product in your catalog; it must exist in your store. Required when `product` is not sent
`order.lineItems[].quantity`	integer	✅	Quantity, greater than 0
`order.lineItems[].product`	object	Conditional	Product described in the request, to charge for something that is not in your catalog
`order.lineItems[].product.name`	string	Conditional	Product name. Required when `product` is sent
`order.lineItems[].product.price`	decimal	Conditional	Unit price, greater than 0. Required when `product` is sent
`order.lineItems[].product.description`	string	❌	Product description
`order.lineItems[].product.imageUrl`	string	❌	Product image URL (max. 512)
`order.description`	string	❌	Order description
`order.name`	string	✅	Order name (max. 150)
`cardId`	string	✅	ID of the token returned during tokenization
`authenticationId`	string	❌	3DS authentication ID (null on first request)
`billingInfo`	object	Conditional*	Billing information, can be null
`billingInfo.countryCode`	string	Conditional*	Country code
`billingInfo.stateCode`	string	Conditional*	State code
`billingInfo.zipCode`	string	Conditional*	Zip code
`locationCode`	string	❌	Branch code. If omitted, the active branch marked as default is used. Obtained from Portal → Configuration → Branches → Edit → below the Phone field

Billing Info

The billingInfo object is required only when the card's issuing country is USA or CAN. You can determine this from the country code of the payment method's BIN.

Location Code

You can find the locationCode in the portal when editing your branch, right below the phone number. Do not confuse with locationId.

- Response Parameters

Parameter	Type	Description
`status`	string	Charge status (`FAILED`, `SUCCEEDED`, `AUTHENTICATION_REQUIRED`)
`message`	string	Description of the result
`error`	object	Error code and message (when applicable)
`authentication`	object	3DS authentication URL and ID (when applicable)
`order`	object	Object containing the purchase order information
`createdAt`	object	Payment creation date

- States

1. FAILED

The payment process has failed. The error node will contain the details.

Details

View response example

{
    "status": "FAILED",
    "message": "The payment could not be processed: We need more validations, please contact customer service at +50324086126. Id: 1b44231a-1cfc-424d-9573-0a3a3ff756bd",
    "error": {
        "code": "FRAUD_PREVENT",
        "message": "We need more validations, please contact customer service at +50324086126",
        "title": "Transaction Error",
        "detail": "We need more validations, please contact customer service at +50324086126"
    },
    "authentication": null,
    "order": null,
    "createdAt": "2025-12-04T17:51:59.1548011Z"
}

2. SUCCEEDED

The payment process was completed successfully.

Details

View response example

{
    "status": "SUCCEEDED",
    "message": "The payment was made successfully",
    "error": null,
    "authentication": null,
    "order": {
        "id": "50582",
        "reference": "EPAY001",
        "amount": 200.9,
        "captureAmount": 200.9,
        "currency": "USD",
        "authorizationCode": "217982"
    },
    "createdAt": "2025-12-04T17:51:59.1548011Z"
}

3. AUTHENTICATION_REQUIRED

If the status is AUTHENTICATION_REQUIRED, the API will return an authentication URL. You must guide the user through this flow (in this case, using an iframe is necessary).

3DS Authentication Guide

For a detailed guide on how to implement the iframe and handle the 3DS flow, see our 3D Secure Authentication documentation.

Details

View response example

{
    "status": "AUTHENTICATION_REQUIRED",
    "message": "Payment requires 3DS authentication",
    "error": null,
    "authentication": {
        "url": "https://front-3ds-sandbox.n1co.com/authentication/9b77e558-7d5d-4fdd-b84c-f295225ba2e1?showBranding=True&lang=es",
        "id": "9b77e558-7d5d-4fdd-b84c-f295225ba2e1"
    },
    "order": null,
    "createdAt": "2025-12-04T17:51:59.1548011Z"
}

📌 Generate a charge refund

Base URL: https://api-sandbox.n1co.shop
Method: POST
Endpoint: /api/v3/Refunds
Description: Create refund.
Required headers:
Content-Type: application/json
Authorization: Bearer {your_token}
Response example:

Request
Response

{
    "orderId": "50634",
    "cancellationReason": "Product in poor condition was returned by the customer"
}

{
    "success": true,
    "message": "Your order has been canceled and your payment refunded",
    "orderId": "50634",
    "status": "SUCCEEDED",
    "amount": 200.9000,
    "currency": "USD"
}

Accept Payments

Features​

📌 Generate a charge for a customer.​

- Request Parameters​

- Response Parameters​

- States​

1. FAILED​

2. SUCCEEDED​

3. AUTHENTICATION_REQUIRED​

📌 Generate a charge refund​

Features

📌 Generate a charge for a customer.

- Request Parameters

- Response Parameters

- States

1. FAILED

2. SUCCEEDED

3. AUTHENTICATION_REQUIRED

📌 Generate a charge refund