API Reference

Aprendamos cómo funciona el API. Sabemos que suele ser dolorosa esta parte, pero tranquila, estamos contigo para cualquier duda en [email protected]

Únete a nuestro espacio de Slack y te ayudaremos con tus dudas

Autenticación

Para tener acceso a los servicios es necesario haber obtenido el api-token para ser usado como cabecera en cada petición. Para más información, puedes revisar como obtener el api-token en la guía de Primeros pasos.

Cuando obtengas tu api-token, es necesario que lo envíes en la cabecera "x-auth-token" en cada petición que quieras hacer.

Servicios

Crear orden

POST https://api.preauth.io/v1/order

Servicio para crear una orden, con el id de la orden luego podrás realizar la retención utilizando el Widget

Headers

Name	Type	Description
x-auth-token*	String	Api token

Request Body

Name	Type	Description
country*	String	ISO 3166-1 alpha-2 (Ej: PE, CL, MX)
currency*	String	ISO 4217 (Ej: PEN, CLP, MXN)
amount*	Integer	Monto en la mínima denominación. Ejemplo: Dólares en centavos (para US$100, enviar 100000) y pesos chilenos en entero (para CLP$100, enviar 100)
reference*	String	Referencia del comercio
limit_date*	String	Fecha límite de la orden (YYYY-mm-dd)
meta.client.phone	String	Formato E.123
meta.client.documentType	String	Tipo de documento
meta.client.document	String	Alfanumérico del documento
meta.client.email	String	RFC 5322
meta.product.title	String	Nombre del producto/servicio
meta.billing.address	String	Dirección del cliente
meta.billing.city	String	Ciudad del cliente
meta.billing.region	String	Región del cliente
meta.billing.country	String	País del cliente
meta.client.name	Stng	Nombre del cliente
card_id	Integer	Id de tarjeta previamente almacenada (asociada a otra orden). Puede hacer que el servicio dure más debido a que intenta generar una preautorización.

200: OK Modelo Order

{
  "id": "4085-whOdSyS2FkGmm4j9feJNeMh0SjQDgLa5xAUENBkajsfQK",
  "reference": "order_00001",
  "currency": "PEN",
  "country": "PE",
  "limit_date": "2022-10-10",
  "amount": 15000,
  "status": "created",
  "pending_amount": 15000,
  "captured_amount": 0,
  "meta": {},
  "card_id": null,
  "created_at": "2021-10-15 20:31:07",
  "updated_at": "2021-10-15 20:35:28"
}

200: OK Modelo Order con card_id

Obtener orden

GET https://api.preauth.io/v1/order/{id}

Obtienes el objeto orden actualizado. Importante utilizarlo luego de recibir la confirmación de que se realizó la retención para verificar que la orden se encuentra en in_progress

Query Parameters

Name	Type	Description
id*	String	Id de la orden

Headers

Name	Type	Description
x-auth-token*	String	Api token

200: OK Modelo Order

{
  "id": "4085-whOdSyS2FkGmm4j9feJNeMh0SjQDgLa5xAUENBkajsfQK",
  "reference": "order_00001",
  "currency": "PEN",
  "country": "PE",
  "limit_date": "2022-10-10",
  "amount": 15000,
  "status": "in_progress",
  "pending_amount": 15000,
  "captured_amount": 0,
  "meta": {},
  "card_id": 1025,
  "created_at": "2021-10-15 20:31:07",
  "updated_at": "2021-10-15 20:35:28"
}

Actualizar orden

PATCH https://api.preauth.io/v1/order/{id}

Modifica el monto o la fecha límite de una orden creada. Solo cuando esté en created o in_progress

Query Parameters

Name	Type	Description
id*	String	Id de la orden

Headers

Name	Type	Description
x-auth-token*	String	Api token

Request Body

Name	Type	Description
amount*	Integer	Monto en centavos, solo puede ser menor a order.pending_amount
limit_date*	String	Fecha límite de la orden, se puede editar según la fecha de expiración de la tarjeta asociada

200: OK

{
  "status": "OK"
}

Cancelar orden

DELETE https://api.preauth.io/v1/order/{id}

Devolverá el dinero retenido y la orden cambiará de estado a canceled.

¡Importante!, una vez cancelada una orden no puede cambiar a otro estado, tendrás que crear una nueva orden desde cero.

Query Parameters

Name	Type	Description
id*	String	Id de la orden

Headers

Name	Type	Description
x-auth-token*	String	Api token

200: OK

{
  "status": "OK"
}

Capturar orden

POST https://api.preauth.io/v1/order/{id}/capture

Cobra todo o parte del dinero retenido, adicionalmente nos indicas si el monto sobrante quieres seguir reteniéndolo o lo liberarás. Ej: si tienes reservado $1000 y cobras $100, ¿qué quieres hacer con los $900 sobrantes? puedes seguir bloqueándolos o liberarlos, dependiendo del caso de uso que tengas.

Query Parameters

Name	Type	Description
id*	String	Id de la orden

Headers

Name	Type	Description
x-auth-token*	String	Api token

Request Body

Name	Type	Description
amount*	Integer	Monto en centavos, solo puede ser menor o igual a order.pending_amount
keep_alive*	Boolean	Flag para preautorizar el monto restante

200: OK

{
  "status": "OK"
}

Hacer prueba de vida

POST https://api.preauth.io/v1/order/{id}/liveness

Realiza una prueba de vida a la tarjeta asociada a la orden. Esto te sirve para saber si la tarjeta está activa en el momento y poder tomar acción en caso no se encuentre activa.

Solo se puede hacer una prueba de vida por día. Si se requiere hacer más de una prueba de vida es necesario enviar el parámetro "force" en true.

Query Parameters

Name	Type	Description
id*	String	Id de la orden

Headers

Name	Type	Description
x-auth-token*	String	Api token

Request Body

Name	Type	Description
force	Boolean	Por defecto es false

200: OK

{
  "status": "OK"
}

Modelos

Order

Attributo	Tipo	Descripción	Ejemplo
id	Text	Identificador de la orden	4085-whOdSyS2FkGmm4j9feJNeMh0SjQDgLa5xAUENBkajsfQK
reference	Text	Referencia del comercio	order_0001
currency	Text	ISO 4217	PEN
country	Text	ISO 3166-1 alpha-2	PE
limit_date	Text	Fecha límite, pasada esta fecha se liberará el valor del pending_amount	2022-10-10
amount	Integer	Monto en centavos	15000
status	OrderStatus	Ver OrderStatus	created
pending_amount	Integer	Monto en centavos de lo que debe mantenerse preautorizado	15000
capture_amount	Integer	Monto en centavos de lo que se ha ido capturando	0
card_id	Integer	Referencia a tarjeta almacenada. Es posible usarla para crear una nueva orden.	1025
meta	Object	Parámetro en donde se puede enviar data adicional.	{ "email": "[email protected]", "name": "Pedro" }
created_at	Text	Fecha de creación de la orden	2021-10-15 20:31:07
update_at	Text	Última fecha de actualización de la orden	2021-10-15 20:35:28

OrderStatus

Attributo	Descripción
created	Cuando la orden ha sido creada y aún no tiene un medio de pago asociado.
in_progress	Cuando la orden ya cuenta con una tarjeta asociada.
canceled	Cuando el comercio solicitó la cancelación.
finished	Cuando la fecha límite ya pasó.
desynchronized	Cuando la tarjeta asociada a la orden no puede ser preautorizada nuevamente.