Void pending rewards

curl --request POST \
  --url https://api.scrip.dev/v1/participants/{participant_id}/balances/void-pending \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "asset_id": "a3bb189e-8bf9-4c8b-9be0-6b5d2f4e7a02",
  "description": "Order #123",
  "program_id": "8f14e45f-ceea-4e70-9df8-2a7d1b3c9f01"
}
'

import requests

url = "https://api.scrip.dev/v1/participants/{participant_id}/balances/void-pending"

payload = {
    "asset_id": "a3bb189e-8bf9-4c8b-9be0-6b5d2f4e7a02",
    "description": "Order #123",
    "program_id": "8f14e45f-ceea-4e70-9df8-2a7d1b3c9f01"
}
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({
    asset_id: 'a3bb189e-8bf9-4c8b-9be0-6b5d2f4e7a02',
    description: 'Order #123',
    program_id: '8f14e45f-ceea-4e70-9df8-2a7d1b3c9f01'
  })
};

fetch('https://api.scrip.dev/v1/participants/{participant_id}/balances/void-pending', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

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

func main() {

	url := "https://api.scrip.dev/v1/participants/{participant_id}/balances/void-pending"

	payload := strings.NewReader("{\n  \"asset_id\": \"a3bb189e-8bf9-4c8b-9be0-6b5d2f4e7a02\",\n  \"description\": \"Order #123\",\n  \"program_id\": \"8f14e45f-ceea-4e70-9df8-2a7d1b3c9f01\"\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))

}

{
  "amount_processed": "100.00",
  "asset_id": "a3bb189e-8bf9-4c8b-9be0-6b5d2f4e7a02",
  "balance": {
    "available": "1400.00",
    "deferred": "0.00",
    "held": "200.00"
  },
  "journal_entry_id": "657a0312-1aaa-4ba7-842b-edfbb39edf14",
  "message": "Processed 100.00",
  "operation": "VOID_PENDING",
  "program_id": "8f14e45f-ceea-4e70-9df8-2a7d1b3c9f01",
  "reference_id": "auth_12345"
}

POST

participants

{participant_id}

balances

void-pending

Void pending rewards

curl --request POST \
  --url https://api.scrip.dev/v1/participants/{participant_id}/balances/void-pending \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "asset_id": "a3bb189e-8bf9-4c8b-9be0-6b5d2f4e7a02",
  "description": "Order #123",
  "program_id": "8f14e45f-ceea-4e70-9df8-2a7d1b3c9f01"
}
'

import requests

url = "https://api.scrip.dev/v1/participants/{participant_id}/balances/void-pending"

payload = {
    "asset_id": "a3bb189e-8bf9-4c8b-9be0-6b5d2f4e7a02",
    "description": "Order #123",
    "program_id": "8f14e45f-ceea-4e70-9df8-2a7d1b3c9f01"
}
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({
    asset_id: 'a3bb189e-8bf9-4c8b-9be0-6b5d2f4e7a02',
    description: 'Order #123',
    program_id: '8f14e45f-ceea-4e70-9df8-2a7d1b3c9f01'
  })
};

fetch('https://api.scrip.dev/v1/participants/{participant_id}/balances/void-pending', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

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

func main() {

	url := "https://api.scrip.dev/v1/participants/{participant_id}/balances/void-pending"

	payload := strings.NewReader("{\n  \"asset_id\": \"a3bb189e-8bf9-4c8b-9be0-6b5d2f4e7a02\",\n  \"description\": \"Order #123\",\n  \"program_id\": \"8f14e45f-ceea-4e70-9df8-2a7d1b3c9f01\"\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))

}

{
  "amount_processed": "100.00",
  "asset_id": "a3bb189e-8bf9-4c8b-9be0-6b5d2f4e7a02",
  "balance": {
    "available": "1400.00",
    "deferred": "0.00",
    "held": "200.00"
  },
  "journal_entry_id": "657a0312-1aaa-4ba7-842b-edfbb39edf14",
  "message": "Processed 100.00",
  "operation": "VOID_PENDING",
  "program_id": "8f14e45f-ceea-4e70-9df8-2a7d1b3c9f01",
  "reference_id": "auth_12345"
}

Cancel pending rewards credited into HELD for a reference_id. The value returns to the program wallet for PREFUNDED assets or system issuance for UNLIMITED assets. Use this when a merchant reverses an authorization before settlement. Only processes lots created directly in HELD via CREDIT. Lots moved to HELD via a HOLD operation are excluded because returning those to the source would confiscate participant-owned funds. Use release for participant-held funds. Requires a LOT-mode asset. Without amount, all pending rewards for the reference_id are voided. lot_ids, earned_from, and earned_to are not supported. With amount, the newest lots are voided first. amount is the rewards to void, in the asset’s units, and must be positive. A blank amount is rejected with 400. For a partial reversal, use the reward difference, rather than the reversed purchase amount. A lot that is only partly voided stays in HELD with its reference_id and dates. An amount above the pending balance cancels only what remains. amount_processed shows the value voided. Void pending is allowed on CLOSED participants and archived assets.

For the full auth/settle pattern and usage examples, see the Balance operations guide.

Authorizations

Authorization

string

header

default:sk_...

required

Send your API key as Authorization: Bearer <key>.

Headers

Idempotency-Key

string

A key you choose to make this request safe to retry: 1 to 255 printable ASCII characters. Send the same key with the same request to get the first response again, marked Idempotent-Replayed: true. Routes that return a secret once, and claim links, do not replay a response. Event ingest uses the key as the event's identity.

Maximum string length: 255

Path Parameters

participant_id

string

required

The participant's id, or ext: followed by the participant's external_id.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}|ext:.{1,255})$

Body

application/json

Void pending operation details

Holds, releases, forfeits or voids value, depending on the endpoint. Choose which value moves with an amount, lot ids, lot dates or a reference_id.

asset_id

string<uuid>

required

Asset to operate on

Example:

"a3bb189e-8bf9-4c8b-9be0-6b5d2f4e7a02"

description

string

required

Reason for this operation

Required string length: 1 - 500

Example:

"Order #123"

program_id

string<uuid>

required

Program this operation belongs to

Example:

"8f14e45f-ceea-4e70-9df8-2a7d1b3c9f01"

amount

string

Amount to process. Omit to process the full balance (SIMPLE) or all matching lots (LOT)

Example:

"100.00"

bucket

enum<string>

Which bucket to forfeit from. Required for forfeit; ignored for hold/release

Available options:

AVAILABLE,

HELD

Example:

"AVAILABLE"

earned_from

string<date-time>

Only process lots earned on or after this time (RFC 3339). LOT mode only.

Example:

"2027-01-01T00:00:00Z"

earned_to

string<date-time>

Only process lots earned on or before this time (RFC 3339). LOT mode only. Must be >= earned_from when both are provided.

Example:

"2027-12-31T23:59:59Z"

idempotency_key

string

Your key for this operation. You can send it in the Idempotency-Key header instead; when both are sent they must match. The same key with the same fields returns the first result again, and the same key with different fields returns 409 idempotency_conflict.

Required string length: 1 - 255

Example:

"order-1001-completed"

lot_ids

string[]

Restrict to specific lots. LOT mode only

Example:

["4a6c8e02-b1d3-4f57-9c80-e2a4b6d8f012"]

reference_id

string

Correlation ID linking holds to releases. LOT mode only. Hold stamps lots; release filters by reference.

Example:

"auth_12345"

Response

Void pending processed

The result of a hold, release, forfeit or void: the amount processed, the lots touched and the balance after.

amount_processed

string

Total amount processed

Example:

"100.00"

asset_id

string<uuid>

The asset the operation applied to.

Example:

"a3bb189e-8bf9-4c8b-9be0-6b5d2f4e7a02"

balance

object

Balance after the operation

Show child attributes

journal_entry_id

string<uuid>

Ledger journal entry created by this operation

Example:

"657a0312-1aaa-4ba7-842b-edfbb39edf14"

lots_processed

object[]

Individual lots affected. Only present for LOT mode assets

Show child attributes

message

string

Confirmation message

Example:

"Processed 100.00"

operation

enum<string>

The balance operation that was performed, matching the endpoint you called.

Available options:

HOLD,

RELEASE,

FORFEIT,

VOID_PENDING

program_id

string<uuid>

The program the operation belongs to.

Example:

"8f14e45f-ceea-4e70-9df8-2a7d1b3c9f01"

reference_id

string

Correlation ID linking this hold/release (if provided)

Example:

"auth_12345"

Scrip API

Endpoints

Void pending rewards

Authorizations

Headers

Path Parameters

Body

Response