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

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

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

 

 

4 GET / payments

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

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

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

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

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.

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

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

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

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

12 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

13 BanksResponse

banks: array[BankItem]

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

15 PaymentMethodsResponse

paymentMethods: array[PaymentMethodItem]

16 PaymentMethodItem

id: (String) Identificador del medio de pago

name: (String) Nombre del medio de pago

logo_url: (String) URL del logo sugerido para mostrar

17 SuccessResponse

message: (String) Mensaje a desplegar al usuario

18 AuthorizationError

status: (Integer) Código del error

message: (String) Mensaje del error

19 ServiceError

status: (Integer) Código del error

message: (String) Mensaje del error

20 ValidationError

status: (Integer) Código del error

message: (String) Mensaje del error

errors: (array[ErrorItem]) Errores de validación

21 ErrorItem

field: (String) Campo que tiene el error de validación

message: (String) Motivo del error de validación

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

 

 

A %d blogueros les gusta esto: