curl --request POST \
--url https://apiv2.gomarketbox.com/v1/projects/{projectId}/orders/{orderId}/transactions \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"amount": {
"amount": 1,
"currency": "<string>"
},
"clientId": "<string>",
"note": "<string>",
"reason": "Service recovery — late supplier",
"idempotencyKey": "9f8c0f7a-1f3f-4c8e-9a2b-6c7d8e9f0a1b"
}
'import requests
url = "https://apiv2.gomarketbox.com/v1/projects/{projectId}/orders/{orderId}/transactions"
payload = {
"amount": {
"amount": 1,
"currency": "<string>"
},
"clientId": "<string>",
"note": "<string>",
"reason": "Service recovery — late supplier",
"idempotencyKey": "9f8c0f7a-1f3f-4c8e-9a2b-6c7d8e9f0a1b"
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/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'},
body: JSON.stringify({
amount: {amount: 1, currency: '<string>'},
clientId: '<string>',
note: '<string>',
reason: 'Service recovery — late supplier',
idempotencyKey: '9f8c0f7a-1f3f-4c8e-9a2b-6c7d8e9f0a1b'
})
};
fetch('https://apiv2.gomarketbox.com/v1/projects/{projectId}/orders/{orderId}/transactions', 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://apiv2.gomarketbox.com/v1/projects/{projectId}/orders/{orderId}/transactions",
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([
'amount' => [
'amount' => 1,
'currency' => '<string>'
],
'clientId' => '<string>',
'note' => '<string>',
'reason' => 'Service recovery — late supplier',
'idempotencyKey' => '9f8c0f7a-1f3f-4c8e-9a2b-6c7d8e9f0a1b'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/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://apiv2.gomarketbox.com/v1/projects/{projectId}/orders/{orderId}/transactions"
payload := strings.NewReader("{\n \"amount\": {\n \"amount\": 1,\n \"currency\": \"<string>\"\n },\n \"clientId\": \"<string>\",\n \"note\": \"<string>\",\n \"reason\": \"Service recovery — late supplier\",\n \"idempotencyKey\": \"9f8c0f7a-1f3f-4c8e-9a2b-6c7d8e9f0a1b\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
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://apiv2.gomarketbox.com/v1/projects/{projectId}/orders/{orderId}/transactions")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": {\n \"amount\": 1,\n \"currency\": \"<string>\"\n },\n \"clientId\": \"<string>\",\n \"note\": \"<string>\",\n \"reason\": \"Service recovery — late supplier\",\n \"idempotencyKey\": \"9f8c0f7a-1f3f-4c8e-9a2b-6c7d8e9f0a1b\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://apiv2.gomarketbox.com/v1/projects/{projectId}/orders/{orderId}/transactions")
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'
request.body = "{\n \"amount\": {\n \"amount\": 1,\n \"currency\": \"<string>\"\n },\n \"clientId\": \"<string>\",\n \"note\": \"<string>\",\n \"reason\": \"Service recovery — late supplier\",\n \"idempotencyKey\": \"9f8c0f7a-1f3f-4c8e-9a2b-6c7d8e9f0a1b\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"projectId": "<string>",
"tenantId": "<string>",
"transactionId": "<string>",
"kind": "PAYMENT",
"source": "STRIPE",
"status": "PENDING",
"amount": {
"amount": 1,
"currency": "<string>"
},
"orderId": "<string>",
"deleted": true,
"version": 1,
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"createdBy": "<string>",
"updatedBy": "<string>",
"platformFee": {
"amount": 1,
"currency": "<string>"
},
"relatedTransactionId": "<string>",
"orderItemId": "<string>",
"allocationId": "<string>",
"bookingId": "<string>",
"clientId": "<string>",
"stripePaymentIntentId": "<string>",
"stripeChargeId": "<string>",
"stripeRefundId": "<string>",
"stripeAccountId": "<string>",
"connectChargeType": "DIRECT",
"failureCode": "<string>",
"failureMessage": "<string>",
"note": "<string>",
"disputeId": "<string>",
"disputeStatus": "needs_response",
"channel": "BACKOFFICE",
"reason": "<string>"
},
"replayed": true
}{
"data": {
"projectId": "<string>",
"tenantId": "<string>",
"transactionId": "<string>",
"kind": "PAYMENT",
"source": "STRIPE",
"status": "PENDING",
"amount": {
"amount": 1,
"currency": "<string>"
},
"orderId": "<string>",
"deleted": true,
"version": 1,
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"createdBy": "<string>",
"updatedBy": "<string>",
"platformFee": {
"amount": 1,
"currency": "<string>"
},
"relatedTransactionId": "<string>",
"orderItemId": "<string>",
"allocationId": "<string>",
"bookingId": "<string>",
"clientId": "<string>",
"stripePaymentIntentId": "<string>",
"stripeChargeId": "<string>",
"stripeRefundId": "<string>",
"stripeAccountId": "<string>",
"connectChargeType": "DIRECT",
"failureCode": "<string>",
"failureMessage": "<string>",
"note": "<string>",
"disputeId": "<string>",
"disputeStatus": "needs_response",
"channel": "BACKOFFICE",
"reason": "<string>"
},
"replayed": false
}{
"code": "NOT_FOUND",
"message": "Booking not found",
"statusCode": 404,
"requestId": "a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"
}{
"code": "NOT_FOUND",
"message": "Booking not found",
"statusCode": 404,
"requestId": "a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"
}{
"code": "NOT_FOUND",
"message": "Booking not found",
"statusCode": 404,
"requestId": "a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"
}{
"code": "NOT_FOUND",
"message": "Booking not found",
"statusCode": 404,
"requestId": "a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"
}Record a manual (cash/external/comp) transaction against an order
Books money that moved outside Stripe — cash at the door, a bank transfer, a comped session. Card payments do not belong here: source accepts only CASH, EXTERNAL and COMP, and STRIPE is rejected, because Stripe rows are created by the payment-intent flow and settled by webhook. kind: "REFUND" is likewise rejected; refunds are not yet supported.
The two kinds behave differently and the difference is easy to miss. PAYMENT adds to the order’s amountPaid in the same atomic write, so it changes what the order still owes. ADJUSTMENT records a ledger row and leaves amountPaid alone — use it for corrections you want visible in history without moving the balance. Either way the row is written SUCCEEDED immediately, with no pending state to poll.
amount.currency must equal the order’s currency exactly or the call is a 400; the order’s currency is fixed at creation and cannot be converted here. A 409 means the order changed between this call reading it and writing — re-read the order and retry, rather than assuming the payment was recorded. clientId defaults to the order’s client.
source: "COMP" REQUIRES reason — a waived charge with no justification on the ledger is refused with a 400. Record why the charge was waived (“Service recovery — late supplier”), not that it was waived; the row already says that.
Send idempotencyKey on any recording you might retry. The same key on the same order returns the row the FIRST call created, as HTTP 200 with replayed: true, instead of recording the money a second time; a first recording is 201 with replayed: false. Branch on the status or on replayed — never on “a 2xx means I just took a payment”. A key belongs to one order and does not expire.
The order settles as a consequence of this write, not through a separate call: once the ledger covers the order’s total the order moves to PAID in the same atomic write, with settledAt and paymentMethod stamped on it. PAID cannot be asked for directly — POST /orders/{orderId}/status answers a PAID target with a 409.
curl --request POST \
--url https://apiv2.gomarketbox.com/v1/projects/{projectId}/orders/{orderId}/transactions \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"amount": {
"amount": 1,
"currency": "<string>"
},
"clientId": "<string>",
"note": "<string>",
"reason": "Service recovery — late supplier",
"idempotencyKey": "9f8c0f7a-1f3f-4c8e-9a2b-6c7d8e9f0a1b"
}
'import requests
url = "https://apiv2.gomarketbox.com/v1/projects/{projectId}/orders/{orderId}/transactions"
payload = {
"amount": {
"amount": 1,
"currency": "<string>"
},
"clientId": "<string>",
"note": "<string>",
"reason": "Service recovery — late supplier",
"idempotencyKey": "9f8c0f7a-1f3f-4c8e-9a2b-6c7d8e9f0a1b"
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/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'},
body: JSON.stringify({
amount: {amount: 1, currency: '<string>'},
clientId: '<string>',
note: '<string>',
reason: 'Service recovery — late supplier',
idempotencyKey: '9f8c0f7a-1f3f-4c8e-9a2b-6c7d8e9f0a1b'
})
};
fetch('https://apiv2.gomarketbox.com/v1/projects/{projectId}/orders/{orderId}/transactions', 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://apiv2.gomarketbox.com/v1/projects/{projectId}/orders/{orderId}/transactions",
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([
'amount' => [
'amount' => 1,
'currency' => '<string>'
],
'clientId' => '<string>',
'note' => '<string>',
'reason' => 'Service recovery — late supplier',
'idempotencyKey' => '9f8c0f7a-1f3f-4c8e-9a2b-6c7d8e9f0a1b'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/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://apiv2.gomarketbox.com/v1/projects/{projectId}/orders/{orderId}/transactions"
payload := strings.NewReader("{\n \"amount\": {\n \"amount\": 1,\n \"currency\": \"<string>\"\n },\n \"clientId\": \"<string>\",\n \"note\": \"<string>\",\n \"reason\": \"Service recovery — late supplier\",\n \"idempotencyKey\": \"9f8c0f7a-1f3f-4c8e-9a2b-6c7d8e9f0a1b\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
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://apiv2.gomarketbox.com/v1/projects/{projectId}/orders/{orderId}/transactions")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": {\n \"amount\": 1,\n \"currency\": \"<string>\"\n },\n \"clientId\": \"<string>\",\n \"note\": \"<string>\",\n \"reason\": \"Service recovery — late supplier\",\n \"idempotencyKey\": \"9f8c0f7a-1f3f-4c8e-9a2b-6c7d8e9f0a1b\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://apiv2.gomarketbox.com/v1/projects/{projectId}/orders/{orderId}/transactions")
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'
request.body = "{\n \"amount\": {\n \"amount\": 1,\n \"currency\": \"<string>\"\n },\n \"clientId\": \"<string>\",\n \"note\": \"<string>\",\n \"reason\": \"Service recovery — late supplier\",\n \"idempotencyKey\": \"9f8c0f7a-1f3f-4c8e-9a2b-6c7d8e9f0a1b\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"projectId": "<string>",
"tenantId": "<string>",
"transactionId": "<string>",
"kind": "PAYMENT",
"source": "STRIPE",
"status": "PENDING",
"amount": {
"amount": 1,
"currency": "<string>"
},
"orderId": "<string>",
"deleted": true,
"version": 1,
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"createdBy": "<string>",
"updatedBy": "<string>",
"platformFee": {
"amount": 1,
"currency": "<string>"
},
"relatedTransactionId": "<string>",
"orderItemId": "<string>",
"allocationId": "<string>",
"bookingId": "<string>",
"clientId": "<string>",
"stripePaymentIntentId": "<string>",
"stripeChargeId": "<string>",
"stripeRefundId": "<string>",
"stripeAccountId": "<string>",
"connectChargeType": "DIRECT",
"failureCode": "<string>",
"failureMessage": "<string>",
"note": "<string>",
"disputeId": "<string>",
"disputeStatus": "needs_response",
"channel": "BACKOFFICE",
"reason": "<string>"
},
"replayed": true
}{
"data": {
"projectId": "<string>",
"tenantId": "<string>",
"transactionId": "<string>",
"kind": "PAYMENT",
"source": "STRIPE",
"status": "PENDING",
"amount": {
"amount": 1,
"currency": "<string>"
},
"orderId": "<string>",
"deleted": true,
"version": 1,
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"createdBy": "<string>",
"updatedBy": "<string>",
"platformFee": {
"amount": 1,
"currency": "<string>"
},
"relatedTransactionId": "<string>",
"orderItemId": "<string>",
"allocationId": "<string>",
"bookingId": "<string>",
"clientId": "<string>",
"stripePaymentIntentId": "<string>",
"stripeChargeId": "<string>",
"stripeRefundId": "<string>",
"stripeAccountId": "<string>",
"connectChargeType": "DIRECT",
"failureCode": "<string>",
"failureMessage": "<string>",
"note": "<string>",
"disputeId": "<string>",
"disputeStatus": "needs_response",
"channel": "BACKOFFICE",
"reason": "<string>"
},
"replayed": false
}{
"code": "NOT_FOUND",
"message": "Booking not found",
"statusCode": 404,
"requestId": "a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"
}{
"code": "NOT_FOUND",
"message": "Booking not found",
"statusCode": 404,
"requestId": "a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"
}{
"code": "NOT_FOUND",
"message": "Booking not found",
"statusCode": 404,
"requestId": "a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"
}{
"code": "NOT_FOUND",
"message": "Booking not found",
"statusCode": 404,
"requestId": "a3f1c2de-9b64-4a2f-8f0e-5c9d1b7a2e10"
}Authorizations
API key minted in the MarketBox dashboard. Scope is restricted to the projects you select at creation time. Every route needs the key's standard API access (*) except POST /v1/projects/{projectId}/events, which needs events:write; a key without * is refused with 403 CAPABILITY_NOT_GRANTED.
Path Parameters
Body
Manual transaction data