Payment structure

A payment is the instruction that moves value between one or more origins and one or more destinations. Every payment has a business type, a currency product, amount fields, lifecycle status, and optional fees.

Note

Think of POST /payments as a typed movement: choose the payment type, choose the product, then describe where funds come from and where they go.

Core shape

Field	Meaning
type	Business intent such as TOPUP_ACCOUNT, WITHDRAWAL_ACCOUNT, PURCHASE, REMITTANCE, P2P, COLLECT, or FEE.
product	Currency pair in the format purchaseCurrency:currency, for example CLP:CLP or USD:COP.
origins	Source nodes. They can be internal ACCOUNT nodes or external pay-in rails.
destinations	Destination nodes. They can be internal ACCOUNT nodes or external payout rails.
purchaseAmount	Amount before fees or conversion. Use this when the customer-facing amount is known first.
totalAmount	Final amount after fees or conversion. Use this when the settlement amount is known first.
status	Current lifecycle state used for reconciliation.

Origins and destinations

origins and destinations are payment nodes. A node always starts with a type; that type tells Conomy which rail or internal account model to validate. If the selected rail requires additional fields, the node includes a same-named object with the provider-specific data.

{
  "type": "TOPUP_ACCOUNT",
  "product": "CLP:CLP",
  "origins": [
    {
      "type": "ETPAY",
      "currency": "CLP",
      "etpay": {
        "successUrl": "https://yourapp.com/success",
        "failedUrl": "https://yourapp.com/failed"
      }
    }
  ],
  "destinations": [
    {
      "type": "ACCOUNT",
      "accountNumber": "<ACCOUNT_NUMBER>",
      "amount": "100000",
      "currency": "CLP"
    }
  ]
}

Node	What it represents	Common examples
Origin	Where funds start. It can be a customer pay-in rail, an external account, or an internal Conomy account.	ETPAY, WEBPAY, PSE, ACCOUNT
Destination	Where funds should land. It can be an internal Conomy account or an external payout rail.	ACCOUNT, BANK_ACCOUNT, SPEI, PIX, SWIFT
Rail object	The data required by the selected type. The shape comes from available products and the OpenAPI object.	etpay, bankAccount, crypto, pix

Node rules are intentionally simple: use the same currency as the node is processing, send amounts as strings, and only include the rail object for the selected type. When you need to support several payment methods, call available products first and render only the nodes returned for that identity, country, and currency.

Lifecycle

01

Created

Conomy accepts the request and prepares the rail instruction.

02

Authorized

Funds are reserved when the selected rail has an authorization step.

03

Captured

The movement is committed and provider processing starts.

04

Received

The provider confirms funds were received.

05

Settled

Reconciliation is complete and the destination is funded.

Required decisions

1. Pick the payment type.
2. Call available products for the identity, country, and currency.
3. Choose one valid origin node and one valid destination node.
4. Fill the required rail object for each selected node.
5. Create the payment, capture when required, and reconcile from webhooks.

Related

Recipe Transaction builder Generate a working payload from payment intent, currency, origin, and destination. → Model Payment types Choose the business behavior before creating the payment. → Rails Origins and destinations Understand the internal account nodes and external rails used by payment payloads. →