Skip to content

Terminal responses

Accepting webhooks

The customer needs to be ready to accept callbacks from the Cloud Link API for the complete flow to work. These should be HTTPS Post endpoints that need to be setup according to the following specification.

Rapyd supports the use of an API key in the response callbacks. A header parameter X-API-KEY is included in api calls from CloudLink and if provided by the customer, a key value will be added to that parameter. Otherwise the value will be empty. Rapyd supports the use of one key for each domain. Key registration for the UAT and PROD environments are separate.

Content type is application/json

The following contract is delivered in the request body. All properties are optional and the endpoints must not fail if new properties are added. Properties will never be removed from the contract. 

{
  "eventType": "NONE",
  "callbackUrl": "string",
  "correlationId": "string",
  "terminalResponse": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  }
}

These are the properties you must expect to receive for eventType SALE_COMPLETED. Properties will never be removed from the contract. 

"terminalResponse": {
    "cardholderReceipt": "string",
    "merchantReceipt": "string",
    "isSignature": "string",
    "signature": "string",
    "responseCode": "string",
    "result": "string",
    "uti": "string",
    "transCancelled": "string",
    "authorizationCode": "string",
    "amount": "string",
    "cardPan": "string",
    "stan": "string",
    "terminalId": "string",
    "merchantId": "string",
    "retrievalReferenceNumber": "string",
    "softwareVersion": "string",
    "cardTypeExtra": "string",
    "longitude": "string",
    "latitude": "string",
    "dccTransaction": "string",
    "dccOriginalAmount": "string",
    "dccCurrency": "string",
    "tipAmount": "string",
    "voided": "string",
    "payerAccountReference": "string",
    "dateTime": "string",
    "cvmResult": "string",
    "acquirer": "string",
    "cardType": "string",
    "currencyCode": "string",
    "transactionSource": "string",
    "voucherBenefitCardIssuer": "string",
    "voucherWalletName": "string",
    "voucherBalance": "string",
    "voucherExpirationDate": "string",
    "aid": "string",
    "tsi": "string",
    "tvr": "string",
    "cvmr": "string",
    "walletProvider": "string",
    "processorCorrelationId": "string",
    "productId": "string",
    "productDescription": "string",
    "issuerIdentifier": "string",
    "issuingCountry": "string",
    "issuerRegion": "string",
    "cardholderBillingCurrency": "string",
    "cardUsage": "string",
    "cardCategory": "string",
    "approved": "string"
}

CloudLinkResponse Object Details

The terminalResponse object contains comprehensive transaction information. Here are the key fields and their descriptions:

Core Transaction Fields

  • cardholderReceipt - Receipt text for the cardholder
  • merchantReceipt - Receipt text for the merchant
  • responseCode - Terminal response code (e.g., "00" for success)
  • result - Human-readable result ("Approved" or "Declined")
  • uti - Unique Transaction Identifier
  • amount - Transaction amount
  • authorizationCode - Bank authorization code

Receipt Format Documentation

The cardholderReceipt and merchantReceipt fields contain formatted receipt data using Rapyd's custom printing format. This format allows for rich text formatting including different fonts, alignments, styles, and special elements like QR codes and barcodes.

Receipt Format Structure

Each receipt is formatted as a JSON array where each element represents a line of text with the following structure:

["Text to print", "font size", "alignment", "style"]

Format Parameters

Font Sizes

  • 1 - Small
  • 5 - Normal (default)
  • 9 - Big

Alignments

  • L - Align left (default)
  • R - Align right
  • C - Align in center
  • S - Split (Align one text on left and the other on the right)
  • QR - QR code

Styles

  • N - Normal text (default)
  • B - Bold
  • I - Italic
  • U - Underline

Default Values

  • Font Size: 5 (Normal)
  • Alignment: L (Left)
  • Style: N (Normal text)

Special Commands

Empty Line

{}
Adds an empty line to the receipt.

Logo Display

["logo"]
Displays the Rapyd logo on the receipt.

QR Code Generation

["Some value", "QR", "Size of qr"]
Generates a QR code with the specified value and size.

Barcode Generation

["Some data", "Barcode", "Width of barcode", "Height of barcode"]
Generates a barcode in CODE_39 format. The system automatically formats the data if it doesn't follow Code_39 format requirements.

Example Receipt

Here's a real example of a cardholderReceipt showing the format in action:

"cardholderReceipt": "[[CARDHOLDER COPY, 5, C, B], [], [#{ADDR0}, 5, L, B], [#{ADDR1}, 5, L, B], [#{ADDR2}, 5, L, B], [], [2025-08-18, 09:18, 5, S, N], [MC CREDIT, 9, L, I], [************0036, 5, L, N], [], [AUTHORISED - 264119, 5, C, B], [], [], [], [SALE, 5, C, N], [AMOUNT, 9, C, B], [80 ISK, 9, C, B], [NO VERIFICATION, 5, L, N], [CONTACTLESS, 5, L, N], [ReceiptNo: 4, 1, L, N], [***********1001, *****576, 1, S, N], [A0000000041010, 1, L, N], []]"

Receipt Breakdown

Line Content Font Alignment Style Description
1 CARDHOLDER COPY 5 (Normal) C (Center) B (Bold) Header text centered and bold
2 {} - - - Empty line
3 #{ADDR0} 5 (Normal) L (Left) B (Bold) Address line 0, left-aligned, bold
4 #{ADDR1} 5 (Normal) L (Left) B (Bold) Address line 1, left-aligned, bold
5 #{ADDR2} 5 (Normal) L (Left) B (Bold) Address line 2, left-aligned, bold
6 {} - - - Empty line
7 2025-08-18, 09:18 5 (Normal) S (Split) N (Normal) Date and time, split alignment
8 MC CREDIT 9 (Big) L (Left) I (Italic) Card type, big font, left-aligned, italic
9 ************0036 5 (Normal) L (Left) N (Normal) Masked card number
10 {} - - - Empty line
11 AUTHORISED - 264119 5 (Normal) C (Center) B (Bold) Authorization message, centered, bold
12-15 {} - - - Multiple empty lines
16 SALE 5 (Normal) C (Center) N (Normal) Transaction type, centered
17 AMOUNT 9 (Big) C (Center) B (Bold) Amount label, big font, centered, bold
18 80 ISK 9 (Big) C (Center) B (Bold) Amount value, big font, centered, bold
19 NO VERIFICATION 5 (Normal) L (Left) N (Normal) Verification status
20 CONTACTLESS 5 (Normal) L (Left) N (Normal) Payment method
21 ReceiptNo: 4 1 (Small) L (Left) N (Normal) Receipt number, small font
22 ***********1001, *****576 1 (Small) S (Split) N (Normal) Reference numbers, split alignment
23 A0000000041010 1 (Small) L (Left) N (Normal) Application identifier
24 [] - - - Empty line

Implementation Notes

When processing receipt data in your application:

  1. Parse the JSON array - Each element represents a receipt line
  2. Handle special commands - Check for empty lines {} and special elements
  3. Apply formatting - Use the font size, alignment, and style parameters
  4. Render appropriately - Display according to the specified formatting
  5. Fallback gracefully - Use default values if parameters are missing

Common Use Cases

  • Display receipts in mobile apps or web interfaces
  • Print receipts using the same formatting
  • Store receipt data with formatting preserved
  • Generate PDF receipts with consistent styling
  • Analyze transaction details from formatted text

Card Information

  • cardPan - Masked card number
  • cardType - Type of card (VISA, Mastercard, etc.)
  • cardTypeExtra - Additional card type information
  • aid - Application Identifier
  • tsi - Terminal Selection Indicator
  • tvr - Terminal Verification Results
  • cvmr - Cardholder Verification Method Results

Terminal & Merchant Details

  • terminalId - Terminal identifier
  • merchantId - Merchant identifier
  • stan - System Trace Audit Number
  • retrievalReferenceNumber - Reference number for retrieval
  • softwareVersion - Terminal software version

Location & Timing

  • longitude - Terminal longitude coordinate
  • latitude - Terminal latitude coordinate
  • dateTime - Transaction timestamp (format: "yyyy-MM-dd HH:mm:ss")

Advanced Features

  • tipAmount - Tip amount if applicable
  • dccTransaction - Dynamic Currency Conversion indicator
  • dccOriginalAmount - Original amount before DCC
  • dccCurrency - DCC currency code
  • voided - Whether transaction was voided
  • walletProvider - Digital wallet provider (if applicable)

Voucher & Loyalty

  • voucherBenefitCardIssuer - Voucher benefit card issuer
  • voucherWalletName - Voucher wallet name
  • voucherBalance - Voucher balance
  • voucherExpirationDate - Voucher expiration date

Security & Verification

  • isSignature - Whether signature was required
  • signature - Signature data if applicable
  • cvmResult - Cardholder Verification Method result
  • payerAccountReference - Payer account reference

Processing Details

  • processorCorrelationId - Processor correlation identifier
  • productId - Product identifier
  • productDescription - Product description
  • issuerIdentifier - Card issuer identifier
  • issuingCountry - Card issuing country
  • issuerRegion - Card issuer region
  • cardholderBillingCurrency - Cardholder billing currency
  • cardUsage - Card usage type
  • cardCategory - Card category
  • approved - Whether transaction was approved ("true"/"false") 
    These are the properties you must expect to receive for eventType **TERMINAL_ERROR**.
Properties will never be removed from the contract.
    "terminalResponse": { "errorMessage": "string" } 
    These are the properties you must expect to receive for eventType **MERCHANT_CONFIG**.
Properties will never be removed from the contract.
    "merchantConfig": [ { "currencyCode": "string", "merchantId": "string", "merchantName": "string", "terminalId": "string" } ] ```

Event types

SALE_RECEIVED - The terminal has received the request and is validating the callback url before starting the authorization process.

SALE_COMPLETED - The terminal has completed the authorization process. Failure to accept this request will cause the POS to void the authorization. Final state for a transaction, no further actions available.

SALE_CANCELLED - Cardholder or merchant have cancelled the transaction at the terminal. Final state for a transaction, no further actions available.

SALE_REQUESTED - Sale initiated at the terminal. If the registry accepts the request it must then initiate the sale using the /sale endpoint.

TERMINAL_BUSY - A terminal can only process one sale at a time. This status indicates that the terminal is in the middle of processing another sale. Retry to check for availability.

TERMINAL_ERROR - The terminal is inoperable. A reason is given in the TerminalResponse. No cleanup required on behalf of the registry system.

MERCHANT_CONFIG - The terminal has provided its merchant configuration information including available merchants, currencies, and terminal details. This response contains a list of merchant configuration items that can be used for transaction processing.