Marketplace

Reverse a previously-posted transaction

Creates a compensating Transaction row whose delta is the negation of the original’s, linked via reverses_transaction_id. Fires TRANSACTION_CREATED so partner webhooks notice the reversal end-to-end.

Idempotent: reversing the same transaction twice returns the existing reversal at HTTP 200 (enforced by the unique constraint on Transaction.reversesTransactionId + a P2002 fallback).

Cannot reverse: • An already-reversed transaction’s reversal (post a new accrue instead). • A transaction in the opposite mode — live keys can’t reverse test rows and vice versa.

Pass either transaction_id (Perkstar’s id) OR external_transaction_id (your POS-side id). Both forms resolve to the same underlying row.

POST

https://dashboard.perkstar.co.uk/api/v1

marketplace

reverse

Reverse a previously-posted transaction

curl --request POST \
  --url https://dashboard.perkstar.co.uk/api/v1/marketplace/reverse \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "transaction_id": "<string>",
  "external_transaction_id": "<string>",
  "reason": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    transaction_id: '<string>',
    external_transaction_id: '<string>',
    reason: '<string>'
  })
};

fetch('https://dashboard.perkstar.co.uk/api/v1/marketplace/reverse', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://dashboard.perkstar.co.uk/api/v1/marketplace/reverse"

payload = {
    "transaction_id": "<string>",
    "external_transaction_id": "<string>",
    "reason": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://dashboard.perkstar.co.uk/api/v1/marketplace/reverse",
  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([
    'transaction_id' => '<string>',
    'external_transaction_id' => '<string>',
    'reason' => '<string>'
  ]),
  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;
}

{
  "transaction": {
    "id": "<string>",
    "enrollment_id": "<string>",
    "type": "STAMP",
    "source": "SCANNER",
    "delta": 123,
    "amount_pence": 123,
    "note": "<string>",
    "external_id": "<string>",
    "external_transaction_id": "<string>",
    "reverses_transaction_id": "<string>",
    "reason_text": "<string>",
    "test_mode": true,
    "created_at": "2023-11-07T05:31:56Z"
  },
  "reverses_transaction_id": "<string>",
  "enrollment": {
    "id": "<string>",
    "balance": 123,
    "redemptions_count": 123
  },
  "idempotent_replay": true
}

{
  "transaction": {
    "id": "<string>",
    "enrollment_id": "<string>",
    "type": "STAMP",
    "source": "SCANNER",
    "delta": 123,
    "amount_pence": 123,
    "note": "<string>",
    "external_id": "<string>",
    "external_transaction_id": "<string>",
    "reverses_transaction_id": "<string>",
    "reason_text": "<string>",
    "test_mode": true,
    "created_at": "2023-11-07T05:31:56Z"
  },
  "reverses_transaction_id": "<string>",
  "enrollment": {
    "id": "<string>",
    "balance": 123,
    "redemptions_count": 123
  },
  "idempotent_replay": true
}

{
  "error": {
    "type": "authentication_error",
    "message": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "authentication_error",
    "message": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "authentication_error",
    "message": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "authentication_error",
    "message": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "authentication_error",
    "message": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "authentication_error",
    "message": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key

string

Replay-safe request key. Repeated requests with the same value within 24h return the original response unchanged.

Maximum string length: 255

Body

application/json

Exactly one of transaction_id or external_transaction_id must be supplied.

transaction_id

string

external_transaction_id

string

reason

string

Maximum string length: 280

Response

Existing reversal returned (idempotent replay)

transaction

object

Show child attributes

reverses_transaction_id

string

enrollment

object

Show child attributes

idempotent_replay

boolean

Set to true when the response is a replay of an existing reversal. Absent on fresh creates.

Reverse a previously-posted transaction

curl --request POST \
  --url https://dashboard.perkstar.co.uk/api/v1/marketplace/reverse \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "transaction_id": "<string>",
  "external_transaction_id": "<string>",
  "reason": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    transaction_id: '<string>',
    external_transaction_id: '<string>',
    reason: '<string>'
  })
};

fetch('https://dashboard.perkstar.co.uk/api/v1/marketplace/reverse', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://dashboard.perkstar.co.uk/api/v1/marketplace/reverse"

payload = {
    "transaction_id": "<string>",
    "external_transaction_id": "<string>",
    "reason": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://dashboard.perkstar.co.uk/api/v1/marketplace/reverse",
  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([
    'transaction_id' => '<string>',
    'external_transaction_id' => '<string>',
    'reason' => '<string>'
  ]),
  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;
}

{
  "transaction": {
    "id": "<string>",
    "enrollment_id": "<string>",
    "type": "STAMP",
    "source": "SCANNER",
    "delta": 123,
    "amount_pence": 123,
    "note": "<string>",
    "external_id": "<string>",
    "external_transaction_id": "<string>",
    "reverses_transaction_id": "<string>",
    "reason_text": "<string>",
    "test_mode": true,
    "created_at": "2023-11-07T05:31:56Z"
  },
  "reverses_transaction_id": "<string>",
  "enrollment": {
    "id": "<string>",
    "balance": 123,
    "redemptions_count": 123
  },
  "idempotent_replay": true
}

{
  "transaction": {
    "id": "<string>",
    "enrollment_id": "<string>",
    "type": "STAMP",
    "source": "SCANNER",
    "delta": 123,
    "amount_pence": 123,
    "note": "<string>",
    "external_id": "<string>",
    "external_transaction_id": "<string>",
    "reverses_transaction_id": "<string>",
    "reason_text": "<string>",
    "test_mode": true,
    "created_at": "2023-11-07T05:31:56Z"
  },
  "reverses_transaction_id": "<string>",
  "enrollment": {
    "id": "<string>",
    "balance": 123,
    "redemptions_count": 123
  },
  "idempotent_replay": true
}

{
  "error": {
    "type": "authentication_error",
    "message": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "authentication_error",
    "message": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "authentication_error",
    "message": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "authentication_error",
    "message": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "authentication_error",
    "message": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "type": "authentication_error",
    "message": "<string>",
    "code": "<string>",
    "param": "<string>"
  }
}

Customers

Enrollments

Transactions

Cards

Webhooks

Locations

Pushes

Marketplace

Outbound webhooks

Reverse a previously-posted transaction

Authorizations

Headers

Body

Response