REST API Reference
Review methods and models that you can use in your implementation
For API 2.0 all methods use the following url as base: https://khipu.com/api/2.0/
Reference Methods
1 - GET / banks
This API call consumes the following types of media using the Content-Type header:
application/x-www-form-urlencodedThis API call produces the following types of media using the Accept header; the type will be converted using the Content-Type header:
application/json
200: Éxito
400: Datos inválidos
403: Error de autorización
503: Error de operación2 - GET / payments
This API call consumes the following types of media using the Content-Type header:
application/x-www-form-urlencodedThis API call produces the following types of media using the Accept header; the type will be converted using the Content-Type header:
application/json200: Éxito
400: Datos inválidos
403: Error de autorización
503: Error de operación3 - POST / payments
Create a Khipu payment and get the URLs for user redirection to complete the payment.
This API call consumes the following types of media using the Content-Type header:
application/x-www-form-urlencodedsubject (required): Motive. This field has a max length of 255 characters.
currency (required): Currency code in format ISO-4217. This field has a max length of 255 characters.
amount (required): Charge amount. No thousands separator and using ‘.’ as decimal separator. Up to 4 decimal places, depending on the currency. This field has a maximum length of 16 characters.
transaction_id (optional): Transaction identifier. Example: billing or purchasing order number. This field has a max length of 255 characters.
custom (optional): Parameter to send personalized information of the transaction. Example: XML document with the Shopping Cart details. This field has a maximum length of 1.073.741.824 characters.
body (optional): Charge description. This field has a max length of 5.120 characters.
bank_id (optional): Bank identifier to be used in the payment. This field has a max length of 5 characters.
return_url (optional): The URL address where the customer will be sent while the payment is being verified. This field has a max length of 1.024 characters.
cancel_url (optional): The URL address where the customer will be sent if he/she decides not to complete the transaction. This field has a max length of 1.024 characters.
picture_url (optional): A URL address of a picture of the product or service. This field has a max length of 1.024 characters.
notify_url (optional): Web-service address to be used by khipu to notify when the payment is reconciled. This field has a max length of 1.024 characters.
contract_url (optional): The URL address of the PDF file with the contract to be signed for this payment. The collector must be enabled for this service and the ‘fixed_payer_personal_identifier’ field is mandatory. This field has a max length of 1.024 characters.
notify_api_version (optional): The notification API version to receive notifications by web-services. This field has a max length of 255 characters.
expires_date (optional): Maximum date to execute a payment (in ISO-8601 format). The customer may make several attempts until this date. Each attempt has an individual period of 3 hours for its execution.
send_email (optional): If ‘true’, a payment request will be sent to the e-mail specified in ‘payer_email’. This field has a max length of 5 characters.
payer_name (optional): Payer’s name. It is mandatory when send_email is ‘true’. This field has a max length of 255 characters.
payer_email (optional): Payer’s e-mail. It is mandatory when send_email is ‘true’. This field has a max length of 255 characters.
send_reminders (optional): If ‘true’, charging reminders will be sent. This field has a max length of 5 characters.
responsible_user_email (optional): The e-mail of the person that is responsible for the charge, it must belong to a khipu user with permissions to collect using a charging account. This field has a max length of 255 characters.
fixed_payer_personal_identifier (optional): Personal identifier. If specified, it could only be payed using this identifier. This field has a max length of 255 characters.
integrator_fee (optional): Commission for the merchant integrator. It is only valid if the charging account is associated to an integrator account. This field has a maximum length of 16 characters.
collect_account_uuid (optional): For collection accounts with more own account. Allows you to choose the account where the transfer should occur. This field has a max length of 255 characters.
confirm_timeout_date (optional): Charge rendition date. It is also the end date to be able to receive the charge. Format ISO-8601. Ex: 2017-03-01T13:00:00Z. This field has a max length of 22 characters.
mandatory_payment_method (optional): The charge can only be paid using the specified means of payment. The possible values for this field are found in the id field of the endpoint response. Check the Available Payment Methods. This field has a max length of 255 characters.
This API call produces the following types of media using the Accept header; the type will be converted using the Content-Type header:
application/json200: Éxito
400: Datos inválidos
403: Error de autorización
503: Error de operación4 - GET / payments / {id}
Complete payment information. Data used in the creation and current status of the payment.
This API call consumes the following types of media using the Content-Type header:
application/x-www-form-urlencodedThis API call produces the following types of media using the Accept header; the type will be converted using the Content-Type header:
application/json200: Éxito
400: Datos inválidos
403: Error de autorización
503: Error de operación5 - DELETE / payments / {id}
This API call consumes the following types of media using the Content-Type header:
application/x-www-form-urlencodedThis API call produces the following types of media using the Accept header; the type will be converted using the Content-Type header:
application/json200: Éxito
400: Datos inválidos
403: Error de autorización
503: Error de operación6 - POST / payments / {id} / confirm
This API call consumes the following types of media using the Content-Type header:
application/x-www-form-urlencodedThis API call produces the following types of media using the Accept header; the type will be converted using the Content-Type header:
application/json200: Éxito
400: Datos inválidos
403: Error de autorización
503: Error de operación7 - POST / payments / {id} / refunds
This API call consumes the following types of media using the Content-Type header:
application/x-www-form-urlencodedThis API call produces the following types of media using the Accept header; the type will be converted using the Content-Type header:
application/json200: Éxito
400: Datos inválidos
403: Error de autorización
503: Error de operación8 - POST / receivers
This API call consumes the following types of media using the Content-Type header:
application/x-www-form-urlencodedThis API call produces the following types of media using the Accept header; the type will be converted using the Content-Type header:
application/json200: Éxito
400: Datos inválidos
403: Error de autorización
503: Error de operación9 - GET / merchants / {id} / paymentMethods
This API call consumes the following types of media using the Content-Type header:
application/x-www-form-urlencodedThis API call produces the following types of media using the Accept header; the type will be converted using the Content-Type header:
application/json200: Éxito
400: Datos inválidos
403: Error de autorización
503: Error de operaciónReference Models
10 - Payments Response
payment_id: (String) Unique identifier of the payment, it is an alphanumeric string of 12 characters. Since this identifier is unique, it can be used, for example, to avoid processing a repeated notification (Khipu expects a 200 code when notifying a payment, if this does not happen it is retried for up to two days)
payment_url: (String) main URL of the payment, if the user hasn’t selected previously a payment method options are shown
simplified_transfer_url: (String) Simplified URL of the payment
transfer_url: (String) URL of a normal payment
app_url: (String) URL to invoke the payment from a mobile device using the Khipu APP
ready_for_terminal: (Boolean) It is ‘true’ if the payment has all necessary data to open the Khipu payment app directly
notification_token: (String) Alphanumeric string of characters that identify the payment in a unique way, is the identifier Khipu server will send to the merchant server to notify when a payment is reconciled
receiver_id: (Long) Unique identifier of a charging account
conciliation_date: (Date) Date and time of a payment reconciliation. Format ISO-8601. Ex.: 2017-03-01T13:00:00Z
subject: (String) Payment reason or motive
amount: (Double)
currency: (String) The currency code in ISO-4217 format
status: (String) Payment status, possible status are: ‘pending’ (payer has not yet started to pay), ‘verifying’ (payment is being verified) or ‘done’ (payment is already confirmed)
status_detail: (String) Detail of the payment status: ‘pending’ (payer has not yet started to pay), ‘normal’ (payment was verified and was paid by some standard payment method), ‘marked-paid-by-receiver’ (collector marked the payment as paid), ‘rejected-by-payer’ (payer refused to pay), ‘marked-as-abuse’ (payer refused to pay as charge was not requested) and ‘reversed’ (payment was cancelled by the merchant and money was returned to the payer).
body: (String) Detail of charge
picture_url: (String) Charge URL
receipt_url: (String) Proof of payment URL
return_url: (String) URL where the payer is redirected after the payment is finished
cancel_url: (String) URL where the payer is redirected after cancelling the payment
notify_url: (String) webservice URL where the payment will be notified
notify_api_version: (String) Notification API version
expires_date: (Date) Maximum date to execute a payment (in ISO-8601 format). The customer will be able to make several payments attempts up to this date. Each attempt has an individual period of 3 hours for its execution
attachment_urls: (array[String]) URLs of files attached to the payment
bank: (String) Name of the bank selected by the payer
bank_id: (String) Identifier of the bank selected by the payer
payer_name: (String) Payer’s name
payer_email: (String) Payer’s e-mail address
personal_identifier: (String) Payer’s personal identifier
bank_account_number: (String) Payer’s bank account number
out_of_date_conciliation: (Boolean) Is ‘true’ if the payment reconciliation was made after the expiration date
transaction_id: (String) Payment identifier assigned by the collector
custom: (String max 4096 characters) Generic field that the collector assigns when the payment is being made
responsible_user_email: (String) e-mail address of the person responsable of the payment
send_reminders: (Boolean) Is ‘true’ if it’s an e-mail charge and Khipu will send reminders
send_email: (Boolean) Is ‘true’ if Khipu will send the e-mail charge
payment_method: (String) Payment method used by the payer, possible values: ‘regular_transfer’ (normal transfer), ‘simplified_transfer’ (simplified transfer).
funds_source: (String) Origin of the funds used by the payer, posible values are: ‘debit’ for debit payment, ‘prepaid’ for payments by prepay, ‘credit’ for payments with credit, and null in the case that it has been paid by bank transfer.
11 - Payments Create Response
payment_id: (String) Unique identifier of the payment, it is an alphanumeric string of 12 characters. Since this identifier is unique, it can be used, for example, to avoid processing a repeated notification (Khipu expects a 200 code when notifying a payment, if this does not happen it is retried for up to two days)
payment_url: (String) main URL of the payment, if the user hasn’t selected previously a payment method options are shown
simplified_transfer_url: (String) Simplified URL of the payment
transfer_url: (String) URL of a normal payment
app_url: (String) URL to invoke the payment from a mobile device using the Khipu APP
ready_for_terminal: (Boolean) It is ‘true’ if the payment has all necessary data to open the Khipu payment app directly.
12 - Receivers Create Response
secret: (String) Secret key of the charging account, used to sign all petitions
13 - Banks Response
14 - Bank Item
name: (String) Name of the bank
message: (String) Message with bank details
min_amount: (Double) Minimum amount the bank accepts in a payment
type: (String) Type of bank
parent: (String) Identifier of the parent bank (if a bank has personal and corporate banking, the first will be the parent of the second)
15 - Payment Methods Response
16 - Payment Method Item
name: (String) Payment method name
logo_url: (String) URL of the logo suggested
17 - Success Response
message: (String) Message to display to the user
18 - Authorization Error
status: (Integer) Error code
message: (String) Error message
19 - Service Error
status: (Integer) Error code
message: (String) Error message
20 - Validation Error
status: (Integer) Error code
message: (String) Error message
errors: (array[ErrorItem]) Validation errors
21 - Error Item
field: (String) Field containing the validation error
message: (String) Reason for the validation error
Chile Address: Las Urbinas 53 oficina 132, Providencia, Santiago, Chile. Postal code 7510093
Argentina Address: Besares 1029, Chacras de Coria, Mendoza, Argentina. Postal code 5505.