CVU | conomy

Rail overview

Use CVU to collect Argentine bank transfers into an internal account (pay-in) or to send ARS to any Argentine CVU address (pay-out). Static and dynamic modes are available for pay-in; pay-out requires the recipient CVU code.

Pay-in: dynamic CVU payments create the payment first, capture it, and then receive the generated CVU code in capture/status; static CVU payments first read the fixed CVU with GET /payment-origins and then send that cvu.code in the CVU origin. Pay-out: funds leave an internal ACCOUNT after capture and settle through the Argentine interbank network.

Region Argentina

Currency ARS

Direction Pay-in / Pay-out

Model Virtual account identifier

For pay-in, show the CVU code clearly to the payer and rely on webhooks for state changes. For pay-out, validate the recipient CVU and customer data before capture to avoid failed transfers.

Static CVU vs dynamic CVU

The platform supports two CVU allocation modes. The mode determines how an incoming transfer is matched to a transaction.

Characteristic	Static CVU	Dynamic CVU
Allocation	A fixed code assigned to a specific identity. Shared across all topups for that identity.	A unique code allocated per payment attempt.
Transfer matching	The client sends the fixed `cvu.code` in the CVU origin when creating the payment.	Automatic 1:1 match with the originating payment attempt.
Typical use case	Recurring topups, off-platform onboarding, bulk collection flows.	Checkout flows where payer identity and amount are known upfront.
Underpaid / overpaid classification	At reconciliation time.	Automatic, by comparing the received amount against the amount on the attempt.

How to tell them apart in the API response

When a CVU topup arrives, inspect the payment object:

Field	Static	Dynamic
`accountNumber`	Set when the fixed CVU payment is created for the destination account	Set — matched to the destination account of the attempt
`origins[0].cvu.code`	The fixed CVU bound to the identity	The unique code allocated for that specific attempt
`status` on arrival	`CREATED` (matched to the fixed-code payment)	`CREATED` (already matched to the attempt)

If accountNumber is empty, the topup is unmatched and requires operational reconciliation on your side.

Static CVU

A static CVU is a fixed code bound to an identity/account in your tenant. First read the fixed cvu.code, then send that code in the payment origin when creating the static CVU payment.

Get the static CVU

Call GET /payment-origins for the account before showing instructions to the payer. Select the CVU origin from the response and display its cvu.code.

Request

GET /sandbox/payment-origins?accountNumber=<ACCOUNT_NUMBER>&currency=ARS 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

package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.conomyhq.com/sandbox/payment-origins?accountNumber=<ACCOUNT_NUMBER>&currency=ARS", 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/payment-origins?accountNumber=<ACCOUNT_NUMBER>&currency=ARS")
        .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

[
  {
    "type": "CVU",
    "currency": "ARS",
    "product": "ARS:ARS",
    "validDestinations": [
      "ACCOUNT"
    ],
    "cvu": {
      "code": "0000003100029518339087"
    },
    "nodeSchema": {
      "cvu": {}
    }
  }
]

For static CVU pay-in, the client supplies the fixed CVU code in origins[0].cvu.code. For dynamic CVU, omit the code and Conomy returns it after capture/status.

Create the static CVU payment

{
  "identityId": "<IDENTITY_ID>",
  "accountNumber": "<ACCOUNT_NUMBER>",
  "product": "ARS:ARS",
  "purchaseAmount": "10000",
  "currency": "ARS",
  "description": "CVU pay-in to internal account",
  "type": "TOPUP_ACCOUNT",
  "purchaseCurrency": "ARS",
  "origins": [
    {
      "name": "CVU",
      "type": "CVU",
      "currency": "ARS",
      "cvu": {
        "code": "<STATIC_CVU_CODE>",
        "customer": {
          "firstName": "Maria",
          "lastName": "Gomez",
          "email": "maria.gomez@example.com"
        }
      }
    }
  ],
  "destinations": [
    {
      "type": "ACCOUNT",
      "currency": "ARS",
      "identity": {
        "identityId": "<IDENTITY_ID>"
      },
      "account": {
        "accountNumber": "<ACCOUNT_NUMBER>"
      }
    }
  ]
}

How topups arrive

The payer initiates an ARS transfer to the static CVU code.
The platform receives the transfer notification and matches it to the payment that used that fixed CVU code.
A webhook fires so your dashboard can surface the pending item.
The payment transitions through the normal lifecycle toward SETTLED.
Webhook payment.settled fires.

Expiry

A topup that is not reconciled within 48 hours expires automatically:

A refund is initiated back to the originating bank account.
A child REFUND transaction is created in RECEIVED state.
The parent transitions to EXPIRED and a payment.expired webhook fires.

Dynamic CVU

A dynamic CVU is allocated per payment. You create a payment with type: CVU as the origin, capture it, and the platform returns a unique CVU code for that specific transaction. The payer transfers to that code and the topup auto-matches.

Create the dynamic CVU payment

Create the payment with a CVU origin node. Do not send cvu.code; Conomy returns it after capture/status.

{
  "identityId": "<IDENTITY_ID>",
  "accountNumber": "<ACCOUNT_NUMBER>",
  "product": "ARS:ARS",
  "type": "PURCHASE",
  "purchaseAmount": "1500.00",
  "purchaseCurrency": "ARS",
  "currency": "ARS",
  "origins": [
    {
      "name": "CVU",
      "type": "CVU",
      "currency": "ARS",
      "cvu": {
        "customer": {
          "firstName": "Juan",
          "lastName": "Perez",
          "documentNumber": "12345678",
          "documentType": "DNI"
        }
      }
    }
  ],
  "destinations": [
    {
      "type": "ACCOUNT",
      "currency": "ARS",
      "identity": {
        "identityId": "<IDENTITY_ID>"
      },
      "account": {
        "accountNumber": "<ACCOUNT_NUMBER>"
      }
    }
  ]
}

Capture and read the CVU code

Call POST /payments/{PAYMENT_ID}/captured without a request body in the generated collection. The response includes the allocated CVU code in origins[0].cvu.code; if not, read it with GET /payments/{PAYMENT_ID}. Display this code to the payer so they can initiate the bank transfer.

Matching

When the topup arrives, the platform matches it to the attempt by CVU code. The attempt is promoted to CREATED and continues through the normal lifecycle toward SETTLED.

If the received amount differs from the expected amount, purchase.overpaid or purchase.underpaid fires alongside the lifecycle events.

Pay-out

CVU can also be used as a destination for withdrawals. Provide the recipient’s CVU code and the funds will be routed through the Argentine interbank network.

Creating a pay-out with CVU

{
  "identityId": "<IDENTITY_ID>",
  "accountNumber": "<ACCOUNT_NUMBER>",
  "product": "ARS:ARS",
  "type": "WITHDRAWAL_ACCOUNT",
  "totalAmount": "1500.00",
  "currency": "ARS",
  "origins": [
    {
      "type": "ACCOUNT",
      "currency": "ARS",
      "identity": {
        "identityId": "<IDENTITY_ID>"
      },
      "account": {
        "accountNumber": "<ACCOUNT_NUMBER>"
      }
    }
  ],
  "destinations": [
    {
      "type": "CVU",
      "currency": "ARS",
      "cvu": {
        "code": "0000003100029518339087"
      }
    }
  ]
}

cvu.code is the recipient’s CVU number and is required for pay-out. The payment follows the standard WITHDRAWAL_ACCOUNT lifecycle: CREATED → CAPTURED → RECEIVED → SETTLED.

Required fields

Field	Type	Description
`type`	`string`	Must be `"CVU"`
`currency`	`string`	Must be `"ARS"`
`cvu.code`	`string`	Required for pay-out. Recipient’s CVU number. Omit for dynamic pay-in allocation.

Optional fields

Field	Type	Description
`cvu.customer`	`object`	Customer data for the counterparty — used for automatic customer resolution on topup receipt, or for payout recipient identification.
`cvu.customer.firstName`	`string`	First name.
`cvu.customer.lastName`	`string`	Last name.
`cvu.customer.documentNumber`	`string`	Document number.
`cvu.customer.documentType`	`string`	Document type, e.g. `"DNI"`.

Valid combinations

Direction	Origin	Destination
Pay-in	`CVU`	`ACCOUNT`
Pay-out	`ACCOUNT`	`CVU`

Object

The CVU code for this node. Required when CVU is used as a destination (pay-out) — provide the recipient's CVU number. For pay-in in dynamic mode, omit this field — the platform allocates a unique code per payment attempt and returns it here in the response. In static pay-in mode, this field carries the fixed CVU pre-assigned to the identity; retrieve it with GET /payment-origins and send it in the CVU origin when creating the static CVU payment.

Information on who pays the transaction

idstring

Unique identifier for the internal service.

firstNamestringrequired

Payer's name

emailstring

Payer's email

lastNamestring

Payer's last name

phoneNumberstring

Payer's phone number without prefix

phoneNumberPrefixstring

Phone number prefix (e.g., +57)

documentTypestring

Documeny type of the entity (e.g., RUT, CURP, CURL). Go to the Supported Identity document types page for the complete list of supported values.

documentNumberstring

The document number associated with the documentType

addressobject

The entity’s address information.