JupiPay

JupiPay
API Documentation

API Reference

Welcome to the JupiPay Payments API reference. This document provides detailed information about all available endpoints, authentication methods, and error handling.

Authentication

The JupiPay API uses API Keys for authentication. You must include an Authorization header in all requests with your API key as a Bearer token. This is the standard and recommended authentication method for all endpoints.

Example Request Header


# Standard authentication method
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json

Rate Limiting

The API is rate-limited to prevent abuse. The default limit for most endpoints is 60 requests per minute per API key. If you exceed this limit, you will receive a 429 Too Many Requests response.

Webpay Plus

Endpoints for creating and managing one-time payments through the Webpay Plus service.

POST /api/v1/webpay/transactions

Create Transaction

Initiates a new Webpay Plus transaction. This will return a URL and a token to redirect the user to the Transbank payment form.

Parameters

buy_order required
string

A unique identifier for the purchase order. Max 26 characters. If not provided, a unique one will be generated.

session_id required
string

A unique identifier for the user session. Max 61 characters. If not provided, a unique one will be generated.

amount required
integer

The total amount to be paid. Must be between 50 and 10,000,000.

return_url required
string (url)

The URL where the user will be redirected back after completing the payment process on Transbank's site.

Example Response


{
  "success": true,
  "message": "Transaction created successfully",
  "data": {
    "transaction": {
      "token": "e8ad219e273f8e4a3df5db8ac62c62c8a38a719cbf4b5d4b5d4b5d4b5d4b5d4b",
      "url": "https://webpay3gint.transbank.cl/webpayserver/initTransaction",
      "buy_order": "WEB-1678886400",
      "session_id": "sid_62c62c8a38a719cbf4b",
      "amount": 10000,
      "return_url": "https://your-store.com/webpay/return"
    },
    "correlation_id": "corr_id_12345"
  }
}
PUT /api/v1/webpay/transactions/{token}/commit

Commit Transaction

Confirms a transaction after the user has returned from the Transbank payment gateway. This endpoint verifies the payment status and must be called to finalize the transaction.

Parameters

token required
string

The token received when creating the transaction. Transbank also sends this token as a POST parameter (`TBK_TOKEN`) to your `return_url`.

Example Response


{
  "success": true,
  "message": "Transaction committed successfully",
  "data": {
    "transaction": {
      "buy_order": "WEB-1678886400",
      "session_id": "sid_62c62c8a38a719cbf4b",
      "amount": 10000,
      "status": "AUTHORIZED",
      "response_code": 0,
      "authorization_code": "1213",
      "payment_type_code": "VN",
      "installments_number": 0,
      "card_detail": {
        "card_number": "6623"
      },
      "accounting_date": "0706",
      "transaction_date": "2024-07-06T14:30:00.000Z",
      "is_approved": true,
      "status_text": "Transaction Approved"
    },
    "correlation_id": "corr_id_67890"
  }
}
GET /api/v1/webpay/transactions/{token}/status

Get Transaction Status

Checks the current status of a transaction using its token. This is useful for verifying if a payment is still pending, has been completed, or failed, especially if the commit process was interrupted.

Parameters

token required
string

The token received when creating the transaction.

Example Response


{
  "success": true,
  "message": "Transaction status retrieved successfully",
  "data": {
    "transaction": {
        "vci": "TSY",
        "buy_order": "WEB-1678886400",
        "session_id": "sid_62c62c8a38a719cbf4b",
        "amount": 10000,
        "status": "AUTHORIZED",
        "response_code": 0,
        "authorization_code": "1213",
        "payment_type_code": "VN",
        "installments_number": 0,
        "card_detail": {
            "card_number": "6623"
        },
        "accounting_date": "0706",
        "transaction_date": "2024-07-06T14:30:00.000Z",
        "is_approved": true,
        "status_text": "Transaction Approved"
    },
    "correlation_id": "corr_id_54321"
  }
}
POST /api/v1/webpay/transactions/{token}/refund

Refund Transaction

Initiates a full or partial refund for a completed transaction.

Parameters

token required
string

The token of the transaction to be refunded.

amount required
integer

The amount to refund. Must be less than or equal to the original transaction amount.

Example Response


{
  "success": true,
  "message": "Transaction refunded successfully",
  "data": {
    "refund": {
        "type": "REVERSED",
        "balance": 0,
        "response_code": 0,
        "authorization_code": "654321",
        "nullified_amount": 10000
    },
    "correlation_id": "corr_id_11223"
  }
}

PatPass

Endpoints for creating and managing recurring subscriptions via PatPass.

POST /api/v1/patpass/subscriptions

Create Subscription

Initiates a new PatPass subscription. Returns a URL and token to redirect the user for authorization.

Parameters

return_url required
string (url)

URL where the user is redirected after the inscription process begins.

final_url required
string (url)

URL where the user is redirected after a successful or failed inscription.

rut required
string

The subscriber's RUT (Chilean National ID).

name required
string

Subscriber's first name.

last_name required
string

Subscriber's first last name.

second_last_name required
string

Subscriber's second last name.

patpass_name required
string

Name to display for the PatPass service in the bank statement.

max_amount required
integer

The maximum amount that can be charged per transaction.

person_email required
string (email)

The subscriber's personal email.

commerce_email required
string (email)

The commerce's notification email.

phone required
string

Subscriber's landline phone.

cell_phone required
string

Subscriber's mobile phone.

address required
string

Subscriber's address.

city required
string

Subscriber's city.

service_id required
string

A unique identifier for the service. If not provided, one will be generated.

Example Response


{
  "success": true,
  "message": "Subscription created successfully",
  "data": {
    "subscription": {
      "token": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
      "url": "https://webpay3gint.transbank.cl/webpayserver/inscription",
      "service_id": "sid_123456789"
    },
    "correlation_id": "corr_id_patpass_123"
  }
}
PUT /api/v1/patpass/subscriptions/{token}/confirm

Confirm Subscription

Confirms a PatPass subscription after the user has authorized it. This is the final step in the subscription process.

Parameters

token required
string

The token received when creating the subscription.

Example Response


{
  "success": true,
  "message": "Subscription confirmed successfully",
  "data": {
    "subscription": {
      "subscription_id": "sub_abcdef123456",
      "status": "ACTIVE",
      "is_active": true,
      "next_payment_date": "2024-08-01"
    },
    "correlation_id": "corr_id_patpass_456"
  }
}
GET /api/v1/patpass/subscriptions/{subscriptionId}/status

Get Subscription Status

Retrieves the current status and details of an active PatPass subscription.

Parameters

subscriptionId required
string

The unique identifier for the subscription (`sub_...`).

Example Response


{
  "success": true,
  "message": "Subscription status retrieved successfully",
  "data": {
    "subscription": {
      "subscription_id": "sub_abcdef123456",
      "status": "ACTIVE",
      "is_active": true,
      "amount": 10000,
      "next_payment_date": "2024-08-01",
      "payments_count": 5,
      "last_payment_date": "2024-07-01",
      "card_info": {
        "type": "CREDIT",
        "last_four_digits": "1234"
      }
    },
    "correlation_id": "corr_id_patpass_789"
  }
}
POST /api/v1/patpass/subscriptions/{subscriptionId}/charge

Charge Subscription

Executes a charge on an active PatPass subscription.

Parameters

subscriptionId required
string

The unique identifier for the subscription (`sub_...`).

amount required
integer

The amount to charge. Must be less than or equal to the `max_amount` defined at creation.

commerce_order required
string

A unique identifier for this specific charge. If not provided, one will be generated.

Example Response


{
  "success": true,
  "message": "Subscription charged successfully",
  "data": {
    "charge": {
      "transaction_id": "tx_123456789",
      "status": "AUTHORIZED",
      "amount": 5000,
      "authorization_code": "123456",
      "transaction_date": "2024-07-06T15:00:00.000Z"
    },
    "correlation_id": "corr_id_patpass_101"
  }
}
DELETE /api/v1/patpass/subscriptions/{subscriptionId}

Cancel Subscription

Cancels an active PatPass subscription. This action is irreversible.

Parameters

subscriptionId required
string

The unique identifier for the subscription (`sub_...`).

Example Response


{
  "success": true,
  "message": "Subscription cancelled successfully",
  "data": {
    "subscription": {
      "subscription_id": "sub_abcdef123456",
      "status": "INACTIVE"
    },
    "correlation_id": "corr_id_patpass_112"
  }
}

Oneclick

Endpoints for managing tokenized card payments (payment on file).

POST /api/v1/oneclick/inscriptions

Start Inscription

Initiates a new card inscription process for a user. Returns a URL to redirect the user to Transbank to authorize the tokenization.

Parameters

username required
string

A unique identifier for the user within your system.

email required
string (email)

The user's email address.

response_url required
string (url)

The URL where the user will be redirected back after the inscription process.

Example Response


{
  "success": true,
  "message": "Inscription started successfully",
  "data": {
    "inscription": {
      "token": "01abf2be78a5b2857e873918a3818e6c7050519342455953534b868e4f5853f7",
      "url_webpay": "https://webpay3gint.transbank.cl/webpayserver/inscription",
      "username": "user123"
    },
    "correlation_id": "corr_id_oneclick_123"
  }
}
PUT /api/v1/oneclick/inscriptions/{token}/confirm

Confirm Inscription

Confirms the card inscription after the user returns from Transbank. This finalizes the tokenization process.

Parameters

token required
string

The token received when starting the inscription. Transbank also sends this as `TBK_TOKEN` to your `response_url`.

Example Response


{
  "success": true,
  "message": "Inscription confirmed successfully",
  "data": {
    "inscription": {
      "tbk_user": "a9b8c7d6-e5f4-g3h2-i1j0-k9l8m7n6o5p4",
      "authorization_code": "1213",
      "card_type": "Visa",
      "card_number": "************6623",
      "response_code": 0,
      "status": "Inscription Approved",
      "is_approved": true
    },
    "correlation_id": "corr_id_oneclick_456"
  }
}
POST /api/v1/oneclick/inscriptions/authorize

Authorize Payment

Authorizes a payment using a user's tokenized card (`tbk_user`).

Parameters

username required
string

The unique identifier for the user in your system.

tbk_user required
string

The `tbk_user` token obtained after a successful inscription.

buy_order required
string

A unique identifier for the purchase order.

amount required
integer

The amount to be charged.

Example Response


{
  "success": true,
  "message": "Payment authorized successfully",
  "data": {
    "payment": {
      "vci": "TSY",
      "amount": 10000,
      "status": "AUTHORIZED",
      "buy_order": "order-12345",
      "session_id": "session-67890",
      "card_detail": {
        "card_number": "6623"
      },
      "accounting_date": "0708",
      "transaction_date": "2024-07-08T12:00:00.000Z",
      "authorization_code": "1213",
      "payment_type_code": "VN",
      "response_code": 0,
      "installments_amount": 10000,
      "installments_number": 1,
      "balance": 0,
      "is_approved": true,
      "status_text": "Payment Authorized"
    },
    "correlation_id": "corr_id_oneclick_789"
  }
}
POST /api/v1/oneclick/inscriptions/{transactionId}/refund

Refund Payment

Refunds a previously authorized payment.

Parameters

transactionId required
string

The `buy_order` of the transaction to be refunded.

amount required
integer

The amount to refund.

Example Response


{
  "success": true,
  "message": "Payment refunded successfully",
  "data": {
    "refund": {
      "type": "REVERSED",
      "response_code": 0,
      "authorization_code": "654321",
      "nullified_amount": 10000,
      "balance": 0
    },
    "correlation_id": "corr_id_oneclick_101"
  }
}
DELETE /api/v1/oneclick/inscriptions/{tbkUser}

Remove Inscription

Deletes a user's tokenized card information. This action is irreversible.

Parameters

tbkUser required
string

The `tbk_user` token to be removed.

Example Response


{
  "success": true,
  "message": "Inscription removed successfully",
  "data": {
    "removed": true
  },
  "correlation_id": "corr_id_oneclick_112"
}
GET /api/v1/oneclick/inscriptions/{tbkUser}

Get Inscription Details

Retrieves details about a specific card inscription.

Parameters

tbkUser required
string

The `tbk_user` token.

Example Response


{
  "success": true,
  "message": "Inscription details retrieved successfully",
  "data": {
    "inscription": {
      "card_type": "Visa",
      "card_number": "************6623",
      "status": "ACTIVE"
    },
    "correlation_id": "corr_id_oneclick_113"
  }
}

SII (Invoicing)

Endpoints for managing electronic invoices (DTE - Documentos Tributarios Electrónicos) with the Chilean SII (Servicio de Impuestos Internos).
Note: These endpoints require session-based authentication (Sanctum) and are intended for backend or dashboard usage, not public API key access.

GET /api/v1/invoices

List Invoices

Retrieves a paginated list of electronic invoices, with support for filtering and searching.

Parameters

status required
string

Filter by status (e.g., `draft`, `sent`, `accepted`, `rejected`).

customer_rut required
string

Filter by the customer's RUT.

issuer_rut required
string

Filter by the issuer's RUT.

date_from required
string (date)

Start of the date range (YYYY-MM-DD).

date_to required
string (date)

End of the date range (YYYY-MM-DD).

search required
string

Search term for customer name, email, or invoice number.

per_page required
integer

Number of results per page (default: 15).

Example Response


{
  "data": [
    {
      "id": 1,
      "invoice_type": "boleta_electronica",
      "folio_number": 123,
      "total_amount": 11900,
      "status": "accepted",
      "issue_date": "2024-07-08T10:00:00.000Z",
      "customer_name": "John Doe",
      // ... other invoice fields
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 10,
    "per_page": 15,
    "total": 150
  }
}
POST /api/v1/invoices

Create Invoice

Creates a new electronic invoice in 'draft' status. The system automatically assigns the next available folio number.

Parameters

type required
string

Type of document (e.g., `boleta_electronica`, `boleta_exenta`).

customer_rut required
string

Customer's RUT.

customer_name required
string

Customer's full name.

customer_email required
string (email)

Customer's email.

issuer_rut required
string

Issuer's RUT.

issuer_name required
string

Issuer's name.

issuer_activity required
string

Issuer's economic activity description.

items required
array

An array of invoice items.

items[].description required
string

Item description.

items[].quantity required
numeric

Item quantity.

items[].unit_price required
numeric

Item unit price.

Example Response


{
  "message": "Factura electrónica creada exitosamente",
  "data": {
    "id": 1,
    "status": "draft",
    "folio_number": 124,
    "total_amount": 15000,
    // ... complete invoice object
  }
}
GET /api/v1/invoices/{invoice}

Get Invoice Details

Retrieves the full details of a specific electronic invoice, including its items and logs.

Parameters

invoice required
integer

The ID of the invoice.

Example Response


{
  "data": {
    "id": 1,
    "status": "accepted",
    "total_amount": 11900,
    "items": [
      {
        "description": "Product A",
        "quantity": 1,
        "unit_price": 10000
      }
    ],
    "sii_logs": [
        // ... logs of interactions with SII
    ]
    // ... complete invoice object
  }
}
PUT /api/v1/invoices/{invoice}

Update Invoice

Updates an electronic invoice, but only if it is in a 'draft' or 'rejected' state.

Parameters

invoice required
integer

The ID of the invoice to update.

customer_name required
string

New customer name.

customer_email required
string (email)

New customer email.

items required
array

A new array of items to replace the existing ones.

Example Response


{
  "message": "Factura actualizada exitosamente",
  "data": {
    "id": 1,
    "customer_name": "Jane Doe",
    // ... updated invoice object
  }
}
DELETE /api/v1/invoices/{invoice}

Delete Invoice

Deletes an electronic invoice, but only if it is in a 'draft' state. This action is irreversible.

Parameters

invoice required
integer

The ID of the invoice to delete.

Example Response


{
  "message": "Factura eliminada permanentemente"
}
POST /api/v1/invoices/{invoice}/generate-dte

Generate DTE XML

Generates the DTE (XML file) for an invoice and signs it digitally. The invoice status changes to 'generated'.

Parameters

invoice required
integer

The ID of the invoice.

Example Response


{
  "message": "DTE generado y firmado exitosamente",
  "data": {
    "id": 1,
    "status": "generated",
    "sii_track_id": null
  }
}
POST /api/v1/invoices/{invoice}/send-to-sii

Send DTE to SII

Sends the generated DTE to the SII for validation. The response includes a track ID for future status checks.

Parameters

invoice required
integer

The ID of the invoice.

Example Response


{
  "message": "DTE enviado al SII exitosamente",
  "data": {
    "id": 1,
    "status": "sent",
    "sii_track_id": "1234567890"
  }
}
GET /api/v1/invoices/{invoice}/sii-status

Check SII Status

Checks the validation status of a sent DTE using its track ID.

Parameters

invoice required
integer

The ID of the invoice.

Example Response


{
  "message": "Estado de la factura actualizado",
  "data": {
    "id": 1,
    "status": "accepted",
    "sii_status_code": "EPR",
    "sii_status_description": "Envío Procesado"
  }
}