API Reference / Payment Links REST

Actions

Creates a reusable payment link for collecting payments.

POST/payment-links

Create payment link

Headers

Authorizationstringrequired

Bearer access token returned by the authentication endpoint.

x-api-keystringrequired

The API key used for authentication when making requests to the API Gateway.

conomyhq-api-versionstring

API version selector for Conomy endpoints. Use 24-04-2025 for the current version.

User-Agentstringrequired

Identifies the application making the request.

Request body

checkoutTokenstringrequired

Reference for checkout url

itemsobject[]required

List of items to pay for

preTaxAmountstringrequired

The amount of the item

totalAmountstringrequired

amount + tax.amount, if no tax it's equal to amount

descriptionstringrequired

The description of the item

taxobjectnullableshow 4 properties

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.

paymentMethodsAllowedstring[]min 1 itemsrequired

Allowed payment methods.

customerobject

Optional customer to pass into the checkout session

idstring

Unique identifier for the internal service.

firstNamestring

Payer's name

emailstring

Payer's email

lastNamestring

Payer's last name

phoneNumberstring

Payer's phone number without prefix

phoneNumberPrefixstring

Phone number prefix (e.g., +57)

documentTypestring

Documeny type of the entity (e.g., RUT, CURP, CURL). Go to the Supported Identity document types page for the complete list of supported values.

documentNumberstring

The document number associated with the documentType

addressobjectshow 8 properties

The entity’s address information.

destinationsobject[]min 1 itemsrequired

A list of destinations for the transaction.

namestring

The name of the source or destination of the transaction.

typestringrequired

ACCOUNT

externalIdstring

External reference identifier for integrations.

amountstringrequired

The amount involved in the transaction.

metadataobjectshow 3 properties

Additional metadata related to the transaction source or destination.

accountobjectrequiredshow 4 properties

durationinteger≥ 30required

Amount of seconds for payment link to be inactivated after creation

customerRequirementsstring[]

ownerobjectrequired

Identity reference object used inside account nodes.

identityIdstringrequired

User unique identifier

namestring

User name

lastnamestring

User lastname

nicknamestring

User nickname

documentNumberstring

User DNI

entityTypestring

Entity type of identity

successUrlstring

The URL to which the end user will be redirected after successful payment completion.

failedUrlstring

The URL to which the end user will be redirected after failed payment or cancellation.

Responses

201Resource created successfully.

idstringrequired

Unique identifier for the internal service.

checkoutTokenstringrequired

Reference for checkout url

statusstringrequired

ATTEMPTACTIVEEXPIREDFINISHEDPROCESSING_PAYMENT

itemsobject[]requiredshow items

List of items to pay for

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.

preTaxAmountstringrequired

Addition of all items preTaxAmounts

totalAmountstringrequired

Addition of all items totalAmounts

urlstringrequired

Url to open checkout flow

paymentMethodsAllowedstring[]min 1 itemsrequired

Allowed payment methods.

customerobjectnullableshow 9 properties

Optional customer to pass into the checkout session

createdAtstringdate-timerequired

When the link expires

destinationsobject[]min 1 itemsrequiredshow items

A list of destinations for the transaction.

durationinteger≥ 30required

Amount of seconds for payment link to be inactivated after creation

customerRequirementsstring[]

ownerobjectrequiredshow 6 properties

Identity reference object used inside account nodes.

successUrlstring

The URL to which the end user will be redirected after successful payment completion.

failedUrlstring

The URL to which the end user will be redirected after failed payment or cancellation.

400Invalid request parameters or payload.

errorobjectshow 2 properties

messagestringnullable

Human-readable message. May be null.

500Unexpected internal server error.

errorobjectshow 2 properties

messagestringnullable

Human-readable message. May be null.

Request

HTTPcurlTypeScriptPythonGoRust

POST /sandbox/payment-links HTTP/1.1
Host: api.conomyhq.com
Authorization: Bearer {ACCESS_TOKEN}
x-api-key: {YOUR_API_KEY}
conomyhq-api-version: 24-04-2025
User-Agent: MyApp/1.0
Content-Type: application/json

{
  "checkoutToken": "string",
  "items": [
    {
      "preTaxAmount": "string",
      "totalAmount": "string",
      "description": "string"
    }
  ],
  "currency": "string",
  "paymentMethodsAllowed": [
    "CARD"
  ],
  "customer": {},
  "destinations": [
    {
      "type": "ACCOUNT",
      "amount": "string",
      "account": {
        "type": null,
        "currency": null,
        "accountNumber": null,
        "accountHolder": null
      }
    }
  ],
  "duration": 30,
  "customerRequirements": [
    "firstName"
  ],
  "owner": {
    "identityId": "string"
  },
  "successUrl": "string"
}

curl -X POST \
  'https://api.conomyhq.com/sandbox/payment-links' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {YOUR_API_KEY}' \
  -H 'conomyhq-api-version: 24-04-2025' \
  -H 'User-Agent: MyApp/1.0' \
  -H 'Content-Type: application/json' \
  -d '{
    "checkoutToken": "string",
    "items": [
      {
        "preTaxAmount": "string",
        "totalAmount": "string",
        "description": "string"
      }
    ],
    "currency": "string",
    "paymentMethodsAllowed": [
      "CARD"
    ],
    "customer": {},
    "destinations": [
      {
        "type": "ACCOUNT",
        "amount": "string",
        "account": {
          "type": null,
          "currency": null,
          "accountNumber": null,
          "accountHolder": null
        }
      }
    ],
    "duration": 30,
    "customerRequirements": [
      "firstName"
    ],
    "owner": {
      "identityId": "string"
    },
    "successUrl": "string"
  }'

const response = await fetch('https://api.conomyhq.com/sandbox/payment-links', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer {ACCESS_TOKEN}',
    'x-api-key': '{YOUR_API_KEY}',
    'conomyhq-api-version': '24-04-2025',
    'User-Agent': 'MyApp/1.0',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "checkoutToken": "string",
    "items": [
      {
        "preTaxAmount": "string",
        "totalAmount": "string",
        "description": "string"
      }
    ],
    "currency": "string",
    "paymentMethodsAllowed": [
      "CARD"
    ],
    "customer": {},
    "destinations": [
      {
        "type": "ACCOUNT",
        "amount": "string",
        "account": {
          "type": null,
          "currency": null,
          "accountNumber": null,
          "accountHolder": null
        }
      }
    ],
    "duration": 30,
    "customerRequirements": [
      "firstName"
    ],
    "owner": {
      "identityId": "string"
    },
    "successUrl": "string"
  }),
});

const data = await response.json();

import requests

payload = {
    "checkoutToken": "string",
    "items": [
        {
            "preTaxAmount": "string",
            "totalAmount": "string",
            "description": "string"
        }
    ],
    "currency": "string",
    "paymentMethodsAllowed": [
        "CARD"
    ],
    "customer": {},
    "destinations": [
        {
            "type": "ACCOUNT",
            "amount": "string",
            "account": {
                "type": null,
                "currency": null,
                "accountNumber": null,
                "accountHolder": null
            }
        }
    ],
    "duration": 30,
    "customerRequirements": [
        "firstName"
    ],
    "owner": {
        "identityId": "string"
    },
    "successUrl": "string"
}

response = requests.post(
    'https://api.conomyhq.com/sandbox/payment-links',
    headers={
    'Authorization': 'Bearer {ACCESS_TOKEN}',
    'x-api-key': '{YOUR_API_KEY}',
    'conomyhq-api-version': '24-04-2025',
    'User-Agent': 'MyApp/1.0',
    'Content-Type': 'application/json',
    },
    json=payload
)

data = response.json()

package main

import (
	"encoding/json"
	"net/http"
	"bytes"
)

func main() {
	payload, _ := json.Marshal(	{
	  "checkoutToken": "string",
	  "items": [
	    {
	      "preTaxAmount": "string",
	      "totalAmount": "string",
	      "description": "string"
	    }
	  ],
	  "currency": "string",
	  "paymentMethodsAllowed": [
	    "CARD"
	  ],
	  "customer": {},
	  "destinations": [
	    {
	      "type": "ACCOUNT",
	      "amount": "string",
	      "account": {
	        "type": null,
	        "currency": null,
	        "accountNumber": null,
	        "accountHolder": null
	      }
	    }
	  ],
	  "duration": 30,
	  "customerRequirements": [
	    "firstName"
	  ],
	  "owner": {
	    "identityId": "string"
	  },
	  "successUrl": "string"
	})
	body := bytes.NewBuffer(payload)
	req, _ := http.NewRequest("POST", "https://api.conomyhq.com/sandbox/payment-links", body)
	req.Header.Set("Authorization", "Bearer {ACCESS_TOKEN}")
	req.Header.Set("x-api-key", "{YOUR_API_KEY}")
	req.Header.Set("conomyhq-api-version", "24-04-2025")
	req.Header.Set("User-Agent", "MyApp/1.0")
	req.Header.Set("Content-Type", "application/json")

	client := &http.Client{}
	resp, _ := client.Do(req)
	defer resp.Body.Close()

	var data map[string]any
	json.NewDecoder(resp.Body).Decode(&data)
}

use reqwest::Client;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new();
    let resp = client
        .post("https://api.conomyhq.com/sandbox/payment-links")
        .header("Authorization", "Bearer {ACCESS_TOKEN}")
        .header("x-api-key", "{YOUR_API_KEY}")
        .header("conomyhq-api-version", "24-04-2025")
        .header("User-Agent", "MyApp/1.0")
        .header("Content-Type", "application/json")
        .json(&json!({
        "checkoutToken": "string",
        "items": [
                {
                        "preTaxAmount": "string",
                        "totalAmount": "string",
                        "description": "string"
                }
        ],
        "currency": "string",
        "paymentMethodsAllowed": [
                "CARD"
        ],
        "customer": {},
        "destinations": [
                {
                        "type": "ACCOUNT",
                        "amount": "string",
                        "account": {
                                "type": null,
                                "currency": null,
                                "accountNumber": null,
                                "accountHolder": null
                        }
                }
        ],
        "duration": 30,
        "customerRequirements": [
                "firstName"
        ],
        "owner": {
                "identityId": "string"
        },
        "successUrl": "string"
}))
        .send()
        .await?;

    let data: serde_json::Value = resp.json().await?;
    Ok(())
}

Response

201 400 401 403 404 422 500

{
  "id": "string",
  "checkoutToken": "string",
  "status": "ATTEMPT",
  "items": [
    {
      "preTaxAmount": "string",
      "totalAmount": "string",
      "description": "string"
    }
  ],
  "currency": "string",
  "preTaxAmount": "string",
  "totalAmount": "string",
  "url": "string",
  "paymentMethodsAllowed": [
    "CARD"
  ],
  "customer": {}
}

{
  "error": {
    "type": "bad_request",
    "info": null
  },
  "message": null
}

{
  "error": {
    "type": "unauthorized",
    "info": null
  },
  "message": null
}

{
  "error": {
    "type": "forbidden",
    "info": null
  },
  "message": null
}

{
  "error": {
    "type": "not_found",
    "info": null
  },
  "message": null
}

{
  "error": {
    "type": "validation_error",
    "info": {
      "field": "string",
      "message": "string"
    }
  },
  "message": null
}

{
  "error": {
    "type": "internal_error",
    "info": null
  },
  "message": null
}