Skip to main content

Order

An Order is the formal request to execute a financial transaction based on the terms established by a previously generated Quote. In the transaction flow, the order is the final step that confirms and processes the payout to the beneficiary using the specified methods.

Technical definition​

An order is built from the details provided by a Quote. The Quote used to create the order must still be valid and its terms unchanged, to guarantee consistency across the transaction.

The order turns the terms of a Quote into an executable action, triggering the transfer of funds to the beneficiary. This is the final stage of the process and must be precise to avoid errors or discrepancies.

Creating an order​

An order references its Quote through quotation_id (POST /orders, with your idempotency reference in the X-Idempotency-Key header):

{
  "quotation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "metadata": { "invoice_id": "INV-2026-00456", "batch_id": "BATCH-VE-032" },
  "purpose": "FAMILY_SUPPORT",
  "sender": {
    "names": "Ana María",
    "last_names": "Pérez Gómez",
    "document": { "type": "CC", "id": "1020304050", "country": "CO" },
    "country": "CO"
  },
  "destination": {
    "receiver": {
      "names": "Carlos Andrés",
      "last_names": "Rodríguez López",
      "document": { "type": "V", "id": "12345678", "country": "VE" },
      "email": "[email protected]",
      "country": "VE"
    },
    "payment_instructions": {
      "bank_phone_account": { "bank_name": "BNC_VE", "phone_number": "+584121234567", "document_id": "12345678" }
    }
  }
}

The quotation_id binds the order to the agreed Quote. Your X-Idempotency-Key value is echoed back as idempotency_key in the order response.

The required purpose field declares the remittance concept, from a closed catalog: FAMILY_SUPPORT, PAYMENT_OF_BILLS, PURCHASE_OF_GOODS, PROFESSIONAL_SERVICES, RENTAL_OF_SPACES, INVESTMENTS, COMMISSIONS_LOANS_CAPITAL_INCREASE, TRANSPORTATION_COSTS, FEES.

Technical considerations​

  • Quote linkage — the order must reference the correct Quote to preserve the integrity of the transaction. Any change to the Quote after the order is created may invalidate it.
  • Data validation — the data provided in the order must match the terms set in the Quote, including amount, currency, and payout method.
  • Transaction status — the order status reflects the progress of the transaction, from creation through to confirmation or failure.
Important

The order is the step that executes the payout. Make sure it is created from a valid, unchanged Quote so the transaction runs under the exact terms that were quoted.