Consultar Disponibilidad

Devuelve qué puede cobrar este comercio antes de que construyas el checkout: qué países puedes pintar, qué métodos tiene habilitados cada uno, y qué rails están abiertos.

A diferencia de Obtener Métodos de Pago, que es un catálogo de plataforma igual para todos, esta respuesta aplica la configuración del comercio: sus billeteras, sus reglas de métodos, su alta en el rail USD y en pagos con tarjeta.

Endpoint

GET /v1/availability

Autenticación

Requiere API Key con header X-API-KEY. No hace falta ningún permiso concreto.

Parámetros de Consulta

Parámetro	Tipo	Requerido	Descripción
amount	number	No	Lo que el comercio quiere recibir, en la moneda de su billetera. Es la misma lectura que hace POST /v1/payment-links con su amount_type por defecto (receive).

Sin amount la respuesta es estructural —billeteras, rails y qué métodos están habilitados— y puedes cachearla para una landing. Con amount se aplica además el mínimo de la plataforma y la respuesta es específica para ese cobro. El campo applies_amount te dice cuál de las dos recibiste.

Ejemplo de Solicitud

cURL

curl -X GET "https://api.aloha.co/api/external/v1/availability?amount=400000" \
  -H "X-API-KEY: tu_api_key_aqui"

JavaScript

const response = await fetch(
  'https://api.aloha.co/api/external/v1/availability?amount=400000',
  {
    headers: {
      'X-API-KEY': 'tu_api_key_aqui'
    }
  }
);
const { data } = await response.json();

const paises = data.countries.filter((pais) => pais.available);

console.log('Países que puedo ofrecer:', paises.map((p) => p.country_code));

Python

import requests

headers = {
    'X-API-KEY': 'tu_api_key_aqui'
}

response = requests.get(
    'https://api.aloha.co/api/external/v1/availability',
    params={'amount': 400000},
    headers=headers
)
data = response.json()['data']

paises = [p['country_code'] for p in data['countries'] if p['available']]

print('Países que puedo ofrecer:', paises)

PHP

<?php
$ch = curl_init();

curl_setopt_array($ch, [
    CURLOPT_URL => 'https://api.aloha.co/api/external/v1/availability?amount=400000',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-KEY: tu_api_key_aqui'
    ]
]);

$response = curl_exec($ch);
$data = json_decode($response, true)['data'];

$paises = array_column(
    array_filter($data['countries'], fn ($pais) => $pais['available']),
    'country_code'
);

print_r($paises);

Respuesta Exitosa (200 OK)

{
  "success": true,
  "message": "Availability retrieved successfully",
  "data": {
    "applies_amount": true,
    "merchant": {
      "verified": true,
      "status": "active"
    },
    "rails": {
      "local": { "available": true, "reason": null },
      "card": { "available": false, "reason": "card_payments_not_enabled" }
    },
    "countries": [
      {
        "country_code": "AR",
        "country_name": "Argentina",
        "currency": "ARS",
        "available": false,
        "reason": "no_payment_methods_enabled",
        "payment_methods": []
      },
      {
        "country_code": "BR",
        "country_name": "Brazil",
        "currency": "BRL",
        "available": true,
        "reason": null,
        "payment_methods": [
          { "name": "Pago con PIX", "description": "Pago con QR o Copia e Cola." }
        ]
      },
      {
        "country_code": "CL",
        "country_name": "Chile",
        "currency": "CLP",
        "available": true,
        "reason": null,
        "payment_methods": [
          { "name": "Webpay", "description": "Tarjeta de Crédito, Débito o Prepaga." }
        ]
      },
      {
        "country_code": "CO",
        "country_name": "Colombia",
        "currency": "COP",
        "available": true,
        "reason": null,
        "payment_methods": [
          { "name": "PSE", "description": "Transferencia Bancaria." },
          { "name": "Nequi", "description": "Transferencia Bancaria." }
        ]
      },
      {
        "country_code": "MX",
        "country_name": "Mexico",
        "currency": "MXN",
        "available": true,
        "reason": null,
        "payment_methods": [
          { "name": "Transferencia Bancaria", "description": "Pago a Clabe de un solo uso." }
        ]
      },
      {
        "country_code": "BO",
        "country_name": "Bolivia",
        "currency": "BOB",
        "available": true,
        "reason": null,
        "payment_methods": [
          { "name": "Pago con QR", "description": "Pago por QR." }
        ]
      },
      {
        "country_code": "US",
        "country_name": "United States",
        "currency": "USD",
        "available": false,
        "reason": "usd_account_not_enabled",
        "payment_methods": []
      }
    ]
  }
}

Campos de Respuesta

Campo	Tipo	Descripción
applies_amount	boolean	true si enviaste amount y la respuesta lo tiene en cuenta
merchant.verified	boolean	Si el comercio completó su verificación (KYB)
merchant.status	string	Estado del comercio, por ejemplo active o paused
rails.local	object	Si el comercio puede cobrar en monedas locales
rails.card	object	Si el comercio puede emitir pagos con tarjeta
countries	array	Una fila por cada moneda que acepta la creación de solicitudes de pago
countries[].country_code	string	Código ISO del país (2 letras)
countries[].country_name	string	Nombre del país
countries[].currency	string	Código de moneda ISO 4217
countries[].available	boolean	Si puedes ofrecerle este país a un pagador
countries[].reason	string | null	Por qué no está disponible. null cuando sí lo está
countries[].payment_methods	array	Métodos habilitados para ese país. Vacío si no está disponible

Tanto rails.local como rails.card llevan la misma pareja available / reason que una fila de país.

Motivos

Motivo	Significado	Quién lo resuelve
merchant_not_verified	El comercio no ha completado su verificación. Hasta que lo haga, toda creación responde 400. Cierra todo.	El comercio
merchant_paused	La cuenta está pausada. Se pueden crear solicitudes, pero el pagador no puede completarlas. Cierra todo.	Aloha
wallet_not_configured	El comercio no tiene billetera para el rail local. Cierra todos los países locales.	Aloha
usd_account_not_enabled	El comercio no está dado de alta para cobrar en USD. Cierra US.	El comercio / Aloha
card_payments_not_enabled	El comercio no tiene cuenta de pagos con tarjeta conectada. Cierra rails.card.	El comercio
no_payment_methods_enabled	Todos los métodos de ese país están deshabilitados para este comercio.	Aloha
below_minimum_amount	El amount está por debajo del mínimo: 2 USD equivalentes para cobros locales y USD, 0,50 USD para tarjeta.	Tú
provider_unreachable	No pudimos consultar los métodos de ese país. No es un problema de configuración del comercio: reintenta en lugar de ocultar el país.	Aloha

Motivos nuevos

Con el tiempo pueden aparecer motivos nuevos. Trata un reason que no reconozcas como “no disponible” y no ramifiques tu lógica sobre cadenas que no manejas.

Notas Importantes

Caso de uso

Llama a este endpoint antes de pintar el selector de país o el resumen de métodos de pago. Es lo que evita ofrecer un país cuyo pagador no podría completar el cobro, u ocultar uno que sí podría.

USD es una fila de país

El rail USD aparece como el país US con moneda USD y un único instrumento, la transferencia bancaria ACH. Así recorres una sola lista y no necesitas un caso especial para él.

La tarjeta no es una pregunta de país

Un pago con tarjeta se emite en USD a un pagador de cualquier lugar, así que vive sólo en rails.card y no tiene fila de país. Es el rail al que recurrir cuando tu pagador no tiene ni un método local ni una cuenta bancaria en Estados Unidos.

Qué hace, y qué no hace, amount

amount aplica el mínimo de la plataforma y nada más. No aplica los límites por método que un comercio puede tener configurados, porque esos se calculan sobre el precio de una solicitud de pago concreta, que todavía no existe. En la práctica es poco frecuente, pero un método puede aparecer aquí y quedar filtrado en el checkout para ese importe.

Caché

El catálogo de métodos del proveedor se cachea una hora, por país y sólo cuando la consulta tuvo éxito: un fallo se reporta como provider_unreachable y se reintenta, nunca se publica como “este país no tiene métodos”. Las reglas del comercio se aplican después de la caché, así que un cambio de configuración se refleja de inmediato.