Developer
  • Getting started keyboard_arrow_down

    Discover

    • arrow_forward
      EV Charging

      Discover our unattended POS solution for the ev market

    Our solutions

    • arrow_forward
      CCV Terminal

      Integrate with a CCV Terminal

    • arrow_forward
      SoftPOS

      Turn your own device into a payment terminal

    • arrow_forward
      CCV Online Payments

      Accepting online payments in your platform without technical knowledge

    • arrow_forward

    • arrow_forward

    Connect to the CCV Platform

    Integrate our products into your software. Let's make payment happen together!

    Look at all the possibilities
  • Documentation
menu
    • expand_more Payment API
      • expand_more General
        • Communication
        • Environments
        • Authentication
        • Idempotency
        • Transaction Types
        • Webhooks
        • Notifications
        • Error Handling
        • Security & Privacy
        • Return URL
      • expand_more Online Payments
        • expand_more Quick Start
          • Initial Setup
          • Create Payment
        • expand_more Basic Operations
          • Create A Payment
          • Refund A Payment
          • Authorise & Capture Payments
          • Query The Payment Status
        • expand_more Payment Features
          • expand_more 3D-Secure 2
            • SCA And 3D-Secure 2
            • Compliance Guide
            • Out Of Scope Transactions
            • Exemptions
          • Payment Links
          • Merchant Initiated Payments
          • Embedded Card Payments
          • Mandates
          • Customers & Loyalty
          • Partial Payment
        • expand_more Payment Methods
          • American Express
          • Apple Pay
          • Google Pay
          • expand_more Bancontact
            • Bancontact Walled Initiated Payments (WIP)
            • Bancontact Deferred Sales
          • Bancontact Mobile
          • Banktransfer
          • IDEAL
          • Klarna
          • Landingpage
          • Maestro
          • Mastercard
          • Payconiq
          • Paypal
          • Visa
        • expand_more Payouts
          • Split Payout
          • Test Payout
        • expand_more Developer Resources
          • Currencies
          • Languages
          • Payment Testing
          • Test Cards
      • expand_more In-person Payments
        • expand_more SoftPOS
          • expand_more General
            • Getting Started
            • Device Requirements
            • SoftPOS TerminalIds
            • SoftPOS Errors
            • Currencies
            • Languages
            • Network And Connectivity
            • Release Notes
          • expand_more Basic Operations
            • Install A Terminal
            • Make A Payment
            • Handling Receipts
          • expand_more API Reference
            • SoftPOS - API Reference
    • expand_more Board Your Merchants At CCV
      • expand_more General
        • Getting Started
        • Authentication
      • expand_more Boarding API
        • StartOrder
        • AddSalesPackage
        • AddProductPSPStandalone
        • AddProductPSPSubmerchant
        • AddTerminalPackage
        • SetShoppingCartPricingDetails
        • SubmitOrder
        • Boarding
      • API Reference
    • expand_more Android Rest Beta API
      • expand_more General
        • Getting Started
        • Brands
        • Supported Languages
      • expand_more Basic Operations
        • Make A Payment
        • Cancel A Payment
        • Handling Receipts
        • Show Display Messages
        • Recover A Payment
      • expand_more Payment Features
        • Authorise & Capture
        • Capture
      • expand_more Terminal Features
        • Transaction Overview
        • Brands
        • Period Closing
        • Terminal - Status
      • expand_more Tokenization
        • Tokenization - Get A Card Token
        • Read A Mifare Card
        • Custom Text On Terminal
      • expand_more API Reference
        • API Reference
    • expand_less Android SDK
      • expand_more General
        • Getting Started
        • Demo Application - Android SDK
        • Result States
        • Language Codes
        • Error Handling
        • Logging
        • EP2
        • Download SDK
        • Release Notes
      • expand_less Basic Operations
        • Make A Payment
        • Stop Ongoing Payment
        • Recover A Payment - Android SDK
      • expand_more Payment Features
        • Account Selection - Android SDK
        • Additional Receipt Text - Android SDK
        • Allow Or Deny Card Brands - Android SDK
        • Authorisation By Voice - Android SDK
        • Authorise - Android SDK
        • Capture - Android SDK
        • Card Detection - Android SDK
        • Card Detection Deprecated - Android SDK
        • Card Token - Android SDK
        • Card Validation - Android SDK
        • Customer Display - Android SDK
        • E-Receipt - Android SDK
        • Manual Card Information Entry - Android SDK
        • Payment Reversal - Android SDK
        • Refund - Android SDK
        • Request Transaction Information - Android SDK
        • Reservation - Android SDK
        • German Eichrecht - Android SDK
      • expand_more SDK Guides
        • Activate Terminal - Android SDK
        • Card Circuits - Android SDK
        • Card Reader Status - Android SDK
        • Card Reader Status - Android SDK
        • Check Password - Android SDK
        • Factory Reset - Android SDK
        • Get Config - Android SDK
        • Get Status - Android SDK
        • Mobile Phone Prepaid - Android SDK
        • Online Agent - Android SDK
        • Partial Period Closing - Android SDK
        • Period Closing - Android SDK
        • Possible Transaction Types - Android SDK
        • Retrieve Last Ticket - Android SDK
        • Retrieve Open Pre Authorisations - Android SDK
        • Startup - Android SDK
        • Taxfree - Android SDK
        • Terminal Administration - Android SDK
        • Terminal Discovery - Android SDK
        • Ticket Reprint Period Closing - Android SDK
        • Transaction Overview - Android SDK
        • Check Password - Android SDK
      • expand_more Hardware Access
        • Getting Started
        • NFC - Android SDK
        • Printing - Android SDK
        • QR And Barcode Scanner - Android SDK
      • expand_more API Reference
        • API Documentation
    • Android App Requirements
    • expand_more Certification
      • Introduction
      • expand_more Attended Certification Tests
        • expand_more Aborting
          • F1A - Regular Abort By Merchant
          • F1B - Failing Abort By Merchant
          • F1D - Hammering Abort By Merchant
        • expand_more Allowed Amounts
          • S1A - Transaction With Amount Of EUR 0,00
          • S1B - Transaction With Negative Amount
          • S1C - Transaction With Highest Possible Amount
          • S1D - Over-Amount Transaction
        • expand_more Connection Lost
          • Q1B - Manual Transaction Recovery
          • Q1C - Ethernet Connection With ITS Fails
          • Q1F - Device Unavailable
          • Q1G - Terminal Not Responding
          • T1A - Automatic Transaction Recovery
        • expand_more E Journal
          • M1A - Store E-Journal
          • M2A - ECR/POS Print Journal Receipts
          • M3A - ECR/POS Storing Journal Receipts
        • expand_more Reprint Ticket
          • L1A - Reprint Ticket
          • L1B - Reprint Ticket Declined Transaction
          • L2A - Reprint Ticket No Printer Available
          • L2B - Reprint Ticket Declined Transaction No Printer Available
        • expand_more Tickets
          • U1A - Request For Identification
          • U1B - Request For Signature
          • U1C - Request For Signature And Identification
          • U1D - Failing Transaction No Receipt
          • U1E - Split Payment
        • expand_more Time Out
          • R1A - Time Out On Presenting A Card
          • R1B - Time Out During Pin Entry
        • expand_more Transactions
          • C1A - Happy Flow
          • C1B - Happy Flow Contactless
          • C1D - Happy Flow Magnetic Stripe
          • C1E - Declined Transaction By Host
          • C1E - Transaction Aborted By Cardholder
          • C1F - Absence Of Thousand Separator
          • C1G - Cashier Display Messages
        • expand_more Validation
          • H1A - Too Many Fingers
          • H1B - Not Removing Card
          • H2A - Power Loss Or Closing Of ECR/POS During Transaction
      • expand_more Unattended Certification Tests
        • expand_more User Guidance
          • C1 - Successful Payment
          • C2 - Next Cardholder
          • C3 - Abort On PIN Entry
          • C4 - Time Out During PIN Entry
          • C5 - No Amount Entered
          • C6 - Language Selection
          • C7 - Amount To Authorise
          • C8 - Available Funds
        • expand_more Device Selection
          • D1 - Device Selection
          • D2 - Invalid Device
          • D3 - Charger Selection Abort
          • D4 - No Charger Selected
          • D5 - Authorisation With No Free Devices
        • expand_more Product Delivery
          • E1 - Product Selection
          • E2 - Enabled Products
          • E3 - Invalid Product Entered
          • E4 - Product Selection Aborted
          • E5 - No Product Selected
          • E6 - Max Delivery Time
          • E7 - Abort Session
          • E7 - Abort By POS
          • E9 - Not Started Charging In Time
          • E10 - Take More Fuel Than AVF
          • E10 - Multiple Sessions Mixed
          • E12 - Postpone Card Financial Advice On New Cardholder Card
          • E13 - Abort Session On Card Reinsert
        • expand_more Receipts
          • F1 - Cardholder Retrieve Receipt Info
          • F2 - Cardholder Receipt Retrieval
          • F3 - Reprint Ticket
          • F4 - F8 - Ticket Printing And Content
          • F9 - TrackingToken Deleted
          • F10 - Printer Paper Low
          • F11 - CardPayment Erased From Storage
          • F12 - E-Receipt Received By Cardholder
          • F13 - E-Receipt Failure
        • expand_more Transaction Limit Handeling Maestro
          • G1 - Maestro CardPayment 1 Euro
          • G2 - Maestro CardPayment 30 Euro
          • G3 - Maestro CardPayment 60 Euro
          • G4 - Maestro CardPayment 500 Euro
        • expand_more Transaction Limit Handeling Mastercard
          • H1 - Mastercard CardPayment 1 Euro
          • H2 - Mastercard CardPayment 30 Euro
          • H3 - Mastercard CardPayment 60 Euro
          • H4 - Mastercard CardPayment 500 Euro
        • expand_more Mifare Handling
          • I1 - Happy Flow Mifare
          • I2 - Unknown Mifare Card
          • I3 - No Mifare Card Presented
          • I4 - Mastercard Presented
        • expand_more Card Circuits
          • L1 - Available Card Circuits
        • expand_more Reconciliation
          • M1 - Reconciliation As Function
          • M2 - Reconciliation By New Shiftnumber
          • M3 - POS Auto Triggers Reconciliation With Closure
        • expand_more Journal
          • N1 - Journal Accessible By Authorized Employees
          • N2 - Journal Cannot Be Altered
        • expand_more Exception Flows
          • O1 - Unknown Card Session
          • O2 - Maximum Time Out
          • O3 - Device Unavailable
          • O4 - Time Out Card-Type Fallback
          • O5 - Time Out On Presenting Card
          • O6 - App Stability
          • O7 - Automatic Startup
          • O8 - Sleep Mode Not Supported
          • O8 - Sleep Mode Supported
        • expand_more Recovery
          • X1 - Recovery After Communication Failure
          • X2 - Recovery After CCV Component Update
          • X3 - Recovery After 24 Hour Reboot
          • X4 - Recovery After CCV-Fusion Client Restart
          • Y1 - Recovery After Power Failure With No Battery Backup
          • Y2 - Recovery After Power Failure With Battery Backup
      • expand_more SoftPOS Certification Tests
        • expand_more Success Scenarios
          • Installation Success - SoftPOS Certification Test
          • Payment Success - SoftPOS Certification Test
        • expand_more Failed Scenarios
          • Installation Failed - CCV SoftPOS App Not Installed - SoftPOS Certification Test
          • Payment Failed - Declined - SoftPOS Certification Test
          • Payment Failed - CCV SoftPOS App Is Closed During Payment - SoftPOS Certification Test
          • Payment Failed -CCV SoftPOS App Is Killed During Payment - SoftPOS Certification Test
          • Payment Failed - SoftPOS App Not Installed Anymore - SoftPOS Certification Test
        • expand_more Other Scenarios
          • Other Scenario - Data Cleared Of The CCV SoftPOS App - SoftPOS Certification Test
    • expand_more Development Kits
      • SoftPOS Dev Kit
      • IM30 Dev Kit
    • Glossary
Return to solutions

  • General expand_more
    • Getting started
    • Demo application
    • Result states
    • Language codes
    • Error handling
    • Logging
    • Ep2
    • Download sdk
    • Release notes
  • Basic operations expand_more
    • Make a payment
    • Stop ongoing payment
    • Recover a payment
  • Payment features expand_more
    • Account selection
    • Additional receipt text
    • Allow or deny card brands
    • Authorisation by voice
    • Authorise
    • Capture
    • Card detection
    • Card detection deprecated
    • Card token
    • Card validation
    • Customer display
    • E receipt
    • Manual card information entry
    • Payment reversal
    • Refund
    • Request transaction information
    • Reservation
    • German eichrecht
  • Terminal actions expand_more
    • Activate terminal
    • Card circuits
    • Card read
    • Card reader status
    • Check password
    • Factory reset
    • Get config
    • Get status
    • Mobile phone prepaid
    • Online agent
    • Partial period closing
    • Period closing
    • Possible transaction types
    • Reprint last ticket
    • Retrieve open pre authorisations
    • Startup
    • Taxfree
    • Terminal administration
    • Terminal discovery
    • Ticket reprint period closing
    • Transaction overview
    • Check password
  • Hardware access expand_more
    • Getting started
    • Nfc
    • Internal printer
    • Qr and barcode scanner
  • API reference expand_more
    • API reference

What's on this page

    • Intro
    • ExternalTerminal
    • Payment
    • Delegate
    • Create API instance
    • Initiate your payment
    • PaymentResult OPI-DE terminals
    • User interaction callback methods
      • Identification and signature (Attended environment only)
      • Deliverybox
Basic Operations / Make A Payment

Intro

This guide will walk you through the process to do a payment using the opiPaymentApi The method we will use for this is:


    void payment(ExternalTerminal terminal,Payment payment,PaymentDelegate paymentDelegate)

next up we will construct our request objects.

ExternalTerminal

The ExternalTerminal object contains everything regarding the terminal setup. The creation can be done manually as the code snippet beneath shows or using the paymentTerminalDiscoveryService which we recommend as this does this construction for you. \ When you retrieve your terminal you will be informed which protocol your terminal uses. FYI, OPI-NL & OPI-DE are terminal communication-protocols which your terminal uses


    ExternalTerminal externalTerminal = ExternalTerminal.builder()
            .ipAddress(ipAddress) // can be found using getting-started guide
            .port(terminalPort) // 4100 for OPI-NL & 20002 for OPI-DE
            .compatibilityPort(compatibilityPort) // 4102 for OPI-NL & 20007 for OPI-DE
            .socketMode(socketMode) // Dual-Socket for OPI-NL & Single-Socket for OPI-DE & OPI-NL
            .terminalType(terminalType) // EnumType which contains terminal protocol combined attended/unattended type
            .languageCode(LanguageCode.EN) // determines the language of the CashierDisplay messages (optional)
            .printerStatus(PrinterStatusType) // EnumType which contains the printer status: Available, Unavailable, PaperEmpty and PaperLow. Only for OPI-NL
            .shiftNumber(shiftNumber) // ShiftNumber is used to create a total during a specific shift.
            .merchantEmailAddress(merchantEmailAddress) // Passes the merchant email address to the terminal so the merchant receipt will be sent to it (OPI-NL via E-ReceiptServer, OPI-DE via OAM server)
            .customerEmailAddress(customerEmailAddress) // Passes the customer email address to the terminal so the customer receipt will be sent to it (OPI-NL via E-ReceiptServer, OPI-DE via OAM server)
            .supportMifareCards(true/false) // Indicates if you also want to read MiFare cards when performing a Sale, PreAuthorisation or CardDetection on an unattended OPI-NL terminal
            .receiptMode(ReceiptMode) // Pass to the terminal how you want to receive your receipts: Default (During the payment), Off (No receipts are send back), ReceiptsInResponse (Terminal send receipts with the end result). This is for OPI-DE terminals only 
            .build();

Payment

The Payment object contains everything about the payment you want to be executed on the terminal.


    Money money = new Money(new BigDecimal("0.05"), Currency.getInstance("EUR"));

    Payment payment = Payment
            .builder()
            .type(Payment.Type.SALE)
            .amount(money)
            .build();

Delegate

This is the callback mechanism which we use to pass the responses asynchronously to the integrator.


    PaymentDelegate paymentDelegate = new PaymentDelegate() {
        @Override
        public void onPaymentSuccess(PaymentResult result) {
            // The payment is completed successful!
            // The paymentResult contains all information about the transaction            
        }
    
        @Override
        public void onError(Error error) {
            // The payment failed
            // The Error object contains information about what went wrong
        }

        @Override
        public void printMerchantReceiptAndSignature(PaymentReceipt receipt) {
            // Code to handle the MerchantReceipt
        }

        @Override   
        public void printCustomerReceiptAndSignature(PaymentReceipt receipt) {
            //Code to handle CustomerReceipt
        }

        @Override
        public void printDccOffer(PaymentReceipt receipt) {
            //Code to handle DCC (Dynamic Currency Conversion) receipt
        }

        @Override
        public void printJournalReceipt(PaymentReceipt receipt) {
            // Code to handle JournalReceipt
            // This is OPI-NL terminal-protocol specific
        }

        @Override
        public void storeEJournal(String journal) {
            // Code to store the E-Journal
            // This is OPI-NL terminal-protocol specific
        }

        @Override
        public void cardUID(String cardUID) {
            // This is OPI-NL Unattended terminal specific
        }
    };

For more information about all possible errorcodes please click here

Create API instance

Now that all our request objects are ready, we can create an instance of the api we want to use. For this guide this will be the paymentApi

    PaymentApi paymentService = new eu.ccvlab.mapi.api.PaymentService();

Initiate your payment

Last but not least, we will execute the specific method payment method which will cause our payment to happen.

    paymentService.payment(externalTerminal, payment, paymentDelegate);

PaymentResult OPI-DE terminals

PaymentResultDE has been removed, please use the PaymentResult object instead.

User interaction callback methods

During a payment it could occur that an extra interaction with the integrator is required.
The possible user interactions are:

  • identification and signature (When identification or signature of the cardholder is required)
  • deliverybox (to indicate if the goods are delivered before completing the transaction)

Identification and signature (Attended environment only)

When an identification and/or signature is needed from the cardholder this will indicated with the following methods on terminals with communication-protocl:
OPI-NL:

  • askMerchantSignature(Callback callback)
  • askCustomerSignature(Callback callback)
  • askCustomerIdentification(Callback callback)

OPI-DE:

  • askCustomerSignature(SignatureAsked signatureAsked)
  • drawCustomerSignature(CustomerSignatureCallback callback)

When an identification and/or signature is needed from the cardholder, the POS needs to create a dialog containing the corresponding message.
Although it is mandatory to show this text at least six seconds to the cashier, it is advised to keep this box available on the screen until the cashier presses/clicks it away.

Example snippet for ask customer signature on an OPI-NL configured terminal:

    PaymentDelegate paymentDelegate = new PaymentDelegate() {
        @Override
        public void askCustomerSignature(Callback callback) {
            //Show dialog with corresponding message
            callback.proceed();
        }
    };

Corresponding example for OPI-DE configured terminal:

    PaymentDelegate paymentDelegate = new PaymentDelegate() {
        @Override
        public void askCustomerSignature(SignatureAsked signatureAsked) {
            //Show dialog with corresponding message
            signatureAsked.signatureAsked();
        }
    };

Deliverybox

The DeliveryBox functionality can be used to indicate if the goods are delivered before completing the transaction. If the goods cannot be dispensed the transaction will be aborted.

During the payment flow, the integrator-app needs to deliver the goods and services. The following PaymentDelegate method is called to perform the delivery.

PaymentDelegate delegate = new PaymentDelegate() {
    ...
    @Override
    public void onDeliverGoodsOrServices(DeliveryBoxCallback deliveryBoxCallback) {
        // Deliver your goods
        // Call the deliveryBoxCallback.proceed(boolean) once you know that your delivery was successful or noet.
        deliveryBoxCallback.proceed(true);
    }
    ...
};
paymentService.payment(terminal, payment, delegate);          
...

Go to

Home
Documentation




Cookies Privacy Statement