Pagos Instantáneos

Post receiver

Instant Payment API (v3.0)

The Khipu Instant Payment API (version 3.0) enables merchants to initiate, query, confirm, refund, or delete real-time bank transfer payments. Key features include retrieving a list of available banks with their limits, fees, and logos; creating payments by specifying a bank or letting users choose; confirming or requesting a refund using the payment ID; and predicting a payment's status using machine learning. Authentication is handled via a secret key in the x-api-key header, without requiring signatures, and all communication is secured with extended validation SSL certificates.

Download OpenAPI description

openapi.json

openapi.yaml

Overview

License

Instant Payments API

Servers

Production

https://payment-api.khipu.com/

Get banks

Request

This method obtains the list of banks that can be used to pay in this collection account.

Security

Api-Key

curl -i -X GET \
  https://payment-api.khipu.com/v3/banks \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

Successful operation. Returns a JSON object with the array of available banks.

Bodyapplication/json

banksArray of objectsnon-emptyrequired

Array with list of banks.

bank_idstringrequired

Bank identifier.

Example: "SDdGj"

namestringrequired

Name of the bank.

Example: "Banco Estado"

messagestringrequired

Message with bank details.

Example: "Tarifa de $300 de transferencia a otros bancos, usando CuentaRUT."

min_amountnumber(double)required

Minimum amount that the bank accepts in a payment.

Example: 1000

typestringrequired

Bank type.

Enum"Persona""Empresa"

Example: "Persona"

parentstringrequired

Identifier of the parent bank (if a bank has personal and business banking, the first will be the parent of the second).

Example: ""

logo_urlstring

URL of the bank's logo.

Example: "https://s3.amazonaws.com/static.khipu.com/logos/bancos/chile/estado-icon.png"

Response

application/json

{
  "banks": [
    {
      "bank_id": "SDdGj",
      "name": "Banco Estado",
      "message": "Tarifa de $300 de transferencia a otros bancos, usando CuentaRUT.",
      "min_amount": 1000,
      "type": "Persona",
      "parent": "",
      "logo_url": "https://s3.amazonaws.com/static.khipu.com/logos/bancos/chile/estado-icon.png"
    }
  ]
}

Confirm payment by Id

Request

Warning: This feature is only available to customers who have contracted it independently. To use it, please contact us at soporte@khipu.com

Confirm payment. Upon confirming payment, the funds will be delivered to the merchant the next business day.

Security

Api-Key

Path

idstring<= 255 charactersrequired

Payment identifier

curl -i -X POST \
  'https://payment-api.khipu.com/v3/payments/{id}/confirm' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

Successful operation.

Bodyapplication/json

messagestringrequired

Message to be displayed to the user.

Example: "Message."

Response

application/json

{
  "message": "Message."
}

Get payment by Id

Request

This method obtains the complete payment information. Includes the current status of the payment.

Security

Api-Key

Path

idstring<= 255 charactersrequired

Payment identifier

curl -i -X GET \
  'https://payment-api.khipu.com/v3/payments/{id}' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

Successful operation. Returns a JSON object with the payment information.

Bodyapplication/json

payment_idstringrequired

Unique identifier of the payment, it is a 12-character alphanumeric string. Because this identifier is unique, it can be used, for example, to avoid processing a repeated notification. (Khipu waits for a code 200 when notifying a payment, if this does not occur it retries for up to two days).

Example: "gqzdy6chjne9"

payment_urlstringrequired

Main payment URL, if the user has not previously chosen a payment method, the options are shown.

Example: "https://khipu.com/payment/info/gqzdy6chjne9"

simplified_transfer_urlstringrequired

Simplified payment URL.

Example: "https://app.khipu.com/payment/simplified/gqzdy6chjne9"

transfer_urlstringrequired

Normal payment URL.

Example: "https://khipu.com/payment/manual/gqzdy6chjne9"

app_urlstringrequired

URL to invoke payment from a mobile device using the Khipu APP.

Example: "khipu:///pos/gqzdy6chjne9"

ready_for_terminalbooleanrequired

It is true if the payment already has all the necessary data to directly open the Khipu payment application.

Example: false

notification_tokenstringrequired

String of alphanumeric characters that uniquely identify the payment, it is the identifier that the Khipu server will send to the merchant server when notifying that a payment is reconciled.

Example: "9dec8aa176c5223026919b3b5579a4776923e646ff3be686b9e6b62ec042e91f"

receiver_idinteger(int64)required

Unique identifier of a collection account.

Example: 985101

conciliation_datestring(date-time)required

Date and time of payment reconciliation. ISO-8601 format.

Example: "2017-03-01T13:00:00.000Z"

subjectstringrequired

Text to summarize the charge.

Example: "Test"

amountnumber(double)required

The amount of the charge.

Example: 1000

currencystringrequired

The currency code in ISO-4217 format.

Example: "CLP"

statusstringrequired

Payment status, it can be pending (the payer has not yet started paying), verifying (the payment is being verified) or done, when the payment is already confirmed.

Enum"pending""verifying""done"

Example: "done"

status_detailstringrequired

Detail of the payment status: pending (the payer has not yet started paying), normal (the payment was verified and was canceled by some standard payment method), marked-paid-by-receiver (the merchant marked the charge as paid), rejected-by-payer (the payer declared that they will not pay), marked-as-abuse (the payer declared that they will not pay and that the charge was unsolicited), and reversed (the payment was canceled by the merchant, the money was returned to the payer).

Enum"pending""normal""marked-paid-by-receiver""rejected-by-payer""marked-as-abuse""reversed"

Example: "normal"

bodystringrequired

Payment details.

Example: "Test"

picture_urlstringrequired

URL with image of the payment.

Example: "https://micomercio.com/picture_url"

receipt_urlstringrequired

URL of the payment receipt.

Example: "https://micomercio.com/order/receipt_url"

return_urlstringrequired

URL where the payer is redirected after the payment is completed.

Example: "https://micomercio.com/order/return_url"

cancel_urlstringrequired

URL where the payer is redirected after they give up making the payment.

Example: "https://micomercio.com/order/cancel_url"

notify_urlstringrequired

URL of the webservice where the payment will be notified.

Example: "https://micomercio.com/webhook/notify_url"

notify_api_versionstringrequired

Notification API version.

Example: "3.0"

expires_datestring(date-time)required

Maximum date to execute the payment (in ISO-8601 format). The client may make several payment attempts until said date. Each attempt has an individual period of 3 hours for its execution.

Example: "2023-12-31T15:45:00-04:00"

attachment_urlsArray of strings>= 0 itemsrequired

Array of URLs of files attached to the payment.

Example: ["https://micomercio.com/attachment1.pdf"]

bankstringrequired

Name of the bank selected by the payer.

Example: "Banco de Chile (Edwards Citi)"

bank_idstringrequired

Identifier of the bank selected by the payer.

Example: "dfFbF"

payer_namestringrequired

Payer's name.

Example: "Nombre Pagador"

payer_emailstring(email)required

Payer email.

Example: "pagador@email.com"

personal_identifierstringrequired

Personal identifier of the payer.

Example: "11.000.111-9"

bank_account_numberstringrequired

Payer's bank account number.

Example: "001120490689"

out_of_date_conciliationbooleanrequired

It is true if the payment reconciliation was made after the expiration date.

Example: true

transaction_idstringrequired

Payment identifier assigned by the merchant.

Example: "zwo3wqz6uulcvajt"

customstringrequired

Generic field assigned by the merchant at the time of making the payment.

Example: "<xml>...</xml>"

responsible_user_emailstringrequired

Email of the person responsible for the payment.

Example: "responsible@email.com"

send_remindersbooleanrequired

It is true when this is an email collection and Khipu will send reminders.

Example: true

send_emailbooleanrequired

It is true when Khipu will send the payment by email.

Example: true

payment_methodstringrequired

Payment method used by the payer, it can be regular_transfer or simplified_transfer.

Enum"regular_transfer""simplified_transfer""not_available"

Example: "simplified_transfer"

funds_sourcestringrequired

Source of funds used by the payer, it can be debit for payment with debit, prepaid for payment with prepaid, credit for payment with credit, or empty in case it has been paid by bank transfer.

Enum"debit""prepaid""credit""not-available"""

Example: "debit"

discountnumber(double)

Amount to be deducted from the value paid.

Example: 0

third_party_authorization_detailsstring

Disregard this field.

Response

application/json

{
  "payment_id": "gqzdy6chjne9",
  "payment_url": "https://khipu.com/payment/info/gqzdy6chjne9",
  "simplified_transfer_url": "https://app.khipu.com/payment/simplified/gqzdy6chjne9",
  "transfer_url": "https://khipu.com/payment/manual/gqzdy6chjne9",
  "app_url": "khipu:///pos/gqzdy6chjne9",
  "ready_for_terminal": false,
  "notification_token": "9dec8aa176c5223026919b3b5579a4776923e646ff3be686b9e6b62ec042e91f",
  "receiver_id": 985101,
  "conciliation_date": "2017-03-01T13:00:00.000Z",
  "subject": "Test",
  "amount": 1000,
  "currency": "CLP",
  "status": "done",
  "status_detail": "normal",
  "body": "Test",
  "picture_url": "https://micomercio.com/picture_url",
  "receipt_url": "https://micomercio.com/order/receipt_url",
  "return_url": "https://micomercio.com/order/return_url",
  "cancel_url": "https://micomercio.com/order/cancel_url",
  "notify_url": "https://micomercio.com/webhook/notify_url",
  "notify_api_version": "3.0",
  "expires_date": "2023-12-31T15:45:00-04:00",
  "attachment_urls": [
    "https://micomercio.com/attachment1.pdf"
  ],
  "bank": "Banco de Chile (Edwards Citi)",
  "bank_id": "dfFbF",
  "payer_name": "Nombre Pagador",
  "payer_email": "pagador@email.com",
  "personal_identifier": "11.000.111-9",
  "bank_account_number": "001120490689",
  "out_of_date_conciliation": true,
  "transaction_id": "zwo3wqz6uulcvajt",
  "custom": "<xml>...</xml>",
  "responsible_user_email": "responsible@email.com",
  "send_reminders": true,
  "send_email": true,
  "payment_method": "simplified_transfer",
  "funds_source": "debit",
  "discount": 0,
  "third_party_authorization_details": "string"
}

Delete payment by Id

Request

Delete a payment. Only applicable to payments with status pending.

Security

Api-Key

Path

idstring<= 255 charactersrequired

Payment identifier

curl -i -X DELETE \
  'https://payment-api.khipu.com/v3/payments/{id}' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

Successful operation.

Bodyapplication/json

messagestringrequired

Message to be displayed to the user.

Example: "Message."

Response

application/json

{
  "message": "Message."
}

Create payment

Request

Create a payment in Khipu and obtain the URLs to redirect the user to complete the payment.

Security

Api-Key

Bodyapplication/json

amountnumber(double)required

The amount of the charge. Without thousands separator and using '.' as decimal separator. Up to 4 decimal places, depending on currency.

Example: 1000

currencystring<= 255 charactersrequired

The currency code in ISO-4217 format.

Enum"CLP""CLF""ARS""PEN""MXN""USD""EUR""BOB""COP"

Example: "CLP"

subjectstring<= 255 charactersrequired

Text to summarize the charge.

Example: "Cobro de prueba"

transaction_idstring<= 255 characters

Transaction's identifier. Ex: invoice or purchase order number.

Example: "zwo3wqz6uulcvajt"

customstring<= 1073741824 characters

Parameter to send personalized transaction information. Ex: XML document with the shopping cart details.

Example: "<xml>...</xml>"

bodystring<= 5120 characters

Description of the charge.

Example: "Cobro de orden de compra #123-abcdef"

bank_idstring<= 5 characters

Bank identifier to use in the payment.

Example: "SDdGj"

return_urlstring<= 1024 characters

The URL to send the customer to while the payment is being verified.

Example: "https://micomercio.com/order/return_url"

cancel_urlstring<= 1024 characters

The URL to send the customer to if they decide not to make the transaction.

Example: "https://micomercio.com/order/cancel_url"

picture_urlstring<= 1024 characters

A URL of a photo of your product or service.

Example: "https://micomercio.com/picture_url"

notify_urlstring<= 1024 characters

The address of the web-service that khipu will use to notify when the payment is reconciled.

Example: "https://micomercio.com/webhook/notify_url"

contract_urlstring<= 1024 characters

The URL address of the PDF file with the contract to be signed through this payment. The merchant must be enabled for this service and the fixed_payer_personal_identifier field is required.

Example: "https://micomercio.com/contract_url"

notify_api_versionstring<= 255 characters

Version of the notifications API to receive notifications by web-service.

Example: "3.0"

expires_datestring(date-time)

Maximum date to execute the payment (in ISO-8601 format). The client may make several payment attempts until said date. Each attempt has an individual period of 3 hours for its execution.

Example: "2023-12-31T15:45:00-04:00"

send_emailboolean

If true, a collection request will be sent to the email specified in payer_email.

Example: false

payer_namestring<= 255 characters

Payer's name. It is required when send_email is true.

Example: "Nombre Pagador"

payer_emailstring(email)<= 255 characters

Payer's email. Required when send_email is true.

Example: "pagador@email.com"

send_remindersboolean

If true, collection reminders will be sent.

Example: true

responsible_user_emailstring(email)<= 255 characters

Email of the person responsible for this collection, must correspond to a khipu user with permissions to collect using this collection account.

Example: "responsible@email.com"

fixed_payer_personal_identifierstring<= 255 characters

Personal identifier. If specified, payment can only be made using that identifier.

Example: "11.000.111-9"

integrator_feestring<= 16 characters

Fee for the integrator. It is only valid if the collection account has an associated integrator account.

Example: "100"

collect_account_uuidstring<= 255 characters

For collection accounts with more own account. Allows you to choose the account where the transfer should occur.

Example: "007367340234"

confirm_timeout_datestring(date-time)

Collection submission date. It is also the final date to be able to refund the charge. ISO-8601 format.

Example: "2017-03-01T13:00:00Z"

mandatory_payment_methodstring<= 255 characters

The charge can only be paid using the specified payment method. Possible values for this field are found in the id field of the response from the /api/3.0/merchants/paymentMethods endpoint.

Example: "simplified_transfer"

psp_client_merchant_namestring[ 3 .. 255 ] characters

Name of the end merchant for whom a Payment Service Provider is processing a payment. Required for PSP client transactions; not applicable for others. In the case of a PSP of PSPs, they must be entered separated by '->'

Example: "PSP 1->PSP 2->Client Name"

curl -i -X POST \
  https://payment-api.khipu.com/v3/payments \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "amount": 1000,
    "currency": "CLP",
    "subject": "Cobro de prueba"
  }'

Responses

Successful operation. Returns a JSON object with the information of the payment created.

Bodyapplication/json

payment_idstringrequired

Example: "gqzdy6chjne9"

payment_urlstringrequired

Main payment URL, if the user has not previously chosen a payment method, the options are shown.

Example: "https://khipu.com/payment/info/gqzdy6chjne9"

simplified_transfer_urlstringrequired

Simplified payment URL.

Example: "https://app.khipu.com/payment/simplified/gqzdy6chjne9"

transfer_urlstringrequired

Normal payment URL.

Example: "https://khipu.com/payment/manual/gqzdy6chjne9"

app_urlstringrequired

URL to invoke payment from a mobile device using the Khipu APP.

Example: "khipu:///pos/gqzdy6chjne9"

ready_for_terminalbooleanrequired

It is true if the payment already has all the necessary data to directly open the Khipu payment application.

Example: false

Response

application/json

{
  "payment_id": "gqzdy6chjne9",
  "payment_url": "https://khipu.com/payment/info/gqzdy6chjne9",
  "simplified_transfer_url": "https://app.khipu.com/payment/simplified/gqzdy6chjne9",
  "transfer_url": "https://khipu.com/payment/manual/gqzdy6chjne9",
  "app_url": "khipu:///pos/gqzdy6chjne9",
  "ready_for_terminal": false
}

Refund payment by Id

Request

Refunds all or part of the amount of a payment. This operation can only be carried out in businesses that collect in a Khipu account and before the corresponding funds are delivered.

Security

Api-Key

Path

idstring<= 255 charactersrequired

Payment identifier

Bodyapplication/json

amountnumber(double)

The amount to be returned. Without thousands separator and using '.' as a decimal separator. Up to 4 decimal places, depending on currency. If it is omitted, the refund will be made for the total payment amount.

Example: 1000

curl -i -X POST \
  'https://payment-api.khipu.com/v3/payments/{id}/refunds' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d '{}'

Responses

Successful operation.

Bodyapplication/json

messagestringrequired

Message to be displayed to the user.

Example: "Message."

Response

application/json

{
  "message": "Message."
}

Get payment prediction

Request

Prediction about the outcome of a payment, whether it will succeed or not. Additional information such as maximum possible transfer to a new recipient.

Security

Api-Key

Query

payer_emailstring<= 255 charactersrequired

Email of the payer

bank_idstring<= 255 charactersrequired

Identifier of the originating bank

amountstring<= 255 charactersrequired

Payment amount

currencystring<= 255 charactersrequired

Currency in ISO-4217 format

curl -i -X GET \
  'https://payment-api.khipu.com/v3/predict?amount=string&bank_id=string&currency=string&payer_email=string' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

Successful operation. Returns a JSON object with the prediction along with additional information.

Bodyapplication/json

new_destinatary_max_amountnumber(double)required

Maximum amount to transfer to a new recipient.

Example: 100000

max_amountnumber(double)required

The maximum possible amount to transfer.

Example: 5000000

resultstringrequired

The result of the prediction.

Enum"ok""new_destinatary_amount_exceeded""max_amount_exceeded""new_destinatary_cool_down""not_available_account"

Example: "ok"

cool_down_datestringrequired

End date for the amount restriction in ISO-8601 format.

Example: "2024-06-21T11:23:09.123Z"

Response

application/json

{
  "result": "ok",
  "max_amount": 5000000,
  "cool_down_date": "2024-06-21T11:23:09.123Z",
  "new_destinatary_max_amount": 100000
}

Post receiver

Request

Warning: This feature is only available to customers who have contracted it independently. To use it, please contact us at soporte@khipu.com

Create a new collection account associated with an integrator.

Security

Api-Key

Bodyapplication/json

admin_first_namestring<= 255 charactersrequired

First name of the administrator of the collection account to be created.

Example: "Nombre"

admin_last_namestring<= 255 charactersrequired

Last name of the administrator of the collection account to be created.

Example: "Apellido"

admin_emailstring(email)<= 255 charactersrequired

Email of the administrator of the collection account to be created.

Example: "admin@email.com"

country_codestring<= 2 charactersrequired

ISO 3166-1 two-character alphanumeric code of the country of the collection account to be created.

Example: "CL"

business_identifierstring[ 8 .. 255 ] charactersrequired

Tax identifier of the merchant associated with the collection account to be created.

Example: "99.999.999-9"

business_categorystring<= 255 charactersrequired

Tax category or tax item of the merchant associated with the collection account to be created.

Example: "VENTA AL POR MAYOR DE FRUTAS Y VERDURAS"

business_namestring<= 255 charactersrequired

Tax name of the merchant associated with the collection account to be created.

Example: "Nombre Tributario"

business_phonestring[ 5 .. 20 ] charactersrequired

Telephone of the merchant associated with the collection account to be created.

Example: "+56988887777"

business_address_line_1string[ 4 .. 300 ] charactersrequired

Address of the merchant of the collection account to be created.

Example: "Calle principal 1111"

business_address_line_2string[ 4 .. 300 ] charactersrequired

Second line of the address of the merchant of the collection account to be created.

Example: "Oficina 3-A"

business_address_line_3string[ 4 .. 300 ] charactersrequired

Third line of the address of the merchant of the collection account to be created.

Example: "Santiago"

contact_full_namestring<= 255 charactersrequired

Name of the merchant's contact.

Example: "Nombre Contacto"

contact_job_titlestring<= 255 charactersrequired

Position of the merchant contact.

Example: "Tesorero"

contact_emailstring(email)<= 255 charactersrequired

Email address of the merchant's contact.

Example: "contacto@email.com"

contact_phonestring[ 5 .. 20 ] charactersrequired

Merchant's contact phone number.

Example: "+56955553333"

bank_account_bank_idstring<= 5 characters

Bank identifier.

Example: "SDdGj"

bank_account_typestring<= 255 characters

Account type. It is required if the alternative trusted integrator model is used.

Example: "Cuenta Corriente"

bank_account_identifierstring<= 50 characters

Personal identifier of the owner of the bank account.

Example: "11.333.555-7"

bank_account_namestring<= 255 characters

Bank account name.

Example: "Alias Cuenta"

bank_account_numberstring<= 255 characters

Bank account number.

Example: "00347909823"

notify_urlstring<= 1024 characters

Default URL for the webservice where the payment will be notified.

Example: "http://micomercio.com/account/notify_url"

rendition_urlstring<= 1024 characters

URL for the webservice where the accountability will be notified.

Example: "http://micomercio.com/account/rendition_url"

curl -i -X POST \
  https://payment-api.khipu.com/v3/receivers \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "admin_first_name": "Nombre",
    "admin_last_name": "Apellido",
    "admin_email": "admin@email.com",
    "country_code": "CL",
    "business_identifier": "99.999.999-9",
    "business_category": "VENTA AL POR MAYOR DE FRUTAS Y VERDURAS",
    "business_name": "Nombre Tributario",
    "business_phone": "+56988887777",
    "business_address_line_1": "Calle principal 1111",
    "business_address_line_2": "Oficina 3-A",
    "business_address_line_3": "Santiago",
    "contact_full_name": "Nombre Contacto",
    "contact_job_title": "Tesorero",
    "contact_email": "contacto@email.com",
    "contact_phone": "+56955553333"
  }'

Responses

Successful operation. Returns a JSON object with the identifier and secret of the new collection account.

Bodyapplication/json

receiver_idstringrequired

Unique identifier of the collection account.

Example: "934568"

secretstringrequired

Secret key to the collection account, used to sign all requests.

Example: "b2025dc47a29a04592fa3c1191110370db0e208c"

Response

application/json

{
  "receiver_id": "934568",
  "secret": "b2025dc47a29a04592fa3c1191110370db0e208c"
}

Get payment methods

Request

Lists available payment methods for a given collection account.

Security

Api-Key

Path

idnumberrequired

Collection account identifier

curl -i -X GET \
  'https://payment-api.khipu.com/v3/merchants/{id}/paymentMethods' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

Successful operation. Returns a JSON object with the array of available payment methods.

Bodyapplication/json

paymentMethodsArray of objectsnon-emptyrequired

Array with available payment methods.

idstringrequired

Payment method identifier.

Example: "simplified_transfer"

namestringrequired

Name of the payment method.

Example: "simplified_transfer"

logo_urlstringrequired

URL of the suggested logo to display.

Example: "https://s3.amazonaws.com/static.khipu.com/buttons/2015/150x50-transparent.png"

Response

application/json

{
  "paymentMethods": [
    {
      "id": "simplified_transfer",
      "name": "simplified_transfer",
      "logo_url": "https://s3.amazonaws.com/static.khipu.com/buttons/2015/150x50-transparent.png"
    }
  ]
}

Instant Payment API (v3.0)

Get banks

Request

Responses

Was this helpful?

Confirm payment by Id

Request

Responses

Was this helpful?

Get payment by Id

Request

Responses

Was this helpful?

Delete payment by Id

Request

Responses

Was this helpful?

Create payment

Request

Responses

Was this helpful?

Refund payment by Id

Request

Responses

Was this helpful?

Get payment prediction

Request

Responses

Was this helpful?

Post receiver

Request

Responses

Was this helpful?

Get payment methods

Request

Responses

Was this helpful?