Referencia de la API REST

Métodos

  1. GET /banks
  2. GET /payments
  3. POST /payments
  4. GET /payments/{id}
  5. DELETE /payments/{id}
  6. POST /payments/{id}/confirm
  7. POST /payments/{id}/refunds
  8. POST /receivers

Modelos

  1. PaymentsResponse
  2. PaymentsCreateResponse
  3. ReceiversCreateResponse
  4. BanksResponse
  5. BankItem
  6. SuccessResponse
  7. AuthorizationError
  8. ServiceError
  9. ValidationError
  10. ErrorItem

Métodos

GET /banks

Obtiene el listado de bancos que pueden usarse para pagar a esta cuenta de cobro.

  • Seguridad
  • Consume
  • Retorno
  • Produce
  • Respuesta

Esta llamada de la API se debe firmar según el procedimiento descrito en Firmar peticiones de la API y se debe utilizar el encabezado "Authorization" para enviar la cadena:

<id cobrador>:<firma>

Esta llamada de la API consume los siguientes tipos de media usando el encabezado Content-Type:

application/x-www-form-urlencoded

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/json

  • 200: Éxito
  • 400: Datos inválidos
  • 403: Error de autorización
  • 503: Error de operación

GET /payments

Información completa del pago. Datos con los que fue creado y el estado actual del pago. Se obtiene del notification_token que envia khipu cuando el pago es conciliado.

  • Seguridad
  • Consume
  • Query
  • Retorno
  • Produce
  • Respuesta

Esta llamada de la API se debe firmar según el procedimiento descrito en Firmar peticiones de la API y se debe utilizar el encabezado "Authorization" para enviar la cadena:

<id cobrador>:<firma>

Esta llamada de la API consume los siguientes tipos de media usando el encabezado Content-Type:

application/x-www-form-urlencoded

  • notification_token (requerido): Token de notifiación recibido usando la API de notificaiones 1.3 o superior.

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/json

  • 200: Éxito
  • 400: Datos inválidos
  • 403: Error de autorización
  • 503: Error de operación

POST /payments

Crea un pago en khipu y obtiene las URLs para redirección al usuario para que complete el pago.

  • Seguridad
  • Consume
  • Parámetros
  • Retorno
  • Produce
  • Respuesta

Esta llamada de la API se debe firmar según el procedimiento descrito en Firmar peticiones de la API y se debe utilizar el encabezado "Authorization" para enviar la cadena:

<id cobrador>:<firma>

Esta llamada de la API consume los siguientes tipos de media usando el encabezado Content-Type:

application/x-www-form-urlencoded

  • subject (requerido): Motivo
  • currency (requerido): El código de moneda en formato ISO-4217
  • amount (requerido): El monto del cobro. Sin separador de miles y usando '.' como separador de decimales. Hasta 4 lugares decimales, dependiendo de la moneda
  • transaction_id (opcional): Identificador propio de la transacción. Ej: número de factura u orden de compra
  • custom (opcional): Parámetro para enviar información personalizada de la transacción. Ej: documento XML con el detalle del carro de compra
  • body (opcional): Descripción del cobro
  • bank_id (opcional): Identificador del banco para usar en el pago
  • return_url (opcional): La dirección URL a donde enviar al cliente mientras el pago está siendo verificado
  • cancel_url (opcional): La dirección URL a donde enviar al cliente si decide no hacer hacer la transacción
  • picture_url (opcional): Una dirección URL de una foto de tu producto o servicio
  • notify_url (opcional): La dirección del web-service que utilizará khipu para notificar cuando el pago esté conciliado
  • 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
  • notify_api_version (opcional): Versión de la API de notifiaciones para recibir avisos por web-service
  • expires_date (opcional): Fecha de expiración del cobro. Pasada esta fecha el cobro es inválido. Formato ISO-8601. Ej: 2017-03-01T13:00:00Z
  • send_email (opcional): Si es 'true', se enviará una solicitud de cobro al correo especificado en 'payer_email'
  • payer_name (opcional): Nombre del pagador. Es obligatorio cuando send_email es 'true'
  • payer_email (opcional): Correo del pagador. Es obligatorio cuando send_email es 'true'
  • send_reminders (opcional): Si es 'true', se enviarán recordatorios de cobro.
  • 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
  • fixed_payer_personal_identifier (opcional): Identificador personal. Si se especifica, solo podrá ser pagado usando ese identificador
  • integrator_fee (opcional): Comisión para el integrador. Sólo es válido si la cuenta de cobro tiene una cuenta de integrador asociada
  • collect_account_uuid (opcional): Para cuentas de cobro con más cuenta propia. Permite elegir la cuenta donde debe ocurrir la transferencia.
  • 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

PaymentsCreateResponse

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/json

  • 200: Éxito
  • 400: Datos inválidos
  • 403: Error de autorización
  • 503: Error de operación

GET /payments/{id}

Información completa del pago. Datos con los que fue creado y el estado actual del pago.

  • Seguridad
  • Parámetros de Ruta
  • Consume
  • Retorno
  • Produce
  • Respuesta

Esta llamada de la API se debe firmar según el procedimiento descrito en Firmar peticiones de la API y se debe utilizar el encabezado "Authorization" para enviar la cadena:

<id cobrador>:<firma>

  • id (requerido): Identificador del pago

Esta llamada de la API consume los siguientes tipos de media usando el encabezado Content-Type:

application/x-www-form-urlencoded

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/json

  • 200: Éxito
  • 400: Datos inválidos
  • 403: Error de autorización
  • 503: Error de operación

DELETE /payments/{id}

Borrar un pago. Solo se pueden borrar pagos que estén pendientes de pagar. Esta operación no puede deshacerse.

  • Seguridad
  • Parámetros de Ruta
  • Consume
  • Retorno
  • Produce
  • Respuesta

Esta llamada de la API se debe firmar según el procedimiento descrito en Firmar peticiones de la API y se debe utilizar el encabezado "Authorization" para enviar la cadena:

<id cobrador>:<firma>

  • id (requerido): Identificador del pago

Esta llamada de la API consume los siguientes tipos de media usando el encabezado Content-Type:

application/x-www-form-urlencoded

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/json

  • 200: Éxito
  • 400: Datos inválidos
  • 403: Error de autorización
  • 503: Error de operación

POST /payments/{id}/confirm

Confirmar el pago. Al confirmar el pago, este será rendido al día siguiente.

  • Seguridad
  • Parámetros de Ruta
  • Consume
  • Retorno
  • Produce
  • Respuesta

Esta llamada de la API se debe firmar según el procedimiento descrito en Firmar peticiones de la API y se debe utilizar el encabezado "Authorization" para enviar la cadena:

<id cobrador>:<firma>

  • id (requerido): Identificador del pago

Esta llamada de la API consume los siguientes tipos de media usando el encabezado Content-Type:

application/x-www-form-urlencoded

SuccessResponse

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/json

  • 200: Éxito
  • 400: Datos inválidos
  • 403: Error de autorización
  • 503: Error de operación

POST /payments/{id}/refunds

Reembolsa total o parcialmente el monto de un pago. Esta operación solo se puede realizar en los comercios que recauden en cuenta khipu y antes de la rendición de los fondos correspondientes.

  • Seguridad
  • Parámetros de Ruta
  • Consume
  • Parámetros
  • Retorno
  • Produce
  • Respuesta

Esta llamada de la API se debe firmar según el procedimiento descrito en Firmar peticiones de la API y se debe utilizar el encabezado "Authorization" para enviar la cadena:

<id cobrador>:<firma>

  • id (requerido): Identificador del pago

Esta llamada de la API consume los siguientes tipos de media usando el encabezado Content-Type:

application/x-www-form-urlencoded

  • amount (opcional): El monto a devolver. Sin separador de miles y usando '.' como separador de decimales. Hasta 4 lugares decimales, dependiendo de la moneda. Si se omite el reembolso se hará por el total del monto del pago.

SuccessResponse

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/json

  • 200: Éxito
  • 400: Datos inválidos
  • 403: Error de autorización
  • 503: Error de operación

POST /receivers

Crear una nueva cuenta de cobro asociada a un integrador. Necesita datos de la cuenta de usuario asociada, datos de facturación y datos de contacto.

  • Seguridad
  • Consume
  • Parámetros
  • Retorno
  • Produce
  • Respuesta

Esta llamada de la API se debe firmar según el procedimiento descrito en Firmar peticiones de la API y se debe utilizar el encabezado "Authorization" para enviar la cadena:

<id cobrador>:<firma>

Esta llamada de la API consume los siguientes tipos de media usando el encabezado Content-Type:

application/x-www-form-urlencoded

  • admin_first_name (requerido): Nombre de pila del administrador de la cuenta de cobro a crear.
  • admin_last_name (requerido): Apellido del administrador de la cuenta de cobro a crear.
  • admin_email (requerido): Correo electrónico del administrador de la cuenta de cobro a crear.
  • country_code (requerido): Código alfanumérico de dos caractéres ISO 3166-1 del país de la cuenta de cobro a crear.
  • business_identifier (requerido): Identificador tributario del cobrador asociado a la cuenta de cobro a crear.
  • business_category (requerido): Categoría tributaria o rubro tributario del cobrador asociado a la cuenta de cobro a crear.
  • business_name (requerido): Nombre tributario del cobrador asociado a la cuenta de cobro a crear.
  • business_phone (requerido): Teléfono del cobrador asociado a la cuenta de cobro a crear.
  • business_address_line_1 (requerido): Dirección del cobrador de la cuenta de cobro a crear.
  • business_address_line_2 (requerido): Segunda línea de la dirección del cobrador de la cuenta de cobro a crear.
  • business_address_line_3 (requerido): Tercera línea de la dirección del cobrador de la cuenta de cobro a crear.
  • contact_full_name (requerido): Nombre del contacto del cobrador.
  • contact_job_title (requerido): Cargo del contacto del cobrador.
  • contact_email (requerido): Correo electrónico del contacto del cobrador.
  • contact_phone (requerido): Teléfono del contacto del cobrador.
  • bank_account_bank_id (opcional): Identificador del banco.
  • bank_account_identifier (opcional): Identificador personal del dueño de la cuenta de banco.
  • bank_account_name (opcional): Nombre de la cuenta de banco.
  • bank_account_number (opcional): Número de la cuenta en el banco.
  • notify_url (opcional): URL por omisión para el webservice donde se notificará el pago.
  • rendition_url (opcional): URL para el webservice donde se notificará la rendición.

ReceiversCreateResponse

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/json

  • 200: Éxito
  • 400: Datos inválidos
  • 403: Error de autorización
  • 503: Error de operación

Modelos

PaymentsResponse

  • payment_id: (String) Identificador único del pago, es una cadena alfanumérica de 12 caracteres
  • 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
  • webpay_url: (String) URL de webpay
  • 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 de expiración del pago. En formato ISO-8601
  • 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) 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) o 'not_available' (para un pago marcado como realizado por otro medio por el cobrador).

PaymentsCreateResponse

  • payment_id: (String) Identificador único del pago, es una cadena alfanumérica de 12 caracteres
  • 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
  • webpay_url: (String) URL de webpay
  • 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

ReceiversCreateResponse

  • receiver_id: (String) Identificador único de la cuenta de cobro
  • secret: (String) Llave secreta de la cuenta de cobro, se usa para firmar todas las peticiones

BanksResponse

BankItem

  • bank_id: (String) Identificador del banco
  • 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)

SuccessResponse

  • message: (String) Mensaje a desplegar al usuario

AuthorizationError

  • status: (Integer) Código del error
  • message: (String) Mensaje del error

ServiceError

  • status: (Integer) Código del error
  • message: (String) Mensaje del error

ValidationError

  • status: (Integer) Código del error
  • message: (String) Mensaje del error
  • errors: (array[ErrorItem]) Errores de validación

ErrorItem

  • field: (String) Campo que tiene el error de validación
  • message: (String) Motivo del error de validación