Create your first Top-up

Tip

You can use payment-attempts or create the payment directly.

A TOPUP_ACCOUNT transaction funds an internal conomy_hq account. The origin is a payment rail (e.g., ETPAY in Chile, PIX in Brazil) and the destination is an internal ACCOUNT.

Payment flow

01

Create payment

Use an external rail as origin and an internal account as destination.

02

Redirect or authorize

Send the customer to the provider URL when the rail requires it.

03

Capture

Capture the payment after authorization or provider confirmation.

04

Receive webhook

Confirm the state change from webhook delivery or sandbox simulation.

05

Check balance

Verify that the destination account reflects the settled funds.

Create Payment

Creates a top-up using a payment rail as the origin and an internal account as the destination.

The example below uses ETPAY (open banking, Chile). Replace the origins node type and sub-object to use a different rail — see the Nodes page for all available rails.

Request

HTTPcurlJavaScriptPythonGoRust

POST /sandbox/payments HTTP/1.1
Host: api.conomyhq.com
x-api-key: {YOUR_API_KEY}
Authorization: Bearer {ACCESS_TOKEN}
conomyhq-api-version: 24-04-2025
User-Agent: MyApp/1.0
Content-Type: application/json
Accept: application/json

{
  "identityId": "<IDENTITY_ID>",
  "accountNumber": "<ACCOUNT_NUMBER>",
  "product": "CLP:CLP",
  "type": "TOPUP_ACCOUNT",
  "purchaseAmount": "700000",
  "purchaseCurrency": "CLP",
  "currency": "CLP",
  "origins": [
    {
      "type": "ETPAY",
      "currency": "CLP",
      "etpay": {
        "successUrl": "https://yourapp.com/success",
        "failedUrl": "https://yourapp.com/failed",
        "customer": {
          "firstName": "John",
          "email": "john@example.com"
        }
      }
    }
  ],
  "destinations": [
    {
      "type": "ACCOUNT",
      "currency": "CLP",
      "identity": {
        "identityId": "<IDENTITY_ID>"
      },
      "account": {
        "accountNumber": "<ACCOUNT_NUMBER>"
      }
    }
  ]
}

curl -X POST 'https://api.conomyhq.com/sandbox/payments' \
  -H 'x-api-key: {YOUR_API_KEY}' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'conomyhq-api-version: 24-04-2025' \
  -H 'User-Agent: MyApp/1.0' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "identityId": "<IDENTITY_ID>",
    "accountNumber": "<ACCOUNT_NUMBER>",
    "product": "CLP:CLP",
    "type": "TOPUP_ACCOUNT",
    "purchaseAmount": "700000",
    "purchaseCurrency": "CLP",
    "currency": "CLP",
    "origins": [
      {
        "type": "ETPAY",
        "currency": "CLP",
        "etpay": {
          "successUrl": "https://yourapp.com/success",
          "failedUrl": "https://yourapp.com/failed",
          "customer": {
            "firstName": "John",
            "email": "john@example.com"
          }
        }
      }
    ],
    "destinations": [
      {
        "type": "ACCOUNT",
        "currency": "CLP",
        "identity": {
          "identityId": "<IDENTITY_ID>"
        },
        "account": {
          "accountNumber": "<ACCOUNT_NUMBER>"
        }
      }
    ]
  }'

const response = await fetch('https://api.conomyhq.com/sandbox/payments', {
  method: 'POST',
  headers: {
    'x-api-key': '{YOUR_API_KEY}',
    'Authorization': 'Bearer {ACCESS_TOKEN}',
    'conomyhq-api-version': '24-04-2025',
    'User-Agent': 'MyApp/1.0',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
  },
  body: JSON.stringify({
    "identityId": "<IDENTITY_ID>",
    "accountNumber": "<ACCOUNT_NUMBER>",
    "product": "CLP:CLP",
    "type": "TOPUP_ACCOUNT",
    "purchaseAmount": "700000",
    "purchaseCurrency": "CLP",
    "currency": "CLP",
    "origins": [
      {
        "type": "ETPAY",
        "currency": "CLP",
        "etpay": {
          "successUrl": "https://yourapp.com/success",
          "failedUrl": "https://yourapp.com/failed",
          "customer": {
            "firstName": "John",
            "email": "john@example.com"
          }
        }
      }
    ],
    "destinations": [
      {
        "type": "ACCOUNT",
        "currency": "CLP",
        "identity": {
          "identityId": "<IDENTITY_ID>"
        },
        "account": {
          "accountNumber": "<ACCOUNT_NUMBER>"
        }
      }
    ]
  }),
});

const data = await response.json();

import requests

payload = {
  "identityId": "<IDENTITY_ID>",
  "accountNumber": "<ACCOUNT_NUMBER>",
  "product": "CLP:CLP",
  "type": "TOPUP_ACCOUNT",
  "purchaseAmount": "700000",
  "purchaseCurrency": "CLP",
  "currency": "CLP",
  "origins": [
    {
      "type": "ETPAY",
      "currency": "CLP",
      "etpay": {
        "successUrl": "https://yourapp.com/success",
        "failedUrl": "https://yourapp.com/failed",
        "customer": {
          "firstName": "John",
          "email": "john@example.com"
        }
      }
    }
  ],
  "destinations": [
    {
      "type": "ACCOUNT",
      "currency": "CLP",
      "identity": {
        "identityId": "<IDENTITY_ID>"
      },
      "account": {
        "accountNumber": "<ACCOUNT_NUMBER>"
      }
    }
  ]
}

response = requests.post(
    'https://api.conomyhq.com/sandbox/payments',
    headers={
    'x-api-key': '{YOUR_API_KEY}',
    'Authorization': 'Bearer {ACCESS_TOKEN}',
    'conomyhq-api-version': '24-04-2025',
    'User-Agent': 'MyApp/1.0',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    },
    json=payload,
)

data = response.json()

package main

import (
	"bytes"
	"net/http"
)

func main() {
	payload := []byte(`{
  "identityId": "<IDENTITY_ID>",
  "accountNumber": "<ACCOUNT_NUMBER>",
  "product": "CLP:CLP",
  "type": "TOPUP_ACCOUNT",
  "purchaseAmount": "700000",
  "purchaseCurrency": "CLP",
  "currency": "CLP",
  "origins": [
    {
      "type": "ETPAY",
      "currency": "CLP",
      "etpay": {
        "successUrl": "https://yourapp.com/success",
        "failedUrl": "https://yourapp.com/failed",
        "customer": {
          "firstName": "John",
          "email": "john@example.com"
        }
      }
    }
  ],
  "destinations": [
    {
      "type": "ACCOUNT",
      "currency": "CLP",
      "identity": {
        "identityId": "<IDENTITY_ID>"
      },
      "account": {
        "accountNumber": "<ACCOUNT_NUMBER>"
      }
    }
  ]
}`)
	body := bytes.NewReader(payload)
	req, _ := http.NewRequest("POST", "https://api.conomyhq.com/sandbox/payments", body)
	req.Header.Set("x-api-key", "{YOUR_API_KEY}")
	req.Header.Set("Authorization", "Bearer {ACCESS_TOKEN}")
	req.Header.Set("conomyhq-api-version", "24-04-2025")
	req.Header.Set("User-Agent", "MyApp/1.0")
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Accept", "application/json")

	client := &http.Client{}
	resp, _ := client.Do(req)
	defer resp.Body.Close()
}

use reqwest::Client;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new();
    let payload = json!({
  "identityId": "<IDENTITY_ID>",
  "accountNumber": "<ACCOUNT_NUMBER>",
  "product": "CLP:CLP",
  "type": "TOPUP_ACCOUNT",
  "purchaseAmount": "700000",
  "purchaseCurrency": "CLP",
  "currency": "CLP",
  "origins": [
    {
      "type": "ETPAY",
      "currency": "CLP",
      "etpay": {
        "successUrl": "https://yourapp.com/success",
        "failedUrl": "https://yourapp.com/failed",
        "customer": {
          "firstName": "John",
          "email": "john@example.com"
        }
      }
    }
  ],
  "destinations": [
    {
      "type": "ACCOUNT",
      "currency": "CLP",
      "identity": {
        "identityId": "<IDENTITY_ID>"
      },
      "account": {
        "accountNumber": "<ACCOUNT_NUMBER>"
      }
    }
  ]
});

    let response = client
        .post("https://api.conomyhq.com/sandbox/payments")
        .header("x-api-key", "{YOUR_API_KEY}")
        .header("Authorization", "Bearer {ACCESS_TOKEN}")
        .header("conomyhq-api-version", "24-04-2025")
        .header("User-Agent", "MyApp/1.0")
        .header("Content-Type", "application/json")
        .header("Accept", "application/json")
        .json(&payload)
        .send()
        .await?;

    let data: serde_json::Value = response.json().await?;
    Ok(())
}

Response

200

{
  "id": "<PAYMENT_ID>",
  "type": "TOPUP_ACCOUNT",
  "status": "CREATED",
  "product": "CLP:CLP",
  "origins": [
    {
      "type": "ETPAY",
      "etpay": {
        "url": "https://provider.example/authorize"
      }
    }
  ]
}

Note

The response will include origins[0].etpay.url — redirect the customer to that URL to authorize the payment at their bank.

Capture Payment

After the customer completes the bank authorization, capture the funds to reflect them in the account.

Request

HTTPcurlJavaScriptPythonGoRust

POST /sandbox/payments/{PAYMENT_ID}/captured HTTP/1.1
Host: api.conomyhq.com
x-api-key: {YOUR_API_KEY}
Authorization: Bearer {ACCESS_TOKEN}
conomyhq-api-version: 24-04-2025
User-Agent: MyApp/1.0
Accept: application/json

curl -X POST 'https://api.conomyhq.com/sandbox/payments/{PAYMENT_ID}/captured' \
  -H 'x-api-key: {YOUR_API_KEY}' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'conomyhq-api-version: 24-04-2025' \
  -H 'User-Agent: MyApp/1.0' \
  -H 'Accept: application/json'

const response = await fetch('https://api.conomyhq.com/sandbox/payments/{PAYMENT_ID}/captured', {
  method: 'POST',
  headers: {
    'x-api-key': '{YOUR_API_KEY}',
    'Authorization': 'Bearer {ACCESS_TOKEN}',
    'conomyhq-api-version': '24-04-2025',
    'User-Agent': 'MyApp/1.0',
    'Accept': 'application/json',
  },
});

const data = await response.json();

import requests

response = requests.post(
    'https://api.conomyhq.com/sandbox/payments/{PAYMENT_ID}/captured',
    headers={
    'x-api-key': '{YOUR_API_KEY}',
    'Authorization': 'Bearer {ACCESS_TOKEN}',
    'conomyhq-api-version': '24-04-2025',
    'User-Agent': 'MyApp/1.0',
    'Accept': 'application/json',
    },
)

data = response.json()

package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.conomyhq.com/sandbox/payments/{PAYMENT_ID}/captured", nil)
	req.Header.Set("x-api-key", "{YOUR_API_KEY}")
	req.Header.Set("Authorization", "Bearer {ACCESS_TOKEN}")
	req.Header.Set("conomyhq-api-version", "24-04-2025")
	req.Header.Set("User-Agent", "MyApp/1.0")
	req.Header.Set("Accept", "application/json")

	client := &http.Client{}
	resp, _ := client.Do(req)
	defer resp.Body.Close()
}

use reqwest::Client;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new();
    let response = client
        .post("https://api.conomyhq.com/sandbox/payments/{PAYMENT_ID}/captured")
        .header("x-api-key", "{YOUR_API_KEY}")
        .header("Authorization", "Bearer {ACCESS_TOKEN}")
        .header("conomyhq-api-version", "24-04-2025")
        .header("User-Agent", "MyApp/1.0")
        .header("Accept", "application/json")
        .send()
        .await?;

    let data: serde_json::Value = response.json().await?;
    Ok(())
}

Response

200

{
  "id": "<PAYMENT_ID>",
  "status": "CAPTURED"
}

Webhook simulation

Simulate a webhook notification to test your payment confirmation handling.

Request

HTTPcurlJavaScriptPythonGoRust

POST /sandboxwebhook/payments/received/payment-provider HTTP/1.1
Host: api.conomyhq.com
x-api-key: {YOUR_API_KEY}
Authorization: Bearer {ACCESS_TOKEN}
conomyhq-api-version: 24-04-2025
User-Agent: MyApp/1.0
Content-Type: application/json
Accept: application/json

{
  "id": "<PAYMENT_ID>"
}

curl -X POST 'https://api.conomyhq.com/sandboxwebhook/payments/received/payment-provider' \
  -H 'x-api-key: {YOUR_API_KEY}' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'conomyhq-api-version: 24-04-2025' \
  -H 'User-Agent: MyApp/1.0' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "id": "<PAYMENT_ID>"
  }'

const response = await fetch('https://api.conomyhq.com/sandboxwebhook/payments/received/payment-provider', {
  method: 'POST',
  headers: {
    'x-api-key': '{YOUR_API_KEY}',
    'Authorization': 'Bearer {ACCESS_TOKEN}',
    'conomyhq-api-version': '24-04-2025',
    'User-Agent': 'MyApp/1.0',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
  },
  body: JSON.stringify({
    "id": "<PAYMENT_ID>"
  }),
});

const data = await response.json();

import requests

payload = {
  "id": "<PAYMENT_ID>"
}

response = requests.post(
    'https://api.conomyhq.com/sandboxwebhook/payments/received/payment-provider',
    headers={
    'x-api-key': '{YOUR_API_KEY}',
    'Authorization': 'Bearer {ACCESS_TOKEN}',
    'conomyhq-api-version': '24-04-2025',
    'User-Agent': 'MyApp/1.0',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    },
    json=payload,
)

data = response.json()

package main

import (
	"bytes"
	"net/http"
)

func main() {
	payload := []byte(`{
  "id": "<PAYMENT_ID>"
}`)
	body := bytes.NewReader(payload)
	req, _ := http.NewRequest("POST", "https://api.conomyhq.com/sandboxwebhook/payments/received/payment-provider", body)
	req.Header.Set("x-api-key", "{YOUR_API_KEY}")
	req.Header.Set("Authorization", "Bearer {ACCESS_TOKEN}")
	req.Header.Set("conomyhq-api-version", "24-04-2025")
	req.Header.Set("User-Agent", "MyApp/1.0")
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Accept", "application/json")

	client := &http.Client{}
	resp, _ := client.Do(req)
	defer resp.Body.Close()
}

use reqwest::Client;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new();
    let payload = json!({
  "id": "<PAYMENT_ID>"
});

    let response = client
        .post("https://api.conomyhq.com/sandboxwebhook/payments/received/payment-provider")
        .header("x-api-key", "{YOUR_API_KEY}")
        .header("Authorization", "Bearer {ACCESS_TOKEN}")
        .header("conomyhq-api-version", "24-04-2025")
        .header("User-Agent", "MyApp/1.0")
        .header("Content-Type", "application/json")
        .header("Accept", "application/json")
        .json(&payload)
        .send()
        .await?;

    let data: serde_json::Value = response.json().await?;
    Ok(())
}

Response

200

{
  "ok": true
}

Check account balance

Verify that the funds were credited correctly into the account.

Request

HTTPcurlJavaScriptPythonGoRust

GET /sandbox/accounts?accountNumber=<ACCOUNT_NUMBER> HTTP/1.1
Host: api.conomyhq.com
x-api-key: {YOUR_API_KEY}
Authorization: Bearer {ACCESS_TOKEN}
conomyhq-api-version: 24-04-2025
User-Agent: MyApp/1.0
Accept: application/json

curl -X GET 'https://api.conomyhq.com/sandbox/accounts?accountNumber=<ACCOUNT_NUMBER>' \
  -H 'x-api-key: {YOUR_API_KEY}' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'conomyhq-api-version: 24-04-2025' \
  -H 'User-Agent: MyApp/1.0' \
  -H 'Accept: application/json'

const response = await fetch('https://api.conomyhq.com/sandbox/accounts?accountNumber=<ACCOUNT_NUMBER>', {
  method: 'GET',
  headers: {
    'x-api-key': '{YOUR_API_KEY}',
    'Authorization': 'Bearer {ACCESS_TOKEN}',
    'conomyhq-api-version': '24-04-2025',
    'User-Agent': 'MyApp/1.0',
    'Accept': 'application/json',
  },
});

const data = await response.json();

import requests

response = requests.get(
    'https://api.conomyhq.com/sandbox/accounts?accountNumber=<ACCOUNT_NUMBER>',
    headers={
    'x-api-key': '{YOUR_API_KEY}',
    'Authorization': 'Bearer {ACCESS_TOKEN}',
    'conomyhq-api-version': '24-04-2025',
    'User-Agent': 'MyApp/1.0',
    'Accept': 'application/json',
    },
)

data = response.json()

package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.conomyhq.com/sandbox/accounts?accountNumber=<ACCOUNT_NUMBER>", nil)
	req.Header.Set("x-api-key", "{YOUR_API_KEY}")
	req.Header.Set("Authorization", "Bearer {ACCESS_TOKEN}")
	req.Header.Set("conomyhq-api-version", "24-04-2025")
	req.Header.Set("User-Agent", "MyApp/1.0")
	req.Header.Set("Accept", "application/json")

	client := &http.Client{}
	resp, _ := client.Do(req)
	defer resp.Body.Close()
}

use reqwest::Client;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new();
    let response = client
        .get("https://api.conomyhq.com/sandbox/accounts?accountNumber=<ACCOUNT_NUMBER>")
        .header("x-api-key", "{YOUR_API_KEY}")
        .header("Authorization", "Bearer {ACCESS_TOKEN}")
        .header("conomyhq-api-version", "24-04-2025")
        .header("User-Agent", "MyApp/1.0")
        .header("Accept", "application/json")
        .send()
        .await?;

    let data: serde_json::Value = response.json().await?;
    Ok(())
}

Response

200

{
  "id": "<ACCOUNT_ID>",
  "accountNumber": "<ACCOUNT_NUMBER>",
  "availableFunds": "700000",
  "currency": "CLP",
  "status": "ACTIVE"
}

---

Top-up by region

Region	Origin type	Example rail
Chile	ETPAY	Open banking
Chile	FINTOC	Open banking
Brazil	PIX	Instant QR
Argentina	PCT	QR Transfer
Colombia	PSE	Bank transfer
Colombia	NEQUI	Wallet