menu

Payment API

What's on this page

API Reference / Payment

Payment API

The payment resource is responsible for initiating new payments and refunds.

Typical payment flow

The general flow will be:

  1. You create a new payment
  2. Redirect the customer to us
  3. Dependent on the selected payment method, we guide the customer throughout the payment process
  4. When the payment is done, we redirect the customer back to your shop
  5. You read the payment to verify the status
  6. Occasionally, you manually approve the transaction in case of suspicious activity

Status Verification

We do not expose the status of the payment or any of its details to the customer. It is up to you to verify the status of the payment and act accordingly. Webhooks are provided to give you feedback, but this principle remains.

Alternatively you can register for Notifications which will replace the webhook configuration and/or request webhook if present. Like webhooks the content of each notification is purely informatively and important events like status changes should be verified with a status request.

Deferred sales

A deferred sale is a payment that is suitable for businesses that need to authorise an amount from the cardholder before the services or goods are delivered. Once the cardholder has received their services or goods, the merchant can than complete the transaction with an amount less than or equal to the reserved amount.

Deferred sales are supported for the following payment methods:

  1. The terminal method
  2. The card and applepay method for card brand Bancontact (bcmc), with several limitations set by Bancontact:
    1. Only merchants in category Automated Fuel Dispensers (MCC 5542) are allowed to use this service
    2. The maximum amount of an authorisation is set to 125 EUR
  3. googlepay

To use deferred sales with our API, you need to implement the following functionality:

  1. Authorise the amount with a payment of type authorise
  2. Complete the transaction with a capture of the final amount

In case the money should be released back to the cardholder, a reversal can be used.

Payment object

Name Description
type Fixed value: sale, credit, authorise or validate
amount The amount of the transaction
currency An ISO 4217 three-letter code. Possible values: Currencies
token If a token was requested and if the payment concerns cards, a max 18 long string will be returned. Else null
tokenMaskedInput If a token was created, the input (PAN or IBAN) will be returned, masked.
status Possible values: Transaction Status
merchantOrderReference A reference, maximum 255 characters, of the order associated with this payment
description A description to show the customer
language The language of the customer. Possible values: Languages
method The payment method that the customer chooses. Possible values: Supported Methods
brand This is only filled in for payments of method card and applepay and softpos and is the brand of the used card. Possible values: Supported Brands
metadata An arbitrary string, maximum 255 characters, that can be used to track payments
payUrl To complete the payment the customer should be redirected to this unique URL.
cardDataUrl To provide the card data for the payment the customer can submit the data to this URL
returnUrl After the payment is completed (successfully or otherwise) the customer is redirected to this URL
cancelUrl This url can be used to cancel the payment. Only included when applicable
reference A unique reference for the payment transaction
originalReference The unique original payment reference. For example, if the current transaction is a Refund, the originalReference contains the reference of the payment that is being refunded. Only present for transactions of type: Refund, Capture or Reversal.
methodTransactionId 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
created The local server datetime the payment was created, epoch timestamp
lastUpdate The local server datetime the payment was updated, epoch timestamp
statusFinalDate The local server datetime the payment reached a final status, epoch timestamp
entryMode The entryMode for the payment resulting from the Api Key used. Possible values: ecom or instore
failureCode An error code indication what caused the failure. Possible values: Failure Codes
cancelledBy Indicates who initiated the cancel. Possible values: customer and merchant
billingAddress The billing street address
billingCity The billing city of the customer
billingState The billing region/state of the customer , an ISO 3166-2 country subdivision code
billingPostalCode The billing postal (zip) code of the customer
billingCountry The billing country of the customer , an ISO 3166 alpha-2 code
billingEmail The billing email of the customer
billingPhoneNumber The billing phone number of the customer
billingPhoneCountry The billing phone number country code of the customer, an ITU-T E.164 country code
billingFirstName The billing first name of the customer
billingLastName The billing last name of the customer
billingHouseNumber The billing house number of the customer
billingHouseExtension The billing house extension of the customer
shippingAddress The shipping street address
shippingCity The shipping address city
shippingState The shipping address region/state of the customer , an ISO-3166 2 country subdivision code
shippingPostalCode The shipping address postal (zip) code
shippingCountry The shipping address country of the customer , an ISO 3166 alpha-2 code
shippingEmail The shipping email of the customer
shippingPhoneNumber The shipping phone number of the customer
shippingPhoneCountry The shipping phone number country code of the customer, an ITU-T E.164 country code
shippingFirstName The shipping first name of the customer
shippingLastName The shipping last name of the customer
shippingHouseNumber The shipping house number of the customer
shippingHouseExtension The shipping house extension of the customer
childReferenceId Contains the referenceId of the resulting child transaction. Applies to landing page and vault payments
manualApprovalRequired A boolean value that indicates whether this transaction is awaiting manual approval
note A text message attached to this transaction
signoff The person who performed the manual approval or rejection
paidout A boolean value that indicates if this transaction has been paid out. Possible values: yes or no. Only available for Collecting Payments
paidoutDate The date on which the payment to the merchant was done. Only available for Collecting Payments
expectedPayoutTimestamp The date on which the payment to the merchant will be done. Only available for Collecting Payments
unstructuredReference The unstructured reference used when performing the payout to the merchant or to the customer in case of refunds. Only available for Collecting Payments
paidoutReference The reference used when performing the payout to the merchant. This can be used to look up transactions related to that payout. Only available for Collecting Payments
details An optional object listing method specific payment details. Possible types: Payment Details
consumer An object with consumer details obtained during the checkout process. See Consumer for more info.
userAuthenticationMethods List of authentication methods performed by the cardholder in case Vault Access Token is used. Required for BCMC WIP. Possible values: User Authentication Method
sequenceType Field indicating the sequence type of the transaction in case Vault Access Token is used. Required for BCMC WIP. Possible values: Sequence Type
scaReady Boolean value set by the payment initiator to indicate that all the required data for SCA is provided for this payment.
payoutInstructions Optional list of Payout Instruction set by the payment initiator to indicate how the payout should be split. See Split Payout for more info.
relatedTransactions Optional list of related transactions. E.g. Indicates possible refunds on sales, captures / reversals on authorisations.
possibleActions Optional list of possible actions. E.g. Indicates if a refund is still possible on the transaction
mandateId The id of the mandate used in conjunction with this transaction.

The payment object can include a list of related transactions. The possible options are

Related Transactions object includes

Name Description
type Fixed value: sale, credit, authorise, refund, reversal, capture or validate
amount The amount of the transaction
status Possible values: Transaction Status
reference A unique reference for the payment transaction
created The local server datetime the payment was created, epoch timestamp
lastUpdate The local server datetime the payment was updated, epoch timestamp
statusFinalDate The local server datetime the payment reached a final status, epoch timestamp
failureCode An error code indication what caused the failure. Possible values: Failure Codes
method The payment method of the related transaction. Possible values: Supported Methods

Possible actions

The payment object can include a list of possible actions that can be done to the transaction. The possible actions are

  • Capture an authorisation when it has not been fully captured or reversed.
  • Reverse an authorisation when it has not been captured or reversed.
  • Refund a capture or sale when it has not been fully refunded.

These are indicated by the values capture, reverse and refund.

Transaction Type Possible actions
SALE refund
CAPTURE refund
AUTHORISE reverse, capture

Transaction Status

Name Description Webhook called?
pending The transaction is created but not completed yet No
failed Transaction processing failed Yes
manualintervention The transaction is in a state of which we can’t recover automatically. Contact the helpdesk for further investigation Yes
success The transaction is processed successfully Yes

User Authentication Method

Name Description
username_password The cardholder used username and password to authenticate successfully
pin The cardholder used PIN to authenticate successfully
hsm Authentication was successfully performed through Secret/Private Key in Secure Hardware Solution
ssm Authentication was performed through Secret/Private Key in Secure Software Solution (mobile app)
location_based Location-based Authentication was successfully performed (GPS location or other location based analysis of customer device)
environmental_based Environmental Authentication in Secure Software Solution (mobile app) was successfully performed (WIFI SSID, MAC addresses of customer device)
behaviour_analysis Behavioural Analysis was successfully performed (methods allowing the actual user from robots like measuring consumer movements for example)
biometrics Biometrics Authentication was successfully performed (for example fingerprint validation on mobile phone)
out_of_band Out Of band Authentication was successfully performed (usage of a second communication channel like phone communication, one time password by SMS)

Sequence Type

Name Description
express_checkout A non-recurring one-time transaction
recurring A periodic based recurring transaction
installment A recurring payment of which the number of payments is limited in frequency and or time

Request Checkout Details

Name Description
shipping Request shipping details the consumer provided during the checkout process.
billing Request billing/invoice details the consumer provided during the checkout process.
phone Request the consumer phone number.
email Request the consumer email.
first_name Request the consumer first name. When communicating to the customer (e.g. for shipping status updates) this is the name you should use for addressing the customer.
last_name Request the consumer last name. When communicating to the customer (e.g. for shipping status updates) this is the name you should use for addressing the customer.

Order line object

Expand Order Line details
Name Description
type The type of product bought
  • PHYSICAL
  • DISCOUNT
  • DIGITAL
  • SHIPPING_FEE
  • STORE_CREDIT
  • GIFT_CARD
  • SURCHARGE
  • SALES_TAX
  • DEPOSIT
name The name of the order line
code The article number of the product bought, can be a SKU, EAN, ISBN or UPC
quantity The number of items in the order line
unit The unit to describe the quantity. For example ‘pcs’ or ‘kg’
unitPrice The price of a single item, including VAT, in the order line
totalPrice The total amount of the order line, including VAT and discounts
discount The sum of all discounts applied to the order line
vatRate The VAT (value-added tax) rate applied to the order line. For example 21 for 21%
vat The amount of VAT (value-added tax) applied to the order line
url The link to the product page
imageUrl The link to an image of the product
brand The brand name of the product
data Any additional data that needs to be added
shippingDetails The shipping attributes of the order line
weightThe weight of the product in grams
heightThe height of the product in mm
widthThe width of the product in mm
lengthThe length of the product in mm
featuresExtra features of the product. For example ‘fragile’

Example

{
  "type" : "sale",
  "amount" : 316.35,
  "currency" : "eur",
  "status" : "success",
  "merchantOrderReference" : "8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
  "description" : "API Payment description",
  "language" : "eng",
  "method" : "card",
  "metadata" : "my custom metadata",
  "reference" : "C1505181754007360.1",
  "methodTransactionId" : "2ddd58ef-ba83-41bd-b208-647bcd8256b2",
  "created" : 1431964440770,
  "lastUpdate" : 1431964458858,
  "statusFinalDate": 1431964458858,
  "payUrl" : "https://onlinepayments.ccv.eu/card/payment.html?reference=C1505181754007360.1",
  "returnUrl" : "http://shop/?order=8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
  "brand" : "visa",
  "token" : "2424242424242424",
  "tokenMaskedInput" : "4111XXXXXXXX1111"
}

Delivery information object

Name Description
shippingCompany Name of the shipping company (as specific as possible). Maximum 100 characters. Example: ‘DHL US’ and not only ‘DHL’
shippingMethod The Shipping method
  • PICKUP_STORE
  • HOME
  • BOX_REG
  • BOX_UNREG
  • PICK_UP_POINT
  • OWN
  • POSTAL
  • DHL_PACKSTATION
  • DIGITAL
  • UNDEFINED
  • PICK_UP_WAREHOUSE
  • CLICK_COLLECT
trackingNumber Tracking number for the shipment. Maximum 100 characters.
trackingUri URI where the customer can track their shipment. Maximum 1024 characters.
returnShippingCompany Name of the shipping company for the return shipment (as specific as possible). Maximum 100 characters. Example: ‘DHL US’ and not only ‘DHL’
returnTrackingNumber Tracking number for the return shipment. Maximum 100 characters.
returnTrackingUri URL where the customer can track the return shipment. Maximum 1024 characters.

Example

{
  "shippingCompany" : "DHL US",
  "shippingMethod" : "DHL_PACKSTATION",
  "trackingNumber" : "13456",
  "trackingUri" : "http://example/tracking/13456",
  "returnShippingCompany" : "DHL US",
  "returnTrackingNumber" : "456789",
  "returnTrackingUri" : "http://example/tracking/456789"
}

Payout instruction payment object

A payout instruction can be used to provide a custom structured reference and facilitate Split Payouts. Multiple Payout Instructions can only be used when boarded for Split Payout.

Name Description
externalReference This is the reference to the merchant for this payout instruction. Present when the payment requires multiple payout instructions to identify different merchants.
amount The amount to be paid out to the referenced merchant.
paidout A boolean value that indicates if the referenced merchant has been paid out. Possible values: yes or no
paidoutDate An epoch timestamp for when the pay out to the referenced merchant took place.
unstructuredReference The message used in the pay out.
structuredReference Custom structured reference used in the pay out.
paidoutReference The reference used the payout to the merchant.

Example

{
  "externalReference" : "0001606469162213",
  "amount" : 5.00,
  "paidout" : "yes",
  "paidoutDate": 1605258439475,
  "unstructuredReference": "579fd569 AFREK. CCV PAY DAT. 20201113/0318 AANT. 3 MREF. Lamp Shop",
  "structuredReference": "123123412345",
  "paidoutReference": "579fd569"
}

Consumer Object

Name Description
firstName The first name of the customer obtained during the checkout process.
lastName The last name of the customer obtained during the checkout process.
phoneNumber The phone number of the customer obtained during the checkout process.
emailAddress The email address of the customer obtained during the checkout process.

When contacting the customer these details should be used. For billing or shipping purposes use the billing and shipping properties of the Payment object.

Payment Details

LandingPage Payment Details

Name Description
expirationDuration The time until payment expiration in ISO 8601 Duration. Default value and absolute maximum is P2M1D.
mail In case of banktransfer, A boolean value that indicates to mail the payment instructions. Defaults to true
mailReminder In case of banktransfer, A boolean value that indicates not to mail a reminder of the payment instructions if mail was true. Defaults to true
vaultAccessToken In case of card with storeInVault, The Vault Access Token result from storing the card in our vault.
maskedPan In case of card with storeInVault, The masked primary account number.
expiryDate In case of card with storeInVault, The expiry date of the card in format MMYY.
scaToken In case of card with storeInVault, Boolean value that indicates if the Vault Access Token is created for an SCA authenticated card. For more information refer to our 3-D Secure 2 compliance guide.
allowCustomerCancel A boolean value to show the cancel link on the landing page and on the child transaction page in case of bank transfer. When false the landing page and its bank transfer child transaction payment page show a return link instead of a cancel link. A PENDING landing page or their child can always be cancelled by cancel the payment. Defaults to true
preselectedMethod The method preselected in order to bypass customer payment method selection on the landing page if possible.
allowedPaymentMethods A list of payment methods to be displayed on the landing page
brand In case of card with storeInVault, the brand of the card.

Example

{
  "expirationDuration" : "P0Y2M1DT0H0M0.000S",
  "mail" :  true,
  "mailReminder" : false
}

Example of card with storeInVault

{
  "expiryDate" : "1222",
  "expirationDuration" : "P0Y2M1DT0H0M0.000S",
  "mail" :  true,
  "maskedPan" : "4111XXXXXXXX1111",
  "vaultAccessToken" : "L210215124735446CB87E192.1",
  "scaToken": false,
  "brand": "visa"
}

BankTransfer Payment Details

Name Description
expirationDuration The time until payment expiration in ISO 8601 Duration. Default value is P12D. Absolute maximum is P2M1D.
iban The IBAN account number the customer must wire the amount to. Will only be present when presence is agreed upon during merchant onboarding, isn’t present on default.
bic The BIC number of the bank the customer should wire the amount to. Will only be present when presence is agreed upon during merchant onboarding, isn’t present on default.
banktransferReference The reference the customer should use for the bank transfer
mail A boolean value that indicates to mail the payment instructions. Defaults to true
mailReminder A boolean value that indicates to mail a reminder of the payment instructions. Only applicable when mail is true. Defaults to true
mailReminderDuration The time until to mail a payment reminder in ISO 8601 Duration
allowCustomerCancel A boolean value to show the cancel link on the bank transfer form. When false the bank transfer form shows a return link to be redirected to the returnUrl instead of a cancel link to cancel and return. Defaults to true

Example

{
  "expirationDuration" : "P0Y0M12DT0H0M0.000S",
  "iban" : "NL91ABNA0417164300",
  "bic" : "INGBNL2A",
  "banktransferReference" : "0000341468425141",
  "mail" : true,
  "mailReminder" : false,
  "mailReminderDuration" : "P0Y0M7DT0H0M0.000S"
}

Card Payment Details

Name Description
maskedPan The masked primary account number
cardholderFirstName The first name of the cardholder
cardholderLastName The last name of the cardholder
qrCode Contains the content of the QR code that should be shown to the customer
urlIntent Contains the URL intent that can open a brand specific mobile app
authorisedAmount The authorised amount of the transaction. Only present for successful authorise transactions. This can be equal to or lower than the requested amount if supported by the acquirer
consumerAccountNumber The account number of the cardholder. Will only be present when presence is agreed upon during merchant onboarding, isn’t present on default. Only for BCMC.
consumerBic The BIC of the cardholder. Will only be present when presence is agreed upon during merchant onboarding, isn’t present on default. Only for BCMC.
authenticationProtocol The authentication protocol. Possible values: BEP, 3DS1 or 3DS2
authenticationStatus The status of the authentication
authenticationStatusReason The status reason associated with the authenticationStatus
acquirer The acquirer used for the authorisation.
acquirerResponseCode The authorisation response code obtained from the acquirer
acquirerResponseCodeDescription The authorisation description obtained from the acquirer
initialTransactionId The schemeTransactionId as received from the issuer. Available if received.
cardUsage Indicates the usage of the card. Available when received for acquirer Valitor. Possible values: UNKNOWN, CREDIT, DEBIT
interchangeFeeRegion Indicates the Interchange Fee Region assigned to the card used. Available when received for acquirer Valitor.
cardCategory Indicates the category of the card used. Available when received for acquirer Valitor.

More information on the use of qrCode and urlIntent for Bancontact payments can be found here.

Example

{
  "maskedPan": "XXXXXXXXXXXXXX227",
  "cardholderFirstName": "testName",
  "cardholderLastName": "testLastName",
  "qrCode": "BEP://1BEP.JFORCE.BE:3417/TMI$2N145W4C2HSHJKGOZNVFOMQG",
  "urlIntent": "BEPGenApp://DoTx?TransId=1BEP.JFORCE.BE:3417/TMI$2N145W4C2HSHJKGOZNVFOMQG",
  "authorisedAmount": 45.33,
  "consumerAccountNumber": "BE54000000000000",
  "consumerBic": "BPOTBEB1",
  "cardUsage": "CREDIT",
  "interchangeFeeRegion": "Visa Domestic",
  "cardCategory": "Consumer Card"
}

Terminal Payment Details

Name Description
terminalId The terminal id as assigned by CCV
managementSystemId The management system id of this terminal as by assigned CCV
accessProtocol The communication protocol between the terminal and access server
ip The browser accessible IP of the terminal for initiating the wake up
port The browser accessible port of the terminal’s socket handling HTTP calls
operatingEnvironment The environment in which the terminal is operating. Possible values: ATTENDED and SEMI_UNATTENDED. Defaults to SEMI_UNATTENDED when empty. Only ATTENDED is supported for payments of type authorise.
merchantLanguage The language of the merchant in which the intermediate page should be displayed
merchantReceipt The receipt for the merchant as an escaped JSON string. The content can be parsed to a JSON array
customerReceipt The receipt for the customer as an escaped JSON string. The content can be parsed to a JSON array
journalReceipt The journal receipt for the merchant as an escaped JSON string. The content can be parsed to a JSON array
eJournal The E-Journal for the merchant as an escaped JSON string. The content can be parsed to a XML
cardCircuit The OPI Card Circuit for the merchant as an escaped JSON string.
askMerchantSignature If true, the receipt should be signed by the merchant
askCustomerSignature If true, the receipt should be signed by the customer
askCustomerIdentification If true, the customer should provide identification
printCustomerReceipt If true, the merchant print the customer receipt

Example

{
    "terminalId" : "1234536",
    "managementSystemId" : "000103030",
    "accessProtocol" : "OPI_NL",
    "ip" : "127.0.0.1",
    "port" : 6235,
    "operatingEnvironment" : "ATTENDED",
    "merchantLanguage" : "NLD",
    "merchantReceipt" : "[ \"Kopie Merchant\", \"\", ...]",
    "customerReceipt" : "[ \"Kopie Klant\", \"\", ...]",
    "journalReceipt" : "[ \"JOURNAAL\", \"\", ...]",
    "eJournal" : "<?xml version=\"1.0\"?>\n<E-Journal>\n...</E-Journal>",
    "cardCircuit" : "MCDB",
    "askMerchantSignature" : false,
    "askCustomerSignature" : false,
    "askCustomerIdentification" : false,
    "printCustomerReceipt" : false
  }
Parsing the receipts

The receipt string contains an escaped JSON array which can be parsed into a JSON node tree. Each item in the array is a line of the receipt. The line should be handled as-is including empty lines and content multiple spaces that handle text alignment.

Example (JavaScript)

var receipt = "[ \"Kopie Merchant\", \"\", \"******* PAS OP: TEST SYSTEEM *******\", \"\", \"Terminal: 20000002\", \"Merchant: 123456789012345\", \"Periode: 3090       Transactie: 10274782\"]";
var lines = JSON.parse(receipt);
lines.forEach(function(line) {
    console.log(line);
}) ;

Kopie Merchant

******* PAS OP: TEST SYSTEEM *******

Terminal: 20000002
Merchant: 123456789012345
Periode: 3090       Transactie: 10274782
Parsing the E-Journal

The string containing the XML is well formed and can be parsed into a DOM tree.

SoftPos Payment Details

Name Description
terminalId The terminal id as assigned by CCV
customerReceipt The receipt for the customer as an escaped JSON string. The content can be parsed to a JSON array
journalReceipt The journal receipt for the merchant as an escaped JSON string. The content can be parsed to a JSON array
eJournal The E-Journal for the merchant as an escaped JSON string. The content can be parsed to a XML
cardCircuit The OPI Card Circuit for the merchant as an escaped JSON string.
acquirerResponseCode An error response code further explaining the failed status. Available when received.
acquirerResponseCodeDescription An error response code description further describing the failed status. Available when received.
receiptData Additional receipt data as an escaped JSON String.

Example

{
    "terminalId" : "1234536",
    "eJournal" : "<E-Journal>\n...</E-Journal>",
    "customerReceipt" : "[ \"Kopie Klant\", \"\", ...]",
    "journalReceipt" : "[ \"JOURNAAL\", \"\", ...]",
    "cardCircuit" : "MCDB",
    "acquirerResponseCode" : "MYPP_SERVER_ERROR",
    "acquirerResponseCodeDescription" : "myPinPad internal server error",
    "receiptData" : "{\"merchantName\":\"Rudy's Pancake House\",\"merchantLocation\":\"Hasselt\",\"terminalId\":\"2222\",\"merchantId\":\"499aa76e-443e-4261-87ef-a4dd07c7a2e4\",\"brand\":\"amex\",\"aid\":\"a0000000041010\",\"maskedCardNumber\":\"00\",\"timeStampUtc\":\"2024-09-05 12:21:26.32Z\",\"authorisationCode\":\"061545\",\"amount\":\"10\",\"currency\":\"EUR\"}"
  }

iDEAL Payment Details

Name Description
consumerBic The BIC of the cardholder. Will only be present when presence is agreed upon during merchant onboarding, isn’t present on default.
consumerAccountNumber The account number of the cardholder. Will only be present when presence is agreed upon during merchant onboarding, isn’t present on default.
notificationResult The notification result returned by the iDeal subsystem. Possible values: PUSH_SENT_SHOW_WAITING_SCREEN, REDIRECT

Example

{
    "consumerBic": "INGBNL2A",
    "consumerAccountNumber": "NL53INGB0654422370"
}

Giropay Payment Details

Warning

Giropay will be temporarily unavailable starting 31st of July 2023. We apologise for the inconvenience. For further information, please contact ecommerce@ccv.eu

Name Description
consumerBic The BIC of the cardholder. Will only be present when presence is agreed upon during merchant onboarding, isn’t present on default.
consumerAccountNumber The account number of the cardholder. Will only be present when presence is agreed upon during merchant onboarding, isn’t present on default.

Example

{
    "consumerBic": "INGBNL2A",
    "consumerAccountNumber": "NL53INGB0654422370"
}

Payconiq Payment Details

Name Description
transactionId The transaction ID known in the system of Payconiq. Only for informational purposes.
qrCode Contains the content of the QR code that should be shown to the customer.

Example

{
    "transactionId": "transaction_id_from_scheme",
    "qrCode": "https://pay-url.payconiq.com/api/transactions/115DS5D5F1QSDG5F1QDG531QGD531QD15GS3"
}

Paypal Payment Details

Name Description
mandateId The CCV mandate id attached to the transaction if a mandate was used
acquirerResponseCode An error response code further explaining the failed status. Available when received.
acquirerResponseCodeDescription An error response code description further describing the failed status. Available when received.

Example

{
   "mandateId": "MAN240205130156564CB87E192.0",
   "acquirerResponseCode": "TRANSACTION_REFUSED",
   "acquirerResponseCodeDescription": "The request was refused"
}

Klarna Payment Details

Name Description
transactionId The ID of the Hosted Payment Page Session of Klarna.
qrCode Contains the QR code that should be shown to the customer.
orderId The ID of the order of Klarna. This matches the order available at Klarna.
expiryDate The date when the order expires at Klarna. All captures should be done before this date

Gift Payment Details

Name Description
maskedGiftCode Masked gift code of the gift card used for payment.
approvedAmount The claimed amount of the transaction. This can be equal to or lower than the requested amount.

Apple Pay Payment Details

Name Description
maskedPan The masked primary account number
cardholderFirstName The first name of the cardholder
cardholderLastName The last name of the cardholder
authorisedAmount The authorised amount of the transaction. Only present for successful authorise transactions. This can be equal to or lower than the requested amount if supported by the acquirer
consumerAccountNumber The account number of the cardholder. Will only be present when presence is agreed upon during merchant onboarding, isn’t present on default.
consumerBic The BIC of the cardholder. Will only be present when presence is agreed upon during merchant onboarding, isn’t present on default.
cardUsage Indicates the usage of the card. Available when received. Possible values: UNKNOWN, CREDIT, DEBIT
interchangeFeeRegion Indicates the Interchange Fee Region assigned to the card used. Available when received.
cardCategory Indicates the category of the card used. Available when received.

Example

{
  "maskedPan": "XXXXXXXXXXXXXX227",
  "cardholderFirstName": "testName",
  "cardholderLastName": "testLastName",
  "authorisedAmount": 45.33,
  "consumerAccountNumber": "BE54000000000000",
  "consumerBic": "BPOTBEB1",
  "cardUsage": "CREDIT",
  "interchangeFeeRegion": "Visa Domestic",
  "cardCategory": "Consumer Card"
}

Google Pay Payment Details

Name Description
maskedPan The masked primary account number 
{
  "maskedPan": "XXXXXXXXXXXXXX227"
}

SCA Details

Name Description
authExemption Enum value set by the payment initiator to indicate that an exemption was requested. Possible values: SCA Exemptions.
initialTransactionId Id of transaction used to obtain a mandate for subsequent transactions called a Customer Initiated Transaction (CIT) or the Id of the last subsequent transaction.
moto Enum value set by the payment initiator to indicate this transaction is a Mail Order / Telephone Order transaction. Possible values SCA MOTO.

SCA Exemptions

Name Description
TRANSACTION_RISK_ANALYSIS Choose to trigger the Risk analysis for each transaction or to disable the TRA from being applied.
LOW_VALUE Transactions with an amount lower than 30 EURO. Every 5 transactions authentication is required or if the total amount of 100 euro non authenticated transactions is exceeded.
SECURE_CORPORATE Business to Business.
TRUSTED_BENEFICIARY A cardholder can indicate that the merchant is trusted and that authentication is no longer required.

Example

{
    "authExemption": "TRANSACTION_RISK_ANALYSIS"
}

SCA Moto

Name Description
MAIL The transaction is initiated through mail.
TELEPHONE The transaction is initiated through telephone.

Example

{
    "moto": "MAIL"
}

Payment request

  • Resource: /api/v1/payment
  • Method: POST
  • Content-Type: application/json
  • Authentication: basic auth
  • Supports idempotency
  • Parameters
Name Required Method Description Max Length
amount Yes All The amount of the transaction with format as defined by the currency used 12 digits in total, of which maximum 2 decimal digits
currency Yes All An ISO 4217 three-letter code. Possible values: Currencies 3
returnUrl No All The customer is redirected to this URL after they authenticate or cancel the payment. If provided it must include a scheme to be usable for browser redirection or Android/iOs app usage. We do not validate the provided URL. If no URL is provided, the customer will be redirected to our CCV return URL. 2000
method Yes All The payment method that the customer chooses. Possible values: Supported Methods n/a
language Yes All The language of the customer. Defines the language to be used in the payment screens the customer will see. Possible values: Languages 3
metadata No All An arbitrary string, maximum of 255 characters, that can be used to track payments 255
merchantOrderReference No All A reference, maximum of 255 characters, of the order associated with this payment 255
description No All A description to show the customer 255
webhookUrl No All The webhook URL invoked for transaction changes. This overrides the merchant webhook if one is present. We do not validate this url 2000
issuer No ideal The issuer chosen by the customer. If not entered, the customer will be presented with a payment page to choose the issuer. Possible values: see List all methods 255
brand No card The card brand chosen by the customer . Possible values: Supported Brands n/a
tokenize No card Return a token calculated from the PAN or IBAN, depending on the payment method. Possible values: yes, no. Default: no 3
storeInVault No card, landingpage Stores the relevant data used in this transaction in the vault for later use. Supported for method card, and card via landingpage. Possible values: yes, no. Default: no 3
obtainMandate No paypal, ideal, applepay Stores the relevant data used in this transaction as a mandate for later use. Possible values: yes, no. Default: no 3
scaReady No card, landingpage Indicates that the payment is ready for SCA used for 3-D Secure 2 cardholder authentication. In addition, it enables strict validation of the SCA required fields for billing and shipping. See Strong Customer Authentication (SCA) for more information. Possible values: yes, no. Default: no 3
billingAddress Conditional All The billing street address.{BR}{BR}Required when scaReady is set to yes. 50+10+10
billingCity Conditional All The billing city of the customer.{BR}{BR}Required when scaReady is set to yes. 50
billingState Conditional All The billing region/state of the customer, an ISO 3166-2 country subdivision code. See for more info: Country Subdivision Codes - ISO 3166-2.{BR}{BR}Required when scaReady is set to yes, and must be a valid subdivision code (if applicable for the country). An invalid subdivision code results in a input error response. 3
billingPostalCode Conditional All The billing postal (zip) code of the customer.{BR}{BR}Required when scaReady is set to yes. 16
billingCountry Conditional All The billing country of the customer, an ISO 3166 alpha-2 code. See for more info: Country Codes - ISO 3166. For value BE and method banktransfer customers will receive an appropriate bank account number and structured reference.{BR}{BR}Required when scaReady is set to yes, and must be a valid alpha-2 code. An invalid alpha-2 code results in a input error response. 2
billingEmail Conditional All The billing email of the customer.{BR}{BR}Required when method is banktransfer. Defines the email to send the payment instructions to.{BR}Required when scaReady is set to yes. Must be a valid email address if present. 255
billingPhoneNumber Conditional All The billing phone number of the customer.{BR}{BR}Required when scaReady is set to yes, and must be a valid subscriber-section of a telephone number, see ITU-T E.164 for more information. An invalid telephone number format results in a input error response. 15
billingPhoneCountry Conditional All The billing phone number country code of the customer.{BR}{BR}Required when scaReady is set to yes, and must be a valid ITU-T E.164 country code. An invalid country code results in a input error response. 3
billingFirstName No All The billing first name of the customer 255
billingLastName No All The billing last name of the customer 255
billingHouseNumber No All The billing house number of the customer 10
billingHouseExtension No All The billing house extension of the customer 10
shippingAddress Conditional All The shipping street address.{BR}{BR}Required when shipping provided* if scaReady is set to yes. 50+10+10
shippingCity Conditional All The shipping address city.{BR}{BR}Required when shipping provided* if scaReady is set to yes. 50
shippingState Conditional All The shipping address region/state, an ISO 3166-2 country subdivision code. See for more info: Country Subdivision Codes - ISO 3166-2.{BR}{BR}Required when shipping provided* if scaReady is set to yes, and must be a valid subdivision code (if applicable for the country). An invalid subdivision code results in a input error response. 3
shippingPostalCode Conditional All The shipping address postal (zip) code.{BR}{BR}Required when shipping provided* if scaReady is set to yes. 16
shippingCountry Conditional All The shipping address country, an ISO 3166 alpha-2 code.{BR}{BR}Required when shipping provided* if scaReady is set to yes, and must be a valid alpha-2 code. An invalid alpha-2 code results in a input error response. 2
shippingEmail No All The shipping email of the customer. Must be a valid email address if present. 255
shippingPhoneNumber No All The shipping phone number of the customer.{BR}{BR}If this field is provided when scaReady is set to yes it must be a valid subscriber-section of a telephone number, see ITU-T E.164 for more information. An invalid telephone number format results in a input error response. 15
shippingPhoneCountry No All The shipping phone number country code of the customer.{BR}{BR}If this field is provided when scaReady is set to yes it must be a valid ITU-T E.164 country code. An invalid country code results in a input error response. 3
shippingFirstName No All The shipping first name of the customer 255
shippingLastName No All The shipping last name of the customer 255
shippingHouseNumber No All The shipping house number of the customer 10
shippingHouseExtension No All The shipping house extension of the customer 10
transactionType No All Indication of TransactionType. Possible values: sale, credit, authorise or validate. Default sale. Note that authorise only applies to terminal, klarna, applepay and card payments. credit and validate only apply to card payments. credit and validate are not supported for brand bcmc n/a
details Conditional All An object which includes method specific details. Possible values: Method Request Details n/a
notificationRequests No All An object which is used to request Notifications for specific events related to this payment. n/a
userAuthenticationMethods Conditional card List of authentication methods performed by the cardholder in case Vault Access Token is used. Required for BCMC WIP. Possible values: User Authentication Method n/a
requestCheckoutDetails No ideal List of possible consumer details the merchant can requested if not present in payment request after checkout is completed. Possible values: Request Checkout Details n/a
sequenceType Conditional card Field indicating the sequence type of the transaction in case Vault Access Token is used. Required for BCMC WIP. Possible values: Sequence Type n/a
orderLines No klarna, ideal Optional list of order lines that can be used for risk analysis and provide information on order amount distribution Order Line n/a
payoutInstructions No Collecting Payments Optional list of Payout Instruction. Indicates how the pay-out should be split when using Split Payout n/a
mandateId Yes card, ideal, paypal, sdd The Mandate Id from CCV to initiate a payment with. 28
accountInfo No card, landingpage Optional information about the customer with the merchant

!INFO * The - Required when shipping provided - fields are mandatory if at least one of them is specified when the scaReady flag is set to yes. If all of them are left blank they become optional and are assigned the corresponding billing-value as default.

Example

{
  "amount" : 316.35,
  "currency" : "eur",
  "method" : "card",
  "returnUrl" : "http://shop/?order=8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
  "metadata" : "my custom metadata",
  "merchantOrderReference" : "8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
  "description" : "API Payment description",
  "language" : "eng"
}

Method Request Details

LandingPage Request Details

These details are possible for a payment using the method landingpage.

Name Required Description Max Length
expirationDuration No The time until payment expiration in ISO 8601 Duration. Default value and absolute maximum is P2M1D. If banktransfer is selected, expiration has a delay. 20
expirationTimestamp No The epoch timestamp when the payment should expire. Default value and absolute maximum is 2 months and 1 day after initial creation. /
mail No A boolean value that indicates to mail the payment instructions for banktransfer payments. Defaults to true 5
mailReminder No A boolean value that indicates to mail a reminder of the payment instructions. Only applicable when mail is true. Defaults to true 5
allowCustomerCancel No A boolean value to show the cancel link on the landing page and on the child transaction page in case of bank transfer. When false the landing page and its bank transfer child transaction payment page show a return link instead of a cancel link. A PENDING landing page or their child can always be cancelled by cancel the payment. Defaults to true 5
preselectedMethod No A method preselection in order to bypass customer payment method selection on the landing page if possible.
allowedPaymentMethods No A list of payment methods to be displayed on the landing page. If a method is available but not present in this list it will not be shown to the customer on the landing page. /

Example

{
  "amount" : 0.1,
  "currency" : "EUR",
  "method" : "landingpage",
  "returnUrl" : "http://shop/?order=8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
  "metadata" : "my custom metadata",
  "merchantOrderReference" : "8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
  "description" : "API Payment description",
  "language" : "eng",
  "details" : {
    "expirationDuration" : "P0Y2M1DT0H0M0.000S"
  }
}

BankTransfer Request Details

These details are possible for a payment using the method banktransfer.

Name Required Description Max Length
expirationDuration No The time until payment expiration in ISO 8601 Duration. Default value is P12D. Absolute maximum is P2M1D. A delay is applied. 20
expirationTimestamp No The epoch timestamp when the payment should expire. Default value is set to 12 days after initial creation. Absolute maximum is 2 months and 1 day. /
mail No A boolean value that indicates to mail the payment instructions. Defaults to true 5
mailReminder No A boolean value that indicates to mail a reminder of the payment instructions. Only applicable when mail is true. Defaults to true 5
mailReminderDuration No The time until to mail a payment reminder in ISO 8601 Duration. Defaults to a maximum of P7D and should be lesser than expirationDuration 20
allowCustomerCancel No A boolean value to show the cancel link on the bank transfer form. When false the bank transfer form shows a return link to be redirected to the returnUrl instead of a cancel link to cancel and return. Defaults to true 5

Example

{
  "amount" : 0.1,
  "currency" : "EUR",
  "method" : "banktransfer",
  "returnUrl" : "http://shop/?order=8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
  "metadata" : "my custom metadata",
  "merchantOrderReference" : "8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
  "description" : "API Payment description",
  "language" : "eng",
  "billingEmail" : "youremail@email.com",
  "details" : {
    "expirationDuration" : "P0Y0M12DT0H0M0.000S",
    "mail" : true,
    "mailReminderDuration" : "P0Y0M7DT0H0M0.000S"
  }
}

Giropay Request Details

Warning

Giropay will be temporarily unavailable starting 31st of July 2023. We apologise for the inconvenience. For further information, please contact ecommerce@ccv.eu

These details are possible for a payment using the method giropay.

Name Required Description Max Length
bic Yes The BIC number of the bank of the customer. 255
iban No The IBAN number of the customer. 255

Example

{
   "amount" : 0.1,
   "currency" : "EUR",
   "method" : "giropay",
   "returnUrl" : "http://shop/?order=8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
   "metadata" : "my custom metadata",
   "merchantOrderReference" : "8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
   "description" : "API Payment description",
   "language" : "eng",
   "billingEmail" : "youremail@email.com",
   "details" : {
      "iban" : "DE89370400440532013000",
      "bic" : "TESTDETT310"
   }
}

iDeal Request Details

These details are possible for a payment using the method ideal.

Name Required Description Max Length
userAgent Yes The user-agent header from the browser of the consumer. Only applicable when using a mandateId. 255

Example

{
  "amount" : 0.1,
  "currency" : "EUR",
  "method" : "ideal",
  "returnUrl" : "http://shop/?order=8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
  "metadata" : "my custom metadata",
  "merchantOrderReference" : "8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
  "description" : "API Payment description",
  "language" : "eng",
  "details" : {
    "userAgent" : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.2 Safari/605.1.15"
  }
}

Card Request Details

Redirect customer to CCV Pay for card entry

Since the introduction of Strong Customer Authentication (SCA), additional customer information can be added to the request and is highly recommended. See more information on the dedicated SCA documentation

Example

{
  "amount" : 0.1,
  "currency" : "EUR",
  "method" : "card",
  "returnUrl" : "http://shop/?order=8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
  "metadata" : "my custom metadata",
  "merchantOrderReference" : "8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
  "description" : "API Payment description",
  "language" : "eng",
  "transactionType": "sale"
}
Using a card stored in the vault
Name Required Description
vaultAccessToken Conditional The Vault Access Token that has valid data card stored in the vault. Only required if transactionType = sale

Example

{
  "amount" : 0.1,
  "currency" : "EUR",
  "method" : "card",
  "returnUrl" : "http://shop/?order=8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
  "metadata" : "my custom metadata",
  "merchantOrderReference" : "8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
  "description" : "API Payment description",
  "language" : "eng",
  "transactionType": "sale",
  "details": {
    "vaultAccessToken": "1GV13YEY8ZKCH8ZBJCEOJKDI"
  }
}
Card data in request

When sending card data directly, you must be PCI compliant. If you don’t want to handle card data on your own, this scenario is not suited for you.

Name Required Description
pan Yes The primary account number. All spaces and dashes are removed
expiryDate Yes The expiry date of the card. Format: MMyy or MMyyyy. Example: 0222 or 022022 are both February 2022
cardholderFirstName Yes The first name of the cardholder
cardholderLastName Yes The last name of the cardholder
cvc Conditional The CVC/CVV2 security code of the card. Only required if transactionType = sale or transactionType = credit and brand is not bcmc. When a vaultAccessToken is used, the cvc code is optional and depending on configuration.

Example

{
  "amount" : 0.1,
  "currency" : "EUR",
  "method" : "card",
  "returnUrl" : "http://shop/?order=8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
  "metadata" : "my custom metadata",
  "merchantOrderReference" : "8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
  "description" : "API Payment description",
  "language" : "eng",
  "details": {
    "pan": "67032222222222227",
    "expiryDate": "1220",
    "cardholderFirstName": "testName",
    "cardholderLastName": "testLastName"
  }
}
Card Data Url

Normally, the payUrl is used to obtain the necessary information from the customer to proceed with the transaction. Alternatively the merchant can send this information to us via the cardDataUrl specified in the transaction response. This is only returned for some cases in the method card and applePay.

  • Method card: when this setting is enabled in the payment method configuration. In this case card data will need to be sent to the cardDataUrl, see method card.
  • Method applepay: when the so-called Hybrid flow is implemented by the merchant. In this case the Apple Pay Encrypted Token will need to be sent to the cardDataUrl, see method Apple Pay.

The field cardDataUrl is used to indicate the endpoint to which card data can be sent. This can be a different endpoint, which different content, depending on the method that is used. Below is the explanation per payment method.

Method Card

Card Data Request

Normally, the payUrl is used to obtain the Card Data from the customer or via Card data in the request. Alternatively, the customer can submit the card data from a mobile app or browser to the cardDataUrl without requiring authentication. However, PCI compliance may be required:

  • If the card data is provided directly by the customer to the PSP, No PCI compliance is required. E.g.: Mobile app or browser uses the cardDataUrl to submit the card data directly to the PSP.
  • If the card data passes through the integrator’s backend system, PCI compliance is always required. E.g.: Mobile app or browser submits card data to integrator’s backend system which in turn uses the cardDataUrl to submit the data to the PSP.

Resource: cardDataUrl e.g. https://onlinepayments.ccv.eu/card/carddata/embedded?reference=YOUR_REFERENCE_HERE

  • Method: POST
  • Content-Type: application/json
  • Authentication: None
  • Parameters
Name Required Description
pan Yes The primary account number. All spaces and dashes are removed
expiryDate Yes The expiry date of the card. Format: MMyy or MMyyyy. Example: 0222 or 022022 are both February 2022
cardholderFirstName Yes The first name of the cardholder. Length of cardholderFirstName and cardholderLastName combined may not exceed 44 characters.
cardholderLastName Yes The last name of the cardholder. Length of cardholderFirstName and cardholderLastName combined may not exceed 44 characters.
cvc Conditional The 3 digit CVC/CVV2 security code of the card. Only required if transactionType = sale or transactionType = credit and brand is not bcmc. When a vaultAccessToken is used, the cvc code is optional and depending on configuration.

Example

{
  "pan": "67032222222222227",
  "expiryDate": "1220",
  "cvc": "1224",
  "cardholderFirstName": "testName",
  "cardholderLastName": "testLastName"
}

Card data response

  • Status Code: 200
Method Apple Pay

Card Data Request

Normally the payUrl is used to obtain the Apple Pay Encrypted Token from the customer or via Apple Pay Request Details. Alternatively, the merchant can host the Apple Pay button on their own checkout page. In this case the merchant can use this cardDataUrl to send the Encrypted Token.

  • Resource: cardDataUrl e.g. https://api.psp.ccv.eu/api/v1/applepay/REFERENCE_ID/encryptedtoken
  • Method: POST
  • Content-Type: application/json
  • Authentication: None
  • Parameters
Name Required Description
encryptedToken Yes The Encrypted Token as received from Apple Pay

Example

{
  "encryptedToken" : {
    "paymentData": {
      "data": "6g1wT...MA2jCj",
      "signature": "MIAGCSqG...AAAAA==",
      "header": {
        "publicKeyHash": "l0xf5...MdLk8=",
        "ephemeralPublicKey": "MFkwEwYH....qjiBeQ==",
        "transactionId": "bc8e4cdaa123456789aba4c65beaf6caf123456789230873509e136c8e53119d"
      },
      "version": "EC_v1"
    },
    "paymentMethod": {
      "displayName": "MasterCard 1471",
      "network": "MasterCard",
      "type": "debit"
    },
    "transactionIdentifier": "BC8E4CDAAD75A123456789C65BEAF612345678976F230873509E136C8E53119D"
  }
}

Card data response

  • Status Code: 200

Terminal Request Details

Name Required Description Max Length
terminalId Yes The terminal id as assigned by CCV 50
managementSystemId Yes The management system id of this terminal as assigned by CCV 50
accessProtocol Yes The communication protocol between the terminal and access server 20
ip Yes The browser accessible IP of the terminal for initiating the wake up 50
port Yes The browser accessible port of the terminal’s socket handling HTTP calls 5
operatingEnvironment Yes The environment in which the terminal is operating. Possible values: ATTENDED and SEMI_UNATTENDED. Defaults to SEMI_UNATTENDED when empty. Only ATTENDED is supported for payments of type authorise. 20
merchantLanguage Yes/No The language of the merchant, used to change the language in which the intermediate page is displayed in ATTENDED operatingEnvironments. Required when operatingEnvironment is ATTENDED, not required otherwise. 3

Example

{
  "amount" : 0.1,
  "currency" : "EUR",
  "method" : "TERMINAL",
  "returnUrl" : "http://shop/?order=3857c68a-f43d-473c-b2ac-2c826bba175a",
  "metadata" : "{'order': '3857c68a-f43d-473c-b2ac-2c826bba175a', 'datetime': 1491207703113}",
  "merchantOrderReference" : "3857c68a-f43d-473c-b2ac-2c826bba175a",
  "description" : "API Payment description for order 3857c68a-f43d-473c-b2ac-2c826bba175a",
  "language" : "NLD",
  "details" : {
    "port" : 6235,
    "managementSystemId" : "000103030",
    "ip" : "127.0.0.1",
    "terminalId" : "1234536",
    "accessProtocol" : "OPI_NL",
    "operatingEnvironment" : "ATTENDED",
    "merchantLanguage" : "NLD"
  }
}

Vault Request Details

When a payment is initiated with a Vault Access Token, the data stored in the vault with this Access Token must be usable for the method indicated. For example, when the method card is used, the Vault Access Token must have card data stored.

Name Required Description Max Length
vaultAccessToken Yes The Vault Access Token that has valid data stored in the vault. 40

Example

{
  "amount" : 0.1,
  "currency" : "EUR",
  "method" : "card",
  "returnUrl" : "http://shop/?order=8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
  "metadata" : "my custom metadata",
  "merchantOrderReference" : "8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
  "description" : "API Payment description",
  "language" : "eng",
  "details": {
    "vaultAccessToken" : "5C810B0AD0B1BC0926EBEA53"
  }
}

Gift Request Details

Warning

Method Gift is a work in progress not yet available for usage by merchants.

Name Required Description Max Length
giftCode No The code of the gift card to be used for the payment. 255

Example

{
  "amount" : 0.1,
  "currency" : "EUR",
  "method" : "gift",
  "returnUrl" : "http://shop/?order=8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
  "metadata" : "my custom metadata",
  "merchantOrderReference" : "8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
  "description" : "API GIFT Payment description",
  "language" : "eng",
  "details": {
    "giftCode" : "CCV000323242"
  }
}

Apple Pay Request Details

These details are possible for a payment using the method applepay. These details are only possible to send if agreed up during merchant onboarding when you are using your own Apple IDs for Apple Pay. Default CCV is hosting the Apple Pay button on a hosted payment page.

Name Required Description Max Length
applePayEncryptedToken No The entire encrypted token as received by Apple,
including paymentData, paymentMethod and transactionIdentifier as json.		 N/A
applePayValidationUrl No The validationUrl as received by the Apple Pay Javascript library in the onvalidatemerchant callback. N/A
applePayDomainName No The domain on which the Apple Pay button has been clicked. e.g: onlinepayments.ccv.eu N/A

Example

{
  "amount" : 0.1,
  "currency" : "EUR",
  "method" : "applepay",
  "returnUrl" : "http://shop/?order=8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
  "metadata" : "my custom metadata",
  "merchantOrderReference" : "8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
  "description" : "API Payment description",
  "language" : "eng",
  "details": {
    "applePayEncryptedToken" : {
      "paymentData": {
        "data": "6g1wT+OeD9vZxL2AhI...DATA_REDACTED",
        "signature": "MIAGCSqGSIb3DQEHAqCAMI...DATA_REDACTED",
        "header": {
          "publicKeyHash": "l0xf53V7Xk3bIRZ2aO4xp2j91oQANO7X4oFsUgMdLk8=",
          "ephemeralPublicKey": "MFkwEwYHKo..DATA_REDACTED",
          "transactionId": "bc8e4cdaad75aeaa4baba4c65beaf6cafefc82876f230873509e136c8e53119d"
        },
        "version": "EC_v1"
      },
      "paymentMethod": {
        "displayName": "MasterCard 1471",
        "network": "MasterCard",
        "type": "debit"
      },
      "transactionIdentifier": "BC8E4CDAAD75AEAA4BABA4C65BEAF6CAFEFC82876F230873509E136C8E53119D"
    }
  }
}

GooglePay Request Details

The following request details apply to the googlepay payment method and are only necessary for direct integration. If you use the hosted payment page integration, CCV manages the Google Pay button and provides these details for you.

Name Required Description Max Length
googlePayEncryptedToken Conditional The unmodified Google Pay encrypted payment method token as received from Google Pay in UTF-8 encoded, serialized JSON object String format. Only required when using CCV’s direct integration. N/A
userAgent No The user-agent header from the browser of the consumer. 255
googlePayTestEncryptedTokenMode No Only used for Test apikeys. This defines the authentication method used for the simulated Google Pay test flow. Possible values: CRYPTOGRAM, PAN_ONLY_FRICTIONLESS, PAN_ONLY_CHALLENGE. Defaults to CRYPTOGRAM. N/A

Example

{
  "googlePayEncryptedToken": "{\"signature\":\"MEUCIG/I9gCiQhavsUWz7knU9iALZFKsX5jWvj01xUsKd4eVAiEAjT4Ie2DKEpASHHob+taAh8BUAqCWW5EKDrqFbYbj ...\"}", 
  "userAgent" : "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.2 Safari/605.1.15", 
  "googlePayTestEncryptedTokenMode": "PAN_ONLY_FRICTIONLESS"
}

SoftPos Request Details

The following payment details are available for the softpos payment method.

Name Required Description Max Length
terminalId Yes The terminal id as assigned by CCV 20

Example

{
  "amount" : 0.1,
  "currency" : "EUR",
  "method" : "softpos",
  "returnUrl" : "http://shop/?order=8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
  "metadata" : "my custom metadata",
  "merchantOrderReference" : "8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
  "description" : "API Payment description",
  "language" : "eng",
  "billingEmail" : "youremail@email.com",
  "details" : {
    "terminalId" : "1234536"
  }
}

Payout Instruction Request Details

A payout instruction can be used to provide a custom structured reference and facilitate Split Payouts. If a single payout instruction is provided the assumption is this refers to the requesting merchant, whereas multiple payout instructions require an externalReference to identify different merchants.

Multiple Payout Instructions can only be used when boarded for Split Payout.

The sum of all payout instructions must match the payment amount.

Name Required Description
externalReference Conditional This is the reference to the merchant for this payout instruction. Required when the payment requires multiple payout instructions to identify different merchants.
structuredReference No Custom structured reference used in the pay out. Must be 12-digits without padding or separators.
amount Yes The amount to be paid out to the referenced merchant.

Example: Instruction for payout to other merchant using the externalReference

{
  "externalReference" : "0001606469162213",
  "amount" : 5.00
}

Example: Instruction for providing a structured reference without an externalReference

{
  "structuredReference" : "123123412345",
  "amount" : 15.00
}

Payment response

  • Status Code: 200
  • Content Type: application/json
  • Content: Payment object