Create Digital Receipt

Follow these steps to successfully send transaction data and create digital receipts for NFC terminals:

Step 1: Generate Webhook Headers

First, gather the secret and API keys from your PSP account dashboard. Then, use our Recipe for generating webhook request headers to create the required authentication headers. This recipe will guide you through generating:

• API Key header (X-API-Key)
• HMAC Signature header (X-Signature)
• Timestamp header (X-Timestamp)
• Request ID header (X-Request-ID)

Step 2: Prepare Your Request Body

Create a JSON payload with the transaction details:

{
  "terminal_id": "uuid",
  "psp_id": "uuid",
  "merchant_id": "uuid",
  "transaction_id": "string",
  "transaction_status": "Approved|Declined|Settled|Authorized|Failed|Declined - Fraud|Declined",
  "transaction_type": "Purchase|Pre-authorization|Capture|Void|Refund|Credit|Adjustment|Chargeback|Verification|Settlement|Reversal",
  "transaction_date": "ISO 8601 datetime",
  "amount": 123.45,
  "currency": "3-letter code",
  "card_type": "Mada|Visa|Mastercard|AMEX|JCB|Union-Pay|Discover",
  "rajb": "string",
  "serial_number": "string",
  "payment_number": "string",
  "approval_code": "string",
  "card_number_masked": "string",
  "customer_name": "string (optional)",
  "status": "string (optional)",
  "duplicate_allowed": "boolean (optional)",
  "receipt_data": "object (optional)"
}

Step 3: Send the Webhook Request

Make a POST request to our webhook endpoint with your headers and payload with the code from recipe or using API Reference GUI.:

POST /functions/v1/psp-webhook
Content-Type: application/json
X-API-Key: [your-api-key]
X-Signature: [generated-signature]
X-Timestamp: [unix-timestamp]
X-Request-ID: [unique-request-id]

Step 4: Handle the Response

Success Response (200 OK):

{
  "success": true,
  "message": "Receipt processed successfully",
  "data": {
    "receipt_id": "uuid",
    "transaction_id": "string",
    "terminal_id": "uuid",
    "amount": 123.45,
    "currency": "string",
    "processing_time_ms": 123,
    "request_id": "uuid"
  }
}

Error Response (4xx/5xx):

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      "additional": "context"
    }
  }
}

Important Notes

• Authentication: All requests require valid API key, HMAC signature, timestamp, and request ID
• Entity Validation: PSP → Merchant → Terminal relationship must be valid
• Duplicate Prevention: Same transaction ID cannot be processed twice per PSP except if duplicate_allowed is true in special cases
• Receipt Lifecycle: Receipts are available for display for 24 hours