Referencia de la API REST 2.0

Métodos

[ Ir a Modelo ]

Tabla de contenidos

  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
get /banks
Obtener listado de bancos (banksGet)
Obtiene el listado de bancos que pueden usarse para pagar a esta cuenta de cobro.

Seguridad

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>

Consume

Esta llamada de la API consume los siguientes tipos de media usando el encabezado Content-Type:
  • application/x-www-form-urlencoded

Retorno

Produce

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

Respuesta

200

Éxito

400

Datos inválidos

403

Error de autorización

503

Error de operación

get /payments
Obtener información de un pago (paymentsGet)
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

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>

Consume

Esta llamada de la API consume los siguientes tipos de media usando el encabezado Content-Type:
  • application/x-www-form-urlencoded

Parámetros de "query"

notification_token (requerido)
Parámetro de "query" — Token de notifiación recibido usando la API de notificaiones 1.3 o superior.

Retorno

Produce

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

Respuesta

200

Éxito

400

Datos inválidos

403

Error de autorización

503

Error de operación

post /payments
Crear un pago (paymentsPost)
Crea un pago en khipu y obtiene las URLs para redirección al usuario para que complete el pago.

Seguridad

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>

Consume

Esta llamada de la API consume los siguientes tipos de media usando el encabezado Content-Type:
  • application/x-www-form-urlencoded

Parámetros de formulario

subject (requerido)
Parámetro de formulario — Motivo
currency (requerido)
Parámetro de formulario — El código de moneda en formato ISO-4217
amount (requerido)
Parámetro de formulario — 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)
Parámetro de formulario — Identificador propio de la transacción. Ej: número de factura u orden de compra
custom (opcional)
Parámetro de formulario — Parámetro para enviar información personalizada de la transacción. Ej: documento XML con el detalle del carro de compra
body (opcional)
Parámetro de formulario — Descripción del cobro
bank_id (opcional)
Parámetro de formulario — Identificador del banco para usar en el pago
return_url (opcional)
Parámetro de formulario — La dirección URL a donde enviar al cliente mientras el pago está siendo verificado
cancel_url (opcional)
Parámetro de formulario — La dirección URL a donde enviar al cliente si decide no hacer hacer la transacción
picture_url (opcional)
Parámetro de formulario — Una dirección URL de una foto de tu producto o servicio
notify_url (opcional)
Parámetro de formulario — La dirección del web-service que utilizará khipu para notificar cuando el pago esté conciliado
contract_url (opcional)
Parámetro de formulario — 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 obgligatorio
notify_api_version (opcional)
Parámetro de formulario — Versión de la API de notifiaciones para recibir avisos por web-service
expires_date (opcional)
Parámetro de formulario — 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)
Parámetro de formulario — Si es 'true', se enviará una solicitud de cobro al correo especificado en 'payer_email'
payer_name (opcional)
Parámetro de formulario — Nombre del pagador. Es obligatorio cuando send_email es 'true'
payer_email (opcional)
Parámetro de formulario — Correo del pagador. Es obligatorio cuando send_email es 'true'
send_reminders (opcional)
Parámetro de formulario — Si es 'true', se enviarán recordatorios de cobro.
responsible_user_email (opcional)
Parámetro de formulario — 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)
Parámetro de formulario — Identificador personal. Si se especifica, solo podrá ser pagado usando ese identificador
integrator_fee (opcional)
Parámetro de formulario — 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)
Parámetro de formulario — Para cuentas de cobro con más cuenta propia. Permite elegir la cuenta donde debe ocurrir la transferencia.
confirm_timeout_date (opcional)
Parámetro de formulario — 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

Retorno

Produce

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

Respuesta

200

Éxito

400

Datos inválidos

403

Error de autorización

503

Error de operación

get /payments/{id}
Obtener información de un pago (paymentsIdGet)
Información completa del pago. Datos con los que fue creado y el estado actual del pago.

Seguridad

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>

Parámetros de ruta

id (requerido)
Parámetro de ruta — Identificador del pago

Consume

Esta llamada de la API consume los siguientes tipos de media usando el encabezado Content-Type:
  • application/x-www-form-urlencoded

Retorno

Produce

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

Respuesta

200

Éxito

400

Datos inválidos

403

Error de autorización

503

Error de operación

delete /payments/{id}
Borrar un pago (paymentsIdDelete)
Solo se pueden borrar pagos que estén pendientes de pagar. Esta operación no puede deshacerse.

Seguridad

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>

Parámetros de ruta

id (requerido)
Parámetro de ruta — Identificador del pago

Consume

Esta llamada de la API consume los siguientes tipos de media usando el encabezado Content-Type:
  • application/x-www-form-urlencoded

Retorno

Produce

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

Respuesta

200

Éxito

400

Datos inválidos

403

Error de autorización

503

Error de operación

post /payments/{id}/confirm
Confirmar el pago. (paymentsIdConfirmPost)
Al confirmar el pago, este será rendido al día siguiente.

Seguridad

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>

Parámetros de ruta

id (requerido)
Parámetro de ruta — Identificador del pago

Consume

Esta llamada de la API consume los siguientes tipos de media usando el encabezado Content-Type:
  • application/x-www-form-urlencoded

Retorno

Produce

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

Respuesta

200

Éxito

400

Datos inválidos

403

Error de autorización

503

Error de operación

post /payments/{id}/refunds
Reembolsar total o parcialmente un pago (paymentsIdRefundsPost)
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

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>

Parámetros de ruta

id (requerido)
Parámetro de ruta — Identificador del pago

Consume

Esta llamada de la API consume los siguientes tipos de media usando el encabezado Content-Type:
  • application/x-www-form-urlencoded

Parámetros de formulario

amount (opcional)
Parámetro de formulario — 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.

Retorno

Produce

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

Respuesta

200

Éxito

400

Datos inválidos

403

Error de autorización

503

Error de operación

post /receivers
Crear una nueva cuenta de cobro (receiversPost)
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

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>

Consume

Esta llamada de la API consume los siguientes tipos de media usando el encabezado Content-Type:
  • application/x-www-form-urlencoded

Parámetros de formulario

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

Retorno

Produce

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

Respuesta

200

Éxito

400

Datos inválidos

403

Error de autorización

503

Error de operación

Modelo

[ Ir a Métodos ]

Tabla de contenidos

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

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
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 pagadon aún no comienza a pagar), 'normal' (el pago fue verificado y fue cancelado por algún medio de pago estandar), '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
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

banks
array[BankItem]

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]

ErrorItem

field
String Campo que tiene el error de validación
message
String Motivo del error de validación