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​

API Request

Response parameters

Example

{
  "type": "sale",
  "amount": 5,
  "currency": "eur",
  "method": "softpos",
  "language": "eng",
  "details": {
    "terminalId": "SP001"
  }
}

API Response

Response parameters

Example

{
  "status": "pending",
  "type": "sale",
  "amount": 5,
  "currency": "eur",
  "method": "softpos",
  "language": "eng",
  "reference": "TL220621151342826CB87E2F6.0",
  "created": 1655817222828,
  "lastUpdate": 1655817222828,
  "methodTransactionId": "665b139a-ff38-44ed-be78-4ff010cbd31b",
  "details": {
    "terminalId": "SP001"
  }
}

2. Start the transaction via the SDK

2.1 SDK example

Start the transaction (Java)

    SoftPosService softPosService = SoftPosService.getInstance(this.applicationContext);
    //The methodTransactionId comes from the response of the previous API request
    softPosService.startTransaction(activity, 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: " + ((TransactionFailed) result).getError());
        }

        return Unit.INSTANCE;
    }

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 a 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=NETWORK_ERROR&internalErrorCode=31001&reason=NETWORK_CONNECTION_ERROR
  

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

  {
    "type":"sale",
    "amount":5.00,
    "currency":"eur",
    "method":"softpos",
    "brand":"maestro",
    "language":"nld",
    "reference":"TL220621152314122CB87E2F4.0",
    "lastUpdate":1655817804294,
    "created":1655817794124,
    "status":"success",
    "details":{
        "terminalId":"SP001",
        "customerReceipt":"[\" Kopie Kaarthouder\",\" \",\"********* PAS OP: TEST SYSTEEM *********\",\" \",\" \",\"Terminal: 20000002  Merchant: 1234      \",\"Periode: 2172       Transactie: 00003324\",\"Contactloze betaling\",\" (A0000000043060)\",\"Kaart: 67340xxxxxxxxxxxxxx\",\"Kaartnr: 01         Exp. Datum: 31/03/23\",\" \",\"BETALING\",\"21/06/2022 15:23    Auth. code:   n0SG25\",\" \",\"Totaal:     5,00 EUR\",\" \",\"      AKKOORD\"]",
        "journalReceipt":"[\"                JOURNAAL\",\" \",\"********* PAS OP: TEST SYSTEEM *********\",\" \",\" \",\"Terminal: 20000002  Merchant: 1234      \",\"Periode: 2172       Transactie: 00003324\",\" (A0000000043060)\",\"Kaart: 67340xxxxxxxxxxxxxx\",\"Kaartnr: 01         Exp. Datum: 31/03/23\",\" \",\"BETALING\",\"21/06/2022 15:23    Auth. code:   n0SG25\",\" \",\"Totaal:     5,00 EUR\",\"      AKKOORD\",\"ACQUIRER ID:    00000002\",\"TRANSACTION TREATMENT RES. 0000\",\"  ================\"]",
        "eJournal":"\r\n  \r\n    \r\n    20000002\r\n    1234\r\n  \r\n  \r\n    2172\r\n    00003324\r\n    BETALING (Contactloze betaling)\r\n    2022-06-21T15:23\r\n    n0SG25\r\n    5,00\r\n    5,00\r\n    AKKOORD\r\n    00000002\r\n    0000\r\n  \r\n  \r\n    Maestro\r\n    \r\n    \r\n    67340xxxxxxxxxxxxxx\r\n    01\r\n    31/03/23\r\n    \r\n    \r\n  \r\n"
    }
  }

Follow-up manuals

• Handling receipts