openapi: 3.0.1 info: title: CCV SoftPos API version: v1 servers: - url: https://vpos-test.jforce.be/vpos/api/v1 description: Integration Environment - url: https://api.psp.ccv.eu/api/v1 description: Production Environment paths: /softpos/terminal/{terminalId}/install: post: tags: - SOFTPOS summary: Start a terminal installation parameters: - $ref: '#/components/parameters/terminalId' responses: '200': description: Post terminal install success content: application/json: schema: $ref: '#/components/schemas/Terminal' examples: PostTerminalResponseSoftPOSInstallation: $ref: >- #/components/examples/PostTerminalResponseSoftPOSInstallation '400': description: Error Response content: application/json: schema: $ref: '#/components/schemas/Error' examples: ErrorResponseTerminalNotFound: $ref: '#/components/examples/ErrorResponseTerminalNotFound' ErrorResponseTerminalAlreadyInstalled: $ref: '#/components/examples/ErrorResponseTerminalAlreadyInstalled' '401': $ref: '#/components/responses/Unauthorized' /payment: post: tags: - PSP summary: Start payment parameters: [] requestBody: required: true description: payment success content: application/json: schema: $ref: '#/components/schemas/PaymentRequest' examples: PostPaymentRequestSuccess: $ref: '#/components/examples/PostPaymentRequestSuccess' responses: '200': description: Post payment success content: application/json: schema: $ref: '#/components/schemas/PaymentResponse' examples: PostPaymentResponseSuccess: $ref: '#/components/examples/PostPaymentResponseSuccess' '400': description: Error Response content: application/json: schema: $ref: '#/components/schemas/Error' examples: ErrorResponseTerminalNotFound: $ref: '#/components/examples/ErrorResponseTerminalNotFound' ErrorResponseTerminalNotInstalled: $ref: >- #/components/examples/ErrorResponsePaymentUninstalledTerminal '401': $ref: '#/components/responses/Unauthorized' /transaction: get: tags: - PSP summary: Get transaction parameters: - $ref: '#/components/parameters/transactionReference' responses: '200': description: Get transaction success content: application/json: schema: $ref: '#/components/schemas/Transaction' examples: GetTransactionResponse: $ref: '#/components/examples/GetTransactionResponse' components: parameters: terminalId: in: path name: terminalId schema: type: string required: true example: SP001 xMerchantReference: in: header name: x-Merchant-Reference schema: type: string required: false transactionReference: in: query name: reference schema: type: string example: SP123456789ABC123456ABC123.A responses: Unauthorized: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: ErrorResponseBadCredentials: $ref: '#/components/examples/ErrorResponseBadCredentials' schemas: Brand: enum: - visa - mastercard - maestro - bcmc - amex type: string description: The card brand chosen by the customer. Currency: enum: - eur - chf - gbp - nok - sek - dkk - cad - usd type: string description: An ISO 4217 three-letter code. Error: type: object properties: type: type: string description: Possible values are input_error, process_error, unexpected_error message: type: string description: >- A generic message. Contains helpful information regarding the cause of the error. This message should not be parsed. In case of input_error this field holds the validation message for the field mentioned in field field: type: string description: >- In case of type input_error the field that caused an error. Otherwise not present. If multiple field validations failed, field contains the first one. fields: type: array items: type: object properties: field: type: string message: type: string description: >- In case of type input_error an array of all failed field validations. For each field the error message is shown. See example below. reference: type: string description: >- A reference that you can provide to the helpdesk for investigation of the failing request failureCode: $ref: '#/components/schemas/FailureCode' description: An optional field that explains more about the cause of the failure. description: An Error is returned when an operation can't be executed like expected. FailureCode: type: string enum: - expired - processing_error - invalid_config - cancelled - unsufficient_balance - fraud_detected - rejected - unknown_reference - refund_limit - unsupported_currency - qr_failed - card_refused - insufficient_funds - vault_token_expired - amount_limit_exceeded - bad_credentials - authentication_failed - duplicate_request description: An error code indication what caused the failure. Language: enum: - eng - nld type: string description: The language of the customer. Method: enum: - softpos type: string description: The payment method that the customer chooses. MerchantOrderReference: type: string description: Custom reference PaymentRequest: required: - amount - currency - method - language - details type: object properties: transactionType: $ref: '#/components/schemas/TransactionType' amount: type: number description: The amount of the transaction. format: double example: 42.02 currency: $ref: '#/components/schemas/Currency' method: $ref: '#/components/schemas/Method' language: $ref: '#/components/schemas/Language' merchantOrderRefence: $ref: '#/components/schemas/MerchantOrderReference' webhookUrl: type: string description: >- The webhook URL invoked for transaction changes. This overrides the merchant webhook if one is present. We do not validate this url. details: $ref: '#/components/schemas/PaymentDetailsSoftPos' PaymentResponse: required: - amount - currency - method - language type: object properties: status: $ref: '#/components/schemas/TransactionStatus' type: $ref: '#/components/schemas/TransactionType' currency: $ref: '#/components/schemas/Currency' amount: type: number description: The amount of the transaction. format: double example: 42.02 method: $ref: '#/components/schemas/Method' language: $ref: '#/components/schemas/Language' merchantOrderRefence: $ref: '#/components/schemas/MerchantOrderReference' created: type: integer description: The local server datetime the payment was created, epoch timestamp. format: int64 example: 1508155139021 lastUpdate: type: integer description: The local server datetime the payment was updated, epoch timestamp. format: int64 example: 1508155139021 reference: type: string description: A unique reference for the payment transaction. example: SP180202161938854CB87E102.0 webhookUrl: type: string description: >- The webhook URL invoked for transaction changes. This overrides the merchant webhook if one is present. We do not validate this url. metadata: type: string description: >- An arbitrary string, maximum 255 characters, that can be used to track payments methodTransactionId: type: string description: >- A third party transaction ID which identifies the payment transaction in external systems. If empty no such id was available or no third party was employed. example: 665b139a-ff38-44ed-be78-4ff010cbd31b details: $ref: '#/components/schemas/PaymentDetailsSoftPos' additionalProperties: false description: Payment PaymentDetailsSoftPos: required: - terminalId type: object properties: terminalId: type: string description: The terminal id as assigned by CCV. example: SP001 additionalProperties: false description: An object listing method specific payment details. Terminal: required: - terminalId - installationStatus type: object properties: terminalId: type: string description: The terminal id as assigned by CCV. example: SP001 installationStatus: $ref: '#/components/schemas/TerminalInstallationStatus' example: installed description: The status of the intallation. installationPayload: type: string example: IfhGLwDjRrr4mgeFOVr6tkA= description: Installation Payload to use with the ActivityForResult Intent nullable: true additionalProperties: false description: Installation Response Details TerminalInstallationStatus: enum: - installed - not_installed type: string description: This field indicates the status of an installation. Transaction: required: - amount - currency - language - method - reference - status - type type: object properties: reference: type: string description: A unique reference for the payment transaction. example: SP180202161938854CB87E102.0 status: $ref: '#/components/schemas/TransactionStatus' example: success type: $ref: '#/components/schemas/TransactionType' currency: $ref: '#/components/schemas/Currency' amount: type: number description: The amount of the transaction. format: double example: 42.02 method: $ref: '#/components/schemas/Method' brand: $ref: '#/components/schemas/Brand' language: $ref: '#/components/schemas/Language' created: type: integer description: "Timestamp issued by PSP server when transaction was created. \r\nEpoch timestamp is number of milliseconds since January 1st, 1970 UTC." format: int64 example: 1508155139021 lastUpdate: type: integer description: "Timestamp issued by PSP server when transaction was updated. \r\nEpoch timestamp is number of milliseconds since January 1st, 1970 UTC." format: int64 example: 1508155139021 methodTransactionId: type: string description: >- A third party transaction ID which identifies the payment transaction in external systems. If empty no such id was available or no third party was employed. example: 665b139a-ff38-44ed-be78-4ff010cbd31b merchantOrderRefence: $ref: '#/components/schemas/MerchantOrderReference' failureCode: $ref: '#/components/schemas/FailureCode' description: An optional field that explains more about the cause of the failure. metadata: type: string description: >- An arbitrary string, maximum 255 characters, that can be used to track payments details: $ref: '#/components/schemas/TransactionDetailsSoftPos' additionalProperties: false description: Transaction Response TransactionStatus: enum: - pending - failed - manualintervention - success type: string description: This field indicates the status of a transaction. TransactionType: enum: - sale type: string description: >- Indication of TransactionType. Possible values: sale, credit, authorise or validate. Default sale. Note that authorise, credit and validate only apply to card payments. credit and validate are not supported for brand bcmc TransactionDetailsSoftPos: required: - terminalId - customerReceipt - journalReceipt - eJournal type: object properties: terminalId: type: string description: The terminal id as assigned by CCV. example: SP001 customerReceipt: type: string description: >- The receipt for the customer as an escaped JSON string. The content can be parsed to a JSON array example: >- [" 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: type: string description: >- The journal receipt for the merchant as an escaped JSON string. The content can be parsed to a JSON array example: >- [" 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: type: string description: >- The E-Journal for the merchant as an escaped JSON string. The content can be parsed to a XML example: "\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" additionalProperties: false description: An object listing method specific payment details. securitySchemes: CcvApiKey: type: http description: Use the PSP (Integrator) API key as Username, leave Password blank scheme: basic examples: PostTerminalResponseSoftPOSInstallation: summary: Install a softpos terminal value: terminalId: SP001 installationStatus: not_installed installationPayload: IfhGLwDjRrr4mgeFOVr6tkA= PostTerminalResponseSoftPOSInstallationCompleted: summary: Install completed for a softpos terminal value: terminalId: SP001 installationStatus: installed PatchTerminalInstallationRequestSuccess: summary: Update terminal installation value: installationStatus: installed PostTerminalResponseSoftPOSUninstallation: summary: Uninstall a softpos terminal value: terminalId: SP001 installationStatus: not_installed GetTerminalResponseSoftPosNotInstalled: summary: SoftPos terminal - not installed value: terminalId: SP001 installationStatus: not_installed GetTerminalResponseSoftPosInstallationSuccess: summary: SoftPos terminal - installed value: terminalId: SP001 installationStatus: installed PostPaymentRequestSuccess: summary: SoftPos payment value: transactionType: sale amount: 0.01 currency: eur method: softpos language: eng merchantOrderReference : Test1234 details: terminalId: 123456 PostPaymentResponseSuccess: summary: SoftPos payment value: status: pending type: sale amount: 0.01 currency: eur method: softpos language: eng reference: SP123456789ABC123456ABC123.A created: 1761919895083 lastUpdate: 1761919895087 methodTransactionId: SP123456789ABC123456ABC123.A merchantOrderReference: Test1234 details: terminalId: 123456 GetTransactionResponse: summary: SoftPos Transaction value: status: success type: sale currency: eur amount: 5 method: softpos brand: mastercard entrymode: ecom language: eng reference: SP123456789ABC123456ABC123.A created: 1761919895083 lastUpdate: 1761919905347 statusFinalDate: 1761919905347 methodTransactionId: SP123456789ABC123456ABC123.A merchantOrderReference: Test1234 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: "CCVARNHEM123456CT123456bfa7293e-3d9b-f9b3-887e-d37089e1b4d8PAYMENT31/10/2025 15:11123456Test12340.01ACCEPTEDDEBIT MASTERCARDxxxxxxxxxxxxx123400" 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\"}" ErrorResponseBadCredentials: summary: Bad credentails value: type: process_error message: The request could not be processed reference: 2e55d91c failureCode: bad_credentials ErrorResponseTerminalNotFound: summary: Terminal not found value: type: process_error message: >- No terminal - TMS id combination found for terminalId SP000002 of Merchant with vid 54 reference: 529a94af failureCode: invalid_config ErrorResponseTerminalAlreadyInstalled: summary: Terminal already installed value: type: process_error message: TERMINAL_ALREADY_INSTALLED reference: c3868a4r failureCode: processing_error ErrorResponseTerminalNotInstalled: summary: Terminal not installed value: type: process_error message: terminal_not_installed reference: c3868a4r failureCode: processing_error ErrorResponsePaymentUninstalledTerminal: summary: Terminal not installed value: status: failed type: sale amount: 5 currency: eur method: softpos language: eng reference: SPL220621151342826CB87E2F6.0 created: 1655817222828 lastUpdate: 1655817222828 failureCode: processing_error details: terminalId: SP001 security: - CcvApiKey: [] tags: - name: SOFTPOS description: SOFTPOS - name: PSP description: CCV Payment API