Payments

Payments represent the intent and execution of moving funds from one or more origins to one or more destinations using a defined method.

Each payment moves through a lifecycle that may include optional authorization and capture stages before final confirmation by the payment provider. Payments are linked to prior attempts and become the definitive execution step once initiated.

A payment can be authorized (reserved but not yet charged), captured (confirmed for collection), and marked as received when the provider notifies that the payment was successful. Final reconciliation (settled) occurs in a separate stage and is managed by a different set of APIs.

Use the Payments API to create payments, retrieve them, or transition them through their authorization, capture, and received stages.

Endpoints

GET /payments
GET /payments/:id
POST /payments
POST /payments/:id/authorized
POST /payments/:id/captured
POST /payments/:id/received

Get Payments

get

Authorizations

BearerToken

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

identityIdstringOptional

Identity Id

Example: 1234a

typestring · enumOptional

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.

Example: PURCHASEPossible values:

accountNumberstringOptional

Account Number

Example: 1234

statusstringOptional

Payment status

Example: CREATED

startDatestringOptional

(dd/mm/yyyy) Start date filters created Date min

Example: 01/04/2025

endDatestringOptional

(dd/mm/yyyy) End date filters created Date max

Example: 08/04/2025

sortstringOptional

Sorts the results by param:asc | param:desc

Example: createdAt:desc

limitstringOptional

Specifies the maximum number of items to return in a single request.

Example: 50

offsetstringOptional

Skips the input value from the current view

Example: 0

checkoutSessionIdstringOptional

checkout session Id

Header parameters

conomyhq-api-versionstringOptional

v1: empty ; v2: 24-04-2025

Default: none, is the first API versionExample: 24-04-2025

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

200Success

application/json

400Error

application/json

500Error

application/json

get

/payments

HTTPcURLJavaScriptPython

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

{
  "pagination": {
    "count": 1,
    "next": 1,
    "previous": 1,
    "total": 1
  },
  "results": [
    {
      "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"
    }
  ]
}

Get Payment

get

Authorizations

BearerToken

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idstringRequired

Unique identifier for the payment.

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

200Success

application/json

400Error

application/json

500Error

application/json

get

/payments/{id}

HTTPcURLJavaScriptPython

GET /payments/{id} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
x-api-key: text
User-Agent: text
Accept: */*

{
  "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"
}

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

200Success

application/json

400Error

application/json

500Error

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"
}

Authorize Payment

post

This endpoint authorizes a transaction before it is captured, ensuring that the payment method has sufficient funds or credit availability. Authorization does not finalize the payment but reserves the amount until the capture is completed.

Authorizations

BearerToken

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idstringRequired

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

200Success

application/json

400Error

application/json

500Error

application/json

post

/payments/{id}/authorized

HTTPcURLJavaScriptPython

POST /payments/{id}/authorized HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
x-api-key: text
User-Agent: text
Accept: */*

{
  "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"
}

Capture Payment

post

Indicates that the payment has been successfully captured. At this stage, the transaction has been confirmed, and the funds have been debited from the payment source. However, the funds may still be in transit before being fully received.

Authorizations

BearerToken

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

idstringRequired

Unique identifier for the payment.

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

200Success

application/json

400Error

application/json

500Error

application/json

post

/payments/{id}/captured

HTTPcURLJavaScriptPython

POST /payments/{id}/captured HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
x-api-key: text
User-Agent: text
Accept: */*

{
  "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"
      }
    }
  ]
}

Receive Payment Provider Notification

post

Indicates that the funds have been received and are available in the destination account. This represents the final stage of the payment process, where the funds are no longer in transit. The next step is to validate that the funds have been settled after the reconciliation process with the payment provider.

Info hints This endpoint is only available in the sandbox environment to simulate the receipt of funds. In production, this step is triggered by the payment provider through a webhook or callback.

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

transactionIdstringRequired

transaction id

signaturestringRequired

provider signature

Responses

200Success

application/json

400Error

application/json

500Error

application/json

post

/payments/received

HTTPcURLJavaScriptPython

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

{
  "id": "YNgma4fqAjwIftRM5Za6D"
}

{
  "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"
}