Transfer Webhook

Receive signed transfer proofs from settlement providers

POST /transfer/webhook

Instant Transfer Notification (ITN)

cURL

curl --request POST \
  --url https://api.merchant.example/opencharge/transfer/webhook \
  --header 'Content-Type: application/json' \
  --header 'X-OC-ID: <x-oc-id>' \
  --header 'X-OC-Nonce: <x-oc-nonce>' \
  --header 'X-OC-Signature: <x-oc-signature>' \
  --header 'X-OC-Timestamp: <x-oc-timestamp>' \
  --data '
{
  "proof": {
    "txid": "gateway_tx_456",
    "issuer": 100,
    "from": {
      "ocid": 200,
      "reference": "wallet_tx_123"
    },
    "to": {
      "ocid": 500,
      "reference": "ord_abc123"
    },
    "amount": "15.00",
    "currency": "USD",
    "timestamp": 1706500500,
    "memo": "Payment for ord_abc123"
  },
  "signature": "a1b2c3d4e5f6..."
}
'

200

{
  "status": "accepted",
  "txid": "gateway_tx_456"
}

Settlement providers POST signed proofs to this endpoint when transfers complete. Match the proof to pending payments and forward your own signed proof to merchants.

When You Receive Webhooks

You receive webhooks when:

1. A settlement provider you accept completes a transfer to your OCID
2. The transfer was for a pending payment at your gateway
3. You need to credit a merchant and notify them

Implementation

app.post('/transfer/webhook', verifyAuth, async (req, res) => {
  const { proof, signature } = req.body;
  const senderOcid = parseInt(req.headers['x-oc-id']);

  // 1. Verify sender is an accepted settlement provider
  if (!ACCEPTED_SETTLEMENT_PROVIDERS.includes(senderOcid)) {
    return res.status(400).json({
      error: { code: 'ISSUER_NOT_ACCEPTED', message: 'Unknown settlement provider' }
    });
  }

  // 2. Verify sender is the proof issuer
  if (proof.issuer !== senderOcid) {
    return res.status(400).json({
      error: { code: 'INVALID_PROOF', message: 'Issuer mismatch' }
    });
  }

  // 3. Verify proof signature
  const publicKey = await getPublicKey(senderOcid);
  const canonical = JSON.stringify(proof, Object.keys(proof).sort());
  if (!secp256k1_verify(publicKey, signature, canonical)) {
    return res.status(400).json({
      error: { code: 'PROOF_SIGNATURE_INVALID', message: 'Invalid signature' }
    });
  }

  // 4. Verify we are the recipient
  if (proof.to.ocid !== YOUR_OCID) {
    return res.status(400).json({
      error: { code: 'INVALID_PROOF', message: 'Wrong recipient' }
    });
  }

  // 5. Find the pending payment
  const payment = await db.getPaymentByReference(proof.to.reference);
  if (!payment) {
    // Log for investigation but accept
    console.log(`Unknown payment reference: ${proof.to.reference}`);
    return res.json({ status: 'accepted', txid: proof.txid });
  }

  // 6. Verify amount matches
  if (proof.amount !== payment.amount || proof.currency !== payment.currency) {
    return res.status(400).json({
      error: { code: 'AMOUNT_MISMATCH', message: 'Amount does not match' }
    });
  }

  // 7. Mark payment as complete
  await db.completePayment(payment.id, proof.txid, proof.timestamp);

  // 8. Credit merchant account
  await db.creditMerchant(payment.merchantOcid, payment.amount, payment.currency);

  // 9. Create and send proof to merchant
  const merchantProof = {
    txid: payment.txid,
    issuer: YOUR_OCID,
    from: proof.from,
    to: { ocid: payment.merchantOcid, reference: payment.orderId },
    amount: payment.amount,
    currency: payment.currency,
    timestamp: Math.floor(Date.now() / 1000),
    memo: `Payment for ${payment.orderId}`
  };

  await notifyMerchant(payment.merchantOcid, merchantProof);

  res.json({ status: 'accepted', txid: proof.txid });
});

Forwarding to Merchants

After receiving a valid proof, create your own proof for the merchant:

async function notifyMerchant(merchantOcid, proof) {
  const merchant = await db.getMerchant(merchantOcid);
  const endpoint = merchant.webhookUrl || await resolveEndpoint(merchantOcid);

  const signature = signProof(proof);

  await fetch(`${endpoint}/transfer/webhook`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      ...createAuthHeaders(YOUR_OCID, YOUR_PRIVATE_KEY)
    },
    body: JSON.stringify({ proof, signature })
  });
}

Always verify the proof signature before crediting accounts or forwarding to merchants.

Headers

X-OC-ID · string · required

Sender's OCID (Opencharge ID)

X-OC-Timestamp · string · required

Unix timestamp in seconds

X-OC-Nonce · string · required

Unique request identifier for replay protection

X-OC-Signature · string · required

secp256k1 ECDSA signature of the canonical request

Body

application/json

proof · object · required

Show child attributes

signature · string · required

secp256k1 signature of the proof from the issuer

Response

200

application/json

Notification received and processed

status · enum<string> · required

Whether you accepted the notification

Available options: accepted, rejected

txid · string · required

The transaction ID from the proof

message · string

Optional message explaining rejection reason