Multicaja logo
Documentation Powered by ReDoc

API Pagos con tarjeta (0.2)

Download OpenAPI specification:Download

Limitaciones

  • Sólo tarjetas de crédito Mastercard
  • Con cuotas emisor
  • Sin captura diferida
  • Todos los montos deben estar en pesos chilenos (ISO 4217 = CLP)
  • La API no soporta CORS
  • No está soportada la devolución ni reversa parcial.

Reglas de la API

  • El campo consumer_transaction_id debe ser único (incluso en días y transacciones distintas).
  • Todos los requerimientos deben ser realizados sobre HTTPS. Los requerimientos sobre HTTP fallarán.
  • Los campos del nodo carddeben ser encriptados utilizando el algoritmo AES-256. El procedimiento para compartir la llave se acordará en otro documento.
  • Todos los requerimientos son autenticados. Debe incluir el encabezado Api-Key: <key>.

Idempotencia

La API soporta idempotencia, por lo tanto puedes reintentar un requerimiento sin peligro de que el recurso se cree dos veces. Para esto debes incluir el encabezado Idempotency-Key: <key>, donde key es un identificador único de tu sistema o UUID. La clave tiene una validez de 24 horas.

  • NOTA: Si envías dos requerimientos con igual consumer_transaction_id y distinto Idempotency-Key, se entendrán como dos requerimientos diferentes y uno de ellos fallará dado que el campo consumer_transaction_id debe ser único.

Gestión de llaves

Los campos del nodo card se deben enviar encriptados por una llave simétrica utilizando el algoritmo AES-256. Para establecer la llave simétrica, el comsumidor de la API debe generar y enviar a Multicaja un componente de la llave con sus respectivos dígitos de chequeo. Multicaja generará y enviará otro componenente. Luego, ambos actores deberán cargar los componentes en sus HSMs, generando la llave final y verificando que los digitos de chequeo coincidan. Esta llave debe ser cambiada cada 3 años.

Venta con tarjeta

Realiza un cargo en una tarjeta de crédito.

Request Body schema: application/json

Venta con tarjeta

card
required
string

Datos de tarjeta encriptados

additional_data
required
object (addtitional_data)

Objeto JSON con atributos adicionales para la transacción.

consumer_transaction_id
required
string

Identificador único de la transacción generado por el consumidor de la API

amount
required
object (amount_and_currency)

Monto en una moneda específica

installments
required
integer

cantidad de cuotas (cuotas emisor)

charge_type
required
object (charge_type)

Tipo de cargo que se realiza. Indica si el pago es recurrente o no y si los datos de la tarjeta fueron digitados por el tarjetahabiente o es card on file.

merchant
required
object (merchant)

Datos del comercio que origina el cargo

Responses

200

OK - Venta exitosa

400

Alguno de los campos requeridos no viene o es inválido

401

API Key no autorizada

402

Transacción se intentó, pero falló.

500

Error indeterminado, se lanza cuando ocurre un error imprevisto de sistema

post /charges
https://api.multicaja.cl/card-payments/v0.2/charges

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "card": "mOoT6vkSI7z0ahhF7kN32cXAshL26UYHw0yzEef0KnFDbhtQRv6b1hoMkmdOCQsg",
  • "additional_data": { },
  • "consumer_transaction_id": "crlfUYEBK14zotCTykezJkfg",
  • "amount":
    {
    },
  • "installments": null,
  • "charge_type":
    {
    },
  • "merchant":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "amount":
    {
    },
  • "consumer_transaction_id": "crlfUYEBK14zotCTykezJkfg",
  • "external_authorization_code": 1231232,
  • "id": 7783834,
  • "timestamps":
    {
    }
}

Consulta de un cargo

Obtiene el objeto cargo

query Parameters
consumer_transaction_id
required
string

Consulta de un cargo dado el consumer_transaction_id

Responses

200

OK - Venta exitosa

400

Alguno de los campos requeridos no viene o es inválido

401

API Key no autorizada

404

El recurso requerido no existe.

500

Error indeterminado, se lanza cuando ocurre un error imprevisto de sistema

get /charges
https://api.multicaja.cl/card-payments/v0.2/charges

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "amount":
    {
    },
  • "consumer_transaction_id": "crlfUYEBK14zotCTykezJkfg",
  • "external_authorization_code": 1231232,
  • "id": 7783834,
  • "timestamps":
    {
    },
  • "status": "refunded",
  • "failure_code": null,
  • "failure_message": null,
  • "amount_refunded":
    {
    },
  • "refunds":
    [
    ],
  • "installments": null,
  • "charge_type":
    {
    },
  • "merchant":
    {
    }
}

Reversa de una venta

Reversa en línea de una venta

Request Body schema: application/json

Reversa de venta con tarjeta

consumer_transaction_id
required
string

Identificador único de la transacción que se quiere reversar.

merchant
required
object (merchant_base)

Datos del comercio que origina el cargo

Responses

200

OK - Reversa exitosa

400

Error en parámetros, se lanza a cuando un parámetro es requerido y no se ha enviado

401

API Key no autorizada

500

Error indeterminado, se lanza cuando ocurre un error imprevisto de sistema

post /charges/reversal
https://api.multicaja.cl/card-payments/v0.2/charges/reversal

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "consumer_transaction_id": "crlfUYEBK14zotCTykezJkfg",
  • "merchant":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "consumer_transaction_id": "crlfUYEBK14zotCTykezJkfg",
  • "id": 7783834,
  • "status": "approved",
  • "timestamps":
    {
    }
}

Consulta de un cargo (NOT IMPLEMENTED)

Obtiene el objeto cargo

path Parameters
id
required
integer

Consulta de un cargo

Responses

200

OK - Venta exitosa

400

Alguno de los campos requeridos no viene o es inválido

401

API Key no autorizada

404

El recurso requerido no existe.

500

Error indeterminado, se lanza cuando ocurre un error imprevisto de sistema

get /charges/{id}
https://api.multicaja.cl/card-payments/v0.2/charges/{id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "amount":
    {
    },
  • "consumer_transaction_id": "crlfUYEBK14zotCTykezJkfg",
  • "external_authorization_code": 1231232,
  • "id": 7783834,
  • "timestamps":
    {
    },
  • "status": "refunded",
  • "failure_code": null,
  • "failure_message": null,
  • "amount_refunded":
    {
    },
  • "refunds":
    [
    ],
  • "installments": null,
  • "charge_type":
    {
    },
  • "merchant":
    {
    }
}

Devolución de un cargo realizado a una tarjeta (NOT IMPLEMENTED)

Devuelve total o parcialmante un cargo realizado a una tarjeta de crédito.

Devolución total

  • El objeto amount es opcional. En caso que se envíe, el campo value debe corresponder al monto total del cargo.

Devolución parcial

  • El objeto amount corresponde al monto que se quiere devolver. Debe ser mayor que cero y menor o igual al monto no devuelto de la venta.
  • Puedes realizar hasta 10 devoluciones parciales asociadas a la misma venta.
Request Body schema: application/json

Devolución de cargo

consumer_transaction_id
required
string

Identificador único de la transacción generado por el consumidor de la API

original_consumer_transaction_id
required
string

Identificador de la venta original, sobre la que se realizará la devolución.

amount
required
object (amount_and_currency)

Monto en una moneda específica

additional_data
required
object (addtitional_data)

Objeto JSON con atributos adicionales para la transacción.

merchant
required
object (merchant_base)

Datos del comercio que origina el cargo

Responses

200

OK - devolución exitosa

400

Error en parámetros, se lanza a cuando un parámetro es requerido y no se ha enviado

401

API Key no autorizada

500

Error indeterminado, se lanza cuando ocurre un error imprevisto de sistema

post /refunds
https://api.multicaja.cl/card-payments/v0.2/refunds

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "consumer_transaction_id": "xhGXSPKviU83lln_xc9lc",
  • "original_consumer_transaction_id": "crlfUYEBK14zotCTykezJkfg",
  • "amount":
    {
    },
  • "additional_data": { },
  • "merchant":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "consumer_transaction_id": "xhGXSPKviU83lln_xc9lc",
  • "amount":
    {
    },
  • "id": 7654320,
  • "external_authorization_code": 1231232,
  • "timestamps":
    {
    }
}

Consulta de una devolución (NOT IMPLEMENTED)

Obtiene el objeto devolución

query Parameters
consumer_transaction_id
required
string

Consulta de una devolución dado el consumer_transaction_id

Responses

200

OK

400

Alguno de los campos requeridos no viene o es inválido

401

API Key no autorizada

404

El recurso requerido no existe.

500

Error indeterminado, se lanza cuando ocurre un error imprevisto de sistema

get /refunds
https://api.multicaja.cl/card-payments/v0.2/refunds

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "consumer_transaction_id": "xhGXSPKviU83lln_xc9lc",
  • "amount":
    {
    },
  • "id": 7654320,
  • "external_authorization_code": 1231232,
  • "timestamps":
    {
    }
}

Reversa de una devolución (NOT IMPLEMENTED)

Reversa en línea de una devolución

Request Body schema: application/json

Reversa de devolución

consumer_transaction_id
required
string

Identificador único de la transacción que se quiere reversar.

merchant
required
object (merchant_base)

Datos del comercio que origina el cargo

Responses

200

OK - Reversa exitosa

400

Error en parámetros, se lanza a cuando un parámetro es requerido y no se ha enviado

401

API Key no autorizada

500

Error indeterminado, se lanza cuando ocurre un error imprevisto de sistema

post /refunds/reversal
https://api.multicaja.cl/card-payments/v0.2/refunds/reversal

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "consumer_transaction_id": "crlfUYEBK14zotCTykezJkfg",
  • "merchant":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "consumer_transaction_id": "crlfUYEBK14zotCTykezJkfg",
  • "id": 7783834,
  • "status": "approved",
  • "timestamps":
    {
    }
}

Consulta de una devolución (NOT IMPLEMENTED)

Obtiene el objeto cargo

path Parameters
id
required
integer

Consulta de una devolución

Responses

200

OK

400

Alguno de los campos requeridos no viene o es inválido

401

API Key no autorizada

404

El recurso requerido no existe.

500

Error indeterminado, se lanza cuando ocurre un error imprevisto de sistema

get /refunds/{id}
https://api.multicaja.cl/card-payments/v0.2/refunds/{id}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "consumer_transaction_id": "xhGXSPKviU83lln_xc9lc",
  • "amount":
    {
    },
  • "id": 7654320,
  • "external_authorization_code": 1231232,
  • "timestamps":
    {
    }
}

Devolución batch de un cargo realizado a una tarjeta

Devuelve total o parcialmante un cargo realizado a una tarjeta de crédito.

Devolución total

  • El objeto amount es opcional. En caso que se envíe, el campo value debe corresponder al monto total del cargo.

Devolución parcial (NOT IMPLEMENTED)

  • El objeto amount corresponde al monto que se quiere devolver. Debe ser mayor que cero y menor o igual al monto no devuelto de la venta.
  • Puedes realizar hasta 10 devoluciones parciales asociadas a la misma venta.
Request Body schema: application/json

Devolución de cargo

consumer_transaction_id
required
string

Identificador único de la transacción generado por el consumidor de la API

original_consumer_transaction_id
required
string

Identificador de la venta original, sobre la que se realizará la devolución.

amount
required
object (amount_and_currency)

Monto en una moneda específica

additional_data
required
object (addtitional_data)

Objeto JSON con atributos adicionales para la transacción.

merchant
required
object (merchant_base)

Datos del comercio que origina el cargo

Responses

200

OK - devolución exitosa

400

Error en parámetros, se lanza a cuando un parámetro es requerido y no se ha enviado

401

API Key no autorizada

500

Error indeterminado, se lanza cuando ocurre un error imprevisto de sistema

post /batch-refund
https://api.multicaja.cl/card-payments/v0.2/batch-refund

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "consumer_transaction_id": "xhGXSPKviU83lln_xc9lc",
  • "original_consumer_transaction_id": "crlfUYEBK14zotCTykezJkfg",
  • "amount":
    {
    },
  • "additional_data": { },
  • "merchant":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "consumer_transaction_id": "xhGXSPKviU83lln_xc9lc",
  • "status": "pending",
  • "id": 7654320,
  • "external_authorization_code": 1231232,
  • "timestamps":
    {
    }
}

Reversa de una devolución batch

Reversa de una devolución

Request Body schema: application/json

Reversa de devolución

consumer_transaction_id
required
string

Identificador único de la transacción que se quiere reversar.

merchant
required
object (merchant_base)

Datos del comercio que origina el cargo

amount
required
object (amount_and_currency)

Monto en una moneda específica

Responses

200

OK - Reversa exitosa

400

Error en parámetros, se lanza a cuando un parámetro es requerido y no se ha enviado

401

API Key no autorizada

500

Error indeterminado, se lanza cuando ocurre un error imprevisto de sistema

post /batch-refund/reversal
https://api.multicaja.cl/card-payments/v0.2/batch-refund/reversal

Request samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "consumer_transaction_id": "crlfUYEBK14zotCTykezJkfg",
  • "merchant":
    {
    },
  • "amount":
    {
    }
}

Response samples

Content type
application/json
Copy
 Expand all Collapse all
{
  • "consumer_transaction_id": "crlfUYEBK14zotCTykezJkfg",
  • "id": 7783834,
  • "status": "approved",
  • "timestamps":
    {
    },
  • "external_authorization_code": 1231232
}