Referencia de la API REST
Te invitamos a revisar los métodos y modelos que puedes utilizar en tu implementación
Para la API 2.0 todos los métodos siguientes utilizan como base la url: https://khipu.com/api/2.0/
Métodos de Referencia
1 - GET / banks
Esta llamada de la API consume los siguientes tipos de media usando el encabezado Content-Type:
application/x-www-form-urlencodedEsta llamada de la API produce los siguientes tipos de media usando el encabezado Accept; el tipo será convertido usando el encabezado Content-Type.
application/json
200: Éxito
400: Datos inválidos
403: Error de autorización
503: Error de operación2 - GET / payments
Esta llamada de la API consume los siguientes tipos de media usando el encabezado Content-Type:
application/x-www-form-urlencodedEsta llamada de la API produce los siguientes tipos de media usando el encabezado Accept; el tipo será convertido usando el encabezado Content-Type.
application/json200: Éxito
400: Datos inválidos
403: Error de autorización
503: Error de operación3 - POST / payments
Crea un pago en Khipu y obtiene las URLs para redirección al usuario para que complete el pago.
Esta llamada de la API consume los siguientes tipos de media usando el encabezado Content-Type:
application/x-www-form-urlencodedsubject (requerido): Motivo. Este campo tiene un largo máximo de 255 caracteres.
currency (requerido): El código de moneda en formato ISO-4217. Este campo tiene un largo máximo de 255 caracteres.
amount (requerido): El monto del cobro. Sin separador de miles y usando ‘.’ como separador de decimales. Hasta 4 lugares decimales, dependiendo de la moneda. Este campo tiene un largo máximo de 16 caracteres.
transaction_id (opcional): Identificador propio de la transacción. Ej: número de factura u orden de compra. Este campo tiene un largo máximo de 255 caracteres.
custom (opcional): Parámetro para enviar información personalizada de la transacción. Ej: documento XML con el detalle del carro de compra. Este campo tiene un largo máximo de 1.073.741.824 caracteres.
body (opcional): Descripción del cobro. Este campo tiene un largo máximo de 5.120 caracteres.
bank_id (opcional): Identificador del banco para usar en el pago. Este campo tiene un largo máximo de 5 caracteres.
return_url (opcional): La dirección URL a donde enviar al cliente mientras el pago está siendo verificado. Este campo tiene un largo máximo de 1.024 caracteres.
cancel_url (opcional): La dirección URL a donde enviar al cliente si decide no hacer hacer la transacción. Este campo tiene un largo máximo de 1.024 caracteres.
picture_url (opcional): Una dirección URL de una foto de tu producto o servicio. Este campo tiene un largo máximo de 1.024 caracteres.
notify_url (opcional): La dirección del web-service que utilizará khipu para notificar cuando el pago esté conciliado. Este campo tiene un largo máximo de 1.024 caracteres.
contract_url (opcional): La dirección URL del archivo PDF con el contrato a firmar mediante este pago. El cobrador debe estar habilitado para este servicio y el campo ‘fixed_payer_personal_identifier’ es obligatorio. Este campo tiene un largo máximo de 1.024 caracteres.
notify_api_version (opcional): Versión de la API de notifiaciones para recibir avisos por web-service. Este campo tiene un largo máximo de 255 caracteres.
expires_date (opcional): Fecha máxima para ejecutar el pago (en formato ISO-8601). El cliente podrá realizar varios intentos de pago hasta dicha fecha. Cada intento tiene un plazo individual de 3 horas para su ejecución
send_email (opcional): Si es ‘true’, se enviará una solicitud de cobro al correo especificado en ‘payer_email’. Este campo tiene un largo máximo de 5 caracteres.
payer_name (opcional): Nombre del pagador. Es obligatorio cuando send_email es ‘true’. Este campo tiene un largo máximo de 255 caracteres.
payer_email (opcional): Correo del pagador. Es obligatorio cuando send_email es ‘true’. Este campo tiene un largo máximo de 255 caracteres.
send_reminders (opcional): Si es ‘true’, se enviarán recordatorios de cobro. Este campo tiene un largo máximo de 5 caracteres.
responsible_user_email (opcional): Correo electrónico del responsable de este cobro, debe corresponder a un usuario khipu con permisos para cobrar usando esta cuenta de cobro. Este campo tiene un largo máximo de 255 caracteres.
fixed_payer_personal_identifier (opcional): Identificador personal. Si se especifica, solo podrá ser pagado usando ese identificador. Este campo tiene un largo máximo de 255 caracteres.
integrator_fee (opcional): Comisión para el integrador. Sólo es válido si la cuenta de cobro tiene una cuenta de integrador asociada. Este campo tiene un largo máximo de 16 caracteres.
collect_account_uuid (opcional): Para cuentas de cobro con más cuenta propia. Permite elegir la cuenta donde debe ocurrir la transferencia. Este campo tiene un largo máximo de 255 caracteres.
confirm_timeout_date (opcional): Fecha de rendición del cobro. Es también la fecha final para poder reembolsar el cobro. Formato ISO-8601. Ej: 2017-03-01T13:00:00Z. Este campo tiene un largo máximo de 22 caracteres.
mandatory_payment_method (opcional): El cobro sólo se podrá pagar utilizando el medio de pago especificado. Los posibles valores para este campo se encuentran en el campo id de la respuesta del endpoint Consulta medios de pago disponibles. Este campo tiene un largo máximo de 255 caracteres.
Esta llamada de la API produce los siguientes tipos de media usando el encabezado Accept; el tipo será convertido usando el encabezado Content-Type.
application/json200: Éxito
400: Datos inválidos
403: Error de autorización
503: Error de operación4 - GET / payments / {id}
Información completa del pago. Datos con los que fue creado y el estado actual del pago.
Esta llamada de la API consume los siguientes tipos de media usando el encabezado Content-Type:
application/x-www-form-urlencodedEsta llamada de la API produce los siguientes tipos de media usando el encabezado Accept; el tipo será convertido usando el encabezado Content-Type.
application/json200: Éxito
400: Datos inválidos
403: Error de autorización
503: Error de operación5 - DELETE / payments / {id}
Esta llamada de la API consume los siguientes tipos de media usando el encabezado Content-Type:
application/x-www-form-urlencodedEsta llamada de la API produce los siguientes tipos de media usando el encabezado Accept; el tipo será convertido usando el encabezado Content-Type.
application/json200: Éxito
400: Datos inválidos
403: Error de autorización
503: Error de operación6 - POST / payments / {id} / confirm
Esta llamada de la API consume los siguientes tipos de media usando el encabezado Content-Type:
application/x-www-form-urlencodedEsta llamada de la API produce los siguientes tipos de media usando el encabezado Accept; el tipo será convertido usando el encabezado Content-Type.
application/json200: Éxito
400: Datos inválidos
403: Error de autorización
503: Error de operación7 - POST / payments / {id} / refunds
Esta llamada de la API consume los siguientes tipos de media usando el encabezado Content-Type:
application/x-www-form-urlencodedEsta llamada de la API produce los siguientes tipos de media usando el encabezado Accept; el tipo será convertido usando el encabezado Content-Type.
application/json200: Éxito
400: Datos inválidos
403: Error de autorización
503: Error de operación8 - POST / receivers
Esta llamada de la API consume los siguientes tipos de media usando el encabezado Content-Type:
application/x-www-form-urlencodedEsta llamada de la API produce los siguientes tipos de media usando el encabezado Accept; el tipo será convertido usando el encabezado Content-Type.
application/json200: Éxito
400: Datos inválidos
403: Error de autorización
503: Error de operación9 - GET / merchants / {id} / paymentMethods
Esta llamada de la API consume los siguientes tipos de media usando el encabezado Content-Type:
application/x-www-form-urlencodedEsta llamada de la API produce los siguientes tipos de media usando el encabezado Accept; el tipo será convertido usando el encabezado Content-Type.
application/json200: Éxito
400: Datos inválidos
403: Error de autorización
503: Error de operaciónModelos de Referencia
10 - Payments Response
payment_id: (String) Identificador único del pago, es una cadena alfanumérica de 12 caracteres. Cómo este identificador es único, se puede usar, por ejemplo, para evitar procesar una notificación repetida. (Khipu espera un código 200 al notificar un pago, si esto no ocurre se reintenta hasta por dos días)
payment_url: (String) URL principal del pago, si el usuario no ha elegido previamente un método de pago se le muestran las opciones
simplified_transfer_url: (String) URL de pago simplificado
transfer_url: (String) URL de pago normal
app_url: (String) URL para invocar el pago desde un dispositivo móvil usando la APP de Khipu
ready_for_terminal: (Boolean) Es ‘true’ si el pago ya cuenta con todos los datos necesarios para abrir directamente la aplicación de pagos Khipu
notification_token: (String) Cadena de caracteres alfanuméricos que identifican unicamente al pago, es el identificador que el servidor de Khipu enviará al servidor del comercio cuando notifique que un pago está conciliado
receiver_id: (Long) Identificador único de una cuenta de cobro
conciliation_date: (Date) Fecha y hora de conciliación del pago. Formato ISO-8601. Ej: 2017-03-01T13:00:00Z
subject: (String) Motivo del pago
amount: (Double)
currency: (String) El código de moneda en formato ISO-4217
status: (String) Estado del pago, puede ser ‘pending’ (el pagador aún no comienza a pagar), ‘verifying’ (se está verificando el pago) o ‘done’, cuando el pago ya está confirmado
status_detail: (String) Detalle del estado del pago, ‘pending’ (el pagador aún no comienza a pagar), ‘normal’ (el pago fue verificado y fue cancelado por algún medio de pago estándar), ‘marked-paid-by-receiver’ (el cobrador marco el cobro como pagado por otro medio), ‘rejected-by-payer’ (el pagador declaró que no pagará), ‘marked-as-abuse’ (el pagador declaró que no pagará y que el cobro fue no solicitado) y ‘reversed’ (el pago fue anulado por el comercio, el dinero fue devuelto al pagador).
body: (String) Detalle del cobro
picture_url: (String) URL de cobro
receipt_url: (String) URL del comprobante de pago
return_url: (String) URL donde se redirige al pagador luego que termina el pago
cancel_url: (String) URL donde se redirige al pagador luego de que desiste hacer el pago
notify_url: (String) URL del webservice donde se notificará el pago
notify_api_version: (String) Versión de la api de notificación
expires_date: (Date) Fecha máxima para ejecutar el pago (en formato ISO-8601). El cliente podrá realizar varios intentos de pago hasta dicha fecha. Cada intento tiene un plazo individual de 3 horas para su ejecución
attachment_urls: (array[String]) URLs de archivos adjuntos al pago
bank: (String) Nombre del banco seleccionado por el pagador
bank_id: (String) Identificador del banco seleccionado por el pagador
payer_name: (String) Nombre del pagador
payer_email: (String) Correo electrónico del pagador
personal_identifier: (String) Identificador personal del pagador
bank_account_number: (String) Número de cuenta bancaria del pagador
out_of_date_conciliation: (Boolean) Es ‘true’ si la conciliación del pago fue hecha luego de la fecha de expiración
transaction_id: (String) Identificador del pago asignado por el cobrador
custom: (String máximo 4096 caracteres) Campo genérico que asigna el cobrador al momento de hacer el pago
responsible_user_email: (String) Correo electrónico de la persona responsable del pago
send_reminders: (Boolean) Es ‘true’ cuando este es un cobro por correo electrónico y Khipu enviará recordatorios
send_email: (Boolean) Es ‘true’ cuando Khipu enviará el cobro por correo electrónico
payment_method: (String) Método de pago usado por el pagador, puede ser ‘regular_transfer’ (transferencia normal), ‘simplified_transfer’ (transferencia simplificada).
funds_source: (String) Origen de fondos usado por el pagador, puede ser ‘debit’ para pago con débito, ‘prepaid’ para pago con prepago, ‘credit’ para pago con crédito o vacío en el caso de que se haya pagado mediante transferencia bancaria.
11 - Payments Create Response
payment_id: (String) Identificador único del pago, es una cadena alfanumérica de 12 caracteres. Cómo este identificador es único, se puede usar, por ejemplo, para evitar procesar una notificación repetida. (Khipu espera un código 200 al notificar un pago, si esto no ocurre se reintenta hasta por dos días)
payment_url: (String) URL principal del pago, si el usuario no ha elegido previamente un método de pago se le muestran las opciones
simplified_transfer_url: (String) URL de pago simplificado
transfer_url: (String) URL de pago normal
app_url: (String) URL para invocar el pago desde un dispositivo móvil usando la APP de Khipu
ready_for_terminal: (Boolean) Es ‘true’ si el pago ya cuenta con todos los datos necesarios para abrir directamente la aplicación de pagos Khip
12 - Receivers Create Response
secret: (String) Llave secreta de la cuenta de cobro, se usa para firmar todas las peticiones
13 - Banks Response
14 - Bank Item
name: (String) Nombre del banco
message: (String) Mensaje con particularidades del banco
min_amount: (Double) Monto mínimo que acepta el banco en un pago
type: (String) Tipo de banco
parent: (String) Identificador del banco padre (si un banco tiene banca personas y empresas, el primero será el padre del segundo)
15 - Payment Methods Response
16 - Payment Method Item
name: (String) Nombre del medio de pago
logo_url: (String) URL del logo sugerido para mostrar
17 - Success Response
message: (String) Mensaje a desplegar al usuario
18 - Authorization Error
status: (Integer) Código del error
message: (String) Mensaje del error
19 - Service Error
status: (Integer) Código del error
message: (String) Mensaje del error
20 - Validation Error
status: (Integer) Código del error
message: (String) Mensaje del error
errors: (array[ErrorItem]) Errores de validación
21 - Error Item
field: (String) Campo que tiene el error de validación
message: (String) Motivo del error de validación
Dirección: Las Urbinas 53 oficina 132, Providencia, Santiago, Chile. Código postal 7510093
Dirección Argentina: Besares 1029, Chacras de Coria, Mendoza, Argentina. Código postal 5505.