Authentication & Environments

Rebell Payment APIs use asymmetric cryptography (RSA) to ensure secure server-to-server communication between your backend and the Rebell platform. Every API request must be signed with your private key, and every response must be validated according to the contract defined in this section.

API Environments

Rebell provides two separate environments for integration and production use:

Sandbox

Base URL: https://sandbox-api.rebellapp.comFor integration, functional testing, and signature verification. Payments are simulated and do not settle.

Production

Base URL: https://api.rebellapp.comLive payment environment. Requires merchant onboarding and contract activation.

Environment Separation Rules

Critical requirements:

Sandbox and Production credentials are not interchangeable
Keys registered in sandbox do not carry over to production
Webhooks must be configured per environment
Testing and live order identifiers must remain separate

Merchant Credentials

Once you complete merchant onboarding (regulatory, KYB, and contractual steps), Rebell provisions a credential set that identifies and authenticates your business.

Credential Components

Client-Id
RSA Public Key
keyVersion

Unique merchant identifierA unique identifier for your merchant account, included in every API request header.

Client-Id: 2022091495540562874792

Key rotation supportA version number assigned to each RSA key pair. Used to support key rotation without downtime.

keyVersion: 1

When you rotate keys, Rebell assigns a new keyVersion while accepting signatures from previous active versions.

These credentials enable secure, authenticated API communication.

RSA Signing Model

All API requests must be signed with your RSA-2048 private key using SHA256.

What Rebell Validates

Rebell validates every request for:

✅ Signature integrity - Cryptographic signature matches request content
✅ Timestamp freshness - Request is within 5-minute tolerance window
✅ Merchant identity - Client-Id matches registered merchant
✅ Payload consistency - Request body hasn’t been tampered with

Purpose of Signing

Merchant Authentication

Ensures that the request originates from the legitimate merchant who owns the Client-Id and private key.

Request Integrity

Prevents tampering with request content during transmission. Any modification invalidates the signature.

Replay Attack Prevention

Timestamp validation prevents attackers from capturing and replaying old requests.

Required HTTP Headers

Every server-to-server API call must include these headers:

Header	Required	Description
`Client-Id`	Yes	Identifies the merchant
`Request-Time`	Yes	ISO 8601 timestamp (UTC)
`Signature`	Yes	RSA signature block
`Content-Type`	Yes	Must be `application/json`

Timestamp Requirement

The Request-Time value must not differ from Rebell server time by more than ±5 minutes.Requests outside this tolerance window are rejected to prevent replay attacks.

Example:

Request-Time: 2024-01-10T12:22:30Z

Signature Construction

Follow these three steps to generate a valid signature:

Build the Signing String

Concatenate the following components:

<HTTP_METHOD> <HTTP_PATH>
<Client-Id>.<Request-Time>.<BODY>

Examples:

POST /v1/payments/retailPay
2022091495540562874792.2024-01-10T12:22:30Z.{"productCode":"51051000101000100040",...}

POST /v1/payments/createQrOrder
2022091495540562874792.2024-01-10T12:22:30Z.{"paymentAmount":{"currency":"EUR","value":1250},...}

Sign with RSA-SHA256

Use your private key to sign the string:

SHA256withRSA(signing_string)

Implementation examples:

const crypto = require('crypto');
const fs = require('fs');

function signRequest(method, path, clientId, requestTime, body) {
  const signingString = `${method} ${path}\n${clientId}.${requestTime}.${JSON.stringify(body)}`;

  const privateKey = fs.readFileSync('private_key.pem', 'utf8');
  const sign = crypto.createSign('RSA-SHA256');
  sign.update(signingString);

  const signature = sign.sign(privateKey, 'base64url');
  return signature;
}

Format the Signature Header

Format the signature header as:

Signature: algorithm=SHA256withRSA, keyVersion=<n>, signature=<base64url>

Example:

Signature: algorithm=SHA256withRSA, keyVersion=1, signature=MIIC...

Important notes:

Signature is base64url-encoded (not standard base64)
Newlines must not be inserted in the signature payload
Ensure all JSON fields are serialized consistently

Complete Example

Here’s a complete signed request:

POST /v1/payments/retailPay
Client-Id: 2022091495540562874792
Request-Time: 2024-01-10T12:22:30Z
Signature: algorithm=SHA256withRSA, keyVersion=1, signature=MIIC...
Content-Type: application/json

{
  "productCode": "51051000101000100040",
  "paymentRequestId": "pos-001",
  "paymentAuthCode": "2810120202624...",
  "paymentAmount": {
    "currency": "EUR",
    "value": 1250
  },
  "order": {
    "orderDescription": "Coffee"
  }
}

Validation Process

This request will be validated for:

Key Rotation

Merchants may rotate keys at any time without downtime.

Rotation Process

Generate New Key Pair

Create a new RSA-2048 key pair while keeping the old one active.

Upload New Public Key

Upload the new public key to Rebell. You’ll receive a new keyVersion identifier.

Gradual Migration

Gradually migrate traffic to use the new key while the old key remains active.

Deprecate Old Key

Once all traffic has migrated, deprecate the old key through the merchant portal.

Rotation Rules

New keyVersion

Every new public key uploaded to Rebell receives a new keyVersion identifier

Multi-Version Support

Rebell accepts signatures generated with any active keyVersion

Gradual Migration

Migrate traffic gradually and deprecate old keys safely

Secure Storage

Private keys must be stored in a secure KMS/HSM

Security Best Practices

Critical Security Requirements:

✅ Store private keys in a Hardware Security Module (HSM) or cloud KMS
✅ Never embed private keys in mobile apps or frontend code
✅ Rotate private keys regularly (recommended every 6-12 months)
✅ Validate webhook signatures using the same RSA mechanism
✅ Log invalid signature attempts for auditing
✅ Ensure system clocks are synchronized (NTP)

Key Storage

Your private key is the most critical security asset. Follow these guidelines:

Use HSM or Cloud KMS

Store private keys in dedicated hardware security modules (HSM) or cloud-based key management systems (AWS KMS, Google Cloud KMS, Azure Key Vault).Never:

Store keys in application code
Commit keys to version control
Share keys via email or chat

Restrict Access

Limit private key access to only the backend services that need to sign requests. Use role-based access control (RBAC) and audit all key access.

Regular Rotation

Rotate keys every 6-12 months or immediately if:

Key may have been compromised
Team member with key access leaves
Security audit recommends rotation

Environment Separation

Use completely separate keys for sandbox and production environments. Never share keys between environments.

Clock Synchronization

Ensure your servers use Network Time Protocol (NTP) to maintain accurate time synchronization. Clock drift can cause valid requests to be rejected due to timestamp validation failures.Check your server time:

date -u

Sync with NTP:

ntpdate -s time.nist.gov

Troubleshooting

Common signature validation errors and solutions:

Invalid Signature Error

Cause: Signature doesn’t match the signing stringSolutions:

Verify signing string format (HTTP method, path, Client-Id, timestamp, body)
Ensure JSON serialization is consistent (no extra whitespace)
Check that you’re using the correct private key
Verify base64url encoding (not standard base64)

Timestamp Out of Range

Cause: Request-Time differs from server time by more than 5 minutesSolutions:

Synchronize your server clock with NTP
Check for timezone issues (must be UTC)
Verify ISO 8601 format: 2024-01-10T12:22:30Z

Invalid Client-Id

Cause: Client-Id not recognized or inactiveSolutions:

Verify you’re using the correct Client-Id for the environment
Check that merchant account is active
Ensure you’re not mixing sandbox and production credentials

Invalid keyVersion

Cause: keyVersion doesn’t match any active keysSolutions:

Verify keyVersion in signature header
Check that key hasn’t been deprecated
Ensure public key was successfully uploaded

Next Steps

Authentication Deep Dive

Advanced authentication topics and implementation details

Retail Pay

Implement merchant-initiated QR scanning payments

Webhooks

Verify webhook signatures using the same RSA mechanism

Error Handling

Handle authentication and signature errors correctly

Getting started

Payment Integration

Mini App Development

API Environments

Sandbox

Production

Environment Separation Rules

Merchant Credentials

Credential Components

RSA Signing Model

What Rebell Validates

Purpose of Signing

Required HTTP Headers

Timestamp Requirement

Signature Construction

Complete Example

Validation Process

Key Rotation

Rotation Process

Rotation Rules

New keyVersion

Multi-Version Support

Gradual Migration

Secure Storage

Security Best Practices

Key Storage

Clock Synchronization

Troubleshooting

Next Steps

Authentication Deep Dive

Retail Pay

Webhooks

Error Handling

Getting started

Payment Integration

Mini App Development

​API Environments

Sandbox

Production

​Environment Separation Rules

​Merchant Credentials

​Credential Components

​RSA Signing Model

​What Rebell Validates

​Purpose of Signing

​Required HTTP Headers

​Timestamp Requirement

​Signature Construction

​Complete Example

​Validation Process

​Key Rotation

​Rotation Process

​Rotation Rules

New keyVersion

Multi-Version Support

Gradual Migration

Secure Storage

​Security Best Practices

​Key Storage

​Clock Synchronization

​Troubleshooting

​Next Steps

Authentication Deep Dive

Retail Pay

Webhooks

Error Handling

API Environments

Environment Separation Rules

Merchant Credentials

Credential Components

RSA Signing Model

What Rebell Validates

Purpose of Signing

Required HTTP Headers

Timestamp Requirement

Signature Construction

Complete Example

Validation Process

Key Rotation

Rotation Process

Rotation Rules

Security Best Practices

Key Storage

Clock Synchronization

Troubleshooting

Next Steps