Request parameters

Each object in the array accepts the following fields. The Nequi notes column describes behaviour that applies only to this wallet.

Attribute	Data type	Mandatory	Nequi notes
`order_id`	String [max_length: 40]	Yes	Payment order identification.
`credit_note`	String [max_length: 40]	Yes	Unique code per merchant. Only letters, numbers, `-` and `_`.
`account_id`	Integer [max_length: 20] — numbers only	Yes	Must be the beneficiary's Nequi mobile phone number.
`account_type`	String [max_length: 9] — `CC`, `CH` or `DP`	Yes	Validated by the API, but it does not change the data forwarded to the Nequi wallet.
`vat_id`	Integer [max_length: 11] — numbers only	Yes	Beneficiary document number.
`vat_id_type`	String [max_length: 4]	No	For Nequi only `CC`, `CE`, `TI` and `PPT` are forwarded. Any other value is replaced automatically — the transaction is not rejected for this reason.
`name`	String [max_length: 100]	Yes	Beneficiary full name.
`amount`	Decimal	Yes	Amount in COP.
`subject`	String [max_length: 100]	Yes	Free use. Example: `Withdrawal request`.
`bank_detail`	String [max_length: 100]	Yes	Free use. Example: `User withdrawal request`.
`channel`	String [max_length: 100]	Yes	`cashout`.
`user_email`	String [max_length: 100]	Yes	Must be a valid address in the format `[email protected]`.
`phone_number`	String [max_length: 30]	Yes	Beneficiary Nequi phone number. Send the same value as `account_id`.
`bank`	Integer	Yes	Nequi entity ID, obtained from `GET /banks/?country=CO&code=1507`.
`currency`	Integer	No	ID from `GET /currencies/`. Only COP is accepted for Colombia. When omitted, the COP currency configured for your Colombian account is applied.

📘
transfer_status is ignored on creation. Every transaction is always created with status 1 (in process).

Nequi-specific behaviour

The phone number is the account

For Nequi, account_id and phone_number must both carry the beneficiary's mobile number. ALPS forwards account_id as the wallet account and phone_number as the beneficiary contact number. If phone_number is empty, account_id is used as the phone number.

Phone number normalisation

Before dispatch, the phone number is normalised to international format: every non-numeric character is removed, a leading 57 is treated as the country code, and the +57 prefix is applied.

Value sent	Value forwarded
`3028367039`	`+573028367039`
`573028367039`	`+573028367039`
`+57 302 836 7039`	`+573028367039`
(empty)	(no phone forwarded — `account_id` is used as the source instead)

📘
Because a leading 57 is always interpreted as the country code, send either the 10-digit local number (3028367039) or the full international number (+573028367039). Both produce the same result.

Document types

Nequi accepts a narrower set of identification documents than the rest of the Colombian corridor:

`vat_id_type`	Description	Accepted by Nequi
`CC`	Cédula de Ciudadanía	Yes
`CE`	Cédula de Extranjería	Yes
`TI`	Tarjeta de Identidad	Yes
`PPT`	Permiso por Protección Temporal	Yes
`NIT`, `PA`	Others accepted for Colombia	No — replaced automatically

When the document type is not in the accepted list, or when the document number is missing, ALPS forwards a non-declared document marker instead and the payout continues with the beneficiary's phone number and full name. The transaction is not rejected by ALPS for this reason.

📘
Depending on the configuration agreed with your ALPS account manager, identification data may be omitted for every Nequi payout and the wallet matched by phone number only. Confirm which mode applies to your account before relying on document validation.

Account type

account_type is validated against the values allowed for Colombia (CC, CH, DP), but for Nequi it does not alter the payment instruction sent to the wallet.

Request example

curl --location 'https://uat-api.alps.cl/api/transactions/' \
--header 'Authorization: ALPS {TOKEN}' \
--header 'Content-Type: application/json' \
--data-raw '[{
    "order_id": "ORD-NEQ-001",
    "credit_note": "ORD-NEQ-001",
    "account_id": "3142210178",
    "account_type": "CH",
    "vat_id": "1014263139",
    "vat_id_type": "CC",
    "name": "John Doe",
    "amount": 50000,
    "subject": "PAYOUT NEQUI",
    "bank_detail": "PAYOUT NEQUI",
    "channel": "Transferencia",
    "user_email": "[email protected]",
    "phone_number": "+573142210178",
    "bank": 939
}]'

import requests

url = "https://uat-api.alps.cl/api/transactions/"

headers = {
    "Authorization": "ALPS {TOKEN}",
    "Content-Type": "application/json",
}

payload = [
    {
        "order_id": "ORD-NEQ-001",
        "credit_note": "ORD-NEQ-001",
        "account_id": "3142210178",
        "account_type": "CH",
        "vat_id": "1014263139",
        "vat_id_type": "CC",
        "name": "John Doe",
        "amount": 50000,
        "subject": "PAYOUT NEQUI",
        "bank_detail": "PAYOUT NEQUI",
        "channel": "Transferencia",
        "user_email": "[email protected]",
        "phone_number": "+573142210178",
        "bank": 939,
    }
]

response = requests.post(url, headers=headers, json=payload)

print(response.text)

const myHeaders = new Headers();
myHeaders.append("Authorization", "ALPS {TOKEN}");
myHeaders.append("Content-Type", "application/json");

const raw = JSON.stringify([
  {
    "order_id": "ORD-NEQ-001",
    "credit_note": "ORD-NEQ-001",
    "account_id": "3142210178",
    "account_type": "CH",
    "vat_id": "1014263139",
    "vat_id_type": "CC",
    "name": "John Doe",
    "amount": 50000,
    "subject": "PAYOUT NEQUI",
    "bank_detail": "PAYOUT NEQUI",
    "channel": "Transferencia",
    "user_email": "[email protected]",
    "phone_number": "+573142210178",
    "bank": 939
  }
]);

const requestOptions = {
  method: "POST",
  headers: myHeaders,
  body: raw,
  redirect: "follow"
};

fetch("https://uat-api.alps.cl/api/transactions/", requestOptions)
  .then((response) => response.text())
  .then((result) => console.log(result))
  .catch((error) => console.error(error));

Response

Successful response — `200 OK`

{
  "data": [
    {
      "id": 104762,
      "payroll": 2851,
      "order_id": "2026080701",
      "credit_note": "2026080701",
      "account_id": "3142210178",
      "account_type": "CH",
      "vat_id": "1014263139",
      "vat_id_type": "CC",
      "name": "John Doe",
      "amount": 50000,
      "subject": "PAYOUT NEQUI",
      "bank_detail": "PAYOUT NEQUI",
      "channel": "Transferencia",
      "user_email": "[email protected]",
      "phone_number": "+573142210178",
      "created_at": "07-08-2026 09:41:12",
      "updated_at": "07-08-2026 09:41:12",
      "transfer_status": 1,
      "transfer_status_description": "in process",
      "currency": 5,
      "currency_code": "COP",
      "bank_id": 1234,
      "bank_name": "NEQUI",
      "fee": 0,
      "tax": 0
    }
  ]
}

📘
Illustrative values. id, payroll, currency and bank_id are assigned by the platform and differ per environment. Fields with a null or empty value are omitted from the response, so the exact set of keys varies by transaction.

Partial success — `200 OK` with `errors`

When a batch contains both valid and invalid transactions, ALPS creates the valid ones and returns 200 OK with an additional errors array. Always inspect errors even on a 200 response.

{
  "data": [
    {
      "id": 104762,
      "credit_note": "2026080701",
      "transfer_status": 1,
      "transfer_status_description": "in process"
    }
  ],
  "errors": [
    {
      "credit_note": "2026080702",
      "index": 1,
      "error": "nota de credito #2026080702 ya fue aprobada"
    }
  ]
}

index is the zero-based position of the failed transaction inside the array you submitted.

Schema validation error — `400 Bad Request`

Returned when the payload does not satisfy the field schema (missing or wrongly typed fields).

{
  "info": [
    {
      "user_email": [
        "The user_email field must be a valid email in the format [email protected]."
      ]
    }
  ],
  "errors": [
    {
      "credit_note": "2026080701",
      "index": 0,
      "fields": {
        "user_email": [
          "The user_email field must be a valid email in the format [email protected]."
        ]
      }
    }
  ]
}

Business validation error — `400 Bad Request`

Returned when every transaction in the batch fails business validation.

{
  "info": [
    "la cuenta no tiene los fondos suficientes para realizar la dispersión, nota de credito #2026080701"
  ],
  "errors": [
    {
      "credit_note": "2026080701",
      "index": 0,
      "error": "la cuenta no tiene los fondos suficientes para realizar la dispersión, nota de credito #2026080701"
    }
  ]
}

Error codes

Code	Description
`200: OK`	The request was processed. The response contains the created transactions in `data`, and an `errors` array if part of the batch was rejected.
`400: Bad request`	The payload has a format, parameter or business-rule error. The response body details each rejected transaction.
`403: Forbidden`	The authenticated user does not have the profile required to create payouts.
`500: Internal server error`	Unexpected server-side condition. Retry later; if it persists, contact support.

Common validation messages

Message	Cause
`payload must be an array of json objects`	The body is not a JSON array, or the array is empty.
`{bank} - banco inválido en colombia`	The `bank` value is not a valid, active bank ID for Colombia.
`country: co is not enabled for your user`	Colombia is not enabled for your API credentials.
`the country: [co] is not available for the processing of withdrawals.`	The Colombia corridor is temporarily disabled on the platform.
`account_type should be one of these [...]`	`account_type` is not one of the values accepted for Colombia.
`vat_id_type should be one of these [...]`	`vat_id_type` is not one of the values accepted for Colombia.
`[credit_note][...] does not allow special characters.`	`credit_note` contains characters outside `A-Z`, `a-z`, `0-9`, `-` and `_`.
`nota de credito #... ya fue aprobada`	A transaction with the same `credit_note` was already approved for your account.
`nota de credito #... está siendo procesada`	A transaction with the same `credit_note` is currently being processed.
`[n]: duplicate credit note #... on request`	The same `credit_note` appears more than once in the submitted array.
`la cuenta no tiene los fondos suficientes para realizar la dispersión, nota de credito #...`	Insufficient COP balance for this transaction.
`amounts greater than 7000 usd require a kyc validation, please contact [email protected]`	The amount, converted to USD, exceeds the KYC-free limit.

📘
Error messages are returned in lower case, and some are in Spanish. Match on the transaction index and credit_note rather than parsing the message text.

Transaction lifecycle

ID	Status	Meaning
`1`	`in process`	Created and awaiting dispatch.
`2`	`approved`	Approved internally and queued for the wallet.
`3`	`rejected`	Rejected before reaching the wallet.
`4`	`rejected by bank`	Rejected by Nequi. The reason is available in `transfer_status_detail`.
`5`	`approved by bank`	Credited to the beneficiary's Nequi wallet.

Retrieve the current status with GET /transactions/{id}/, or wait for the IPN notification. The full list is available at Transaction status list.

Nequi (Wallet)

Request parameters

`transfer_status` is ignored on creation. Every transaction is always created with status `1` (`in process`).

Nequi-specific behaviour

The phone number is the account

Phone number normalisation

Because a leading `57` is always interpreted as the country code, send either the 10-digit local number (`3028367039`) or the full international number (`+573028367039`). Both produce the same result.

Document types

Depending on the configuration agreed with your ALPS account manager, identification data may be omitted for every Nequi payout and the wallet matched by phone number only. Confirm which mode applies to your account before relying on document validation.

Account type

Request example

Response

Successful response — `200 OK`

Illustrative values. `id`, `payroll`, `currency` and `bank_id` are assigned by the platform and differ per environment. Fields with a `null` or empty value are omitted from the response, so the exact set of keys varies by transaction.

Partial success — `200 OK` with `errors`

Schema validation error — `400 Bad Request`

Business validation error — `400 Bad Request`

Error codes

Common validation messages

Error messages are returned in lower case, and some are in Spanish. Match on the transaction `index` and `credit_note` rather than parsing the message text.

Transaction lifecycle

Request parameters

transfer_status is ignored on creation. Every transaction is always created with status 1 (in process).

Nequi-specific behaviour

The phone number is the account

Phone number normalisation

Because a leading 57 is always interpreted as the country code, send either the 10-digit local number (3028367039) or the full international number (+573028367039). Both produce the same result.

Document types

Depending on the configuration agreed with your ALPS account manager, identification data may be omitted for every Nequi payout and the wallet matched by phone number only. Confirm which mode applies to your account before relying on document validation.

Account type

Request example

Response

Successful response — 200 OK

Illustrative values. id, payroll, currency and bank_id are assigned by the platform and differ per environment. Fields with a null or empty value are omitted from the response, so the exact set of keys varies by transaction.

Partial success — 200 OK with errors

Schema validation error — 400 Bad Request

Business validation error — 400 Bad Request

Error codes

Common validation messages

Error messages are returned in lower case, and some are in Spanish. Match on the transaction index and credit_note rather than parsing the message text.

Transaction lifecycle

`transfer_status` is ignored on creation. Every transaction is always created with status `1` (`in process`).

Because a leading `57` is always interpreted as the country code, send either the 10-digit local number (`3028367039`) or the full international number (`+573028367039`). Both produce the same result.

Successful response — `200 OK`

Illustrative values. `id`, `payroll`, `currency` and `bank_id` are assigned by the platform and differ per environment. Fields with a `null` or empty value are omitted from the response, so the exact set of keys varies by transaction.

Partial success — `200 OK` with `errors`

Schema validation error — `400 Bad Request`

Business validation error — `400 Bad Request`

Error messages are returned in lower case, and some are in Spanish. Match on the transaction `index` and `credit_note` rather than parsing the message text.