In-person Payments / SoftPOS / Basic Operations / Refund A Payment / Card Present Refund

Refund: Card Present

The refund is initiated via the API, but requires the customer to be physically present and have a valid payment method available (e.g. a debit or credit card).

Following conditions apply to the Refund Card Present functionality:

• reference parameter is not required when performing a Card Present Refund.

1. Make a Refund request

API Request

• End-point: /api/v1/refund
• Method: POST​
• Authentication: API Key
• Request Headers
  • Content-Type: application/json​

Request parameters

¹Min/MaxLength: 1/100
Allowed character A–Z a–z 0–9 <space> / - ? : ( ) . , ' + & * @ #

Example

{
  "amount": 0.01,
  "currency": "eur",
  "method": "softpos",
  "language": "eng",
  "merchantOrderReference": "Test1234",
  "details": {
    "terminalId": "123456",
    "cardPresent": "true"
  }
}

API Response

Response parameters

Example

{
  "status": "pending",
  "reference": "SP123456789ABC123456ABC123.A",
  "method": "softpos",
  "type": "refund",
  "language": "eng",
  "currency": "eur",
  "lastUpdate": 1761920500,
  "created": 1761920495,
  "methodTransactionId": "SP123456789ABC123456ABC123.A",
  "amount": 0.01,
  "merchantOrderReference": "Test1234",
  "details": {
    "terminalId": "123456"
  }
}

2. Refund a transaction in the CCV SoftPOS Application

2.1 SDK example

public class MainActivity extends Activity {

    //The methodTransactionId comes from the response of the previous API request
    void startTransaction(String methodTransactionId) {
        SoftPosService softPosService = SoftPosService.Companion.getInstance(this.getApplicationContext());
        softPosService.startTransaction(this, methodTransactionId, this::handleTransactionResult);
    }

    private Unit handleTransactionResult(SoftPosTransactionResult result) {
        if(result instanceof TransactionSucceeded) {
            showAlertDialog("SoftPos Transaction", "Transaction succeeded");
        } else if (result instanceof TransactionFailed) {
            showAlertDialog("SoftPos Transaction", "Transaction failed with error");
        }

        return Unit.INSTANCE;
    }
}

class MainActivity : Activity() {

    //The methodTransactionId comes from the response of the previous API request
    fun startTransaction(methodTransactionId: String) {
        val softPosService = getInstance(this.getApplicationContext())
        softPosService.startTransaction(
            this,
            methodTransactionId
        ) { ::handleTransactionResult }
    }

    private fun handleTransactionResult(result: SoftPosTransactionResult) {
        if (result is TransactionSucceeded) {
            showAlertDialog("SoftPos Transaction", "Transaction succeeded")
        } else if (result is TransactionFailed) {
            showAlertDialog("SoftPos Transaction", "Transaction failed with error")
        }
    }
}

SoftPosTransactionResult is either a

• TransactionSucceeded in case of success
• TransactionFailed in case of failure

In case of TransactionFailed, the failures are grouped in 4 categories/subclasses

• TransactionFailedError: A device state or timeout caused the transaction to fail
• TransactionFailedCancelled: The transaction was cancelled (potentially by the user)
• TransactionFailedNotAuthorised: Authorisation failed because of card or host issues
• TransactionFailedInternalError: An unexpected error occurred

Possible values for reason and how to handle these is described here: Transaction errors

2.2 Deeplink example

2.2.1 Deeplink url

Deeplink url on development

ccvsoftpos-demo://transaction?methodTransactionId={methodTransactionId}&callback={callback}

ccvsoftpos-demo://transaction?methodTransactionId=myMethodTransactionId&callback=https%3A%2F%2Fccvposexample.eu%2Ftransaction-complete

Deeplink url on production

ccvsoftpos://transaction?methodTransactionId={methodTransactionId}&callback={callback}

ccvsoftpos://transaction?methodTransactionId=myMethodTransactionId&callback=https%3A%2F%2Fccvposexample.eu%2Ftransaction-complete

2.2.2 Deeplink callback

❗️The callback url needs to be URL encoded❗️

The callback should be an url scheme that will redirect to the webpage of the integrator. When the transaction completes the CCV SoftPOS app will redirect back to the callback url. Launching the callback url is a best effort from the CCV SoftPOS app. If the callback url is not url encoded or overal an invalid url, the CCV SoftPOS app will continue with the transaction but not launch the callback url on transaction completion.

In case of a successful transaction the callback will be followed by a status:
{callback}?status=SUCCEEDED

https://ccvposexample.eu/transaction-complete?status=SUCCEEDED

In case of a failed transaction the callback will be followed by a status, a failure and failureCode with an optional internalErrorCode and optional reason:
{callback}?status=FAILED&failure={FAILURE}&failureCode={failure_code}&internalErrorCode={internal_error_code}&reason={REASON}

https://ccvposexample.eu/transaction-complete?status=FAILED&failure=TRANSACTION_ERROR&failureCode=13000&internalErrorCode=31001&reason=NETWORK_ERROR

Possible values for failure(Code) and how to handle these is described here: Transaction errors

Invalid deeplink scheme

❗️When launching the “ccvsoftpos://” deeplink with a path other then (installation or transaction) the transaction will fail with an INVALID_URL_SCHEME (11010) failure, only if a callback url is provided. If no callback url is provided, the CCV SoftPOS app will just close❗️

3. Get the transaction result

In the example above you saw that you receive a SoftPosTransactionResult from the SDK once the refund has completed. This result will be mainly used for error handling and collecting info in case of an issue. For receiving the status of the transaction with transaction receipts you will need to get the transaction info from our Payment API.

API Request​

• End-point: /api/v1/transaction
• Method: GET​
• Authentication: API Key
• Request Headers
  • Content-Type: application/json​
• Query parameter
  • reference: the reference of the response of the refund API request

API Response

Response parameters

Example

{
  "status": "success",
  "reference": "SP123456789ABC123456ABC123.A",
  "merchantOrderReference": "Test1234",
  "amount": 0.01,
  "type": "refund",
  "currency": "eur",
  "language": "eng",
  "method": "softpos",
  "brand": "visa",
  "entryMode": "instore",
  "methodTransactionId": "SP123456789ABC123456ABC123.A",
  "created": 1761920495,
  "lastUpdate": 1761920500,
  "statusFinalDate": 1761920500,
  "details": {
    "terminalId": "123456",
    "cardCircuit": "VISA",
    "customerReceipt": "[\"Customer's receipt\",\" \",\"CCV\",\"ARNHEM\",\" \",\"Terminal: ****3456\",\"Merchant: ****3456\",\" \",\"Retrieval reference: 123abc123\",\" \",\"Transaction: bfa7293e-3d9b-f9b3-887e-d37089e1b4d8\",\" \",\"MASTERCARD(a0000000041010)\",\"Card: xxxxxxxxxxxxx1234\",\"Card Sequence Nr: 00\",\" \",\"REFUND\",\"Date: 31/10/2025 15:11\",\"Auth. code: 123456\",\"Merchant Ref.: Test1234\",\" \",\"Total: 0.01 EUR\",\" \",\"ACCEPTED\"]",
    "journalReceipt": "[\"Merchant's receipt\",\" \",\"CCV\",\"ARNHEM\",\" \",\"Terminal: CT123456\",\"Merchant: 123456\",\" \",\"Retrieval reference: 123abc123\",\" \",\"Transaction: bfa7293e-3d9b-f9b3-887e-d37089e1b4d8\",\" \",\"MASTERCARD(a0000000041010)\",\"Card: xxxxxxxxxxxxx1234\",\"Card Sequence Nr: 00\",\" \",\"REFUND\",\"Date: 31/10/2025 15:11\",\"Auth. code: 123456\",\"Merchant Ref.: Test1234\",\" \",\"Total: 0.01 EUR\",\" \",\"ACCEPTED\"]",
    "eJournal": "<E-Journal><ShopInfo><CardAcceptorName>CCV</CardAcceptorName><CardAcceptorLocation>ARNHEM</CardAcceptorLocation><CardAcceptorIdentifier>123456</CardAcceptorIdentifier><TerminalIdentifier>CT123456</TerminalIdentifier></ShopInfo><TransactionInfo><TransactionIdentifier>bfa7293e-3d9b-f9b3-887e-d37089e1b4d8</TransactionIdentifier><ServiceLabelName>REFUND</ServiceLabelName><DateAndTime>31/10/2025 15:11</DateAndTime><AuthorisationCode>123456</AuthorisationCode><MerchantReference>Test1234</MerchantReference><TotalAmount Currency=\"EUR\">0.01</TotalAmount><TransactionResultText>ACCEPTED</TransactionResultText></TransactionInfo><CardInfo><ApplicationIdentifier>DEBIT MASTERCARD</ApplicationIdentifier><CardNumber>xxxxxxxxxxxxx1234</CardNumber><CardSequenceNumber>00</CardSequenceNumber></CardInfo></E-Journal>"
    "receiptData": "{\"transactionId\":\"bfa7293e-3d9b-f9b3-887e-d37089e1b4d8\",\"retrievalReferenceNumber\":\"123abc123\",\"merchantOrderReference\":\"Test1234\",\"terminalId\":\"CT123456\",\"merchantId\":\"123456\",\"merchantName\":\"CCV\",\"merchantLocation\":\"ARNHEM\",\"merchantLanguage\":\"eng\",\"aid\":\"a0000000041010\",\"brand\":\"DEBIT MASTERCARD\",\"cardPreferredName\":null,\"maskedCardNumber\":\"xxxxxxxxxxxxx1234\",\"panEnd\":\"1234\",\"cardSequenceNumber\":\"00\",\"transactionType\":\"refund\",\"timeStampUtc\":\"2025-10-31T14:11:45.213Z\",\"requestDateTimeFormatted\":\"31/10/2025 15:11\",\"amount\":1,\"amountFormatted\":\"0.01\",\"currency\":\"EUR\",\"authorisationCode\":\"123456\",\"acquirerResponse\":\"APPROVED\",\"cardholderVerificationMethod\":\"NONE\",\"posEntryMode\":\"CONTACTLESS\",\"localTransactionDateTimeIso\":\"2025-10-31T15:11:36\",\"localTransactionDateTimeFormatted\":\"31/10/2025 15:11\"}",
  }
}