Billing

Records a payment received outside Gorelo against an approved invoice.

Required: InvoiceId, PaymentDate and Reference.

Optional:Amount - defaults to the invoice’s whole amount due. It must be greater than 0 and no more than what the invoice still owes, so an invoice cannot be overpaid. PaymentDate is a calendar date and cannot be later than today in the service provider’s time zone.

The invoice must be Approved. A payment that leaves nothing owing marks the invoice Paid; otherwise its status is unchanged. The payment is added to the invoice’s timeline and appears in Payments on GET /v1/invoices/{invoiceId}.

Refused with 409 while the service provider has Xero or QuickBooks Online connected - record the payment there instead and it syncs to Gorelo. An invoice that doesn’t exist, or belongs to another service provider, is a 404.

The response is just the recorded payment’s Id.

POST

payments

Records a payment received outside Gorelo against an approved invoice.

curl --request POST \
  --url https://api.usw.gorelo.io/v1/payments \
  --header 'Content-Type: application/json-patch+json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "InvoiceId": "3f1a9e2b-6c4d-4e2a-8b1a-0e2f7c9d1a44",
  "Amount": 250,
  "PaymentDate": "2026-10-01",
  "Reference": "BANK-20261001-118"
}
'

import requests

url = "https://api.usw.gorelo.io/v1/payments"

payload = {
    "InvoiceId": "3f1a9e2b-6c4d-4e2a-8b1a-0e2f7c9d1a44",
    "Amount": 250,
    "PaymentDate": "2026-10-01",
    "Reference": "BANK-20261001-118"
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json-patch+json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json-patch+json'},
  body: JSON.stringify({
    InvoiceId: '3f1a9e2b-6c4d-4e2a-8b1a-0e2f7c9d1a44',
    Amount: 250,
    PaymentDate: '2026-10-01',
    Reference: 'BANK-20261001-118'
  })
};

fetch('https://api.usw.gorelo.io/v1/payments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.usw.gorelo.io/v1/payments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'InvoiceId' => '3f1a9e2b-6c4d-4e2a-8b1a-0e2f7c9d1a44',
    'Amount' => 250,
    'PaymentDate' => '2026-10-01',
    'Reference' => 'BANK-20261001-118'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json-patch+json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.usw.gorelo.io/v1/payments"

	payload := strings.NewReader("{\n  \"InvoiceId\": \"3f1a9e2b-6c4d-4e2a-8b1a-0e2f7c9d1a44\",\n  \"Amount\": 250,\n  \"PaymentDate\": \"2026-10-01\",\n  \"Reference\": \"BANK-20261001-118\"\n}")

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

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json-patch+json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.usw.gorelo.io/v1/payments")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json-patch+json")
  .body("{\n  \"InvoiceId\": \"3f1a9e2b-6c4d-4e2a-8b1a-0e2f7c9d1a44\",\n  \"Amount\": 250,\n  \"PaymentDate\": \"2026-10-01\",\n  \"Reference\": \"BANK-20261001-118\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.usw.gorelo.io/v1/payments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json-patch+json'
request.body = "{\n  \"InvoiceId\": \"3f1a9e2b-6c4d-4e2a-8b1a-0e2f7c9d1a44\",\n  \"Amount\": 250,\n  \"PaymentDate\": \"2026-10-01\",\n  \"Reference\": \"BANK-20261001-118\"\n}"

response = http.request(request)
puts response.read_body

{
  "StatusCode": 100,
  "IsSuccess": true,
  "Data": {
    "Id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  },
  "DataContext": null,
  "Notifications": [
    {
      "Code": "070101",
      "Message": "<string>",
      "PropertyName": "<string>",
      "ActionHint": "<string>",
      "DocUrl": "<string>"
    }
  ]
}

{
  "StatusCode": 100,
  "IsSuccess": true,
  "Data": null,
  "DataContext": {
    "TraceId": "<string>"
  },
  "Notifications": [
    {
      "Code": "070101",
      "Message": "<string>",
      "PropertyName": "<string>",
      "ActionHint": "<string>",
      "DocUrl": "<string>"
    }
  ]
}

{
  "StatusCode": 100,
  "IsSuccess": true,
  "Data": null,
  "DataContext": {
    "TraceId": "<string>"
  },
  "Notifications": [
    {
      "Code": "070101",
      "Message": "<string>",
      "PropertyName": "<string>",
      "ActionHint": "<string>",
      "DocUrl": "<string>"
    }
  ]
}

{
  "StatusCode": 100,
  "IsSuccess": true,
  "Data": null,
  "DataContext": {
    "TraceId": "<string>"
  },
  "Notifications": [
    {
      "Code": "070101",
      "Message": "<string>",
      "PropertyName": "<string>",
      "ActionHint": "<string>",
      "DocUrl": "<string>"
    }
  ]
}

{
  "StatusCode": 100,
  "IsSuccess": true,
  "Data": null,
  "DataContext": {
    "TraceId": "<string>"
  },
  "Notifications": [
    {
      "Code": "070101",
      "Message": "<string>",
      "PropertyName": "<string>",
      "ActionHint": "<string>",
      "DocUrl": "<string>"
    }
  ]
}

{
  "StatusCode": 100,
  "IsSuccess": true,
  "Data": null,
  "DataContext": {
    "TraceId": "<string>"
  },
  "Notifications": [
    {
      "Code": "070101",
      "Message": "<string>",
      "PropertyName": "<string>",
      "ActionHint": "<string>",
      "DocUrl": "<string>"
    }
  ]
}

التفويضات

X-API-Key

string

header

مطلوب

Your Gorelo API key. See Generate API key. If your data is hosted in Australia, click the base URL at the top of this page and select https://api.aue.gorelo.io.

الجسم

The payment to record.

Records a payment received outside Gorelo against an invoice.

InvoiceId

string<uuid>

Invoice the payment is recorded against. Required. The invoice must be Approved; an invoice that does not exist, or belongs to another service provider, is a 404.

مثال:

"3f1a9e2b-6c4d-4e2a-8b1a-0e2f7c9d1a44"

Amount

number<double> | null

Amount received. Optional - defaults to the invoice's whole amount due when omitted. Must be greater than 0 and no more than the invoice's amount due.

مثال:

250

PaymentDate

string<date> | null

Date the payment was received, a calendar date. Required. Cannot be later than today in the service provider's time zone.

مثال:

"2026-10-01"

Reference

string

Your reference for the payment, such as a bank transaction or remittance number. Required, max 50 characters.

مثال:

"BANK-20261001-118"

الاستجابة

StatusCode

enum<integer>

الخيارات المتاحة:

100,

101,

102,

103,

200,

201,

202,

203,

204,

205,

206,

207,

208,

226,

300,

301,

302,

303,

304,

305,

306,

307,

308,

400,

401,

402,

403,

404,

405,

406,

407,

408,

409,

410,

411,

412,

413,

414,

415,

416,

417,

421,

422,

423,

424,

426,

428,

429,

431,

451,

500,

501,

502,

503,

504,

505,

506,

507,

508,

510,

511

IsSuccess

boolean

Data

object

Result of recording a payment: just the new payment's Id, the same minimal shape Create Invoice returns. The payment appears in Payments on GET /v1/invoices/{invoiceId}.

Show child attributes

DataContext

object | null

مثال:

null

Notifications

object[]

Show child attributes

⌘I

Records a payment received outside Gorelo against an approved invoice.

curl --request POST \
  --url https://api.usw.gorelo.io/v1/payments \
  --header 'Content-Type: application/json-patch+json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "InvoiceId": "3f1a9e2b-6c4d-4e2a-8b1a-0e2f7c9d1a44",
  "Amount": 250,
  "PaymentDate": "2026-10-01",
  "Reference": "BANK-20261001-118"
}
'

import requests

url = "https://api.usw.gorelo.io/v1/payments"

payload = {
    "InvoiceId": "3f1a9e2b-6c4d-4e2a-8b1a-0e2f7c9d1a44",
    "Amount": 250,
    "PaymentDate": "2026-10-01",
    "Reference": "BANK-20261001-118"
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json-patch+json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json-patch+json'},
  body: JSON.stringify({
    InvoiceId: '3f1a9e2b-6c4d-4e2a-8b1a-0e2f7c9d1a44',
    Amount: 250,
    PaymentDate: '2026-10-01',
    Reference: 'BANK-20261001-118'
  })
};

fetch('https://api.usw.gorelo.io/v1/payments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.usw.gorelo.io/v1/payments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'InvoiceId' => '3f1a9e2b-6c4d-4e2a-8b1a-0e2f7c9d1a44',
    'Amount' => 250,
    'PaymentDate' => '2026-10-01',
    'Reference' => 'BANK-20261001-118'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json-patch+json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.usw.gorelo.io/v1/payments"

	payload := strings.NewReader("{\n  \"InvoiceId\": \"3f1a9e2b-6c4d-4e2a-8b1a-0e2f7c9d1a44\",\n  \"Amount\": 250,\n  \"PaymentDate\": \"2026-10-01\",\n  \"Reference\": \"BANK-20261001-118\"\n}")

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

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json-patch+json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.usw.gorelo.io/v1/payments")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json-patch+json")
  .body("{\n  \"InvoiceId\": \"3f1a9e2b-6c4d-4e2a-8b1a-0e2f7c9d1a44\",\n  \"Amount\": 250,\n  \"PaymentDate\": \"2026-10-01\",\n  \"Reference\": \"BANK-20261001-118\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.usw.gorelo.io/v1/payments")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json-patch+json'
request.body = "{\n  \"InvoiceId\": \"3f1a9e2b-6c4d-4e2a-8b1a-0e2f7c9d1a44\",\n  \"Amount\": 250,\n  \"PaymentDate\": \"2026-10-01\",\n  \"Reference\": \"BANK-20261001-118\"\n}"

response = http.request(request)
puts response.read_body

{
  "StatusCode": 100,
  "IsSuccess": true,
  "Data": {
    "Id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  },
  "DataContext": null,
  "Notifications": [
    {
      "Code": "070101",
      "Message": "<string>",
      "PropertyName": "<string>",
      "ActionHint": "<string>",
      "DocUrl": "<string>"
    }
  ]
}

{
  "StatusCode": 100,
  "IsSuccess": true,
  "Data": null,
  "DataContext": {
    "TraceId": "<string>"
  },
  "Notifications": [
    {
      "Code": "070101",
      "Message": "<string>",
      "PropertyName": "<string>",
      "ActionHint": "<string>",
      "DocUrl": "<string>"
    }
  ]
}

{
  "StatusCode": 100,
  "IsSuccess": true,
  "Data": null,
  "DataContext": {
    "TraceId": "<string>"
  },
  "Notifications": [
    {
      "Code": "070101",
      "Message": "<string>",
      "PropertyName": "<string>",
      "ActionHint": "<string>",
      "DocUrl": "<string>"
    }
  ]
}

{
  "StatusCode": 100,
  "IsSuccess": true,
  "Data": null,
  "DataContext": {
    "TraceId": "<string>"
  },
  "Notifications": [
    {
      "Code": "070101",
      "Message": "<string>",
      "PropertyName": "<string>",
      "ActionHint": "<string>",
      "DocUrl": "<string>"
    }
  ]
}

{
  "StatusCode": 100,
  "IsSuccess": true,
  "Data": null,
  "DataContext": {
    "TraceId": "<string>"
  },
  "Notifications": [
    {
      "Code": "070101",
      "Message": "<string>",
      "PropertyName": "<string>",
      "ActionHint": "<string>",
      "DocUrl": "<string>"
    }
  ]
}

{
  "StatusCode": 100,
  "IsSuccess": true,
  "Data": null,
  "DataContext": {
    "TraceId": "<string>"
  },
  "Notifications": [
    {
      "Code": "070101",
      "Message": "<string>",
      "PropertyName": "<string>",
      "ActionHint": "<string>",
      "DocUrl": "<string>"
    }
  ]
}