Transaction builder

Build any valid POST /payments payload from user intent, currency pair, and rail availability.

This builder is dynamic: it uses GET /payments/available-products to discover rails and required fields per identity and currency at runtime.

Goal of this page: users can assemble a payment request and copy JSON or cURL from the GitBook API playground, without executing the transaction.

1. Interactive block (recommended)

If the ConomyHQ Transaction Builder integration is installed in your space, use this block to select values and generate payloads.

Transaction Builder

Build and validate POST /payments payloads, then copy generated JSON or cURL (no execution).

2. Builder inputs

Input	Description
User intent	TOPUP_ACCOUNT, WITHDRAWAL_ACCOUNT, REMITTANCE, PURCHASE
Amount	purchaseAmount
Source currency	purchaseCurrency
Settlement currency	currency
Identity	identityId

3. Resolve products and rails (dynamic step)

Use this endpoint first. It defines what the user can build for each currency.

Get available products

get

Returns all payment products available for a given identity, organized by currency. Each currency entry includes available pay-in methods with their products and pay-out (withdrawal) methods with their products. Use this endpoint to discover what payment rails are enabled for an account before building a payment flow.

Authorizations

BearerToken

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

identityIdstringOptional

Identity ID to retrieve available products for.

currenciesstringOptional

Comma-separated list of currency codes to filter results (e.g., ARS,CLP).

Header parameters

x-api-keystringRequired

The API key used for authentication when making requests to the API Gateway.

User-AgentstringRequired

Identifies the application making the request.

Responses

200

Request processed successfully.

application/json

Available payment products for an identity, organized by currency.

supportedPaymentCurrenciesstring[]Required

Currencies for which pay-in products are available.

supportedPayoutCurrenciesstring[]Required

Currencies for which pay-out products are available.

400

Invalid request parameters or payload.

application/json

500

Unexpected internal server error.

application/json

get

/payments/available-products

HTTPcURLJavaScriptPython

GET /payments/available-products HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
x-api-key: text
User-Agent: text
Accept: */*

{
  "supportedPaymentCurrencies": [
    "ARS",
    "CLP"
  ],
  "supportedPayoutCurrencies": [
    "ARS",
    "CLP"
  ],
  "supportedPaymentMethods": [
    "CVU",
    "ETPAY",
    "PCT",
    "PIX"
  ],
  "supportedWithdrawalMethods": [
    "BANK_ACCOUNT"
  ],
  "byCurrency": [
    {
      "currency": "ARS",
      "payin": {
        "paymentMethods": [
          "CVU",
          "PCT"
        ],
        "products": [
          {
            "name": "PCT",
            "type": "PCT",
            "currency": "ARS",
            "product": "ARS:ARS",
            "minAmount": "10",
            "maxAmount": "5000000",
            "requiredFields": [
              "pct.customer.phoneNumber",
              "pct.customer.phoneNumberPrefix",
              "pct.customer.email"
            ],
            "validDestinations": [
              "ACCOUNT"
            ],
            "nodeSchema": {
              "pct": {
                "customer": {
                  "email": "string",
                  "phoneNumber": "string",
                  "phoneNumberPrefix": "string"
                }
              }
            },
            "requiredFieldTypes": {
              "pct.customer.email": "string",
              "pct.customer.phoneNumber": "string",
              "pct.customer.phoneNumberPrefix": "string"
            }
          }
        ]
      },
      "payout": {
        "withdrawalMethods": [
          "BANK_ACCOUNT"
        ],
        "products": [
          {
            "name": "BANK_ACCOUNT",
            "type": "BANK_ACCOUNT",
            "currency": "ARS",
            "product": "ARS:ARS",
            "minAmount": "10",
            "maxAmount": "5000000",
            "requiredFields": [
              "bank.accountNumber",
              "bank.bank"
            ],
            "validOrigins": [
              "ACCOUNT"
            ],
            "nodeSchema": {
              "bank": {
                "accountNumber": "string",
                "bank": "string"
              }
            },
            "requiredFieldTypes": {
              "bank.accountNumber": "string",
              "bank.bank": "string"
            }
          }
        ]
      }
    }
  ]
}

Use:

• byCurrency[].payin.paymentMethods to render origin choices.

• byCurrency[].payout.withdrawalMethods to render destination choices.

• requiredFields and requiredFieldTypes to build and validate node inputs.

• validOrigins and validDestinations to enforce allowed combinations.

4. Route rules by intent

User intent	type	Origin rule	Destination rule
Load internal account	TOPUP_ACCOUNT	Any pay-in rail from paymentMethods	ACCOUNT
Withdraw from internal account	WITHDRAWAL_ACCOUNT	ACCOUNT	Any pay-out rail from withdrawalMethods
Cross-border transfer	REMITTANCE	ACCOUNT or pay-in rail	Any valid pay-out rail
Checkout / customer charge	PURCHASE	Any pay-in rail	ACCOUNT

5. Request shape

{
  "identityId": "<IDENTITY_ID>",
  "accountNumber": "<INTERNAL_ACCOUNT_NUMBER>",
  "type": "<TYPE>",
  "product": "<PURCHASE_CURRENCY>:<SETTLEMENT_CURRENCY>",
  "purchaseAmount": "<AMOUNT>",
  "purchaseCurrency": "<PURCHASE_CURRENCY>",
  "currency": "<SETTLEMENT_CURRENCY>",
  "origins": [
    {
      "type": "<ORIGIN_TYPE>",
      "currency": "<ORIGIN_CURRENCY>",
      "<originNodeKey>": {
        "<requiredField1>": "<value>",
        "<requiredField2>": "<value>"
      }
    }
  ],
  "destinations": [
    {
      "type": "<DESTINATION_TYPE>",
      "currency": "<DESTINATION_CURRENCY>",
      "<destinationNodeKey>": {
        "<requiredField1>": "<value>",
        "<requiredField2>": "<value>"
      }
    }
  ]
}

Use only one node object matching type in each origin/destination. Example: if type is PIX, send only pix.

6. Generate JSON/cURL in the API playground

Use the POST /payments block below to fill the request body and copy the generated request code.

1. Click Try it in the block.

2. Complete type, currencies, product, origins, and destinations.

3. Use the code preview to copy cURL or JSON.

4. Do not send the request if you only want request generation.

Create Payment

post

When creating a transaction, this endpoint provides a payment method and a provider system to process the payment.

Authorizations

BearerToken

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Header parameters

x-api-keystringRequired

The API key used for authentication when making requests to the API Gateway.

User-AgentstringRequired

Identifies the application making the request.

Body

application/json

externalIdstringRequired

External reference identifier for integrations.

identityIdstringRequired

Identifier linking the transaction to a specific user or organization.

identityExternalIdstringOptional

External reference identifier for the identity associated with the transaction.

accountNumberstringRequired

The account number involved in the transaction.

totalAmountstringRequired

The total amount of the transaction.

currencystringRequired

Specifies the currency used, following the ISO 4217 standard for fiat currencies (e.g., CLP, ARS, MXN). Go to the currencies page for the complete list of supported values.

descriptionstringOptional

A brief description of the transaction.

typestring · enumRequired

Indicates the purpose of the payment. This field defines how the payment should be processed within the system, based on its intent—such as funding an account, withdrawing funds, transferring between users, collecting funds, or applying fees. Go to the payment types page for the complete list of supported values.

Possible values:

purchaseAmountstringOptional

The amount paid in the transaction.

purchaseCurrencystringOptional

Specifies the currency used, following the ISO 4217 standard for fiat currencies (e.g., CLP, ARS, MXN). Go to the currencies page for the complete list of supported values.

expiresAtstringOptional

Timestamp indicating when the transaction expires, if applicable.

Responses

200

Request processed successfully.

application/json

Schema representing a financial transaction, including details about the transaction's origins, destinations, amounts, fees, and status.

idstringRequired

Unique identifier for the internal service.

externalIdstringRequired

External reference identifier for integrations.

identityIdstringRequired

Identifier linking the transaction to a specific user or organization.

identityExternalIdstringOptional

External reference identifier for the identity associated with the transaction.

accountNumberstringRequired

The account number involved in the transaction.

totalAmountstringRequired

The total amount of the transaction.

currencystringRequired

Specifies the currency used, following the ISO 4217 standard for fiat currencies (e.g., CLP, ARS, MXN). Go to the currencies page for the complete list of supported values.

descriptionstringOptional

A brief description of the transaction.

productstringOptional

The product or service related to the transaction. purchaseCurrency:Currency

statusstringRequired

The current status of the transaction (e.g., PENDING, AUTHORIZED, CAPTURED, ATTEMPT, REFUNDED).

typestring · enumRequired

Indicates the purpose of the payment. This field defines how the payment should be processed within the system, based on its intent—such as funding an account, withdrawing funds, transferring between users, collecting funds, or applying fees. Go to the payment types page for the complete list of supported values.

Possible values:

purchaseAmountstringOptional

The amount paid in the transaction.

purchaseCurrencystringOptional

Specifies the currency used, following the ISO 4217 standard for fiat currencies (e.g., CLP, ARS, MXN). Go to the currencies page for the complete list of supported values.

createdAtstringRequired

Timestamp indicating when the transaction was created.

updatedAtstringRequired

Timestamp indicating the last update to the transaction.

expiresAtstringOptional

Timestamp indicating when the transaction expires, if applicable.

capturedAtstringOptional

Timestamp indicating when the transaction was captured.

authorizedAtstringOptional

Timestamp indicating when the transaction was authorized.

refundedAtstringOptional

Timestamp indicating when the transaction was refunded, if applicable.

settlementstringOptional

Settlement period for the transaction.

400

Invalid request parameters or payload.

application/json

500

Unexpected internal server error.

application/json

post

/payments

HTTPcURLJavaScriptPython

POST /payments HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
x-api-key: text
User-Agent: text
Content-Type: application/json
Accept: */*
Content-Length: 567

{
  "identityId": "679c482ee4420cb5b0966c9a",
  "accountNumber": "123456",
  "product": "ARS:ARS",
  "type": "PAYMENT",
  "purchaseAmount": "100",
  "purchaseCurrency": "ARS",
  "currency": "ARS",
  "origins": [
    {
      "name": "ETPAY",
      "type": "PAYMENT_INITATION",
      "amount": "100",
      "currency": "ARS",
      "paymentInitiation": {
        "origin": "ETPAY",
        "referenceId": "external_payment_id_1"
      }
    }
  ],
  "destinations": [
    {
      "type": "ACCOUNT",
      "amount": "100",
      "currency": "ARS",
      "identity": {
        "userId": "679c482ee4420cb5b0966c9a",
        "name": "Juan Pérez",
        "lastname": "Zúñiga",
        "nickname": "Juanpe",
        "dni": "12312252"
      },
      "account": {
        "accountNumber": "123456"
      }
    }
  ]
}

{
  "id": "text",
  "externalId": "text",
  "identityId": "text",
  "identityExternalId": "text",
  "accountNumber": "text",
  "totalAmount": "text",
  "currency": "text",
  "description": "text",
  "product": "text",
  "status": "text",
  "type": "PURCHASE",
  "purchaseAmount": "text",
  "purchaseCurrency": "text",
  "fees": [
    {
      "name": "text",
      "type": "FIXED",
      "value": "text",
      "amount": "text",
      "currency": "text"
    }
  ],
  "createdAt": "text",
  "updatedAt": "text",
  "expiresAt": "text",
  "capturedAt": "text",
  "authorizedAt": "text",
  "refundedAt": "text",
  "origins": [
    {
      "externalId": "text",
      "name": "text",
      "type": "CARD",
      "amount": "text",
      "currency": "text",
      "settlement": "text",
      "fee": {
        "name": "text",
        "type": "FIXED",
        "value": "text",
        "amount": "text",
        "currency": "text"
      },
      "identity": {},
      "metadata": {
        "image": "text",
        "description": "text",
        "category": "text"
      },
      "amountOut": "text",
      "card": {
        "holder": "text",
        "scheme": "text",
        "type": "text",
        "mask": "text",
        "country": "text",
        "token": "text"
      }
    }
  ],
  "destinations": [
    {
      "externalId": "text",
      "name": "text",
      "type": "CARD",
      "amount": "text",
      "currency": "text",
      "settlement": "text",
      "fee": {
        "name": "text",
        "type": "FIXED",
        "value": "text",
        "amount": "text",
        "currency": "text"
      },
      "identity": {},
      "metadata": {
        "image": "text",
        "description": "text",
        "category": "text"
      },
      "amountOut": "text",
      "card": {
        "holder": "text",
        "scheme": "text",
        "type": "text",
        "mask": "text",
        "country": "text",
        "token": "text"
      }
    }
  ],
  "settlement": "text"
}

7. Common route presets

Load ARS account with CVU

type: TOPUP_ACCOUNT product: ARS:ARS origin: CVU destination: ACCOUNT

Load ARS account with PCT

Pay in BRL (PIX) and settle CLP

8. Builder validation rules

1. type controls which origin/destination families are valid.

2. product must match purchaseCurrency:currency.

3. For single origin and single destination, amount per node is optional.

4. For split flows, each node must include amount, and all sums must match the payment amount.

5. Keep only the node object that matches origins[].type or destinations[].type.

9. Builder checklist

• Confirm the user goal (TOPUP_ACCOUNT, WITHDRAWAL_ACCOUNT, REMITTANCE, PURCHASE).

• Confirm source currency (purchaseCurrency) and settlement currency (currency).

• Call GET /payments/available-products for the target identity.

• Select a rail that appears in paymentMethods/withdrawalMethods.

• Render only the fields listed in requiredFields.

• Generate and copy cURL/JSON.

Related docs

• Available products

• Origins and Destinations

• Nodes reference

• Creating payments