Creación de sesión de pago

Request #

Método: POST
Endpoint: /v1/session/init

La guía define este endpoint para crear la sesión que inicia el flujo de pago.

Headers

Content-Type: application/json
Accept: application/json
Authorization: Bearer <accessToken>

Body

Campo	Tipo	Obligatorio	Descripción
products	array	Sí	Lista de productos de la compra. Debe contener al menos un elemento.
products[].brand	string	Sí	Marca del producto; longitud máxima de 255 caracteres.
products[].model	string	Sí	Modelo del producto; longitud máxima de 255 caracteres.
products[].price	number	Sí	Precio unitario del producto. Debe ser mayor o igual a 0.
customer_document	number	Sí	Número de documento de identidad del cliente (valor numérico ≥ 1).
firstname	string	Sí	Nombre del cliente; longitud máxima de 255 caracteres.
lastname	string	Sí	Apellido del cliente; longitud máxima de 255 caracteres.
external_order_id	string	Sí	Identificador único del pedido generado por el Ecommerce; máximo 255 caracteres.
callback_url	string	Sí	URL con protocolo HTTPS a la cual será redirigido el usuario al finalizar o salir del flujo; máximo 512 caracteres.
currency	string	Sí	Código de la moneda de la transacción; longitud máxima de 16 caracteres.
birthdate	string	Sí	Fecha de nacimiento del cliente en formato de fecha válido (ej. DD-MM-AAAA).

Body ejemplo

{
  "products": [
    {
      "brand": "Samsung",
      "model": "A56",
      "price": 655000
    }
  ],
  "customer_document": 79975843,
  "firstname": "CARLOS ALBERTO",
  "lastname": "PEREZ GONZALEZ",
  "external_order_id": "TEST-000006",
  "currency": "COP",
  "birthdate": "10-05-1990",
  "callback_url": "https://www.google.com/"
}

Respuesta

Campo	Tipo	Descripción
success	boolean	Indica que la petición fue procesada correctamente. Valor fijo: true.
code	number	Código de estado de la respuesta. Valor fijo: 200.
message	string	Mensaje descriptivo de la operación. Ejemplo: Session initialized.
data	object	Objeto contenedor que incluye los detalles específicos de la sesión.

Datos de la sesión

Campo	Tipo	Descripción
session_token	string	Token opaco que identifica de forma única la sesión de flujo creada.
start_url	string	URL del frontend de CrediSmart que incluye el session_token como parámetro de consulta para iniciar la experiencia del usuario.
expires_at	string	Fecha y hora de expiración de la sesión en formato ISO 8601. Una vez cumplida, el token dejará de ser válido.
partner_tx_id	string	Identificador de correlación único para la transacción.

Respuesta ejemplo

{
  "success": true,
  "code": 200,
  "message": "Session initialized",
  "data": {
    "session_token": "UTMFlsaFda9Fa5bx2Pwvw3pXvz7WyxtYmHJxwC52LFmwIRQxoVCEDqlKCeX5egDk",
    "start_url": "?session_token=UTMFlsaFda9Fa5bx2Pwvw3pXvz7WyxtYmHJxwC52LFmwIRQxoVCEDqlKCeX5egDk",
    "expires_at": "2026-04-23T20:55:45-05:00",
    "partner_tx_id": "TEST-000006"
  }
}

Respuesta con error

{
  "success": false,
  "message": "El campo es obligatorio.",
  "code": 422
}

Códigos de error esperados

HTTP	Mensaje de referencia	Data	Notas
422	La sesión no contiene external_order_id en los datos de la orden.	—	Inconsistencia de datos internos.
409	La solicitud de esta sesión ya finalizó o fue cancelada. Inicie una nueva sesión.	status, credismart_transaction_status	Estado terminal o sesión cerrada.

Ejemplo de petición

curl --location '<URL POR DEFINIR>/v1/session/init' \
--header 'Authorization: Bearer <AccessToken>' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
  "products": [
    {
      "brand": "Samsung",
      "model": "A56",
      "price": 655000
    }
  ],
  "customer_document": 79975843,
  "firstname": "CARLOS ALBERTO",
  "lastname": "PEREZ GONZALEZ",
  "external_order_id": "TEST-000006",
  "currency": "COP",
  "birthdate": "10-05-1990",
  "callback_url": "https://www.google.com/"
}'