Payments API ReferenceOrders

Create an order

Creates a new order of the specified type:

  1. PAYIN: Receive funds from external sources into virtual balance or real accounts

    • originCurrencySymbol and destinationCurrencySymbol must be fiat
    • Must include exactly one payment method
    • destinationAccountId is optional (defaults to virtual balance)

  2. PAYOUT: Send funds from virtual balance to external accounts

    • originCurrencySymbol and destinationCurrencySymbol must be fiat
    • destinationAccountId is required (must be a real bank account)

  3. ONRAMP: Convert fiat to crypto

    • originCurrencySymbol must be fiat
    • destinationCurrencySymbol must be crypto
    • destinationAccountId is required (must be a crypto wallet)
    • paymentMethods is optional (defaults to virtual balance)

  4. OFFRAMP: Convert crypto to fiat

    • originCurrencySymbol must be crypto
    • destinationCurrencySymbol must be fiat
    • destinationAccountId is optional (defaults to virtual balance)

  5. BALANCE_TRANSFER: Transfer between virtual balances

    • originCurrencySymbol and destinationCurrencySymbol must be fiat
    • No destinationAccountId needed (handled internally)

  6. PAYMENT_LINK: Create a payment link for external users

    • originCurrencySymbol and destinationCurrencySymbol must be fiat
    • destinationAccountId is optional (defaults to virtual balance)
    • paymentMethods can be empty (all methods) or multiple methods
    • dueDate can be set for expiry

Path parameters

merchantIdstringRequired
Merchant ID
organizationIdstringRequired
Organization ID

Headers

AuthorizationstringRequired

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.
typeenumRequired
Type of order
originCurrencySymbolstringRequired

Currency symbol for origin. Must be fiat for PAYIN/PAYOUT/PAYMENT_LINK/BALANCE_TRANSFER and crypto for OFFRAMP (e.g., COP, USD, ETH). Not required when quoteId is provided.

destinationCurrencySymbolstringRequired

Currency symbol for destination. Must be fiat for PAYIN/PAYOUT/PAYMENT_LINK/BALANCE_TRANSFER/OFFRAMP and crypto for ONRAMP (e.g., COP, USD, BTC). Not required when quoteId is provided.

destinationAccountIdstringOptional

Destination Account ID (bank account or wallet). Required for PAYOUT and ONRAMP. Optional for PAYIN, OFFRAMP, and PAYMENT_LINK (defaults to merchant virtual balance if omitted).

amountIndoubleOptional
amountOutobjectOptional

Amount in destination currency. Must provide either amountIn or amountOut (but not both) when quoteId is not provided. Not required when quoteId is provided.

dueDatestringOptional

ISO 8601 date for order expiry, applies to PAYMENT_LINK type.

descriptionstringOptional
Description of the order
externalIdstringOptional
Optional unique idempotent identifier provided by the client. If provided, it prevents duplicate operations for the same merchantId and type. If omitted, idempotency check is skipped.
failedUrlstringOptional
URL for failed order notifications
successUrlstringOptional
URL for successful order notifications
paymentMethodslist of objectsOptional

Array of payment methods. Required for PAYIN (exactly one method). Optional for PAYMENT_LINK (can be empty for all available methods or multiple specific methods).

quoteIdstringOptional

Quote ID to fix exchange rate for cross-currency or crypto operations (ONRAMP, OFFRAMP, BALANCE_TRANSFER). When provided, originCurrencySymbol, destinationCurrencySymbol, amountIn, and amountOut must not be provided.

enforcedDocumentstringOptional

Government-issued ID number required for the operation (e.g. DNI, RUT, Cédula)

contactIdstringOptional
Contact ID for the person involved in the order transaction. This identifies who the order is directed to. Required for using notification features.
sendEmailbooleanOptional
Whether to send email notifications to the contact. Requires contactId to be set.
sendNotificationbooleanOptional

Whether to send in-app notifications to the contact. Requires contactId to be set.

sendWhatsappbooleanOptional
Whether to send WhatsApp notifications to the contact. Requires contactId to be set.
sendRemindersbooleanOptional
Whether to send order reminders when order is pending. Requires contactId to be set.
isMerchantSelfOrderbooleanOptional

Indicates that the order is initiated by the merchant for themselves, rather than involving a third-party contact (such as a customer or supplier).

Response

Order created successfully
idstring
Unique order ID
typeenum
Type of order
destinationAccountIdstring

Destination account ID (bank or wallet)

originCurrencySymbolstring
Origin currency symbol
destinationCurrencySymbolstring
Destination currency symbol
amountIndouble
Amount in origin currency
amountOutdouble
Amount in destination currency
dueDatestring
Due date for payment links
descriptionstring
Description of the order
externalIdstring

External ID (idempotent identifier)

paymentMethodslist of objects
Payment methods used
quoteIdstring
Quote ID used for currency conversion
contactIdstring
Contact ID identifying the counterparty to whom this order is directed. This represents the entity on the other side of the transaction.
enforcedDocumentstring

National ID document (e.g. DNI, RUT, Cédula) that must be provided to complete the order

sendEmailboolean
Whether email notifications are enabled
sendNotificationboolean

Whether in-app notifications are enabled

sendWhatsappboolean
Whether WhatsApp notifications are enabled
sendRemindersboolean
Whether order reminders are enabled
providedActionstring
Action URL or data provided to the user to complete the order, such as a QR code, payment link, or other actionable payment method
providedActionTypeenum
Type of provided action
Allowed values:
createdAtstring
Timestamp when the order was created
statusenum
Current status of the order

Errors