Record a Payment observation

curl --request PUT \
  --url https://api.sandbox.paypathiq.com/v1/clients/{clientCode}/payment-observations/{externalPaymentObservationId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": {
    "amount": "300.00",
    "currency": "EUR"
  },
  "effectiveAt": "2026-08-29T11:45:00Z",
  "method": "bank_transfer",
  "sourceReference": "payment-ref-example",
  "type": "payment"
}
'

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    amount: {amount: '300.00', currency: 'EUR'},
    effectiveAt: '2026-08-29T11:45:00Z',
    method: 'bank_transfer',
    sourceReference: 'payment-ref-example',
    type: 'payment'
  })
};

fetch('https://api.sandbox.paypathiq.com/v1/clients/{clientCode}/payment-observations/{externalPaymentObservationId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.sandbox.paypathiq.com/v1/clients/{clientCode}/payment-observations/{externalPaymentObservationId}"

payload = {
    "amount": {
        "amount": "300.00",
        "currency": "EUR"
    },
    "effectiveAt": "2026-08-29T11:45:00Z",
    "method": "bank_transfer",
    "sourceReference": "payment-ref-example",
    "type": "payment"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sandbox.paypathiq.com/v1/clients/{clientCode}/payment-observations/{externalPaymentObservationId}"

	payload := strings.NewReader("{\n  \"amount\": {\n    \"amount\": \"300.00\",\n    \"currency\": \"EUR\"\n  },\n  \"effectiveAt\": \"2026-08-29T11:45:00Z\",\n  \"method\": \"bank_transfer\",\n  \"sourceReference\": \"payment-ref-example\",\n  \"type\": \"payment\"\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://api.sandbox.paypathiq.com/v1/clients/{clientCode}/payment-observations/{externalPaymentObservationId}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": {\n    \"amount\": \"300.00\",\n    \"currency\": \"EUR\"\n  },\n  \"effectiveAt\": \"2026-08-29T11:45:00Z\",\n  \"method\": \"bank_transfer\",\n  \"sourceReference\": \"payment-ref-example\",\n  \"type\": \"payment\"\n}")
  .asString();

using RestSharp;


var options = new RestClientOptions("https://api.sandbox.paypathiq.com/v1/clients/{clientCode}/payment-observations/{externalPaymentObservationId}");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("Authorization", "Bearer <token>");
request.AddJsonBody("{\n  \"amount\": {\n    \"amount\": \"300.00\",\n    \"currency\": \"EUR\"\n  },\n  \"effectiveAt\": \"2026-08-29T11:45:00Z\",\n  \"method\": \"bank_transfer\",\n  \"sourceReference\": \"payment-ref-example\",\n  \"type\": \"payment\"\n}", false);
var response = await client.PutAsync(request);

Console.WriteLine("{0}", response.Content);

{
  "allocations": [
    {
      "amount": {
        "amount": "250.00",
        "currency": "EUR"
      },
      "externalReceivableId": "REC_123"
    }
  ],
  "amount": {
    "amount": "300.00",
    "currency": "EUR"
  },
  "effectiveAt": "2026-08-29T11:45:00Z",
  "externalCustomerId": "CUS_123",
  "method": "bank_transfer",
  "sourceReference": "payment-ref-example",
  "type": "payment",
  "acceptedAt": "2026-08-29T12:00:00Z",
  "allocationBasis": "explicit",
  "externalPaymentObservationId": "PAY_123",
  "unappliedAmount": {
    "amount": "50.00",
    "currency": "EUR"
  }
}

Payment observations

Record a Payment observation

Record a payment, refund or reversal that happened outside PayPathIQ. Requires payment_observations:write. Records one immutable payment, refund or reversal with its allocations, ledger effects and audit evidence in one locked transaction. A payment applies its explicit allocations first; with none, the connection’s Client-approved allocation rule applies when the paying Customer is identified and the rule’s condition is unambiguous; otherwise the whole amount stays unapplied. Oldest-first is never assumed. Only allocated amounts reduce a Receivable, and an allocation may not exceed its Receivable’s balance. New observations require matching Source and working positions without unused working credits; otherwise explicit reconciliation is required and the request returns 409 financial_operation_required. A refund or reversal records an exact amount against an original Payment and may be partial. Its allocations return amounts to the Receivables that Payment was allocated to (each with an optional resulting-balance guard) and the remainder is taken from the Payment’s unapplied funds; cumulative corrections may not exceed the Payment, any single allocation, or the unapplied remainder. It updates the canonical Payment, its allocations and each Receivable’s working balance atomically. Recording a refund or reversal is evidence only; it never executes a transfer, and it is distinct from credits and write-offs. Money that stays unapplied is announced as a customer.updated change for the paying Customer. If the response is lost, repeat the identical payload with the same observation ID; a replay changes nothing and conflicting reuse returns 409 payment_observation_conflict.

PUT

clients

{clientCode}

payment-observations

{externalPaymentObservationId}

Record a Payment observation

curl --request PUT \
  --url https://api.sandbox.paypathiq.com/v1/clients/{clientCode}/payment-observations/{externalPaymentObservationId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": {
    "amount": "300.00",
    "currency": "EUR"
  },
  "effectiveAt": "2026-08-29T11:45:00Z",
  "method": "bank_transfer",
  "sourceReference": "payment-ref-example",
  "type": "payment"
}
'

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    amount: {amount: '300.00', currency: 'EUR'},
    effectiveAt: '2026-08-29T11:45:00Z',
    method: 'bank_transfer',
    sourceReference: 'payment-ref-example',
    type: 'payment'
  })
};

fetch('https://api.sandbox.paypathiq.com/v1/clients/{clientCode}/payment-observations/{externalPaymentObservationId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.sandbox.paypathiq.com/v1/clients/{clientCode}/payment-observations/{externalPaymentObservationId}"

payload = {
    "amount": {
        "amount": "300.00",
        "currency": "EUR"
    },
    "effectiveAt": "2026-08-29T11:45:00Z",
    "method": "bank_transfer",
    "sourceReference": "payment-ref-example",
    "type": "payment"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.sandbox.paypathiq.com/v1/clients/{clientCode}/payment-observations/{externalPaymentObservationId}"

	payload := strings.NewReader("{\n  \"amount\": {\n    \"amount\": \"300.00\",\n    \"currency\": \"EUR\"\n  },\n  \"effectiveAt\": \"2026-08-29T11:45:00Z\",\n  \"method\": \"bank_transfer\",\n  \"sourceReference\": \"payment-ref-example\",\n  \"type\": \"payment\"\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.put("https://api.sandbox.paypathiq.com/v1/clients/{clientCode}/payment-observations/{externalPaymentObservationId}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": {\n    \"amount\": \"300.00\",\n    \"currency\": \"EUR\"\n  },\n  \"effectiveAt\": \"2026-08-29T11:45:00Z\",\n  \"method\": \"bank_transfer\",\n  \"sourceReference\": \"payment-ref-example\",\n  \"type\": \"payment\"\n}")
  .asString();

using RestSharp;


var options = new RestClientOptions("https://api.sandbox.paypathiq.com/v1/clients/{clientCode}/payment-observations/{externalPaymentObservationId}");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("Authorization", "Bearer <token>");
request.AddJsonBody("{\n  \"amount\": {\n    \"amount\": \"300.00\",\n    \"currency\": \"EUR\"\n  },\n  \"effectiveAt\": \"2026-08-29T11:45:00Z\",\n  \"method\": \"bank_transfer\",\n  \"sourceReference\": \"payment-ref-example\",\n  \"type\": \"payment\"\n}", false);
var response = await client.PutAsync(request);

Console.WriteLine("{0}", response.Content);

{
  "allocations": [
    {
      "amount": {
        "amount": "250.00",
        "currency": "EUR"
      },
      "externalReceivableId": "REC_123"
    }
  ],
  "amount": {
    "amount": "300.00",
    "currency": "EUR"
  },
  "effectiveAt": "2026-08-29T11:45:00Z",
  "externalCustomerId": "CUS_123",
  "method": "bank_transfer",
  "sourceReference": "payment-ref-example",
  "type": "payment",
  "acceptedAt": "2026-08-29T12:00:00Z",
  "allocationBasis": "explicit",
  "externalPaymentObservationId": "PAY_123",
  "unappliedAmount": {
    "amount": "50.00",
    "currency": "EUR"
  }
}

Authorizations

Authorization

string

header

required

Integration-owned environment-specific API key. Never paste a production key into documentation tools.

Path Parameters

clientCode

string

required

Stable non-sensitive Client code authorized by the Integration grant.

Pattern: ^[A-Za-z0-9_-]{1,128}$

externalPaymentObservationId

string

required

Opaque immutable Payment-observation identifier supplied by the Integration.

Pattern: ^[A-Za-z0-9_-]{1,128}$

Body

application/json

One uncompressed resource representation, limited to 256 KiB.

Option 1
Option 2
Option 3

A payment applies explicit allocations first, otherwise a Client-approved allocation rule, otherwise it stays unapplied; only allocated amounts reduce a Receivable. A refund or reversal records an exact, possibly partial, amount against the original Payment: the part named in allocations returns to those Receivables and the remainder is taken from the Payment's unapplied funds. Cumulative corrections cannot exceed the Payment, any allocation, or the unapplied remainder. Recording evidence never executes a transfer.

amount

object

required

Show child attributes

effectiveAt

string<date-time>

required

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$

method

enum<string>

required

Available options:

bank_transfer,

direct_debit,

card,

cash,

cheque,

unknown

sourceReference

string

required

Required string length: 1 - 200

type

string

required

Allowed value: "payment"

allocations

object[]

Explicit allocations to Receivables. Each Receivable may appear once and the total may not exceed amount; any remainder stays unapplied. When omitted, the connection's Client-approved allocation rule may apply, otherwise the whole amount stays unapplied.

Required array length: 1 - 25 elements

Show child attributes

externalCustomerId

string

The paying Customer, when known. Required for a Client-approved allocation rule to apply; unapplied funds are associated with this Customer.

Pattern: ^[A-Za-z0-9_-]{1,128}$

Response

Identical retry of the accepted observation.

Option 1
Option 2
Option 3

amount

object

required

Show child attributes

effectiveAt

string<date-time>

required

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$

method

enum<string>

required

Available options:

bank_transfer,

direct_debit,

card,

cash,

cheque,

unknown

sourceReference

string

required

Required string length: 1 - 200

allocations

object[]

required

Maximum array length: 25

Show child attributes

type

string

required

Allowed value: "payment"

acceptedAt

string<date-time>

required

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$

externalPaymentObservationId

string

required

Pattern: ^[A-Za-z0-9_-]{1,128}$

allocationBasis

enum<string>

required

Available options:

explicit,

rule,

unapplied

unappliedAmount

object

required

Show child attributes

externalCustomerId

string

The paying Customer, when known. Required for a Client-approved allocation rule to apply; unapplied funds are associated with this Customer.

Pattern: ^[A-Za-z0-9_-]{1,128}$

Balance snapshots

Batches

Complete books

Changes

Financial events

Customers

Payment observations

Payment delivery

Payment reconciliation

Payment requests

Receipt delivery

Receivables

Receivable lifecycle

Collection summaries

Recovery instructions

Source freshness

Webhooks

Specification

Record a Payment observation

Authorizations

Path Parameters

Body

Response