En tu propio lenguaje

Documentación

Referencia de la API REST

Métodos

GET /banks

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

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.

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.

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

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.

 

 

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.

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.

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.

 

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}/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.

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.

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.

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.

 

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 /merchants/{id}/paymentMethods

Obtiene el listado de medios de pago disponible para una cuenta de cobrador

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 de la cuenta de cobro

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

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 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), ‘webpay_psp’ (Webpay), ‘webpay_debit_psp’ (Webpay en botón exclusivo para pago con débito o prepago), ‘webpay_crebit_psp’ (Webpay en botón exclusivo para pago con crédito) o ‘not_available’ (para un pago marcado como realizado por otro medio por el cobrador).
  • 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.

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)

PaymentMethodsResponse

PaymentMethodItem

  • id: (String) Identificador del medio de pago
  • name: (String) Nombre del medio de pago
  • logo_url: (String) URL del logo sugerido para mostrar

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
A %d blogueros les gusta esto: