API Reference

Aprendamos cómo funciona el API. Sabemos que suele ser dolorosa esta parte, pero tranquila, estamos contigo para cualquier duda en devs@preauth.io

Ú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

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.

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.

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

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

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

Name

Type

Description

id*

String

Id de la orden

Headers

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

Name

Type

Description

x-auth-token*

String

Api token

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

Name

Type

Description

id*

String

Id de la orden

Headers

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

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

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

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

Name

Type

Description

id*

String

Id de la orden

Headers

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

Name

Type

Description

x-auth-token*

String

Api token

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

Name

Type

Description

id*

String

Id de la orden

Headers

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

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

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

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

Name

Type

Description

id*

String

Id de la orden

Headers

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

Name

Type

Description

x-auth-token*

String

Api token

Request Body

Name	Type	Description
force	Boolean	Por defecto es false

Name

Type

Description

force

Boolean

Por defecto es false

{
  "status": "OK"
}

Modelos

Order

Attributo Tipo Descripción Ejemplo

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": "example@preauth.io", "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

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

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

card_id

Integer

Referencia a tarjeta almacenada. Es posible usarla para crear una nueva orden.

1025

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.

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.

AnteriorPrimeros pasos SiguienteWidget

Última actualización hace 1 año