Referencia de la API REST

Te invitamos a revisar los métodos y modelos que puedes utilizar en tu implementación

Métodos de Referencia

1 - 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

2 - 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 notificación recibido usando la API de notificaiones 1.3 o superior. Este campo tiene un largo fijo de 64 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/json
200: Éxito
400: Datos inválidos
403: Error de autorización
503: Error de operación

3 - 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. 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/json
200: Éxito
400: Datos inválidos
403: Error de autorización
503: Error de operación

4 - 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. Este campo tiene un largo máximo de 255 caracteres.

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

5 - 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. Este campo tiene un largo máximo de 255 caracteres.

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

6 - 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. Este campo tiene un largo máximo de 255 caracteres.

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

7 - 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. Este campo tiene un largo máximo de 255 caracteres.

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

8 - 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. Este campo tiene un largo máximo de 255 caracteres.
admin_last_name (requerido): Apellido del administrador de la cuenta de cobro a crear. Este campo tiene un largo máximo de 255 caracteres.
admin_email (requerido): Correo electrónico del administrador de la cuenta de cobro a crear. Este campo tiene un largo máximo de 255 caracteres.
country_code (requerido): Código alfanumérico de dos caractéres ISO 3166-1 del país de la cuenta de cobro a crear. Este campo tiene un largo máximo de 2 caracteres.
business_identifier (requerido): Identificador tributario del cobrador asociado a la cuenta de cobro a crear. Este campo tiene un largo mínimo de 8 caracteres y un máximo de 255 caracteres.
business_category (requerido): Categoría tributaria o rubro tributario del cobrador asociado a la cuenta de cobro a crear. Este campo tiene un largo máximo de 255 caracteres.
business_name (requerido): Nombre tributario del cobrador asociado a la cuenta de cobro a crear. Este campo tiene un largo máximo de 255 caracteres.
business_phone (requerido): Teléfono del cobrador asociado a la cuenta de cobro a crear. Este campo tiene un largo mínimo de 5 caracteres y un máximo de 20 caracteres.
business_address_line_1 (requerido): Dirección del cobrador de la cuenta de cobro a crear. Este campo tiene un largo mínimo de 4 caracteres y máximo de 300 caracteres.
business_address_line_2 (requerido): Segunda línea de la dirección del cobrador de la cuenta de cobro a crear. Este campo tiene un largo mínimo de 4 caracteres y máximo de 300 caracteres.
business_address_line_3 (requerido): Tercera línea de la dirección del cobrador de la cuenta de cobro a crear. Este campo tiene un largo mínimo de 4 caracteres y máximo de 300 caracteres.
contact_full_name (requerido): Nombre del contacto del cobrador. Este campo tiene un largo máximo de 255 caracteres.
contact_job_title (requerido): Cargo del contacto del cobrador. Este campo tiene un largo máximo de 255 caracteres.
contact_email (requerido): Correo electrónico del contacto del cobrador. Este campo tiene un largo máximo de 255 caracteres.
contact_phone (requerido): Teléfono del contacto del cobrador. Este campo tiene un largo mínimo de 5 caracteres y un máximo de 20 caracteres.
bank_account_bank_id (opcional): Identificador del banco. Este campo tiene un largo máximo de 5 caracteres.
bank_account_identifier (opcional): Identificador personal del dueño de la cuenta de banco. Este campo tiene un largo máximo de 50 caracteres.
bank_account_name (opcional): Nombre de la cuenta de banco. Este campo tiene un largo máximo de 255 caracteres.
bank_account_number (opcional): Número de la cuenta en el banco. Este campo tiene un largo máximo de 255 caracteres.
notify_url (opcional): URL por omisión para el webservice donde se notificará el pago. Este campo tiene un largo máximo de 1.024 caracteres.
rendition_url (opcional): URL para el webservice donde se notificará la rendición. Este campo tiene un largo máximo de 1.024 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/json
200: Éxito
400: Datos inválidos
403: Error de autorización
503: Error de operación

9 - 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 Este campo tiene un largo máximo de 255 caracteres.

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

webpay_url: (String) URL de webpay para comercios que tengan hablitado webpay en modalidad débito, prepago y crédito

webpay_debit_url: (String) URL de webpay para comercios que tengan habilitado webpay en modalidad débito y prepago

webpay_credit_url: (String) URL de webpay para comercios que tengan habilitado webpay en modalidad sólo crédito

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), ‘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.

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

webpay_url: (String) URL de webpay para comercios que tengan hablitado webpay en modalidad débito, prepago y crédito

webpay_debit_url: (String) URL de webpay para comercios que tengan habilitado webpay en modalidad débito y prepago

webpay_credit_url: (String) URL de webpay para comercios que tengan habilitado webpay en modalidad sólo crédito

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

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

13 - Banks Response

banks: array[BankItem]

14 - Bank Item

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)

15 - Payment Methods Response

paymentMethods: array[PaymentMethodItem]

16 - Payment Method Item

id: (String) Identificador del medio de pago

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