Create a remittance

A remittance moves value from a funded Conomy account to a recipient outside the platform. Use it when the business intent is cross-border payout, marketplace settlement, family transfer, or provider payout where currency and destination data may differ from the origin.

Attention

Validate the recipient document, destination rail, and destination currency before capture. Remittance failures are usually caused by missing country-specific payout fields.

Flow

01

Fund origin

Confirm the source account has enough available balance.

02

Build recipient

Collect document, bank, and country-specific payout fields.

03

Create remittance

Submit the origin account and payout destination.

04

Capture

Commit the payout for processing.

05

Reconcile

Wait for the terminal webhook state.

Create the remittance

Request

HTTPcurlJavaScriptPythonGoRust

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

{
  "externalId": "remittance-1001",
  "identityId": "<IDENTITY_ID>",
  "accountNumber": "<ACCOUNT_NUMBER>",
  "product": "USD:COP",
  "type": "REMITTANCE",
  "purchaseAmount": "250.00",
  "purchaseCurrency": "USD",
  "currency": "COP",
  "origins": [
    {
      "type": "ACCOUNT",
      "amount": "250.00",
      "currency": "USD",
      "identity": {
        "identityId": "<IDENTITY_ID>"
      },
      "account": {
        "accountNumber": "<ACCOUNT_NUMBER>"
      }
    }
  ],
  "destinations": [
    {
      "type": "BANK_ACCOUNT",
      "currency": "COP",
      "bank": {
        "accountNumber": "0312345678",
        "bank": "BANCOLOMBIA",
        "currency": "COP",
        "typeAccount": "SAVINGS",
        "accountHolder": "Jane Doe",
        "accountHolderDni": "1000000000",
        "country": "CO"
      },
      "customer": {
        "firstName": "Jane",
        "lastName": "Doe",
        "documentNumber": "1000000000",
        "country": "COL",
        "email": "jane@example.com"
      }
    }
  ]
}

curl -X POST 'https://api.conomyhq.com/sandbox/payments' \
  -H 'x-api-key: {YOUR_API_KEY}' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'conomyhq-api-version: 24-04-2025' \
  -H 'User-Agent: MyApp/1.0' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "externalId": "remittance-1001",
    "identityId": "<IDENTITY_ID>",
    "accountNumber": "<ACCOUNT_NUMBER>",
    "product": "USD:COP",
    "type": "REMITTANCE",
    "purchaseAmount": "250.00",
    "purchaseCurrency": "USD",
    "currency": "COP",
    "origins": [
      {
        "type": "ACCOUNT",
        "amount": "250.00",
        "currency": "USD",
        "identity": {
          "identityId": "<IDENTITY_ID>"
        },
        "account": {
          "accountNumber": "<ACCOUNT_NUMBER>"
        }
      }
    ],
    "destinations": [
      {
        "type": "BANK_ACCOUNT",
        "currency": "COP",
        "bank": {
          "accountNumber": "0312345678",
          "bank": "BANCOLOMBIA",
          "currency": "COP",
          "typeAccount": "SAVINGS",
          "accountHolder": "Jane Doe",
          "accountHolderDni": "1000000000",
          "country": "CO"
        },
        "customer": {
          "firstName": "Jane",
          "lastName": "Doe",
          "documentNumber": "1000000000",
          "country": "COL",
          "email": "jane@example.com"
        }
      }
    ]
  }'

const response = await fetch('https://api.conomyhq.com/sandbox/payments', {
  method: 'POST',
  headers: {
    'x-api-key': '{YOUR_API_KEY}',
    'Authorization': 'Bearer {ACCESS_TOKEN}',
    'conomyhq-api-version': '24-04-2025',
    'User-Agent': 'MyApp/1.0',
    'Content-Type': 'application/json',
    'Accept': 'application/json',
  },
  body: JSON.stringify({
    "externalId": "remittance-1001",
    "identityId": "<IDENTITY_ID>",
    "accountNumber": "<ACCOUNT_NUMBER>",
    "product": "USD:COP",
    "type": "REMITTANCE",
    "purchaseAmount": "250.00",
    "purchaseCurrency": "USD",
    "currency": "COP",
    "origins": [
      {
        "type": "ACCOUNT",
        "amount": "250.00",
        "currency": "USD",
        "identity": {
          "identityId": "<IDENTITY_ID>"
        },
        "account": {
          "accountNumber": "<ACCOUNT_NUMBER>"
        }
      }
    ],
    "destinations": [
      {
        "type": "BANK_ACCOUNT",
        "currency": "COP",
        "bank": {
          "accountNumber": "0312345678",
          "bank": "BANCOLOMBIA",
          "currency": "COP",
          "typeAccount": "SAVINGS",
          "accountHolder": "Jane Doe",
          "accountHolderDni": "1000000000",
          "country": "CO"
        },
        "customer": {
          "firstName": "Jane",
          "lastName": "Doe",
          "documentNumber": "1000000000",
          "country": "COL",
          "email": "jane@example.com"
        }
      }
    ]
  }),
});

const data = await response.json();

import requests

payload = {
  "externalId": "remittance-1001",
  "identityId": "<IDENTITY_ID>",
  "accountNumber": "<ACCOUNT_NUMBER>",
  "product": "USD:COP",
  "type": "REMITTANCE",
  "purchaseAmount": "250.00",
  "purchaseCurrency": "USD",
  "currency": "COP",
  "origins": [
    {
      "type": "ACCOUNT",
      "amount": "250.00",
      "currency": "USD",
      "identity": {
        "identityId": "<IDENTITY_ID>"
      },
      "account": {
        "accountNumber": "<ACCOUNT_NUMBER>"
      }
    }
  ],
  "destinations": [
    {
      "type": "BANK_ACCOUNT",
      "currency": "COP",
      "bank": {
        "accountNumber": "0312345678",
        "bank": "BANCOLOMBIA",
        "currency": "COP",
        "typeAccount": "SAVINGS",
        "accountHolder": "Jane Doe",
        "accountHolderDni": "1000000000",
        "country": "CO"
      },
      "customer": {
        "firstName": "Jane",
        "lastName": "Doe",
        "documentNumber": "1000000000",
        "country": "COL",
        "email": "jane@example.com"
      }
    }
  ]
}

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

data = response.json()

package main

import (
	"bytes"
	"net/http"
)

func main() {
	payload := []byte(`{
  "externalId": "remittance-1001",
  "identityId": "<IDENTITY_ID>",
  "accountNumber": "<ACCOUNT_NUMBER>",
  "product": "USD:COP",
  "type": "REMITTANCE",
  "purchaseAmount": "250.00",
  "purchaseCurrency": "USD",
  "currency": "COP",
  "origins": [
    {
      "type": "ACCOUNT",
      "amount": "250.00",
      "currency": "USD",
      "identity": {
        "identityId": "<IDENTITY_ID>"
      },
      "account": {
        "accountNumber": "<ACCOUNT_NUMBER>"
      }
    }
  ],
  "destinations": [
    {
      "type": "BANK_ACCOUNT",
      "currency": "COP",
      "bank": {
        "accountNumber": "0312345678",
        "bank": "BANCOLOMBIA",
        "currency": "COP",
        "typeAccount": "SAVINGS",
        "accountHolder": "Jane Doe",
        "accountHolderDni": "1000000000",
        "country": "CO"
      },
      "customer": {
        "firstName": "Jane",
        "lastName": "Doe",
        "documentNumber": "1000000000",
        "country": "COL",
        "email": "jane@example.com"
      }
    }
  ]
}`)
	body := bytes.NewReader(payload)
	req, _ := http.NewRequest("POST", "https://api.conomyhq.com/sandbox/payments", body)
	req.Header.Set("x-api-key", "{YOUR_API_KEY}")
	req.Header.Set("Authorization", "Bearer {ACCESS_TOKEN}")
	req.Header.Set("conomyhq-api-version", "24-04-2025")
	req.Header.Set("User-Agent", "MyApp/1.0")
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Accept", "application/json")

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

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

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new();
    let payload = json!({
  "externalId": "remittance-1001",
  "identityId": "<IDENTITY_ID>",
  "accountNumber": "<ACCOUNT_NUMBER>",
  "product": "USD:COP",
  "type": "REMITTANCE",
  "purchaseAmount": "250.00",
  "purchaseCurrency": "USD",
  "currency": "COP",
  "origins": [
    {
      "type": "ACCOUNT",
      "amount": "250.00",
      "currency": "USD",
      "identity": {
        "identityId": "<IDENTITY_ID>"
      },
      "account": {
        "accountNumber": "<ACCOUNT_NUMBER>"
      }
    }
  ],
  "destinations": [
    {
      "type": "BANK_ACCOUNT",
      "currency": "COP",
      "bank": {
        "accountNumber": "0312345678",
        "bank": "BANCOLOMBIA",
        "currency": "COP",
        "typeAccount": "SAVINGS",
        "accountHolder": "Jane Doe",
        "accountHolderDni": "1000000000",
        "country": "CO"
      },
      "customer": {
        "firstName": "Jane",
        "lastName": "Doe",
        "documentNumber": "1000000000",
        "country": "COL",
        "email": "jane@example.com"
      }
    }
  ]
});

    let response = client
        .post("https://api.conomyhq.com/sandbox/payments")
        .header("x-api-key", "{YOUR_API_KEY}")
        .header("Authorization", "Bearer {ACCESS_TOKEN}")
        .header("conomyhq-api-version", "24-04-2025")
        .header("User-Agent", "MyApp/1.0")
        .header("Content-Type", "application/json")
        .header("Accept", "application/json")
        .json(&payload)
        .send()
        .await?;

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

Response

201

{
  "id": "<PAYMENT_ID>",
  "externalId": "remittance-1001",
  "type": "REMITTANCE",
  "status": "CREATED"
}

Capture and track it

Request

HTTPcurlJavaScriptPythonGoRust

POST /sandbox/payments/{PAYMENT_ID}/captured HTTP/1.1
Host: api.conomyhq.com
x-api-key: {YOUR_API_KEY}
Authorization: Bearer {ACCESS_TOKEN}
conomyhq-api-version: 24-04-2025
User-Agent: MyApp/1.0
Accept: application/json

curl -X POST 'https://api.conomyhq.com/sandbox/payments/{PAYMENT_ID}/captured' \
  -H 'x-api-key: {YOUR_API_KEY}' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'conomyhq-api-version: 24-04-2025' \
  -H 'User-Agent: MyApp/1.0' \
  -H 'Accept: application/json'

const response = await fetch('https://api.conomyhq.com/sandbox/payments/{PAYMENT_ID}/captured', {
  method: 'POST',
  headers: {
    'x-api-key': '{YOUR_API_KEY}',
    'Authorization': 'Bearer {ACCESS_TOKEN}',
    'conomyhq-api-version': '24-04-2025',
    'User-Agent': 'MyApp/1.0',
    'Accept': 'application/json',
  },
});

const data = await response.json();

import requests

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

data = response.json()

package main

import (
	"net/http"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.conomyhq.com/sandbox/payments/{PAYMENT_ID}/captured", nil)
	req.Header.Set("x-api-key", "{YOUR_API_KEY}")
	req.Header.Set("Authorization", "Bearer {ACCESS_TOKEN}")
	req.Header.Set("conomyhq-api-version", "24-04-2025")
	req.Header.Set("User-Agent", "MyApp/1.0")
	req.Header.Set("Accept", "application/json")

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

use reqwest::Client;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new();
    let response = client
        .post("https://api.conomyhq.com/sandbox/payments/{PAYMENT_ID}/captured")
        .header("x-api-key", "{YOUR_API_KEY}")
        .header("Authorization", "Bearer {ACCESS_TOKEN}")
        .header("conomyhq-api-version", "24-04-2025")
        .header("User-Agent", "MyApp/1.0")
        .header("Accept", "application/json")
        .send()
        .await?;

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

Response

200

{
  "id": "<PAYMENT_ID>",
  "type": "REMITTANCE",
  "status": "CAPTURED"
}