Skip to main content

Documentation

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",
    "responseCode": "string",
    "result": "string",
    "transCancelled": "string",
    "cardTypeExtra": "string"
    "authorizationCode": "string",
    "amount": "string",
    "cardPan": "string",
    "stan": "string",
    "terminalId": "string",
    "merchantId": "string",
    "softwareVersion": "string",
    "retrievalReferenceNumber": "string",
    "longitude": "string",
    "latitude": "string",
    "radius": "string",
    "lastSync": "string"
}

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

      • "terminalResponse": {
    "errorMessage": "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.

In this section: