Your First Crypto Payment Integration: From API Key to Transaction

Adding crypto payments to a product can look intimidating at first. You have blockchains, multiple coins, networks, confirmations, webhooks, invoice expiration, and payment status changes to think about. But the first step toward accepting crypto payments is not as complicated as it seems when you treat the integration as a clear backend flow instead of a mysterious blockchain problem.

The mistake many developers make is trying to think about everything at once.

They start with questions like:

• Which blockchain should I support?
• How do I detect a transaction?
• What if the user pays late?
• What if the webhook is duplicated?
• What if the customer sends the wrong amount?
• What if the order is fulfilled twice?

Those questions matter, but they come later.

Your first crypto payment integration should start with one simple goal:

Create a payment request, send the customer to checkout, receive the payment update, and update your system safely.

This article walks through that first complete flow using a practical developer mindset.

We will not only create an invoice and redirect the user. We will also look at the parts that usually break later: API key handling, local payment records, webhook validation, idempotency, payment status mapping, and reconciliation.

---

The Integration Flow

Before writing code, it helps to see the whole payment lifecycle.

A basic crypto payment integration looks like this:

Customer clicks "Pay with Crypto"
        |
        v
Your backend creates an invoice through the payment API
        |
        v
Payment provider returns track_id + payment_url
        |
        v
Your backend stores the payment record
        |
        v
Customer is redirected to the hosted payment page
        |
        v
Customer selects coin/network and sends funds
        |
        v
Payment provider detects the transaction
        |
        v
Payment provider sends webhook to your backend
        |
        v
Your backend validates the webhook
        |
        v
Your backend updates payment/order state
        |
        v
Order is fulfilled only when the final business rule is met

This is the core idea.

You are not trying to manage the blockchain directly.

You are connecting your application state to a payment infrastructure layer.

For this article, I will use OxaPay examples because it provides invoice generation, payment URLs, webhooks, payment status tracking, and payment information endpoints through a developer-facing API.

---

What You Are Actually Building

A crypto payment integration is not just a checkout button.

At minimum, you are building four small backend components:

1. Invoice creation
2. Payment record storage
3. Webhook receiver
4. Payment state updater

In a very simple project, these can live in one backend service.

In a production project, they may be split across your order service, payment service, webhook worker, and admin dashboard.

The important thing is that your application should not rely only on the user returning from checkout.

A customer can close the tab.

A browser redirect can fail.

A wallet transaction can take time.

A webhook can arrive after the customer has already left the page.

That is why the backend must own the payment lifecycle.

---

Step 1: Create and Protect Your API Key

Like most modern APIs, a crypto payment provider gives you an API key.

In OxaPay, you generate a Merchant API Key from the merchant service section of your account. Your backend uses this key to authenticate requests when creating invoices or fetching payment details.

The first rule is simple:

Never expose your Merchant API Key in frontend code.

Do not put it in JavaScript running in the browser.

Do not hardcode it into a public repository.

Do not send it to the client.

Store it as an environment variable.

Example:

OXAPAY_MERCHANT_API_KEY="your_merchant_api_key_here"
OXAPAY_WEBHOOK_SECRET="your_merchant_api_key_here"
APP_BASE_URL="https://example.com"

In this example, the webhook secret is also the Merchant API Key because OxaPay uses the Merchant API Key as the shared secret for validating payment callback HMAC signatures.

In a real production setup, keep secrets in a proper secret manager or secure environment variable system.

At minimum:

• keep API keys server-side only
• use HTTPS everywhere
• do not commit secrets to GitHub
• rotate keys if exposed
• separate sandbox and production environments
• restrict who can access merchant credentials

This sounds basic, but many payment integration problems start with poor key handling.

---

Step 2: Create the Invoice From Your Backend

In crypto payment APIs, an invoice is a payment request.

It usually contains:

• amount
• pricing currency
• expiration time
• order reference
• callback URL
• return URL
• optional description or customer metadata

With OxaPay, you can generate an invoice using the Generate Invoice endpoint.

Here is a simple curl example:

curl -X POST https://api.oxapay.com/v1/payment/invoice \
  -H "merchant_api_key: $OXAPAY_MERCHANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 49.99,
    "currency": "USD",
    "lifetime": 60,
    "callback_url": "https://example.com/webhooks/oxapay",
    "return_url": "https://example.com/orders/ORD-1001/thank-you",
    "order_id": "ORD-1001",
    "description": "Order #ORD-1001",
    "sandbox": true
  }'

A successful response returns payment data such as:

{
  "data": {
    "track_id": "184747701",
    "payment_url": "https://pay.oxapay.com/12373985/184747701",
    "expired_at": 1734546589,
    "date": 1734510589
  },
  "message": "Operation completed successfully!",
  "error": {},
  "status": 200,
  "version": "1.0.0"
}

Two fields matter immediately:

track_id     → provider-side payment session reference
payment_url  → URL where the customer completes the payment

The track_id is especially important.

Do not treat it as a temporary value.

Store it in your database. You will need it later for webhook matching, support investigations, payment status checks, and reconciliation.

---

Step 3: Create a Local Payment Record Before Redirecting the User

A common mistake is redirecting the user to checkout before saving the payment record locally.

That creates risk.

If the user pays and the webhook arrives before your database knows about the payment, your system may not be able to match the payment to the order.

A safer flow is:

Create order
→ Create invoice through payment API
→ Store local payment record
→ Redirect user to payment_url

Your local payment record can be simple at first.

Example database structure:

CREATE TABLE payments (
  id BIGSERIAL PRIMARY KEY,
  order_id TEXT NOT NULL,
  provider TEXT NOT NULL,
  provider_track_id TEXT NOT NULL UNIQUE,
  amount NUMERIC(18, 8) NOT NULL,
  currency TEXT NOT NULL,
  status TEXT NOT NULL,
  payment_url TEXT NOT NULL,
  expires_at TIMESTAMP NULL,
  created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  updated_at TIMESTAMP NOT NULL DEFAULT NOW()
);

You can start with a status like:

invoice_created

or:

pending

The naming is up to you, but the principle is important:

Your system should have its own payment state, not only the provider status.

The provider tells you what happened externally.

Your application decides what that means internally.

---

Step 4: Create the Invoice With Node.js

Here is a simple backend example using Node.js.

This example assumes you already have an order in your system.

async function createCryptoPaymentForOrder(order) {
  const response = await fetch("https://api.oxapay.com/v1/payment/invoice", {
    method: "POST",
    headers: {
      "merchant_api_key": process.env.OXAPAY_MERCHANT_API_KEY,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      amount: order.total,
      currency: "USD",
      lifetime: 60,
      callback_url: `${process.env.APP_BASE_URL}/webhooks/oxapay`,
      return_url: `${process.env.APP_BASE_URL}/orders/${order.id}/thank-you`,
      order_id: order.id,
      description: `Order #${order.id}`,
      sandbox: true
    })
  });

  const result = await response.json();

  if (!response.ok || result.status !== 200) {
    throw new Error(`Invoice creation failed: ${JSON.stringify(result.error)}`);
  }

  const payment = result.data;

  await db.payments.insert({
    order_id: order.id,
    provider: "oxapay",
    provider_track_id: payment.track_id,
    amount: order.total,
    currency: "USD",
    status: "invoice_created",
    payment_url: payment.payment_url,
    expires_at: new Date(payment.expired_at * 1000)
  });

  return {
    trackId: payment.track_id,
    paymentUrl: payment.payment_url
  };
}

This function does three things:

1. Sends invoice creation request to OxaPay
2. Stores track_id and payment_url locally
3. Returns payment_url so the frontend can redirect the user

The frontend should not call OxaPay directly.

The frontend should call your backend:

const response = await fetch("/api/orders/ORD-1001/pay-with-crypto", {
  method: "POST"
});

const payment = await response.json();

window.location.href = payment.paymentUrl;

This keeps your Merchant API Key private.

---

Step 5: Redirect the Customer to Checkout

Once your backend returns the payment_url, redirect the customer.

The hosted payment page handles the customer-facing crypto payment experience.

The customer can choose the asset and network available for the payment, then send funds from their wallet or exchange.

At this point, your application should show a clear payment state.

A good UX might say:

Waiting for crypto payment.
You can complete the payment in the opened checkout page.
This order will update automatically after payment confirmation.

Do not tell the customer that the order is paid yet.

At this stage, the invoice exists, but the money has not been received and confirmed.

---

Step 6: Understand Payment Statuses

Payment APIs usually expose their own statuses.

OxaPay has a payment status table that includes statuses such as:

OxaPay Status	Meaning	Suggested Internal Handling
new	Invoice created, payer has not selected payment currency yet	Keep order unpaid
waiting	Payer selected currency, waiting for payment	Keep order unpaid, show waiting state
paying	Payer is attempting to complete payment	Show payment in progress
paid	Invoice has been fully paid	Mark payment as paid, trigger fulfillment once
underpaid	Payer made a partial payment	Hold order, show support/recovery state
manual_accept	Invoice manually accepted	Mark as accepted by admin rule
refunding	Refund has started	Lock fulfillment/refund-sensitive actions
refunded	Payment has been refunded	Mark payment as refunded
expired	Invoice was not paid in time	Expire payment attempt

Your internal statuses do not need to match these exactly.

In fact, they usually should not.

A cleaner internal state machine might look like this:

created
waiting_for_payment
payment_detected
confirming
paid
underpaid
expired
manual_review
refunding
refunded
failed

The goal is not to copy provider statuses blindly.

The goal is to translate external payment events into business-safe internal states.

---

Step 7: Listen for Webhooks

Crypto payments are asynchronous.

The customer may pay after 20 seconds, 5 minutes, or longer.

The transaction may need confirmations.

The customer may leave your website before the payment completes.

That is why webhooks matter.

With OxaPay, you set a callback_url when creating the invoice. OxaPay sends payment updates to that URL as JSON. You can read more in the OxaPay Webhook documentation.

A webhook endpoint should do five things:

1. Receive the raw request body
2. Validate the HMAC signature
3. Store the event
4. Update payment state idempotently
5. Return HTTP 200 with "ok"

Do not skip signature validation.

A webhook changes payment and order state. It must be treated as a sensitive endpoint.

---

Step 8: Validate the Webhook Signature

OxaPay sends an HMAC signature in the HMAC header.

You should calculate your own HMAC SHA-512 signature from the raw request body and compare it with the received header.

Important detail:

The signature must be calculated from the raw request body, not from a parsed and re-stringified JSON object.

Here is a Node.js + Express example:

import express from "express";
import crypto from "crypto";

const app = express();

function isValidOxaPayHmac(rawBody, receivedHmac) {
  if (!receivedHmac) return false;

  const calculatedHmac = crypto
    .createHmac("sha512", process.env.OXAPAY_MERCHANT_API_KEY)
    .update(rawBody)
    .digest("hex");

  const receivedBuffer = Buffer.from(receivedHmac, "hex");
  const calculatedBuffer = Buffer.from(calculatedHmac, "hex");

  if (receivedBuffer.length !== calculatedBuffer.length) {
    return false;
  }

  return crypto.timingSafeEqual(receivedBuffer, calculatedBuffer);
}

app.post(
  "/webhooks/oxapay",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    const receivedHmac = req.header("HMAC");
    const rawBody = req.body;

    if (!isValidOxaPayHmac(rawBody, receivedHmac)) {
      return res.status(401).send("invalid signature");
    }

    const event = JSON.parse(rawBody.toString("utf8"));

    await handleOxaPayWebhook(event, rawBody);

    return res.status(200).send("ok");
  }
);

This is the minimum security layer you need before trusting webhook data.

For local webhook testing, remember that many payment providers cannot send callbacks to localhost. Use a public HTTPS URL, a staging environment, or a tunneling tool for local development.

---

Step 9: Store Webhook Events Before Processing

Another common mistake is processing webhook events without saving them.

That makes debugging difficult.

When a payment issue happens, you need to know:

• Did the webhook arrive?
• What payload did it contain?
• Was the signature valid?
• Was it processed successfully?
• Was it a duplicate event?
• Did it arrive before or after another event?

Create a table for webhook events.

Example:

CREATE TABLE payment_events (
  id BIGSERIAL PRIMARY KEY,
  provider TEXT NOT NULL,
  provider_track_id TEXT NOT NULL,
  event_hash TEXT NOT NULL UNIQUE,
  event_status TEXT NULL,
  raw_payload JSONB NOT NULL,
  received_at TIMESTAMP NOT NULL DEFAULT NOW(),
  processed_at TIMESTAMP NULL
);

You can create an event_hash from stable fields in the payload or from the raw body.

Example:

function createEventHash(rawBody) {
  return crypto
    .createHash("sha256")
    .update(rawBody)
    .digest("hex");
}

Then store the event before processing:

async function storeWebhookEvent(event, rawBody) {
  const eventHash = createEventHash(rawBody);

  try {
    await db.payment_events.insert({
      provider: "oxapay",
      provider_track_id: event.track_id,
      event_hash: eventHash,
      event_status: event.status,
      raw_payload: event
    });

    return { isDuplicate: false, eventHash };
  } catch (error) {
    if (error.code === "23505") {
      return { isDuplicate: true, eventHash };
    }

    throw error;
  }
}

Why does this matter?

Because webhooks can be retried.

If the same webhook arrives twice, your system should not fulfill the same order twice.

That is called idempotency.

---

Step 10: Process Webhooks Idempotently

A simple but dangerous webhook handler looks like this:

if (event.status === "paid") {
  await markOrderAsPaid(event.order_id);
  await sendProductToCustomer(event.order_id);
}

This looks fine until the same webhook arrives twice.

Then the product may be delivered twice, emails may be sent twice, or accounting entries may be duplicated.

A safer pattern is:

Receive webhook
→ validate signature
→ store raw event
→ check duplicate
→ load local payment by track_id
→ compare current state
→ apply valid state transition
→ trigger fulfillment only once
→ mark event processed

Example:

async function handleOxaPayWebhook(event, rawBody) {
  const storedEvent = await storeWebhookEvent(event, rawBody);

  if (storedEvent.isDuplicate) {
    return;
  }

  const payment = await db.payments.findOne({
    provider: "oxapay",
    provider_track_id: event.track_id
  });

  if (!payment) {
    await flagWebhookForManualReview(event, "payment_not_found");
    return;
  }

  const nextStatus = mapOxaPayStatusToInternalStatus(event.status);

  await updatePaymentStateSafely(payment, nextStatus, event);

  await db.payment_events.update({
    event_hash: storedEvent.eventHash,
    processed_at: new Date()
  });
}

The status mapper can start simple:

function mapOxaPayStatusToInternalStatus(status) {
  const statusMap = {
    new: "created",
    waiting: "waiting_for_payment",
    paying: "payment_detected",
    paid: "paid",
    underpaid: "underpaid",
    manual_accept: "paid",
    refunding: "refunding",
    refunded: "refunded",
    expired: "expired"
  };

  return statusMap[status] || "manual_review";
}

The key rule is this:

Never let a duplicate webhook repeat a business action.

Updating a database field twice may be harmless.

Shipping a product twice is not.

---

Step 11: Update the Order Only When the Payment Is Actually Paid

Do not mark an order as paid just because the invoice was created.

Do not mark an order as paid just because the user returned to your website.

Do not mark an order as paid just because a payment attempt started.

For a simple first integration, use the paid status as the trigger for fulfillment.

Example:

async function updatePaymentStateSafely(payment, nextStatus, event) {
  const currentStatus = payment.status;

  if (currentStatus === "paid") {
    return;
  }

  await db.payments.update({
    id: payment.id,
    status: nextStatus,
    updated_at: new Date()
  });

  if (nextStatus === "paid") {
    await fulfillOrderOnce(payment.order_id, event);
  }

  if (nextStatus === "underpaid") {
    await notifySupportOrCustomer(payment.order_id, "Payment is underpaid");
  }

  if (nextStatus === "expired") {
    await expirePaymentAttempt(payment.order_id);
  }
}

Now make fulfillment idempotent too.

Example:

CREATE TABLE order_fulfillments (
  id BIGSERIAL PRIMARY KEY,
  order_id TEXT NOT NULL UNIQUE,
  payment_id BIGINT NOT NULL,
  fulfilled_at TIMESTAMP NOT NULL DEFAULT NOW()
);

Then:

async function fulfillOrderOnce(orderId, event) {
  const order = await db.orders.findOne({ id: orderId });

  if (!order) {
    throw new Error(`Order not found: ${orderId}`);
  }

  if (order.status === "fulfilled") {
    return;
  }

  await db.transaction(async (trx) => {
    await trx.order_fulfillments.insert({
      order_id: orderId,
      payment_id: event.track_id
    });

    await trx.orders.update({
      id: orderId,
      payment_status: "paid",
      status: "fulfilled",
      fulfilled_at: new Date()
    });
  });
}

The exact implementation depends on your database and ORM, but the principle is universal:

Payment completion and order fulfillment must be protected against duplicates.

---

Step 12: Add a Payment Status Page

After redirecting the customer to the hosted payment page, you still need a status page in your own application.

The return URL is useful, but it should not be treated as proof of payment.

A good status page reads from your backend.

Example frontend flow:

Customer returns from checkout
        |
        v
Frontend calls: GET /api/orders/ORD-1001/payment-status
        |
        v
Backend reads local payment status
        |
        v
Frontend shows the correct message

Example messages:

Internal Status	Customer Message
created	Your crypto invoice has been created.
waiting_for_payment	Waiting for payment.
payment_detected	Payment detected. Waiting for confirmation.
paid	Payment completed. Your order is confirmed.
underpaid	Payment received, but the amount is lower than expected.
expired	This payment link has expired. Please create a new payment.
manual_review	Your payment needs review. Support will check it shortly.

This improves trust.

Crypto payments can take time. A blank or confusing status page creates support tickets.

A clear status page tells the customer what is happening.

---

Step 13: Use Payment Information for Reconciliation

Webhooks are important, but they should not be your only recovery mechanism.

Sometimes a webhook may fail.

Your server may be down.

A firewall rule may block the request.

A worker may crash after receiving the event.

That is why reconciliation matters.

OxaPay provides a Payment Information endpoint that lets you retrieve payment details using the track_id.

Example:

curl -X GET https://api.oxapay.com/v1/payment/184747701 \
  -H "merchant_api_key: $OXAPAY_MERCHANT_API_KEY" \
  -H "Content-Type: application/json"

You can use this endpoint when:

• an invoice is stuck in pending state
• a webhook was missed
• support needs to investigate a payment
• your local state does not match the provider state
• a customer claims they paid but the order is not updated

A simple reconciliation job can run every few minutes:

Find unresolved payments
→ Fetch latest provider status by track_id
→ Compare provider status with local status
→ Apply safe state transition
→ Flag mismatches for manual review

Example:

async function reconcilePendingPayments() {
  const unresolvedPayments = await db.payments.findMany({
    provider: "oxapay",
    status_in: [
      "created",
      "waiting_for_payment",
      "payment_detected",
      "manual_review"
    ]
  });

  for (const payment of unresolvedPayments) {
    const providerPayment = await fetchOxaPayPayment(payment.provider_track_id);

    const nextStatus = mapOxaPayStatusToInternalStatus(
      providerPayment.data.status
    );

    await updatePaymentStateSafely(payment, nextStatus, providerPayment.data);
  }
}

async function fetchOxaPayPayment(trackId) {
  const response = await fetch(`https://api.oxapay.com/v1/payment/${trackId}`, {
    method: "GET",
    headers: {
      "merchant_api_key": process.env.OXAPAY_MERCHANT_API_KEY,
      "Content-Type": "application/json"
    }
  });

  const result = await response.json();

  if (!response.ok || result.status !== 200) {
    throw new Error(`Payment lookup failed: ${JSON.stringify(result.error)}`);
  }

  return result;
}

This turns your first integration from a fragile checkout flow into a reliable payment workflow.

---

Step 14: Test in Sandbox Before Going Live

Do not go straight to production.

Use sandbox mode first.

In the invoice request, OxaPay supports a sandbox field. Set it to true while testing:

{
  "amount": 49.99,
  "currency": "USD",
  "sandbox": true
}

Test the happy path first:

Create invoice
→ Open payment_url
→ Complete test payment
→ Receive webhook
→ Update payment status
→ Fulfill order once

Then test failure and edge cases.

Your sandbox checklist should include:

• invoice creation
• redirect to checkout
• webhook receipt
• webhook HMAC validation
• duplicate webhook handling
• expired invoice
• underpaid payment
• paid payment
• return URL behavior
• payment status page behavior
• reconciliation by track_id
• order fulfillment idempotency
• missing local payment record
• webhook arriving twice
• webhook arriving after order expiration

The goal of sandbox testing is not only to prove that a payment can succeed.

The real goal is to prove that your system stays consistent when payment events are delayed, duplicated, incomplete, or unexpected.

---

Step 15: Go Live Carefully

Going live is not just changing sandbox: true to sandbox: false.

Before production, check the whole payment path:

API key is production key
callback_url uses HTTPS
return_url is correct
webhook endpoint returns HTTP 200 with "ok"
HMAC validation works with raw body
payment records are stored before redirect
track_id is stored and searchable
paid status triggers fulfillment only once
underpaid status does not auto-fulfill
expired status does not incorrectly cancel paid orders
reconciliation job is enabled
support can search by order_id and track_id

A simple production readiness checklist:

Area	Question
Security	Is the Merchant API Key stored only on the server?
Webhooks	Are callbacks validated with HMAC?
State	Do you have internal payment statuses?
Idempotency	Can the same webhook arrive twice safely?
UX	Can users see payment progress clearly?
Support	Can support search by order ID and track ID?
Reconciliation	Can your backend recover from a missed webhook?
Fulfillment	Can an order be fulfilled only once?

If these are covered, your first integration is no longer just a demo.

It is much closer to production-ready.

---

Common Mistakes to Avoid

Here are the mistakes I would avoid from day one.

1. Creating invoices from the frontend

This exposes sensitive logic and may expose credentials.

Always create invoices from your backend.

2. Treating redirect as proof of payment

A return URL only means the user came back.

It does not prove that the payment is complete.

3. Trusting webhooks without validation

Always validate the HMAC signature before processing payment updates.

4. Not storing track_id

The track_id connects your system to the provider-side payment session.

Without it, support and reconciliation become painful.

5. Marking orders as paid too early

Invoice creation is not payment completion.

Payment started is not payment completed.

6. Ignoring underpaid payments

Underpaid payments need a clear rule.

Do not silently fail them.

Do not fulfill them automatically unless your business explicitly accepts that risk.

7. Forgetting idempotency

Every payment-side effect should be safe to run once, even if the event is received more than once.

8. Skipping reconciliation

Webhook-only systems are fragile.

A simple reconciliation job can prevent many production issues.

---

The Minimal Production Architecture

For a first integration, this architecture is enough:

Frontend
  |
  | 1. User clicks Pay with Crypto
  v
Backend API
  |
  | 2. Create invoice through OxaPay
  v
OxaPay
  |
  | 3. Return track_id + payment_url
  v
Backend Database
  |
  | 4. Store payment record
  v
Frontend
  |
  | 5. Redirect user to payment_url
  v
OxaPay Checkout
  |
  | 6. User completes payment
  v
Webhook Endpoint
  |
  | 7. Validate HMAC + store event + update state
  v
Order System
  |
  | 8. Fulfill order once when payment is paid
  v
Reconciliation Job
  |
  | 9. Check unresolved payments by track_id

This is still simple.

But it avoids the biggest mistake:

Treating crypto payment integration as a single API call.

It is not a single API call.

It is a small payment system.

---

Final Thoughts

Your first crypto payment integration does not need to be complicated.

You need:

1. A secure API key
2. A backend invoice creation endpoint
3. A local payment record
4. A customer redirect to checkout
5. A validated webhook endpoint
6. Idempotent payment updates
7. A payment status page
8. A reconciliation path

Once those pieces are in place, you can accept your first crypto payment with much more confidence.

The biggest lesson is this:

Do not build only for the happy path.

Build for delayed transactions, duplicate webhooks, expired invoices, underpayments, and users who leave the checkout page before the payment is complete.

That is what separates a demo integration from a production-ready payment flow.

For developers who want to move faster, OxaPay provides hosted crypto invoices, payment APIs, webhooks, payment tracking, and developer documentation through its payment API documentation. That means you can focus less on building payment infrastructure from scratch and more on connecting crypto payments safely to your product logic.

The first transaction is only the beginning.

The real goal is a payment flow that stays correct after the transaction happens.