Authentication Process

Overview

The C2C Merchant API uses two credentials, issued together:

Credential	Format	Used for
API key	`mk_live_` + 32 alphanumeric characters	Identifies your merchant account. Sent in the `C2C-API-Key` header on every request.
Signing secret	`sksec_` + 40 alphanumeric characters	Signs deposit and withdrawal orders and verifies the webhooks C2C sends you. Never sent over the wire. See the Signature Generation Guide.

Both credentials are shown only once, when C2C issues them. C2C stores only a hash of your API key and cannot show it to you again. Store both immediately in a secret manager or environment variables, and never expose them in client-side code.

Getting your credentials

A C2C administrator issues API keys for your merchant account, and each key comes with its own signing secret. In the Merchant Portal you can see your keys (name, prefix, status, last used) and revoke a key, but you can’t create new ones there. Contact C2C to get a key or to rotate one.

You can hold more than one active API key (for example one per backend service). Each key has its own signing secret.
Idempotency keys are scoped to the API key that used them. Orders belong to your merchant account: any of your active keys can query their status, including orders created before a key rotation.
Regenerating your API key issues a new key and secret and revokes every previously active key on your account.
A revoked key stops working immediately.

What you can do in the Merchant Portal depends on your portal role. The account owner has full access. Team members only see the pages their role allows: API Keys to view or revoke keys, Settings to change the default callback URL, and Transactions for order history. The account owner manages roles in the portal.

Authentication method

Send your API key in the C2C-API-Key header:

C2C-API-Key: mk_live_your_api_key

Authorization: Bearer mk_live_... is still accepted for existing integrations. If a request carries both, C2C-API-Key is used.

Required headers

Header	Required on	Value
`C2C-API-Key`	All requests	`mk_live_...`
`Content-Type`	Requests with a body	`application/json`
`Idempotency-Key`	`POST /api/merchant/orders`	Your unique key for this order attempt, up to 100 characters. See Idempotency.

Deposit and withdrawal requests also carry a signature field in the JSON body. See the Signature Generation Guide. Status and balance requests need only the API key.

Example request

curl --request GET \
  --url https://api.c2cpayment.net/api/merchant/orders/balance \
  --header "C2C-API-Key: $C2C_API_KEY"

const response = await fetch(
  'https://api.c2cpayment.net/api/merchant/orders/balance',
  { headers: { 'C2C-API-Key': process.env.C2C_API_KEY } }
);
console.log(response.status, await response.json());

import os
import requests

response = requests.get(
    "https://api.c2cpayment.net/api/merchant/orders/balance",
    headers={"C2C-API-Key": os.environ["C2C_API_KEY"]},
)
print(response.status_code, response.json())

A successful call returns 200:

{
  "data": {
    "availableBalance": 0.0,
    "reservedBalance": 0.0,
    "frozenBalance": 0.0,
    "currency": "PKR"
  }
}

GET /api/merchant/orders/balance has no side effects, so it is a good way to test your API key. Test your signing code against the worked examples.

Storing credentials securely

export C2C_API_KEY="mk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export C2C_SIGNING_SECRET="sksec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

$env:C2C_API_KEY="mk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
$env:C2C_SIGNING_SECRET="sksec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# Add .env to .gitignore
C2C_API_KEY=mk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
C2C_SIGNING_SECRET=sksec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Server-side only

Call the C2C API from your backend. Never ship the API key or signing secret to a browser or mobile app.

Use a secret manager in production

Azure Key Vault, AWS Secrets Manager or HashiCorp Vault, not plain configuration files.

Never log credentials

Mask the C2C-API-Key (or Authorization) header and never log the signing secret.

Separate keys per environment

Use different keys for development and production. Keys only work in the environment that issued them.

Rotate on exposure

If a key or secret may have leaked, contact C2C to revoke it and issue a replacement.

Account-level access controls

Besides the API key and signature, C2C applies these checks when you create an order. The Merchant API has no request rate limits.

Check	Result when it fails
Merchant account is Active	`403`: `Merchant account is suspended; new orders are not accepted.`
IP whitelist, if C2C has enabled one for your account (Deposit / Withdrawal scope)	`403`: `IP not in whitelist.`
Payment method (`walletType`) enabled for your account and order type	`422`: `JazzCash deposits are disabled for this merchant.`

Authentication errors

401 Unauthorized: API key

Returned when no API key is sent (neither C2C-API-Key nor Authorization: Bearer mk_...), the C2C-API-Key value isn’t an mk_ key, or the key is unknown or revoked. The response has an empty body.

HTTP/1.1 401 Unauthorized
Content-Length: 0

Checklist

The header is exactly C2C-API-Key: mk_live_..., with no quotes or extra spaces.
The key belongs to the environment you are calling.
The key has not been revoked or replaced by a regeneration.

401 Unauthorized: signature

Returned on order creation when the API key is valid but the body’s signature is missing, malformed, wrong or replayed. Unlike an API key failure, this response has a JSON body with a code:

{
  "success": false,
  "error": "The request body must include a 'signature' field.",
  "code": "SIGNATURE_REQUIRED",
  "traceId": "15f1bf9c3472631576b915f2382451fd"
}

See Signature error responses.

Next steps

Signature Generation Guide

Sign requests correctly

Create a deposit

Create your first order

Errors

Every error response the API returns

Quickstart

End-to-end integration

API documentation

Authentication

Account Balance

Deposit

Withdrawal

Order Status

Reference

Overview

Getting your credentials

Authentication method

Required headers

Example request

Storing credentials securely

Account-level access controls

Authentication errors

401 Unauthorized: API key

401 Unauthorized: signature

Next steps

Signature Generation Guide

Create a deposit

Errors

Quickstart

​Overview

​Getting your credentials

​Authentication method

​Required headers

​Example request

​Storing credentials securely

​Account-level access controls

​Authentication errors

​401 Unauthorized: API key

​401 Unauthorized: signature

​Next steps

Signature Generation Guide

Create a deposit

Errors

Quickstart

Overview

Getting your credentials

Authentication method

Required headers

Example request

Storing credentials securely

Account-level access controls

Authentication errors

401 Unauthorized: API key

401 Unauthorized: signature

Next steps