In-person Payments / SoftPOS / Basic Operations / Make A Payment

Make a payment

Introduction

This guide will walk you through the process to do a payment with CCV SoftPOS.

Transaction session

When making a payment the CCV SoftPOS app will need to start a transaction session that will be used for making a payment. Creating this transaction session takes some time thus increasing the total time it takes to make a payment. Optionally you can start this transaction session yourself before making a payment. This can be done in the background and this will make for a faster transaction startup.

For example you can start this transaction session in the background when the transaction amount is being entered by the user. Once the user starts the transaction the session will already be created and the payment will go smoother.

Start a transaction session (Java)

    SoftPosService softPosService = SoftPosService.getInstance(this.applicationContext);
    //This method will return immediately and will continue in the background asynchronously.
    softPosService.initTransactionSession();
    

1. Make a payment request

CCV has a single Payment API that support multiple payment solutions.
The following request starts a SoftPOS payment.

API Request​

• End-point: /api/v1/payment
• 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"
  }
}

API Response

Response parameters

Example

{
  "status": "pending",
  "reference": "SP123456789ABC123456ABC123.A",
  "method": "softpos",
  "type": "sale",
  "language": "eng",
  "currency": "eur",
  "lastUpdate": 1761919895087,
  "created": 1761919895083,
  "methodTransactionId": "SP123456789ABC123456ABC123.A",
  "amount": 0.01,
  "merchantOrderReference": "Test1234",
  "returnUrl": "https://onlinepayments.ccv.eu/payredirect/return?reference=SP123456789ABC123456ABC123.A",
  "details": {
    "terminalId": "123456"
  }
}

2. Start the transaction via the SDK

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

2.2.3 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 payment 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 payment API request

API Response

Response parameters

Example

{
  "reference": "SP123456789ABC123456ABC123.A",
  "merchantOrderReference": "Test1234",
  "amount": 0.01,
  "type": "sale",
  "status": "success",
  "currency": "eur",
  "language": "eng",
  "method": "softpos",
  "brand": "mastercard",
  "entryMode": "ecom",
  "returnUrl": "https://onlinepayments.ccv.eu/payredirect/return?reference=SP123456789ABC123456ABC123.A",
  "methodTransactionId": "SP123456789ABC123456ABC123.A",
  "created": 1761919895083,
  "lastUpdate": 1761919905347,
  "statusFinalDate": 1761919905347,
  "details": {
    "terminalId": "123456",
    "cardCircuit": "MASTERCARD",
    "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\",\" \",\"PAYMENT\",\"Date: 31/10/2025 15:11\",\"Auth. code: 123456\",\"Merchant Ref.: Test1234\",\" \",\"Total: 0.01 EUR\",\"Contactless payment\",\"Verified by consumer device\",\" \",\"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\",\" \",\"PAYMENT\",\"Date: 31/10/2025 15:11\",\"Auth. code: 123456\",\"Merchant Ref.: Test1234\",\" \",\"Total: 0.01 EUR\",\"Contactless payment\",\"Verified by consumer device\",\" \",\"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>PAYMENT</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\":\"purchase\",\"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\"}",
  }
}

Follow-up manuals

• Handling receipts