Payments

Payments represent the intent and execution of moving funds from one or more origins to one or more destinations. Every payment progresses through a lifecycle of statuses (see Payment status).

Use the Payments API to create payments, list or retrieve them, issue refunds, assign unassigned balances to an account, attach compliance documentation, and resolve the persistent customer record tied to the payment.

Lifecycle endpoints

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

Refunds

POST /payments/:id/refund
GET  /payments/:id/refund

Unassigned balance

POST /payments/:id/assign

Review documents

POST /payments/:id/documents

Customer link

GET  /payments/:id/customer

---

Lifecycle

Get Payments

get

Lists payments with filtering and pagination options.

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

200

Request processed successfully.

application/json

400

Invalid request parameters or payload.

application/json

500

Unexpected internal server error.

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

Retrieves a payment by ID.

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

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

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

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

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

Unique identifier of the payment to authorize.

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

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/{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

200

Request processed successfully.

application/json

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.

productstringRequired

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:

purchaseAmountstringRequired

The amount paid in the transaction.

purchaseCurrencystringRequired

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.

400

Invalid request parameters or payload.

application/json

500

Unexpected internal server error.

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

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

---

Refunds

Refunds are issued as child transactions linked to the parent via parentPaymentId. See Refunds for the full guide.

POST /payments/{id}/refund

Creates a refund on a SETTLED parent. Supports partial refunds.

Path parameters

Name	Type	Description
id	string	Parent payment id.

Body

{
  "amount": "150.00",
  "reason": "Client requested partial refund"
}

Field	Type	Required	Description
amount	string		Positive decimal. When omitted, refunds the full remaining refundable balance (parent total minus active refunds).
reason	string		Free-text. Stored on the refund child's description for audit.

Response 201 Created

{
  "refundId": "69e25383b604159c5b8ba5bb",
  "parentPaymentId": "69e0df45b604159c5b8ba5a9",
  "status": "RECEIVED",
  "totalAmount": "150.00",
  "currency": "ARS",
  "createdAt": "2026-04-17T14:37:44Z"
}

Errors

HTTP	Meaning
404	Parent payment not found.
422	Parent is not in SETTLED, or the requested amount exceeds the remaining refundable.

The parent payment stays in SETTLED regardless of how many refunds are issued. Watch your webhooks for payment.refund.created and payment.refund.settled.

GET /payments/{id}/refund

Returns the list of refund children plus an aggregated summary.

Response 200 OK

{
  "parentId": "69e0df45b604159c5b8ba5a9",
  "refunds": [
    {
      "id": "69e25383b604159c5b8ba5bb",
      "status": "RECEIVED",
      "totalAmount": "150.00",
      "currency": "ARS",
      "parentPaymentId": "69e0df45b604159c5b8ba5a9",
      "createdAt": "2026-04-17T14:37:44Z"
    }
  ],
  "summary": {
    "parentPaymentId": "69e0df45b604159c5b8ba5a9",
    "parentAmount": "2000.00",
    "currency": "ARS",
    "totalRefunded": "0",
    "totalInProgress": "150.00",
    "totalFailed": "0",
    "maxRefundable": "1850.00",
    "completedCount": 0,
    "inProgressCount": 1,
    "failedCount": 0
  }
}

Bucket	Includes children in status
totalRefunded	SETTLED
totalInProgress	CREATED, AUTHORIZED, CAPTURED, RECEIVED
totalFailed	FAILED, EXPIRED, UNSETTLED

maxRefundable = parentAmount − (totalRefunded + totalInProgress). Use it to size your next refund.

---

Assign an unassigned balance

When a topup arrives without a destination account (see Unassigned balances), the payment sits in CREATED until an account is assigned. Use this endpoint to reconcile the payment against one of your accounts.

POST /payments/{id}/assign

Path parameters

Name	Type	Description
id	string	Payment id of the unassigned topup.

Body

{
  "accountNumber": "17733420419010021326597",
  "expectedAmount": "10000.00"
}

Field	Type	Required	Description
accountNumber	string	✓	Destination account number. Must belong to the same client.
expectedAmount	string		Expected amount for reconciliation. When supplied, drives amount classification (UNDERPAID / OVERPAID) and spawns a companion child transaction for the difference. When omitted, the topup is treated as PAID.

Response 200 OK

{
  "paymentId": "69e25246baa9fd9b463d6baf",
  "accountNumber": "17733420419010021326597",
  "status": "SETTLED",
  "reconciliationStatus": "PAID",
  "settledAt": "2026-04-17T15:00:00Z",
  "totalAmount": "10000.00",
  "currency": "ARS"
}

Response 200 OK — underpaid / overpaid case

When expectedAmount does not match the received amount, the response includes a childPaymentId pointing at the companion transaction that captures the difference:

{
  "paymentId": "69e25246baa9fd9b463d6baf",
  "accountNumber": "17733420419010021326597",
  "status": "SETTLED",
  "reconciliationStatus": "UNDERPAID",
  "settledAt": "2026-04-17T15:00:00Z",
  "totalAmount": "7500.00",
  "currency": "ARS",
  "relatedPaymentId": "69e25247baa9fd9b463d6bb0",
  "childPaymentId": "69e25247baa9fd9b463d6bb0"
}

See Amount reconciliation for how the platform classifies the delta.

Errors

HTTP	Meaning
404	Payment not found, or the accountNumber does not belong to the caller's client.
422	Payment is not in CREATED — already assigned, expired, or in another terminal state.

Webhook fired: payment.settled (plus purchase.underpaid / purchase.overpaid when applicable).

---

Attach a review document

When a payment is in REQUIRES_REVIEW and documentationStatus is PENDING_UPLOAD, attach a document to resume the lifecycle. See Review flow for the end-to-end compliance flow.

POST /payments/{id}/documents

Body

{
  "type": "source_of_funds",
  "url": "https://documents.conomyhq.com/payments/.../source_of_funds/file.pdf",
  "contentType": "application/pdf"
}

Field	Type	Required	Description
type	string	✓	Document type. See Supported documents.
url	string		Canonical storage URL. When omitted, the document is stored in PENDING_UPLOAD.
contentType	string		MIME type.

Response 201 Created

{
  "paymentId": "69e25244baa9fd9b463d6bad",
  "status": "REQUIRES_REVIEW",
  "documentationStatus": "UPLOADED",
  "document": {
    "type": "source_of_funds",
    "url": "https://documents.conomyhq.com/...",
    "contentType": "application/pdf",
    "uploadedAt": "2026-04-17T15:34:23Z",
    "status": "UPLOADED"
  }
}

---

Customer link

GET /payments/{id}/customer

Returns the persistent Customer record bound to the payment.

Response 200 OK

{
  "paymentId": "69e25244baa9fd9b463d6bad",
  "attached": true,
  "customer": {
    "id": "69e25243baa9fd9b463d6bac",
    "clientId": "your-client-id",
    "firstName": "Carlos",
    "lastName": "Nuevo",
    "documentNumber": "23111222331",
    "operationLevel": "BASIC",
    "autoCreated": true,
    "documents": []
  }
}

attached: false is returned for legacy payments that do not carry a persistent customer reference. In that case, fall back to the payment's embedded customer snapshot.