Match a payout to a deposit

curl --request POST \
  --url https://api.arcuserp.com/v1/entities/{entity_id}/reconciliation/match-marketplace-payout \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "bank_transaction_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "marketplace_payout_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "reconciliation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "skip_settlement_correction": false
}
'

import requests

url = "https://api.arcuserp.com/v1/entities/{entity_id}/reconciliation/match-marketplace-payout"

payload = {
    "bank_transaction_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "marketplace_payout_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "reconciliation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "skip_settlement_correction": False
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    bank_transaction_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    marketplace_payout_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    reconciliation_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    skip_settlement_correction: false
  })
};

fetch('https://api.arcuserp.com/v1/entities/{entity_id}/reconciliation/match-marketplace-payout', 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.arcuserp.com/v1/entities/{entity_id}/reconciliation/match-marketplace-payout",
  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([
    'bank_transaction_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'marketplace_payout_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'reconciliation_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'skip_settlement_correction' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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.arcuserp.com/v1/entities/{entity_id}/reconciliation/match-marketplace-payout"

	payload := strings.NewReader("{\n  \"bank_transaction_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"marketplace_payout_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"reconciliation_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"skip_settlement_correction\": false\n}")

	req, _ := http.NewRequest("POST", 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.post("https://api.arcuserp.com/v1/entities/{entity_id}/reconciliation/match-marketplace-payout")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"bank_transaction_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"marketplace_payout_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"reconciliation_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"skip_settlement_correction\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.arcuserp.com/v1/entities/{entity_id}/reconciliation/match-marketplace-payout")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"bank_transaction_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"marketplace_payout_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"reconciliation_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"skip_settlement_correction\": false\n}"

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

{
  "bank_transaction_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "marketplace_payout_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "platform": "<string>",
  "matched": true,
  "amount_warning": "<string>",
  "bank_account_warning": "<string>",
  "bank_account_scope": "same_bank_account",
  "settlement_correction": {
    "status": "posted",
    "posted": true,
    "shape": "none",
    "reason": "<string>",
    "corrects_entry_number": "<string>",
    "payout_date": "2023-12-25",
    "entry_date": "2023-12-25",
    "amount": 123,
    "entries": [
      "<string>"
    ],
    "legs": [
      {
        "role": "reclass",
        "entry_date": "2023-12-25",
        "entry_number": "<string>",
        "amount": 123,
        "source_type": "RECLASSIFICATION"
      }
    ],
    "idempotent": true,
    "baseline_adoptions": [
      {
        "role": "<string>",
        "entry_number": "<string>",
        "bank_account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "anchor": "2023-12-25",
        "stamped": 123
      }
    ]
  },
  "settlement_mapping": {
    "status": "learned",
    "platform": "<string>",
    "external_destination_id": "<string>",
    "bank_account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  },
  "book_side": {
    "stamped": 123,
    "line_ids": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ],
    "reason": "no_leg_on_bank_gl",
    "historical_import": true,
    "correction_legs": [
      {
        "journal_entry_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "entry_number": "<string>",
        "entry_date": "2023-12-25",
        "stamped": 123
      }
    ]
  },
  "correction_book_side": [
    {
      "role": "reclass",
      "entry_number": "<string>",
      "stamped": 123,
      "reason": "<string>"
    }
  ]
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

Reconciliation

Match a payout to a deposit

Pairs an inbound bank transaction with an unmatched, posted marketplace payout (Shopify, Amazon, or eBay), atomically linking the two records and flipping the transaction to matched. When the payout’s own journal entry was booked against a different bank account, the match also posts a settlement-correction entry to move the deposit onto the right bank unless skip_settlement_correction is set; requires accounting:write scope and is idempotent via the Idempotency-Key header.

POST

entities

{entity_id}

reconciliation

match-marketplace-payout

Match a payout to a deposit

curl --request POST \
  --url https://api.arcuserp.com/v1/entities/{entity_id}/reconciliation/match-marketplace-payout \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "bank_transaction_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "marketplace_payout_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "reconciliation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "skip_settlement_correction": false
}
'

import requests

url = "https://api.arcuserp.com/v1/entities/{entity_id}/reconciliation/match-marketplace-payout"

payload = {
    "bank_transaction_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "marketplace_payout_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "reconciliation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "skip_settlement_correction": False
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    bank_transaction_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    marketplace_payout_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    reconciliation_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    skip_settlement_correction: false
  })
};

fetch('https://api.arcuserp.com/v1/entities/{entity_id}/reconciliation/match-marketplace-payout', 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.arcuserp.com/v1/entities/{entity_id}/reconciliation/match-marketplace-payout",
  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([
    'bank_transaction_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'marketplace_payout_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'reconciliation_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    'skip_settlement_correction' => false
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$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.arcuserp.com/v1/entities/{entity_id}/reconciliation/match-marketplace-payout"

	payload := strings.NewReader("{\n  \"bank_transaction_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"marketplace_payout_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"reconciliation_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"skip_settlement_correction\": false\n}")

	req, _ := http.NewRequest("POST", 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.post("https://api.arcuserp.com/v1/entities/{entity_id}/reconciliation/match-marketplace-payout")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"bank_transaction_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"marketplace_payout_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"reconciliation_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"skip_settlement_correction\": false\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.arcuserp.com/v1/entities/{entity_id}/reconciliation/match-marketplace-payout")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"bank_transaction_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"marketplace_payout_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"reconciliation_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n  \"skip_settlement_correction\": false\n}"

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

{
  "bank_transaction_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "marketplace_payout_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "platform": "<string>",
  "matched": true,
  "amount_warning": "<string>",
  "bank_account_warning": "<string>",
  "bank_account_scope": "same_bank_account",
  "settlement_correction": {
    "status": "posted",
    "posted": true,
    "shape": "none",
    "reason": "<string>",
    "corrects_entry_number": "<string>",
    "payout_date": "2023-12-25",
    "entry_date": "2023-12-25",
    "amount": 123,
    "entries": [
      "<string>"
    ],
    "legs": [
      {
        "role": "reclass",
        "entry_date": "2023-12-25",
        "entry_number": "<string>",
        "amount": 123,
        "source_type": "RECLASSIFICATION"
      }
    ],
    "idempotent": true,
    "baseline_adoptions": [
      {
        "role": "<string>",
        "entry_number": "<string>",
        "bank_account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "anchor": "2023-12-25",
        "stamped": 123
      }
    ]
  },
  "settlement_mapping": {
    "status": "learned",
    "platform": "<string>",
    "external_destination_id": "<string>",
    "bank_account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  },
  "book_side": {
    "stamped": 123,
    "line_ids": [
      "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    ],
    "reason": "no_leg_on_bank_gl",
    "historical_import": true,
    "correction_legs": [
      {
        "journal_entry_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "entry_number": "<string>",
        "entry_date": "2023-12-25",
        "stamped": 123
      }
    ]
  },
  "correction_book_side": [
    {
      "role": "reclass",
      "entry_number": "<string>",
      "stamped": 123,
      "reason": "<string>"
    }
  ]
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

{
  "error": "not_found",
  "code": "not_found",
  "type": "not_found",
  "hint": "The requested order does not exist or does not belong to this entity.",
  "param": "expand[0]",
  "required": "accounts:read",
  "request_id": "req_abc123"
}

Authorizations

Authorization

string

header

required

API key issued per entity via Settings > Developers > API Keys. Each key carries scopes (e.g. orders:read, products:write). Bearer token format: Authorization: Bearer ark_live_ent_Test keys use ark_test_ent_. Both are issued per entity via Settings > Developers > API Keys.

Headers

Idempotency-Key

string

Deduplicates retried match submissions for 24 hours.

Maximum string length: 255

Path Parameters

entity_id

string<uuid>

required

Body

application/json

bank_transaction_id

string<uuid>

required

The inbound bank transaction to match.

marketplace_payout_id

string<uuid>

required

The unmatched, posted marketplace payout to pair with it.

reconciliation_id

string<uuid> | null

Optional open bank-reconciliation to attach the match to.

skip_settlement_correction

boolean

default:false

Record the match without correcting the journal entry when the payout settles a different bank account than the transaction. The match still succeeds and the bank side still ties; the general-ledger side stays on the account it is on. The choice is recorded on the audit trail for the match.

Response

Match recorded. A settlement correction is posted only when the payout settles a different bank account than the matched transaction and skip_settlement_correction was not sent; settlement_correction.status says which happened.

bank_transaction_id

string<uuid>

marketplace_payout_id

string<uuid>

platform

string

matched

boolean

amount_warning

string | null

Set when bank and payout amounts differ by more than $0.05.

bank_account_warning

string | null

A plain sentence for the operator when the payout settles a different bank account, saying what was done about it. Null when the banks agree or the payout's bank cannot be attributed.

bank_account_scope

enum<string>

Whether the payout's journal entry settles the same bank as the matched transaction. unknown_bank_account means the entry has no single bank leg to compare, which is not a mismatch.

Available options:

same_bank_account,

different_bank_account,

unknown_bank_account

settlement_correction

object

What happened to the GENERAL LEDGER when you matched a connector deposit to a bank line. Added 2026-09-19 by BANKFEED wave 4 lane W4-F2.

A processor states which bank account it paid, on every payout. Arcus used to book every payout to one bank account configured per platform, so when the settlement bank changed, deposits kept landing on the old account in the books while the cash landed in the new one at the bank. Matching the deposit to the real bank line is the moment Arcus learns the truth, and this object says what it did with it.

status is the field to switch on:

posted a correction was written. shape says which.
not_applicable the banks already agree, or the payout has no single bank leg to compare.
not_needed right bank, right day: there is nothing to correct.
pending_operator_review the payout settles a different bank, but this match was automatic or part of a bulk approve, and Arcus never moves money in the ledger without a person asking. Open the payout and match it yourself to correct the books.
skipped_by_operator you asked for the match without the correction.
not_resolvable the payout, one of the two banks, or the date to post on could not be resolved. reason says which: payout_has_no_journal_entry, settle_bank_gl_unresolved, target_bank_gl_unresolved, or bank_line_has_no_date when the bank line being matched carries no date to post the correction on. Nothing is posted and the match itself still succeeds.
entry_not_live the payout's journal entry is voided or reversed.

shape says how the correction was written:

reclass_only one entry, dated on the payout date, moving the deposit from the bank it was booked to onto the bank it was paid into.
redate_and_reclass the payout entry was ALSO dated in a later month than the day the money arrived, so the correction is a dated pair: one entry removes the deposit from the month it was wrongly booked in, the other records it in the month it arrived. Each month closes on the truth, and the clearing account carries the money in between, which is where it genuinely was.
redate_only the bank was right and only the month was wrong.

The ledger effect of any shape is zero: every entry balances, and the trial balance is the same to the cent before and after. What moves is which bank account, and which month, holds the deposit.

Show child attributes

settlement_mapping

object | null

Set when this match taught Arcus which bank account a processor destination pays into, so later payouts from the same destination book to the right bank without anyone configuring it. Learned only from an explicit match by a named user.

Show child attributes

book_side

object | null

What the GENERAL LEDGER now says about the money this bank line explains. Added 2026-09-19 by BANKFEED wave 4 lane W4-G, and it is purely additive: no request field changed and no existing response field changed meaning.

A bank reconciliation has two sides. The bank side is reconciliation_status on the bank transaction. The BOOK side is reconciled_at on the journal entry's line on that bank account's GL account, and until this lane no verb outside a statement session ever wrote it, so matched money could read UNCLEARED in the ledger forever.

STILL NO GL IS POSTED. The stamp writes no debit and no credit; the trial balance is identical before and after, and a closed period cannot be moved by it. What it changes is which lines the reconciliation workbench and the bank register's open-items tile still treat as outstanding.

stamped: 0 with a reason is an honest answer, not an error: no_leg_on_bank_gl means the entry carries no line on THIS account's GL (a payout settled to a different account, for example); already_reconciled means a session or a baseline had already cleared it; missing_argument means the record carries no journal entry to stamp.

Show child attributes

correction_book_side

object[]

The settlement-correction entries whose bank line was marked cleared by this match, so the cleared balance follows the correction rather than staying on the original entry.

Show child attributes

Overview

All Endpoints

Match a payout to a deposit

Authorizations

Headers

Path Parameters

Body

Response