Handling callbacks

Because of the need to maintain backward compatibility (so that existing clients don't stop working) we cannot update the content of the callback payload too often, we recommend using the callback as a signal that the payment has been processed.

At the time the callback is received, we recommend making a Payment Status request to get actual information about the payment.

As soon as the user transfers Crypto, you will receive a callback to the URL specified in the integration settings.

Callback contains information about payment such as paymentID, original amount, actual amount, timestamp and signature.

You MUST to validate signature to make sure that callback is really sent by CoinPipe server.

Callback Details

HTTP Method	POST
Content-Type	application/json
Expected response codes	200 - 299 (or redirect but final code must be 200-299)

If callback fails status of payment will set to ERR_CALLBACK. After it our backend will retry sending callback every 10 minutes until receiving success code.

We will try to send a callback within 3 days, after which the attempts will stop and the status will remain ERR_CALLBACK.

Callback Payload

Parameter	Type	Description
payment_id	string	PaymentID in our system.
amount	string	Original amount of payment in NEAR.
amount_usd	string	Original amount of payment in USD. Converted on our side.
received_amount	string	Actual paid amount in NEAR.
received_amount_usd	string	Actual paid amount in USD. Converted on our side.
current_datetime	timestamp (RFC3339)	Timestamp when callback was sent (not payment processed).
signature	string	Signature of callback to prove that it was sent by CoinPipe server.

Validating Signature

You MUST validate the signature on your backend in order to prove that callback was sent by StreamPayments server

To calculate the signature you have to build a string that contains a callback payload in the following format:

Amount={amount};AmountUsd={amount_usd};CurrentDateTime={current_datetime};PaymentID={payment_id};ReceivedAmount={received_amount};ReceivedAmountUsd={received_amount_usd};SecretKey={api_integration_secret_key}

Where {api_integration_secret_key} is the secret key you got when creating API Integration. If you lost it you can re-generate the secret key on the Shop details page.

The resulting string should be hashed using sha256 algorithm.

Code examples

Python (Flask)

@app.route("/payment/callback", methods=["POST"])
def callback():
    json = request.get_json()
    amount = json.get('amount')
    amount_usd = json.get('amount_usd')
    current_datetime = json.get('current_datetime')
    payment_id = json.get('payment_id')
    received_amount = json.get('received_amount')
    received_amount_usd = json.get('received_amount_usd')
    signature = json.get('signature')

    raw_signature = f"Amount={amount};AmountUsd={amount_usd};CurrentDateTime={current_datetime};PaymentID={payment_id};ReceivedAmount={received_amount};ReceivedAmountUsd={received_amount_usd};SecretKey={API_INTEGRATION_SECRET_KEY}"
    computed_signature = sha256(raw_signature.encode()).hexdigest()

PHP

<?php

$rawJson = file_get_contents('php://input');
$payload = json_decode($rawJson, true);

$rawSignature = sprintf(
    'Amount=%s;AmountUsd=%s;CurrentDateTime=%s;PaymentID=%s;ReceivedAmount=%s;ReceivedAmountUsd=%s;SecretKey=%s',
    $payload['amount'],
    $payload['amount_usd'],
    $payload['current_datetime'],
    $payload['payment_id'],
    $payload['received_amount'],
    $payload['received_amount_usd'],
    API_INTEGRATION_SECRET_KEY,
);

$computedSignature = hash('sha256', $rawSignature);

JavaScript (NodeJs)

const crypto = require('crypto');

const server = http.createServer(async (req, res) => {
  const buffers = [];

  for await (const chunk of req) {
    buffers.push(chunk);
  }

  const data = Buffer.concat(buffers).toString();
  const payload = JSON.parse(data);
  const rawSignature = `Amount=${payload['amount']};AmountUsd=${payload['amount_usd']};CurrentDateTime=${payload['current_datetime']};PaymentID=${payload['payment_id']};ReceivedAmount=${payload['received_amount']};ReceivedAmountUsd=${payload['received_amount_usd']};SecretKey=${process.env.API_INTEGRATION_SECRET_KEY}`;
  const computedSignature = crypto.createHash('sha256').update(rawSignature).digest('hex');

  res.end();
})