Pagos Automáticos
/
Automatic Payments API
/
Subscription creation

Automatic Payment API (v1.0)

The Automatic Payment API (version 1.0) by Khipu allows merchants to set up recurring payment subscriptions using bank debits (PAC). Through the POST /v1/automatic-payment/subscription endpoint, merchants submit details such as the subscription name, customer email, maximum amount, currency, and URLs for notification, return, or cancellation. Upon success, the API returns a unique subscription_id and a redirect_url where the user can authorize the debit mandate with their bank. Merchants can later query and manage the PAC status using additional endpoints. Authentication is handled via the x-api-key header.

Download OpenAPI description
openapi.json
openapi.yaml
Overview
License

Khipu Automatic Payment API

Languages
Servers
Production

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

Subscription creation

Request

This method creates a new subscription.

Security
Api-Key
Bodyapplication/jsonrequired
namestring<= 255 charactersrequired

Name to identify the subscription.

Example: "Service XYZ Id 11.222.333-0"
emailstring<= 255 charactersrequired

The customer e-mail.

Example: "personal.email@gmail.com"
max_amountnumber<= 255 charactersrequired

max amount for every charge intent.

Example: 1000
currencystring<= 4 charactersrequired

the currency code in the ISO 4217.

Example: "CLP"
notify_urlstring<= 1024 charactersrequired

URL that will be called when the customer complete the signing process with the bank. A JSON message will be sent via POST with the information of the subscription with the following structure (status can be "enabled" or "disabled"):

  {
    "subscription_id": string,
    "status": "enabled"
  }
Example: "https://my-domain.biz/subscription-notify-api"
return_urlstring<= 1024 charactersrequired

URL to redirect the customer when the signing process has been completed.

Example: "https://my-domain.biz/subscription-result"
cancel_urlstring<= 1024 charactersrequired

URL to redirect the customer if the signing process could not be completed.

Example: "https://my-domain.biz/subscription-cancel"
service_referencestring

Value to associate with the subscription. It can be useful when you don't want your client to be identified with a random unique string in the bank's mandate subscription form.

Example: "12345678K"
image_urlstring<= 1024 characters

URL of the image associated with the subscription.

Example: "https://my-domain.biz/subscription-image.png"
descriptionstring

Detailed description of the PAC (Automatic Payment) subscription carried out at banks for products.

Example: "PAC subscription for automatic payment of products at your bank."
curl -i -X POST \
  https://payment-api.khipu.com/v1/automatic-payment/subscription \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "name": "Service XYZ Id 11.222.333-0",
    "email": "personal.email@gmail.com",
    "max_amount": 1000,
    "currency": "CLP",
    "notify_url": "https://my-domain.biz/subscription-notify-api",
    "return_url": "https://my-domain.biz/subscription-result",
    "cancel_url": "https://my-domain.biz/subscription-cancel"
  }'

Responses

Successful operation. Returns a JSON object with the subscription id that can be used to ask the customer to sign the direct debit mandate.

Bodyapplication/json
subscription_idstring<= 255 charactersrequired

Unique subscription identifier, to be associated with the service acquired by the customer. Subsequently, this value can be used to check the status of the subscription.

Example: "13a0f1aa-5e47-4894-aa8b-282dd19593ec"
redirect_urlstring<= 1024 charactersrequired

The url where the merchant must redirect the user so that they can sign the subscription with their personal bank. It uses the subscription id as a url parameter.

Example: "https://khipu.com/pac-manager/13a0f1aa-5e47-4894-aa8b-282dd19593ec"
Response
application/json
{
  "subscription_id": "13a0f1aa-5e47-4894-aa8b-282dd19593ec",
  "redirect_url": "https://khipu.com/pac-manager/13a0f1aa-5e47-4894-aa8b-282dd19593ec"
}

Subscription status

Request

This method get the current state of a automatic payment subscription.

Security
Api-Key
Path
idstring<= 255 charactersrequired

unique identifier of a subscription.

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

Responses

Successful operation. Returns a JSON object with the subscription id information.

Bodyapplication/json
subscription_idstring<= 255 charactersrequired

Unique subscription identifier.

Example: "13a0f1aa-5e47-4894-aa8b-282dd19593ec"
statusstringrequired

The current status of the subscription. A charge intent can only be made if the status is ENABLED.

Enum"DISABLED""SIGNED""ENABLED"
Example: "SIGNED"
developerbooleanrequired

Indicates if the subscription was created using the sandbox environment. A false value means that is a production subscription.

Example: false
customer_bank_codestring<= 255 charactersrequired

The bank used by the customer to sign the subscription. The possible values are the ones used in the Khipu Payment API, or no-bank if the subscription has not been signed.

Example: "8"
service_referencestring<= 255 charactersrequired

The alias used to identify the subscription.

Example: "My Merchant name"
Response
application/json
{
  "subscription_id": "13a0f1aa-5e47-4894-aa8b-282dd19593ec",
  "status": "SIGNED",
  "developer": false,
  "customer_bank_code": "8",
  "service_reference": "My Merchant name"
}

Charge intent creation

Request

This method creates a new charge request for the specified subscription.

Security
Api-Key
Bodyapplication/jsonrequired
subscription_idstring<= 255 charactersrequired

The subscription id that will be charged.

Example: "13a0f1aa-5e47-4894-aa8b-282dd19593ec"
amountnumber(float)>= 1required

Amount that will be charged. Do not use thousands separator, and a maximum of 4 decimal places. It will assume the currency in which the merchant registered its account in Khipu.

Example: 10000
subjectstring<= 255 charactersrequired

Subject to identify the charge.

Example: "Charge Service XYZ Id 11.222.333-0"
bodystring<= 5120 charactersrequired

Charge description.

Example: "Service XYZ - November 2022 - Amount: $10.000"
error_response_urlstring<= 1024 charactersrequired

URL that will be called if an error occurs in the charge process. A JSON will be sent by POST with the following structure:

  {
    "subscription_id": string,
    "transaction_id": string,
    "error_message": string
  }
Example: "https://my-domain.biz/charge-error-api"
customstring<= 1073741824 charactersrequired

This field can be used to send custom information about the charge intent. It can be in text format or base64-encoded document.

Example: "Custom information content."
transaction_idstring<= 255 charactersrequired

Merchant's unique identifier for this operation. For example, the invoice number.

Example: "INVOICE-23ffcfbe1e4a4d1c9dc631fe70bddaa0"
notify_urlstring<= 1024 charactersrequired

URL that will be called once the charging process finishes and the payment is conciliated. A POST will be sent with parameters that allows fetch the payment details, using the same flow of a normal payment. See the documentation for details.

Example: "https://my-domain.biz/charge-notify-api"
notify_api_versionstring<= 255 characters

API version for instant payment notification(same value as used for the payment API).

Example: "1.3"
curl -i -X POST \
  https://payment-api.khipu.com/v1/automatic-payment/charge-intent \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d '{
    "subscription_id": "13a0f1aa-5e47-4894-aa8b-282dd19593ec",
    "amount": 10000,
    "subject": "Charge Service XYZ Id 11.222.333-0",
    "body": "Service XYZ - November 2022 - Amount: $10.000",
    "error_response_url": "https://my-domain.biz/charge-error-api",
    "custom": "Custom information content.",
    "transaction_id": "INVOICE-23ffcfbe1e4a4d1c9dc631fe70bddaa0",
    "notify_url": "https://my-domain.biz/charge-notify-api"
  }'

Responses

Successful operation. Returns a JSON object with the charge intent id that can be used to trace the request of a direct debit charge.

Bodyapplication/json
payment_idstring<= 12 charactersrequired

Unique charge identifier. Represents the automatic payment id that will be used to trace the request to charge the customer's account.

Example: "v67prof2ugg3"
Response
application/json
{
  "payment_id": "v67prof2ugg3"
}