Recursos

• Recursos
  • Overview
  • Moneda
  • Frecuencia
  • Tipo De Descuento
  • Tipo de identificación
  • Tipo de entrega
  • Tipo de checkout
  • Frecuencias de expiración en efectivo
  • Estados de una reserva de cupo
  • Códigos de respuesta de reserva de cupo
  • Lista de países
  • Lista de departamentos
  • Lista de ciudades
  • Impuestos
  • Metodos de pago
  • Lista efectivos
  • Lista bancos pse
  • Tipos de identificación pse
  • Plantillas de checkout
  • Estados de transacciones

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

Peligro

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.

Precaución

Todos cuelgan del host de la API (https://sag.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

GEThttps://sag.efipay.co/api/v1/resources/currency-enum

Token de acceso

ProbarCopiar como cURL

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

Consejo

Respuesta satisfactoria

200OK

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

Frecuencia

GET /api/v1/resources/frequency-enum

GEThttps://sag.efipay.co/api/v1/resources/frequency-enum

Token de acceso

ProbarCopiar como cURL

Consejo

Respuesta satisfactoria

200OK

[
    { "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

GEThttps://sag.efipay.co/api/v1/resources/discount-type-enum

Token de acceso

ProbarCopiar como cURL

Consejo

Respuesta satisfactoria

200OK

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

Tipo de identificación

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

GEThttps://sag.efipay.co/api/v1/resources/identification-types-enum

Token de acceso

ProbarCopiar como cURL

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

Consejo

Respuesta satisfactoria

200OK

[
    { "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

GEThttps://sag.efipay.co/api/v1/resources/delivery-service-type-enum

Token de acceso

ProbarCopiar como cURL

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

Consejo

Respuesta satisfactoria

200OK

[
    { "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

GEThttps://sag.efipay.co/api/v1/resources/checkout-type-enum

Token de acceso

ProbarCopiar como cURL

Consejo

Respuesta satisfactoria

200OK

[
    { "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

GEThttps://sag.efipay.co/api/v1/resources/cash-frequencies

Token de acceso

ProbarCopiar como cURL

Consejo

Respuesta satisfactoria

200OK

[
    { "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

GEThttps://sag.efipay.co/api/v1/resources/mit/status-enum

Token de acceso

ProbarCopiar como cURL

Consejo

Respuesta satisfactoria

200OK

[
    { "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

GEThttps://sag.efipay.co/api/v1/resources/mit/response-codes

Token de acceso

ProbarCopiar como cURL

Consejo

Respuesta satisfactoria

200OK

[
    {
        "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

GEThttps://sag.efipay.co/api/v1/resources/get-countries

Token de acceso

ProbarCopiar como cURL

Precaución

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.

Consejo

Respuesta satisfactoria

200OK

{
    "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

GEThttps://sag.efipay.co/api/v1/resources/get-departments

Token de acceso

ProbarCopiar como cURL

Consejo

Respuesta satisfactoria

200OK

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

Lista de ciudades

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

GEThttps://sag.efipay.co/api/v1/resources/get-cities/%7Bdepartment%7D

Token de acceso

ProbarCopiar como cURL

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

Consejo

Respuesta satisfactoria

200OK

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

Impuestos

GET /api/v1/resources/get-taxes

GEThttps://sag.efipay.co/api/v1/resources/get-taxes

Token de acceso

ProbarCopiar como cURL

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

Consejo

Respuesta satisfactoria

200OK

[
    { "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

GEThttps://sag.efipay.co/api/v1/resources/available-payment-methods

Token de acceso

ProbarCopiar como cURL

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

Consejo

Respuesta satisfactoria

200OK

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

Lista efectivos

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

GEThttps://sag.efipay.co/api/v1/resources/checkout/available-cash

Token de acceso

ProbarCopiar como cURL

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.

Consejo

Respuesta satisfactoria

200OK

[
    {
        "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

GEThttps://sag.efipay.co/api/v1/resources/checkout/pse-banks

Token de acceso

ProbarCopiar como cURL

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

Precaución

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

Consejo

Respuesta satisfactoria

200OK

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

Tipos de identificación pse

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

GEThttps://sag.efipay.co/api/v1/resources/checkout/pse-identification-types

Token de acceso

ProbarCopiar como cURL

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.

Consejo

Respuesta satisfactoria

200OK

[
    {
        "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

GEThttps://sag.efipay.co/api/v1/resources/get-checkout-templates

Token de acceso

ProbarCopiar como cURL

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.

Consejo

Respuesta satisfactoria

200OK

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

Estados de transacciones

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

GEThttps://sag.efipay.co/api/v1/resources/get-status-transaction

Token de acceso

ProbarCopiar como cURL

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

Consejo

Respuesta satisfactoria

200OK

[
    { "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 }
]