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

{
    "customer": {
        "id": "customer114",
        "name": "Carlos Dúran",
        "email": "[email protected]",
        "phoneNumber": "+50364331900"
    },
    "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"
}

Response

{
    "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
customer.id	string	❌	Unique customer identifier
customer.name	string	✅	Customer's full name
customer.email	string	✅	Customer's email
customer.phoneNumber	string	❌	Phone number with country code
order	object	✅	Order information
order.id	string	✅	Unique order identifier
order.amount	decimal	✅	Amount to charge
order.description	string	❌	Order description
order.name	string	✅	Order name
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, 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.h4b.dev/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

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

Response

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