Guides
GuidesAPI ReferenceGo to DashboardSite >
Start typing to search…

ETPAY (Chile)

Localpayment enables merchants to process secure bank transfer payments through ETPAY, Chile's leading payment gateway that facilitates direct bank transfers and authentication with major Chilean financial institutions. This guide outlines the process for initiating ETPAY-based payments through Localpayment's API, detailing required parameters, handling responses, and interpreting status codes for seamless integration with Chile's banking infrastructure.

Before You Begin

Ensure you have:

Step 1. Create ETPAY Payment

To initiate a ETPAY payment in Chile, send a POST request to the Create Payin endpoint with ETPAY-specific parameters.

Key Request Parameters

The request requires several key objects specific to Chile ETPAY payments:

ObjectDescriptionRequired
paymentMethod.typeMust be BankTransfer.✅
paymentMethod.codeUse 2528 for Chile ETPAY.✅
senderSender information for compliance.✅
merchantMerchant/business details.✅
paymentMethodPayment method configuration.✅
amountTransaction amount.✅
currencyTransaction currency code.✅
countryMust be CHL.✅

See all available parameters in the request.

Example Request

Below is an example using curl:

curl --request POST \
     --url https://api.stage.localpayment.com/api/payin/ \
     --header 'accept: application/json' \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'content-type: application/json' \
     --data '
{
  "paymentMethod": {
    "type": "BankTransfer",
    "code": "2528",
    "flow": "REDIRECT"
  },
  "currency": "CLP",
  "merchant": {
    "type": "COMPANY",
    "document": {
      "type": "RUT",
      "id": "{{id}}"
    },
    "name": "Company",
    "email": "[email protected]"
  },
  "payer": {
    "type": "INDIVIDUAL",
    "document": {
      "type": "RUT",
      "id": "{{id}}"
    },
    "phone": {
      "areaCode": "57",
      "countryCode": "57",
      "number": "12345678"
    },
    "address": {
      "country": "CHL",
      "number": "",
      "state": "RM",
      "city": "RM",
      "street": "Street",
      "comment": ""
    },
    "bank": {
      "account": {
        "type": "c",
        "number": "{{bankAccountNumber}}"
      },
      "name": "Banco Estado",
      "code": "012"
    },
    "name": "John",
    "lastname": "Doe",
    "email": "[email protected]"
  },
  "externalId": "c8b360f1-895e-483d-b734-e3ea17eb2b63",
  "country": "CHL",
  "amount": 100,
  "accountNumber": "{{AccountNumber}}",
  "conceptCode": "0038",
  "comment": "Payer"
}
'

Step 2. Handle the Response

Successful Response

A successful ETPAY payment creation includes the redirect URL and transaction details:

{
  "transactionType": "PayIn",
  "externalId": "7e6c8cd9-55ea-4f94-8f05-f0e13fb24e78",
  "internalId": "6b9dfc0b-1fa0-44b4-a4ff-fd46007ae9a2",
  "paymentMethod": {
    "type": "BankTransfer",
    "code": "2528",
    "flow": "REDIRECT"
  },
  "country": "CHL",
  "currency": "CLP",
  "amount": 100,
  "accountNumber": "{{AccountNumber}}",
  "confirmed": {
    "currency": "CLP",
    "amount": 1,
    "fxQuote": 0
  },
  "payment": {
    "currency": "CLP",
    "fxQuote": 0,
    "financingFee": 0,
    "amount": 1
  },
  "localTaxes": [],
  "withHoldings": [],
  "fees": {
    "description": "Fee",
    "currency": "CLP",
    "fxSource": 1,
    "fxQuote": 1,
    "amount": 0,
    "account": "{{Account}}"
  },
  "status": {
    "code": "100",
    "description": "INPROGRESS",
    "detail": "The payin is pending the confirmation"
  },
  "merchant": {
    "type": "COMPANY",
    "name": "Company",
    "document": {
      "type": "{{Type}}",
      "id": "{{documentId}}"
    },
    "email": "[email protected]"
  },
  "payer": {
    "bank": {
      "name": "Banco Estado",
      "code": "012",
      "account": {
        "type": "c",
        "number": "{{Number}}"
      }
    },
    "type": "INDIVIDUAL",
    "name": "John",
    "lastname": "Doe",
    "document": {
      "type": "RUT",
      "id": "{{documentId}}"
    },
    "email": "[email protected]",
    "phone": {
      "countryCode": "57",
      "areaCode": "57",
      "number": "3196741234"
    },
    "address": {
      "street": "Calle 123",
      "number": "0012",
      "city": "RM",
      "state": "RM",
      "country": "CHL",
      "comment": ""
    }
  },
  "intermediaries": [],
  "wireInstructions": {
    "referenceCode": "FDEG-HVCF-JUWX"
  },
  "date": {
    "creationDate": "2024-12-01T15:44:55.058+00:00",
    "processedDate": "2024-12-01T15:45:01.4368519",
    "expirationDate": "2024-12-08T15:44:55.4677488"
  },
  "redirectUrl": "https://web-checkout.stage.localpayment.com/redirect/aHR0cHM6Ly9wbXQtc2FuZGJveC5ldHBheS5jb20vc2Vzc2lvbi9mT09OZkdvcEVuM1F4RUs4aUZKcWVEdGpadDU5T3ExcjhOamNUM213aFNFbjN0S2sxSzNLcXVtUjk5dTFKTFVS",
  "errors": []
}

Key Response Fields

ParameterDescriptionUse Case
redirectUrlURL to redirect customer to ETPAY payment flow.Direct customer to bank authentication and payment processing.
wireInstructions.referenceCodeUnique payment reference code.Display to customer for payment tracking.
externalIdYour original reference number.Internal reconciliation and order matching.
status.codeCurrent transaction state (100 = INPROGRESS)Determine next steps in payment flow.
date.creationDateWhen transaction was created.Analytics and performance tracking.

Error Response

When ETPAY payment creation fails for Chile, you'll receive specific error information:

{
  "externalId": "ce0aaa1a-4532-43b9-930a-26e780aba99b",
  "status": {
    "code": "812",
    "description": "REJECTED"
  },
  "errors": [
    {
      "code": "812",
      "detail": "External Id already used - duplication"
    }
  ]
}

Step 3. Handle ETPAY Payment Flow

  1. Payment Initiation: Redirect customer to ETPAY payment url.
  2. Bank Selection: Customer selects their Chilean bank from supported institutions.
  3. Bank Authentication: Customer logs into their online banking environment.
  4. Payment Authorization: Customer confirms payment within their banking interface.
  5. Real-time Confirmation: Localpayment receives payment notification.
  6. Status Update: Your system receives webhook with payment confirmation.

Step 4. Track Transaction Status

Monitor ETPAY payment progress through these methods:

Webhooks (Recommended)

Receive real-time notifications when transaction status changes. Most efficient for production environments.

Status API Endpoint

Query transaction status programmatically. Useful for polling or recovering lost webhook notifications.

Dashboard View

Visual interface for monitoring transactions. Great for manual oversight and detailed transaction analysis.

Common Status Codes

The Localpayment API provides various status codes to indicate the progress and outcome of the payment in the response.

CodeStatusDescription
103APPROVEDThe payin was confirmed but not credited yet.
200CompletedThe payin was completed.
811RejectedRequested amount is higher or lower than allowed max/min values.

📝

Note: For complete status code reference, see the Transaction Status Documentation.

Testing Your Integration

Sandbox Environment

Use the staging environment for testing:

https://api.stage.localpayment.com/api/payin/

Test Scenarios for Chile

Verify your integration handles these scenarios:

  1. Successful Payment: Complete ETPAY payment flow with bank simulation.
  2. Bank Authentication: Test different bank authentication flows.
  3. Payment Expiration: Handle payment link expiration gracefully.
  4. Authentication Failure: Test failed bank login scenarios.
  5. Bank Rejection: Simulate bank-side payment rejection.
  6. Status Updates: Webhook handling and status polling.

Next Steps

After implementing ETPAY payments, consider these additional capabilities:

Refund the transaction

If necessary, you can refund the payment to the customer. Refer to the documentation for details.

Review transaction details

You can retrieve transaction information using the Localpayment API for detailed insights.


Updated 3 days ago