Payment references are numbers which can be attached to bitcoin or asset transactions.

This provides a simple mechanism for merchants to identify the source of a payment containing bitcoin and/or CoinSpark assets, without creating a new pair of private and public bitcoin keys for every potential transaction. As a result, payments can safely be accepted from many different customers into an offline or cold wallet with a single bitcoin address.

A CoinSpark payment reference is an unsigned integer up to 52 bits in length, i.e. between 0 and 4503599627370500. When requesting payment from a customer, a merchant should generate a unique value in this range, and then encode that value together with their regular bitcoin address inside the CoinSpark address provided to the customer. When the customer enters this address into their CoinSpark-compatible wallet, the wallet will automatically extract the payment reference and add it to the transaction being sent out to that address.

You can easily work with payment references using the appropriate CoinSpark library for your programming language.

Creating and encoding payment references

C/C++

CoinSparkPaymentRef paymentRef;
char metadata[40]; // assume 40 byte limit for OP_RETURNs
size_t metadataLen;

paymentRef=CoinSparkPaymentRefRandom(); // creates a random reference which is valid
metadataLen=CoinSparkPaymentRefEncode(paymentRef, metadata, sizeof(metadata));

if (metadataLen)
    ; // use CoinSparkMetadataToScript() to embed metadata (length metadataLen) in an output script
else
    ; // handle error

Java

CoinSparkPaymentRef paymentRef=new CoinSparkPaymentRef();
paymentRef.randomize(); // randomizes the payment reference
byte[] metadata = paymentRef.encode(40); // assume 40 byte limit for OP_RETURNs

if (metadata!=null)
    ; // use CoinSparkBase.metadataToScript() to embed metadata in an output script
else
    ; // handle error

Javascript

var paymentRef=new CoinSparkPaymentRef();
paymentRef.randomize(); // randomizes the payment reference
var metadata=paymentRef.encode(40); // 40 byte limit for OP_RETURN
 
if (metadata)
    ; // use CoinSparkMetadataToScript() to embed metadata in an output script
else
    ; // handle error

PHP

$paymentRef=new CoinSparkPaymentRef();
$paymentRef->randomize(); // randomizes the payment reference
$metadata=$paymentRef->encode(40); // 40 byte limit for OP_RETURN
 
if (isset($metadata))
    ; // use CoinSparkMetadataToScript() to embed $metadata in an output script
else
    ; // handle error

Python

paymentRef=CoinSparkPaymentRef()
paymentRef.randomize() # randomizes the payment reference
metadata=paymentRef.encode(40) # assume 40 byte limit for OP_RETURNs

if not metadata is None:
     # use CoinSparkMetadataToScript() to embed metadata in an output script
else:
     # handle error

Ruby

paymentRef=CoinSparkPaymentRef.new
paymentRef.randomize # randomizes the payment reference
metadata=paymentRef.encode(40) # assume 40 byte limit for OP_RETURNs

if metadata!=nil
     # use CoinSparkMetadataToScript() to embed metadata in an output script
else
     # handle error
end

Extracting and decoding payment references

Please see the general metadata sample code.