Recursos

Overview

Los recursos son catálogos de solo lectura: las listas de valores válidos que esperan los demás endpoints. Monedas, tipos de documento, países, bancos de PSE, tus impuestos, tus plantillas de checkout.

Consúltalos en vez de escribir los valores a mano. Si mañana agregamos un banco a PSE o un tipo de documento, tu integración lo recoge sola.

Qué es público y qué no

Los catálogos que no dependen de tu comercio son públicos: no necesitan token. Los que sí dependen de tu configuración piden tu Authorization.

Ruta Auth Qué devuelve
GET /api/v1/resources/get-countries Pública Países con indicativo e ISO
GET /api/v1/resources/get-departments Pública Departamentos con sus ciudades
GET /api/v1/resources/get-cities/{department} Pública Ciudades de un departamento
GET /api/v1/resources/identification-types-enum Pública Tipos de documento
GET /api/v1/resources/currency-enum Pública Monedas
GET /api/v1/resources/frequency-enum Pública Frecuencias de recurrencia
GET /api/v1/resources/discount-type-enum Pública Tipos de descuento
GET /api/v1/resources/checkout-type-enum Pública Tipos de checkout
GET /api/v1/resources/cash-frequencies Pública Vencimientos de pago en efectivo
GET /api/v1/resources/delivery-service-type-enum Pública Tipos de entrega
GET /api/v1/resources/mit/status-enum Pública Estados de una reserva de cupo
GET /api/v1/resources/mit/response-codes Pública Códigos de la red, con retryable y action
GET /api/v1/resources/get-status-transaction Token Estados de transacción
GET /api/v1/resources/get-taxes Token Los impuestos configurados en tu comercio
GET /api/v1/resources/available-payment-methods Token Los métodos habilitados para ti
GET /api/v1/resources/checkout/available-cash Token Redes de efectivo habilitadas
GET /api/v1/resources/checkout/pse-banks Token Bancos de PSE
GET /api/v1/resources/checkout/pse-identification-types Token Tipos de documento y de persona para PSE
GET /api/v1/resources/get-checkout-templates Token Tus plantillas de checkout

{danger} La lista de bancos de PSE no es pública. Es el error más común al leer esta página: checkout/pse-banks exige Authorization, porque depende de la configuración de tu comercio. Si la llamas sin token, recibes 401.

{warning} Todos cuelgan del host de la API (https://sag-qa.efipay.co/api/v1), el mismo del resto de los endpoints. No los consumas desde el host de QA en producción: no hay garantía de disponibilidad. Ver Autenticación y ambientes.

Moneda

GET /api/v1/resources/currency-enum

El valor que envías en currency_type es el abbreviation.

{success} Respuesta satisfactoria code: 200

[
{ "symbol": "$", "abbreviation": "COP", "name": "Peso Colombiano" },
{ "symbol": "$", "abbreviation": "USD", "name": "Dolares Estadounidenses" },
{ "symbol": "€", "abbreviation": "EUR", "name": "Euro" }
]

Frecuencia

GET /api/v1/resources/frequency-enum

{success} Respuesta satisfactoria code: 200

[
{ "value": "day", "label": "Day" },
{ "value": "week", "label": "Week" },
{ "value": "month", "label": "Month" },
{ "value": "year", "label": "Year" }
]

Tipo De Descuento

GET /api/v1/resources/discount-type-enum

{success} Respuesta satisfactoria code: 200

[
{ "value": "value", "label": "Value" },
{ "value": "percentage", "label": "Percentage" }
]

Tipo de identificación

GET /api/v1/resources/identification-types-enum

Cada tipo impone su propio formato al número de documento:

Tipo Formato del número
CC 6 a 10 dígitos
CE alfanumérico, 6 a 15 caracteres
TI 10 a 11 dígitos
PPT 7 a 15 dígitos
DNI alfanumérico, 6 a 20 caracteres
NIT 9 a 10 dígitos
Pasaporte alfanumérico, 6 a 20 caracteres
Otro texto, máximo 30 caracteres

{success} Respuesta satisfactoria code: 200

[
{ "value": "CC", "label": "Cédula de Ciudadanía" },
{ "value": "CE", "label": "Cédula de Extranjería" },
{ "value": "TI", "label": "Tarjeta de Identidad" },
{ "value": "PPT", "label": "Permiso Temporal" },
{ "value": "DNI", "label": "DNI" },
{ "value": "NIT", "label": "NIT/TAX" },
{ "value": "Pasaporte", "label": "Pasaporte" },
{ "value": "Otro", "label": "Otro" }
]

Tipo de entrega

GET /api/v1/resources/delivery-service-type-enum

Ojo: el valor que se envía va en español (Gratis, Con Valor); la etiqueta está en inglés.

{success} Respuesta satisfactoria code: 200

[
{ "value": "Gratis", "label": "Free" },
{ "value": "Con Valor", "label": "With Value" }
]

Tipo de checkout

redirect (te damos un link y rediriges) o api (capturas el pago en tu propio checkout). Es el valor de payment.checkout_type al generar un pago.

GET /api/v1/resources/checkout-type-enum

{success} Respuesta satisfactoria code: 200

[
{ "value": "redirect", "label": "Redirect" },
{ "value": "api", "label": "Api" }
]

Frecuencias de expiración en efectivo

Unidades válidas para advanced_options.cash_expired_interval, que define cuánto dura un cupón de pago en efectivo.

GET /api/v1/resources/cash-frequencies

{success} Respuesta satisfactoria code: 200

[
{ "value": "minute", "label": "Minute(s)" },
{ "value": "hour", "label": "Hour(s)" },
{ "value": "day", "label": "Day(s)" },
{ "value": "week", "label": "Week(s)" },
{ "value": "month", "label": "Month(es)" },
{ "value": "year", "label": "Year(s)" }
]

Estados de una reserva de cupo

Los estados por los que pasa una reserva de cupo, con su etiqueta.

GET /api/v1/resources/mit/status-enum

{success} Respuesta satisfactoria code: 200

[
{ "value": "Iniciada", "label": "Esperando al cliente", "color": "warning" },
{ "value": "Pre-autorizada", "label": "Cupo reservado", "color": "info" },
{ "value": "Confirmada", "label": "Cobrada", "color": "success" },
{ "value": "Anulada", "label": "Reserva liberada", "color": "muted" },
{ "value": "Vencida", "label": "Reserva vencida", "color": "muted" },
{ "value": "Rechazada", "label": "Rechazada", "color": "danger" },
{ "value": "Fallida", "label": "Fallida", "color": "danger" },
{ "value": "Indeterminada", "label": "Verificando", "color": "warning" }
]

Códigos de respuesta de reserva de cupo

Catálogo de códigos de la red con su mensaje, la acción sugerida y si tiene sentido reintentar. Consúltalo en vez de escribir los códigos a mano.

GET /api/v1/resources/mit/response-codes

{success} Respuesta satisfactoria code: 200

[
{
"code": "00",
"message": "Transacción aprobada",
"action": "Continúa con el cobro final cuando corresponda.",
"retryable": false
},
{
"code": "51",
"message": "Fondos insuficientes",
"action": "Pide otro medio de pago a tu cliente.",
"retryable": false
}
]

Lista de países

GET /api/v1/resources/get-countries

{warning} Este catálogo devuelve un objeto indexado por el código ISO2, no un arreglo. Donde la API te pida un país (customer_payer.country, customer_information.country) espera el iso3_code; donde te pida iso_code —como al crear una sucursal— espera el de dos letras.

{success} Respuesta satisfactoria code: 200

{
"CO": {
"name": "Colombia",
"dialling_code": "+57",
"iso_code": "CO",
"iso3_code": "COL",
"region": "latinAmerica"
},
"AD": {
"name": "Andorra",
"dialling_code": "+376",
"iso_code": "AD",
"iso3_code": "AND",
"region": "europe"
}
}

Lista de departamentos

GET /api/v1/resources/get-departments

{success} Respuesta satisfactoria code: 200

[
{ "id": 1, "name": "Amazonas" },
{ "id": 5, "name": "Antioquia" }
]

Lista de ciudades

GET /api/v1/resources/get-cities/{department}

El {department} de la ruta es el id de la lista de departamentos.

{success} Respuesta satisfactoria code: 200

[
{ "id": 1, "name": "Medellín", "department_id": 5 },
{ "id": 2, "name": "Envigado", "department_id": 5 }
]

Impuestos

GET /api/v1/resources/get-taxes

En payment.selected_taxes envías los id; en el campo tax de un plan envías el value.

{success} Respuesta satisfactoria code: 200

[
{ "id": 1, "name": "IVA 19%", "value": 19, "active": true },
{ "id": 2, "name": "IVA 5%", "value": 5, "active": true }
]

Metodos de pago

GET /api/v1/resources/available-payment-methods

Los medios que tu comercio tiene habilitados. Es lo que puedes listar en advanced_options.payment_methods al generar un pago.

{success} Respuesta satisfactoria code: 200

{
"credit": ["Visa", "Mastercard"],
"debit": [],
"pse": ["pse"],
"cash": ["Efecty", "Carulla"]
}

Lista efectivos

GET /api/v1/resources/checkout/available-cash

El valor que envías en cash.franchise al cobrar en efectivo es el name. min y max son los límites de monto de ese punto de recaudo.

{success} Respuesta satisfactoria code: 200

[
{
"name": "Carulla",
"logo": "/images/methods_payments/carulla.png",
"association_code": 26212,
"network": "Occidente",
"active": true,
"barcode": true,
"min": 1,
"max": 9999999
}
]

Lista bancos pse

GET /api/v1/resources/checkout/pse-banks

El valor que envías en pse.financialInstitutionCode es el financialInstitutionCode.

{warning} La lista cambia según el ambiente del token. Consúltala siempre con el mismo token con el que vas a cobrar.

{success} Respuesta satisfactoria code: 200

[
{ "financialInstitutionCode": "1022", "financialInstitutionName": "BANCO UNION COLOMBIANO" },
{ "financialInstitutionCode": "1040", "financialInstitutionName": "BANCO AGRARIO" }
]

Tipos de identificación pse

GET /api/v1/resources/checkout/pse-identification-types

pse.userType recibe el value del user_type, y pse.identificationType recibe uno de los value de ese mismo user_type. Mezclarlos hace fallar la validación.

{success} Respuesta satisfactoria code: 200

[
{
"user_type": { "name": "Natural", "value": "person" },
"identification_types": [
{ "name": "Cedula De Ciudadania", "value": "CedulaDeCiudadania" },
{ "name": "Registro Civil De Nacimiento", "value": "RegistroCivilDeNacimiento" },
{ "name": "Tarjeta De Identidad", "value": "TarjetaDeIdentidad" }
]
},
{
"user_type": { "name": "Juridica", "value": "company" },
"identification_types": [
{ "name": "NIT", "value": "NIT" }
]
}
]

Plantillas de checkout

GET /api/v1/resources/get-checkout-templates

Su id es lo que envías en payment.checkout_template_id. La plantilla decide qué campos se le piden al cliente, y por tanto cuáles de los campos del checkout dejan de ser obligatorios.

{success} Respuesta satisfactoria code: 200

[
{
"id": 3,
"name": "Checkout corto",
"active": true,
"offices": []
}
]

Estados de transacciones

GET /api/v1/resources/get-status-transaction

El campo status de una transacción trae el value, en español.

{success} Respuesta satisfactoria code: 200

[
{ "value": "Iniciada", "label": "Started", "index": 1 },
{ "value": "Pendiente", "label": "Pending", "index": 2 },
{ "value": "Aprobada", "label": "Approved", "index": 3 },
{ "value": "Rechazada", "label": "Rejected", "index": 4 },
{ "value": "Fallida", "label": "Failed", "index": 5 },
{ "value": "Por Pagar", "label": "For Pay", "index": 6 },
{ "value": "Reversada", "label": "Reversed", "index": 7 },
{ "value": "Reversion Escalada", "label": "Escaleted Reversal", "index": 8 },
{ "value": "Anulada", "label": "Cancelled", "index": 9 },
{ "value": "Autorizada", "label": "Authorized", "index": 10 }
]