Integrate our products into your software. Let's make payment happen together!
Look at all the possibilitiesThe payment resource is responsible for initiating new payments and refunds.
The general flow will be:
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.
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 his 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:
terminal
methodcard
method for card brand Bancontact (bcmc
), with several limitations set by Bancontact:
To use deferred sales with our API, you need to implement the following functionality:
authorise
In case the money should be released back to the cardholder, a reversal can used.
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 |
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 |
The payment object can include a list of possible actions that can be done to the transaction. The possible actions are
These are indicated by the values capture
, reverse
and refund
.
Transaction Type | Possible actions |
---|---|
SALE | refund |
CAPTURE | refund |
AUTHORISE | reverse, capture |
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 |
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) |
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 |
Name | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
type | The type of product bought
|
||||||||||
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
|
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"
}
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
|
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"
}
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"
}
Name | Description |
---|---|
expirationDuration | The time until payment expiration in ISO 8601 Duration. Default value and absolute maximum is P2M1D . |
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 his 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"
}
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 |
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"
}
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"
}
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
}
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
The string containing the XML is well formed and can be parsed into a DOM tree.
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. |
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"
}
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"
}
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"
}
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"
}
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 |
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. The approvedAmount is limited to 50 due to EU regulations. |
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"
}
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. |
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"
}
Name | Description |
---|---|
The transaction is initiated through mail. | |
TELEPHONE | The transaction is initiated through telephone. |
Example
{
"moto": "MAIL"
}
/api/v1/payment
POST
application/json
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 |
Stores the relevant data used in this transaction as a mandate for later use. Supported for method paypal and ideal . 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 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 |
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 |
Optional list of order lines that can be used for risk analysis. 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"
}
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. | / |
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 his 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"
}
}
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. | / |
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"
}
}
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"
}
}
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"
}
}
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"
}
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"
}
}
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"
}
}
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
.
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.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.
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:
cardDataUrl
to submit the card data directly to the PSP.cardDataUrl
to submit the data to the PSP.Resource: cardDataUrl
e.g. https://onlinepayments.ccv.eu/card/carddata/embedded?reference=YOUR_REFERENCE_HERE
POST
application/json
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
200
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
POST
application/json
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
200
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"
}
}
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"
}
}
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"
}
}
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"
}
}
}
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"
}
}
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
}
200
application/json
It is possible to extend the authorisation time of an existing authorisation until the authorisation should be captured.
Notes:
only transactions of type authorise
which were successful can have their authorisation period extended.
only transactions of method klarna
can have their authorisation period extended.
only allowed for transactions that have not already been captured, or are not in progress of being captured.
Resource: /api/v1/payment/{reference}/extend-authorisation-time
Method: POST
Authentication: basic auth
Parameters
Name | Required | Description | Max Length |
---|---|---|---|
reference | Yes | The unique reference of the payment which should have the authorisation time extended | 255 |
Example
200
Refunds are allowed for all existing payment methods, except LandingPage
, Token
and Vault
.
UNSUFFICIENT_BALANCE
Name | Description |
---|---|
type | Fixed value: refund |
amount | The refund amount |
currency | Echo from the Payment |
status | Possible values: Transaction Status |
paidout | A boolean value that indicates if this transaction has been paid out. Only available for collecting protocols. Possible values: yes or no |
paidoutDate | The date when the payment to the customer was done. Only valid for collecting protocols. |
merchantOrderReference | Echo from the Payment |
description | A description of the transaction |
language | Echo from the Payment |
method | Echo from the Payment |
brand | Echo from the Payment |
metadata | Echo from the Payment |
reference | A unique reference for the refund transaction |
originalReference | The unique reference for the payment transaction this payment is attempting to refund. |
unstructuredReference | The unstructured reference used when performing the payout to the merchant. Only valid for collecting protocols |
paidoutReference | The reference used when performing the payout to the customer. This can be used to look up transactions related to that payout. Only valid for collecting protocols |
created | The local server datetime the refund was created, epoch timestamp |
lastUpdate | The local server datetime the refund was updated, epoch timestamp |
statusFinalDate | The local server datetime the refund reached a final status, epoch timestamp |
failureCode | An error code indication what caused the failure. Possible values: Failure Codes |
payUrl | To complete the payment the customer should be redirected to this unique URL. Only valid for Terminal |
returnUrl | After the payment is completed (successfully or otherwise) the customer is redirected to this URL. Only valid for Terminal |
payoutInstructions | Optional list of Payout Instruction set by the refund initiator to indicate which merchants of the original payment were eligible for a refund. See Split Payout for more info. |
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 sub merchant for this payout instruction. |
amount | The amount to withhold for pay out to the sub merchant. |
paidout | A boolean value that indicates that the payout instruction’s amount is withheld from a pay out to the sub merchant. Possible values: yes or no |
paidoutDate | An epoch timestamp of the payout to the sub merchant where this payout instruction is withheld from. |
unstructuredReference | The message used in the payout to the sub merchant. |
paidoutReference | The reference to the payout to the sub merchant. |
Example
{
"externalReference" : "0001606469162213",
"amount" : 5.00,
"paidout" : "yes",
"paidoutDate": 1605258439475,
"unstructuredReference": "579fd569 AFREK. CCV PAY DAT. 20201113/0318 AANT. 3 MREF. Lamp Shop",
"paidoutReference": "579fd569"
}
/api/v1/refund
POST
application/json
Name | Required | Description | Max Length |
---|---|---|---|
reference | Yes | The unique reference of the payment to refund | 255 |
description | No | The description of the refund. If not provided we use the original payment description | 255 |
amount | No | The amount to refund. If not provided we use the original payment amount. The currency used will be the currency of the original payment and the format must be the same | 12 digits in total, of which maximum 2 decimal digits |
webhookUrl | No | The webhook URL invoked for transaction changes. This overrides the merchant webhook if one is present. We do not validate this url | 2000 |
returnUrl | No | The customer is redirected to this URL after the payment is completed (successfully or otherwise). 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. Only valid for Terminal . |
2000 |
notificationRequests | No | An object which is used to request Notifications for specific events related to this refund. | n/a |
payoutInstructions | No | Optional list of Payout Instruction to indicate which merchants of the original payment were eligible for a refund. See Split Payout for more info. | n/a |
Example
{
"reference": "C1505181754007360.1",
"description": "API Refund Description"
}
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.
Requirements:
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 withheld for pay out to the referenced merchant. |
Example
{
"externalReference" : "0001606469162213",
"amount" : 5.00
}
200
application/json
Example
{
"type" : "refund",
"amount" : 316.35,
"currency" : "eur",
"status" : "PENDING",
"merchantOrderReference" : "8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
"description" : "API Refund Description",
"language" : "eng",
"method" : "card",
"metadata" : "my custom metadata",
"reference" : "C1505181613078800.1",
"brand" : "visa",
"created" : 1431958387914,
"lastUpdate" : 1431958387914,
"statusFinalDate" : 1431958387914
}
An existing authorise can be captured using this resource.
Name | Description |
---|---|
type | Fixed value: capture |
amount | The capture amount |
currency | Echo from the Payment |
status | Possible values: Transaction Status |
paidout | A boolean value that indicates if this transaction has been paid out. Only available for collecting Payments. Possible values: yes or no |
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 |
merchantOrderReference | Echo from the Payment |
description | The description of the transaction |
language | Echo from the Payment |
method | Echo from the Payment |
brand | Echo from the Payment |
metadata | Echo from the Payment |
reference | A unique reference for the capture transaction |
originalReference | The unique reference for the payment transaction this payment is attempting to capture. |
unstructuredReference | The unstructured reference used when performing the payout to the merchant. 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 |
created | The local server datetime the capture was created, epoch timestamp |
lastUpdate | The local server datetime the capture was updated, epoch timestamp |
statusFinalDate | The local server datetime the capture reached a final status, epoch timestamp |
failureCode | An error code indication what caused the failure. Possible values: Failure Codes |
/api/v1/capture
POST
application/json
Name | Required | Description | Max Length |
---|---|---|---|
reference | Yes | The unique reference of the payment to capture | 255 |
description | No | The description of the capture. If not provided we use the original payment description | 255 |
amount | No | The amount to capture. If not provided we use the original payment amount. The currency used will be the currency of the original payment and the format must be the same | 12 digits in total, of which maximum 2 decimal digits |
webhookUrl | No | The webhook URL invoked for transaction changes. This overrides the merchant webhook if one is present. We do not validate this url | 2000 |
notificationRequests | No | An object which is used to request Notifications for specific events related to this capture. | n/a |
orderLines | No | Optional list of order lines that this capture includes (e.g. For a partial capture, only some of the orderlines are captured. Order Line | n/a |
deliveryInfo | No | Optional list containing one or more delivery information objects for this capture. Note: Currently only supported by payment method klarna . |
500 delivery information objects |
details | No | An object which includes method specific details. Possible values: Method Capture Details. | n/a |
Example
{
"reference": "C1505181754007360.1",
"description": "API Capture Description",
"deliveryInfo": [
{
"shippingCompany" : "DHL EU",
"trackingNumber" : "13456",
"trackingUri" : "http://example/tracking/13456",
"returnShippingCompany" : "DHL EU",
"returnTrackingNumber" : "456789",
"returnTrackingUri" : "http://example/tracking/456789"
}
]
}
These details are possible when capturing a payment which was made using the method terminal
.
Name | Required | Description |
---|---|---|
cardPresent | No | Specify whether the customer’s card has to be present to perform the capture. Defaults to false . |
200
application/json
Example
{
"type" : "capture",
"amount" : 316.35,
"currency" : "eur",
"status" : "PENDING",
"merchantOrderReference" : "8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
"description" : "API Capture Description",
"language" : "eng",
"method" : "card",
"metadata" : "my custom metadata",
"reference" : "C1505181613078800.1",
"brand" : "visa",
"created" : 1431958387914,
"lastUpdate" : 1431958387914,
"statusFinalDate" : 1431958387914
}
The funds reserved with an authorisation can be released with a reversal. A transaction cannot be reversed a second time or when a previous reversal attempt is pending.
Notes:
authorise
can be reversed.card
, klarna
and terminal
can be reversed.Name | Description |
---|---|
type | Fixed value: reversal |
amount | Echo from the Payment |
currency | Echo from the Payment |
status | Possible values: Transaction Status |
merchantOrderReference | Echo from the Payment |
description | The description of the transaction |
language | Echo from the Payment |
method | Echo from the Payment |
brand | Echo from the Payment |
metadata | Echo from the Payment |
reference | A unique reference for the reversal transaction |
originalReference | The unique reference for the payment transaction this payment is attempting to reverse. |
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 reversal was created, epoch timestamp |
lastUpdate | The local server datetime the reversal was updated, epoch timestamp |
statusFinalDate | The local server datetime the reversal reached a final status, epoch timestamp |
failureCode | An error code indication what caused the failure. Possible values: Failure Codes |
/api/v1/reversal
POST
application/json
Name | Required | Description | Max Length |
---|---|---|---|
reference | Yes | The unique reference of the payment to reverse | 255 |
description | No | The description of the reversal. If not provided we use the original payment description | 255 |
webhookUrl | No | The webhook URL invoked for transaction changes. This overrides the merchant webhook if one is present. We do not validate this url | 2000 |
Example
{
"reference": "C1505181754007360.1",
"description": "API Reversal Description"
}
These details are possible when reversing an authorisation which was made using the method terminal
.
Name | Required | Description |
---|---|---|
cardPresent | No | Specify whether the customer’s card has to be present to perform the reversal. Defaults to false . |
200
Example
{
"type" : "reversal",
"amount" : 316.35,
"currency" : "eur",
"status" : "PENDING",
"merchantOrderReference" : "8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
"description" : "API Reversal Description",
"language" : "eng",
"method" : "card",
"metadata" : "my custom metadata",
"reference" : "C1505181613078800.1",
"brand" : "visa",
"created" : 1431958387914,
"lastUpdate" : 1431958387914,
"statusFinalDate" : 1431958387914
}
When it is possible to cancel a payment, a cancelUrl
will be included in the Payment object.
A cancellation is only possible up to a certain point in the payment flow. If the cancel is sent after this point it is rejected. A rejected cancel has no effect on the payment process.
When a LandingPage is cancelled, the underlying child transaction will be cancelled too. If the child transaction is already past the cancellation point, the whole cancel will be rejected.
cancelUrl
or /api/v1/cancel?reference={reference}
POST
application/json
200
application/json
400
application/json
In case a payment (transaction type sale
or authorise
) must no longer be processed, you can void the transaction.
For more information see Void payments
/api/v1/void?reference={reference}
POST
application/json
Name | Required | Description | Max Length |
---|---|---|---|
reference | Yes | The unique reference of the payment to void | 255 |
Example
curl https://api.psp.ccv.eu/api/v1/void?reference=I1506151348179039.1 -u apikey:
204
application/json
400
application/json
Payment method Klarna supports the release of authorized funds of a payment. If the order capture is partial, releasing the remaining amount is allowed. Releasing the authorization of a canceled or non-captured payment is not allowed.
Other payment methods do not support this functionality.
Multiple requests are allowed. The PSP forwards the request only once.
Is used to release the remaining amount of a previous authorization.
/api/v1/release
POST
application/json
Name | Required | Description | Max Length |
---|---|---|---|
reference | Yes | The unique reference of the payment authorisation to release | 255 |
description | No | The description of the release. If not provided we use the original payment description | 255 |
webhookUrl | No | The webhook URL invoked for transaction changes. This overrides the merchant webhook if one is present. We do not validate this url | 2000 |
notificationRequests | No | An object which is used to request Notifications for specific events related to this transaction. |
Example
{
"reference": "K1506151348179039.1",
"description": "Partial Order Shipment",
"webhookUrl" : "https://merchant.ecom/checkout/webhook?order=1234"
}
204
application/json
400
application/json
A transaction can be a Payment (Sale, Credit, Authorise), Refund, Capture, Token or Vault transaction depending on the type.
/api/v1/transaction?reference={reference}
GET
reference
: The unique reference of the transaction, max 255200
application/json
/api/v1/transaction
GET
Name | Required | Description |
---|---|---|
referenceBefore | No | Returns previous payments before this reference |
referenceAfter | No | Returns next payments after this reference |
references | No | Returns the payments that have a references in this list. Example value: reference1,reference2,.. |
originalReferences | No | Returns the payments that are a refund , capture or reversal of another payment with reference in this list. Example value: originalReference1,originalReference2,.. |
merchantOrderReference | No | Returns payments with the exact same merchant order reference |
createdBefore | No | Returns payments created before this timestamp, excluding payments with this create timestamp |
createdAfter | No | Returns payments created after this timestamp, excluding payments with this create timestamp |
amountMinimum | No | Returns payments with the same or a greater amount |
amountMaximum | No | Returns payments with the same or a smaller amount |
type | No | Returns payments with the same type. Possible values: sale , refund , token , credit , authorise , capture or vault |
method | No | Returns payments with the same method. Possible values: Supported Methods |
status | No | Returns payments with the same status. Possible values: Transaction Status |
paidout | No | Returns payments with the same paidout status. This can be yes for all payments, no for transactions that are not yet paid out, and never for transactions that are not collecting. Possible values: yes , no , or never |
paidoutAfter | Conditional | Returns payments paidout after this timestamp, excluding payments with this paidout timestamp |
paidoutBefore | Conditional | Returns payments paidout before this timestamp, excluding payments with this paidout timestamp |
unstructuredReference | No | Returns payments with the same collector payment reference. Only valid for collecting protocols |
paidoutReference | No | Returns the transactions related to that paidoutReference. Can be used to find the transactions that form the payment to the merchant. Only valid for collecting protocols |
orderBy | No | Returns payments ordered by a property. Possible values: reference , created or amount , default: created |
order | No | Returns payments ordered by the direction. Possible values: asc or desc , default: desc |
count | No | Limits the returned payments to the count. Default & maximum: 500 |
We do not support paging using a page parameter, but provide parameters to implement a sliding window. If the response list has the same count as you requested, you may request the next page by using the referenceBefore or the referenceAfter parameter with the data of the first or last item in the list, respectively. The default & maximum value for the count parameter is 500. Changing this value, changes the size of the sliding window.
200
application/json
Example
# First 100 transactions created after 2015/01/01 01:01:01.000, sorted ascending
curl https://api.psp.ccv.eu/api/v1/transaction?createdAfter=1420074061000&count=100&order=asc -u apikey:
[
{
"type" : "sale",
"amount" : 316.35,
"currency" : "eur",
"status" : "success",
"merchantOrderReference" : "CFED8B1C8B9F292500E2E837767900BF2448EE28",
"description" : "A description for an order",
"language" : "eng",
"method" : "card",
"brand" : "visa",
"metadata" : "CFED8B1C8B9F292500E2E837767900BF2448EE28",
"returnUrl" : "http://shop?order=CFED8B1C8B9F292500E2E837767900BF2448EE28",
"entryMode" : "ecom",
"reference" : "AC130090D6C19A09CD4B8B3EECCE199AD895B6E0",
"created" : 1420106400000,
"lastUpdate" : 1420106700000,
"statusFinalDate" : 1420106700000
}, {
"type" : "sale",
"amount" : 316.35,
"currency" : "eur",
"status" : "success",
"paidout" : "yes",
"merchantOrderReference" : "f1699892-25eb-4c1c-9cc3-3e345ccc1cec",
"description" : "A description for an order",
"language" : "nld",
"method" : "ideal",
"metadata" : "I1506151348179039.1",
"reference" : "I1506151348179039.1",
"created" : 1434368898588,
"lastUpdate" : 1434368901391,
"statusFinalDate" : 1434368901391,
"payUrl" : "https://idealtest.secure-ing.com/ideal/issuerSim.do?trxid=0050000101228409&ideal=prob",
"returnUrl" : "http://shop?order=f1699892-25eb-4c1c-9cc3-3e345ccc1cec",
"entryMode" : "ecom"
}
]
Second Example
# Payments with references: C1507300954022980.1,C1507300955272271.1,I1507301136243800.1,I1507301136354361.1
curl https://api.psp.ccv.eu/api/v1/transaction?references=C1507300954022980.1,C1507300955272271.1,I1507301136243800.1,I1507301136354361.1 -u apikey:
[ {
"type" : "sale",
"amount" : 0.40,
"currency" : "eur",
"status" : "success",
"merchantOrderReference" : "ca47e7aa-5d57-42e3-bb53-532006c93d9c",
"description" : "API Payment description",
"language" : "nld",
"method" : "ideal",
"metadata" : "ca47e7aa-5d57-42e3-bb53-532006c93d9c",
"reference" : "I1507301136354361.1",
"created" : 1438248996081,
"lastUpdate" : 1438249968771,
"statusFinalDate" : 1438249968771,
"payUrl" : "https://onlinepayments.ccv.eu",
"returnUrl" : "http://shop?order=f1699892-25eb-4c1c-9cc3-3e345ccc1cec",
"entryMode" : "ecom",
"paidout" : "yes",
"unstructuredReference" : "AFREK. CPSPi BCMC DAT. 20150730/5211 AANT. 2 MREF. Joury Gokel"
}, {
"type" : "sale",
"amount" : 0.20,
"currency" : "eur",
"status" : "success",
"merchantOrderReference" : "e3c56b80-c97c-48b7-91ec-67262e99c628",
"description" : "API Payment description",
"language" : "nld",
"method" : "ideal",
"metadata" : "e3c56b80-c97c-48b7-91ec-67262e99c628",
"reference" : "I1507301136243800.1",
"created" : 1438248985129,
"lastUpdate" : 1438249968768,
"statusFinalDate" : 1438249968771,
"payUrl" : "https://onlinepayments.ccv.eu",
"returnUrl" : "http://shop?order=f1699892-25eb-4c1c-9cc3-3e345ccc1cec",
"entryMode" : "ecom",
"paidout" : "yes",
"unstructuredReference" : "AFREK. CPSPi BCMC DAT. 20150730/5211 AANT. 2 MREF. Joury Gokel"
}, {
"type" : "sale",
"amount" : 0.15,
"currency" : "eur",
"status" : "success",
"merchantOrderReference" : "0c01096f-4122-4dd9-be49-5872a1fb91ad",
"description" : "API Payment description",
"language" : "nld",
"method" : "card",
"metadata" : "0c01096f-4122-4dd9-be49-5872a1fb91ad",
"reference" : "C1507300955272271.1",
"created" : 1438242927232,
"lastUpdate" : 1438246838175,
"statusFinalDate" : 1438246838175,
"payUrl" : "https://onlinepayments.ccv.eu",
"returnUrl" : "http://shop?order=f1699892-25eb-4c1c-9cc3-3e345ccc1cec",
"entryMode" : "ecom",
"brand" : "bcmc",
"token" : "93333333333333076",
"tokenMaskedInput" : "4111XXXXXXXX1111",
"paidout" : "yes",
"unstructuredReference" : "AFREK. CPSPi BCMC DAT. 20150730/5211 AANT. 1 MREF. Joury Gokel"
}, {
"type" : "sale",
"amount" : 316.35,
"currency" : "eur",
"status" : "pending",
"merchantOrderReference" : "0c01096f-4122-4dd9-be49-5872a1fb91ad",
"description" : "API Payment description",
"language" : "nld",
"method" : "card",
"metadata" : "0c01096f-4122-4dd9-be49-5872a1fb91ad",
"reference" : "C1507300954022980.1",
"created" : 1438242842320,
"lastUpdate" : 1438242842320,
"statusFinalDate" : 1438242842320,
"payUrl" : "https://onlinepayments.ccv.eu",
"returnUrl" : "http://shop?order=f1699892-25eb-4c1c-9cc3-3e345ccc1cec",
"entryMode" : "ecom",
"token" : "PENDING"
} ]
Payments are scanned for fraudulent activity and if a payment is seen as suspicious, it will be flagged, meaning manual approval is required. This is exposed in the payment status with the manualApprovalRequired
field set to true
. A transaction in this situation will remain pending until it is either manually approved or rejected by contacting support. Upon confirmation:
FAILED
and the failure code is set to REJECTED
The transaction processing is an asynchronous process and will update the status after an undetermined time. If you have webhooks configured, you’ll be notified accordingly. If not, you should poll the transaction until a final status is reached.
The confirm transaction request is used to manually approve or reject a transaction.
/api/v1/transaction/confirm
POST
application/json
Name | Required | Description |
---|---|---|
reference | Yes | The transaction to approve |
note | Yes | A text message that will be attached to the transaction |
action | Yes | Possible values: approve or reject |
Example
{
"reference" : "C1507301136356120.1",
"note" : "This transaction was considered OK after manual inspection",
"action" : "approve"
}
200
application/json
Until a payment transaction has a final status, you can update the expiration duration.
It is possible for the payment methods banktransfer
and landingpage
.
The update transaction request is used to manually update a transaction’s expiration duration.
/api/v1/transaction/update
POST
application/json
Name | Required | Description |
---|---|---|
reference | Yes | The transaction to update |
expirationDuration | Yes* | The time until payment expiration in ISO 8601 Duration. |
expirationTimestamp | Yes* | The epoch timestamp when the payment should expire. |
‘*’ Expiration fields are mutually exclusive. When both are filled in, an error is returned.
Example
{
"reference" : "C1507301136356120.1",
"expirationDuration" : "P0Y2M1DT0H0M0.001S"
}
200
application/json
We support export of successfully completed transactions in ING’s MT940-format. The operating Mode of the Api Key used decides if the export will contain TEST or LIVE transactions.
An MT940 Customer Statement Message is a message standard for electronic account statements from the Society for Worldwide Interbank Financial Telecommunication (SWIFT). ING MT940 format is based on the standard of SWIFT FIN: Category 9 Cash Management and Customer Status. Many software process the data structured according to this international standard. With this guide, you can deploy the MT940 format itself into your systems.
-- Mijn ING Zakelijk [Download](/documentation/payment_api/general/transaction/export/MT940_ING_NL.pdf)
Mapping of Tag 61 subfields with our transaction details.
Subfield | Length | Content | Mapping | Example |
---|---|---|---|---|
Valuta date | 6!n | YYMMDD | Create date | 150930 |
Booking date | 4!n | MMDD | If paid out the paid out date, else create date | 0930 |
Credit/Debit | 1!x | C or D | type | Sale:C or Refund:D |
Amount | 15n | Transaction amount | Amount | 10.99 |
Transaction type | 4!x | The SWIFT transaction code is used and starts with “N” followed by a transaction type. SWIFT Transaction types are available in the attachments | Fixed value: Transfer | NTRF |
Payment reference | 16x | The payment reference is derived from the transaction during processing. If no payment reference is available, “NONREF” is used | If available your merchant order reference, else NONREF |
Order 1234 |
Transaction reference | 16!x | Starts with “//” followed by a unique ING reference (14 characters) | If available the paid out reference, else 00000000000000 | //00000000000000 |
Additional details | 34x | /TRCD/ |
Fixed value: SEPA Credit Transfer | /TRCD/00100 |
Example
:61:1509280928C316,35NTRF1091fbae-c4f7-45//00000000000000
/TRCD/00100/
Mapping of Tag 86 code words with our transaction details.
Code word | Description | Length | Mapping | Example |
---|---|---|---|---|
/EREF/ |
End to End reference | 35x | Transaction reference | EREF/I15092816080395614.1/ |
/CNTP/ |
Counterpart ID | 131x | If available customer name & customer city | CNTP///John Doe/Brussel/ |
/REMI/ |
Remittance info | max 255x | Contains custom tags /MOP/ and /TXDATE/ . If available the unstructured reference used to collect the sale or pay the refund is prefixed |
REMI/USTD//0ad76e30 AFREK. CPSPi BCMC DAT. 20150923/5266 AANT. 1 MREF. CCV Demo/ |
In addition to these tags which are part of the MT940 spec, the remittance info contains custom tags to facilitate parsing useful information about the transaction.
Code word | Description | Length | Mapping | Example |
---|---|---|---|---|
/MOP/ |
Method of Payment | 3x - 12x | Will contain the payment method or in case of method card the brand. Always uppercase | /MOP/IDEAL |
/TXDATE/ |
Transaction date | 15x | Contains he creation date of the transaction in format ‘YYYYMMDD HHMMSS’ | /TXDATE/20190514 071433 |
Example
:86:/EREF/I15092816080395614.1/
/api/v1/transaction/export/mt940
GET
Name | Required | Description |
---|---|---|
from | Conditional | Returns payments created after this timestamp, including payments with this create timestamp. Must be used with until. |
until | Conditional | Returns payments created before this timestamp, excluding payments with this create timestamp. Must be used with from. |
paidoutAfter | Conditional | Returns payments paidout after this timestamp, including payments with this paidout timestamp. Must be used with paidoutBefore. |
paidoutBefore | Conditional | Returns payments paidout before this timestamp, excluding payments with this paidout timestamp. Must be used with paidoutAfter. |
currency | No | Returns payments with the same currency. Possible values: Currencies. Defaults to EUR |
customIban | No | This value will override your user’s merchant IBAN in the resulting file (if present and not empty) |
Example
{1:F01INGBNL2ABXXX0000000000}{2:I940INGBNL2ABXXXN}{4:
:20:0001461842521445
:25:GE62510007547061EUR
:28C:00000
:60F:C160428EUR0
:62F:C160428EUR0
:64:C160428EUR0
:65:C160428EUR0
:86:/SUM/0/0/0/0/
We support the following payment methods:
Warning
Method Gift is a work in progress not yet available for usage by merchants.
Warning
Giropay will be temporarily unavailable starting 31st of July 2023. We apologise for the inconvenience. For further information, please contact ecommerce@ccv.eu
Additionally our landing page method allows the customer to select a method of choice.
The keys for these are respectively
card
, ideal
, sofort
, paypal
, giropay
, banktransfer
, terminal
, payconiq
, alipay
, klarna
, gift
, sdd
, applepay
and landingpage
.
A payment method where we provide the payment method selection for you.
After you create a landing page transaction, a customer can create a child transaction via the landing page form (where a method can be selected). This transaction can be retrieved using the childReferenceId value. A landing page transaction can have multiple attempts which may result in a child transaction. When a child transaction reaches a final transaction status such as success
or manualintervention
, the landing page (parent) transaction will be updated with the same status.
The general flow will be:
landingpage
payment.When the payment of the chosen method fails within 30 seconds, the customer can retry again using possibly another method.
The default expiration duration is P2M
, which means:
expired
one day later. You will be notified with a webhook when the payment eventually expired.It’s possible to preselect a payment method for landing page usage. This will attempt to create a new payment for this method when the customer accesses the landingpage via the payurl. The customer will be redirected to the method payment page right away without selecting a method. If the method is invalid, not available to the merchant or not allowed, the value will be disregarded and the landing page is displayed with all available methods.
Methods that do not support preselection:
Example of a landingpage payment request with a method preselection
{
"amount" : 100.00,
"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 with method preselection ideal",
"language" : "eng",
"details" : {
"expirationDuration" : "P0Y2M1DT0H0M0.000S",
"preselectedMethod" : "ideal"
}
}
As a merchant can have multiple payment methods enabled for landing page use, the merchant can optimize the list by limiting the payment methods shown, or changing the default order.
Each method name must be correct, and at least one from the list must match an enabled payment method. The PSP ignores payment methods that are not available to the merchant.
Klarna is not supported If the merchant requests Klarna, it is ignored and not visible on the customers’ payment page.
Example of a landingpage payment request with a list of allowed payment methods
{
"amount" : 20.00,
"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 with a list of methods to ",
"language" : "eng",
"details" : {
"allowedPaymentMethods" : ["ideal", "gift"]
}
}
The method request is used to return a list of available payment methods for the merchant. The list is a JSON array containing an item per method. Each item contains the method name and method specific options.
/api/v1/method
GET
200
application/json
Example
curl https://api.psp.ccv.eu/api/v1/method -u apikey:
[
{
"method": "card",
"options": [
{
"brand": "visa"
},
{
"brand": "mastercard"
},
{
"brand": "maestro"
},
{
"brand": "bcmc"
}
]
},
{
"method": "ideal",
"options": [
{
"group": "Nederland",
"grouptype": "country",
"issuerdescription": "Issuer Simulation V3 - ING",
"issuerid": "INGBNL2A"
},
{
"group": "Nederland",
"grouptype": "country",
"issuerdescription": "Issuer Simulation V3 - RABO",
"issuerid": "RABONL2U"
}
]
},
{
"method": "sofort"
},
{
"method": "paypal"
},
{
"method": "landingpage"
},
{
"method": "banktransfer"
},
{
"method": "giropay",
"options": [
{
"issuerdescription": "Test HBCI PIN/TAN Institut III",
"issuerid": "TESTDETT310"
},
{
"issuerdescription": "Deutsche Bank Fil Berlin",
"issuerid": "DEUTDEDBBER"
}
]
},
{
"method": "payconiq",
"options": [
{
"qr" : "true"
}
]
},
{
"method": "gift",
"options": [
{
"giftacquirer" : "connect",
"giftbrand" : "City Loyalty Deluxe"
},
{
"giftacquirer" : "connect",
"giftbrand" : "CCV Thanks Gift Card",
"imageurl" : "http://ccvthanksbrand/imageurl.png"
}
]
},
{
"method": "klarna",
"options": [
{
"qr" : "true"
}
]
},
{
"method": "sdd"
},
{
"method": "applepay"
}
]
Name | Description |
---|---|
method | Fixed value: card |
options | An array of specific options for the card method |
options[x].brand | Possible values: Supported Brands |
options[x].qr | If payment via QR code is possible. Only shown as true when possible. |
Name | API name |
---|---|
Visa | visa |
MasterCard | mastercard |
Maestro | maestro |
Bancontact | bcmc |
American Express | amex |
iDEAL 1.0 specifications require you to group the issuers. You should group the items with the same group
, as required by the iDEAL 1.0 specification (version 3.3.1). This is currently by country.
Name | Description |
---|---|
method | Fixed value: ideal |
options | An array of specific options for the iDEAL method |
options[x].group | Contains the group specifier, such as for example the country names in the official languages of the country, separated by a ‘/’ (e.g. ‘België/Belgique’) |
options[x].grouptype | Specifies the type of group, currently fixed value: country |
options[x].issuerdescription | The description of the issuer (as this should be displayed to the customer in the merchant’s issuer list, e.g. ‘ABN AMRO’) |
options[x].issuerid | Unique identifier of the issuer used within iDEAL |
For iDEAL 2.0 the issuer selection is moved to the iDEAL environment. This means the method response no longer contains any issuer information.
Name | Description |
---|---|
method | Fixed value: ideal |
!INFO The use of iDEAL 2.0 depends on your payment method configuration. Please contact ecommerce@ccv.eu for more information regarding iDEAL 2.0.
Name | Description |
---|---|
method | Fixed value: sofort |
Sofort currently has no options.
Name | Description |
---|---|
method | Fixed value: paypal |
PayPal currently has no options.
Name | Description |
---|---|
method | Fixed value: landingpage |
LandingPage currently has no options.
Name | Description |
---|---|
method | Fixed value: banktransfer |
BankTransfer currently has no options.
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 |
---|---|
method | Fixed value: giropay |
options | An array of specific options for the GiroPay method |
options[x].issuerdescription | The description of the issuer (as this should be displayed to the customer in the merchant’s issuer list, e.g. ‘Deutsche Bank’). |
options[x].issuerid | Unique identifier of the issuer used within GiroPay. |
Name | Description |
---|---|
method | Fixed value: terminal |
Terminal currently has no options.
Name | Description |
---|---|
method | Fixed value: payconiq |
qr | If payment via QR code is possible. Only shown as true when possible. |
Name | Description |
---|---|
method | Fixed value: klarna |
qr | If payment via QR code is possible. Only shown as true when possible. |
Name | Description |
---|---|
method | Fixed value: gift |
options | An array of brands specific for the gift method |
options[x].giftbrand | Specifies one of the gift brands available to the merchant |
options[x].giftacquirer | Contains the acquirer for the gift brand |
options[x].imageurl | Contains an image url for the gift brand if present |
Name | Description |
---|---|
method | Fixed value: sdd |
SDD currently has no options.
Name | Description |
---|---|
method | Fixed value: applepay |
Apple Pay currently has no options.
For enabled collecting methods a balance can be given or requested to show why an action has failed, or to allow a merchant to see which actions will be possible depending on the available balance. For example, when a refund fails the balance calculated during the process will be returned to show the merchant is short if applicable.
Name | Description |
---|---|
creditAmount | The sum of all refunds not yet paid out |
debitAmount | The sum of all sales and captures not yet paid out |
total | The total available balance. The difference between debitAmount and creditAmount |
brand | Present if obtained via the balance request. Uniquely identifies the balance amount for a specific brand of methods card or applepay |
country | Present if obtained via the balance request. Uniquely identifies the balance amount for a specific customer’s billingCountry of method banktransfer |
The balance request is used to return a list of available payment methods for the merchant with the associated balance amounts. The list is a JSON array containing an item per method. Each item contains the method name and available balance(s).
/api/v1/balance
GET
200
application/json
Example
curl https://api.psp.ccv.eu/api/v1/balance -u apikey:
Example with list of method names
curl https://api.psp.ccv.eu/api/v1/balance?methods=card,ideal,payconiq,alipay,applepay -u apikey:
[
{
"method": "ideal",
"balances": [
{
"creditAmount": 0,
"debitAmount": 0.10,
"total": 0.10
}
]
},
{
"method": "card",
"balances": [
{
"creditAmount": 0,
"debitAmount": 19.98,
"total": 19.98,
"brand": "bcmc"
}
]
},
{
"method": "payconiq",
"balances": [
{
"creditAmount": 0,
"debitAmount": 0,
"total": 0
}
]
},
{
"method": "alipay",
"balances": [
{
"creditAmount": 0,
"debitAmount": 0,
"total": 0
}
]
},
{
"method": "applepay",
"balances": [
{
"creditAmount": 0,
"debitAmount": 0,
"total": 0,
"brand": "visa"
},
{
"creditAmount": 0,
"debitAmount": 19.98,
"total": 19.98,
"brand": "bcmc"
}
]
}
]
A simple endpoint to query for the status of the PSP.
The execution will not check for the status of the payment methods. To get an indication of what methods are available, see the Method resource.
Name | Description |
---|---|
app.name | The name of the application |
app.version | The current version of the application |
server.localtime | The current datetime of the server, epoch timestamp |
/api/v1/status
GET
200
application/json
Example
curl https://api.psp.ccv.eu/api/v1/method -u apikey:
{
"app":
{
"name": "VPOS",
"version": "1.1"
},
"server":
{
"localtime": 1420106400000
}
}
Name | Description |
---|---|
terminalId | The terminal id as assigned by CCV |
installationStatus | The status of the installation. Possible values are: installed and not_installed |
installationPayload | Installation Payload to be used to complete a softpos terminal installation through the mobile application |
Example
{
"terminalId" : "SP001",
"installationStatus": "installed",
"installationPayload" : "IfhGLwDjRrr4mgeFOVr6tkA"
}
Read the terminal information for a specific SoftPos terminal. An error response is returned when a call is performed towards this endpoint prior to the installation call.
/api/v1/softpos/terminal/{terminalId}
GET
Example
curl https://api.psp.ccv.eu/api/v1/softpos/terminal/123456 -u apikey:
200
application/json
Start the installation procedure for a specific SoftPos terminal.
/api/v1/softpos/terminal/{terminalId}/install
POST
Example
curl https://api.psp.ccv.eu/api/v1/softpos/terminal/123456/install -u apikey:
200
application/json
Complete the installation procedure for a specific SoftPos terminal. An error response is returned when a call is performed towards this endpoint prior to the installation call.
/api/v1/softpos/terminal/{terminalId}/install-completed
POST
Example
curl https://api.psp.ccv.eu/api/v1/softpos/terminal/123456/install-completed -u apikey:
200
application/json
Uninstall a specific SoftPos terminal. An error response is returned when a call is performed towards this endpoint prior to the installation completed call.
/api/v1/softpos/terminal/{terminalId}/uninstall
POST
Example
curl https://api.psp.ccv.eu/api/v1/softpos/terminal/123456/uninstall -u apikey:
200
application/json
A token resource represents a tokenized PAN or IBAN.
Note: if you call the token resource in operating mode TEST, you will not get a real token. The simulated token contains the reversed pan with a prefix and should not be used to store in a production system.
The general flow is:
We do not expose the token to the customer. It is up to you to verify the status of the token request and act accordingly. Webhooks are provided to give you feedback, but this principle remains.
Two types of token are supported, being card
tokens and web
tokens.
A card
token is a token calculated from the complete PAN of a credit or debit card. This token will always consist of the prefix 99
followed by 16 characters given a token of 18 characters long.
Example 991234567890123456
A web
token is calculated on (part of) the IBAN of a debit card. Reason for this addition to the Token Service Provider is that there are countries where the banks do no print the PAN on their debit cards. Examples are the Netherlands and Germany.
For the Netherlands the IBAN is as follows
Example NL91ABNA0417164300
NL
)91
)ABNA
)0417164300
)The NL Web Token is calculated using the 10 char account number and is prefixed with 96
.
Note: The banks BUNQ and KNAB are not supported in the TSP. Example 961234567890123456
For Germany the IBAN is as follows
Example DE89370400440532013000
DE
)89
)37040044
)0532013000
)The bank code needs to be converted to the institute number using the table from the Bundesbank Germany.
The NL Web Token is calculated using the institute number and the account number and is always prefixed with 95
.
For other countries there is no support for token calculation based on IBAN.
Name | Description |
---|---|
type | Fixed value: token |
token | The token, a max 18 long string identifying the given PAN/IBAN |
tokenMaskedInput | If a token was created, the input (PAN or IBAN) will be returned, masked. |
status | Possible values: Transaction Status |
description | A description to show the customer |
language | The language of the customer. Possible values: Languages |
metadata | An arbitrary, max 255 character long string that can be used to track payments |
payUrl | To complete the tokenization request the customer should be redirected to this URL. |
returnUrl | After tokenization is completed (successfully or otherwise) the customer is redirected to this URL |
reference | A unique reference for the tokenization request |
created | The local server datetime the tokenization request was created, epoch timestamp |
lastUpdate | The local server datetime the tokenization request was updated, epoch timestamp |
statusFinalDate | The local server datetime the tokenization request reached a final status, epoch timestamp |
failureCode | An error code indication what caused the failure. Possible values: Failure Codes |
cardDataUrl | To complete a card tokenization request the customer can also submit card data directly to this URL using an HTTP post. |
Example
{
"type" : "token",
"token" : "998171576462127534",
"tokenMaskedInput" : "DE60xxxxxxxxxxxxxx6789",
"status" : "success",
"description" : "A token description",
"language" : "eng",
"metadata" : "CFED8B1C8B9F292500E2E837767900BF2448EE28",
"reference" : "AC130090D6C19A09CD4B8B3EECCE199AD895B6E0",
"created" : 1420106400000,
"lastUpdate" : 1420106700000,
"statusFinalDate" : 1420106700000,
"returnUrl" : "http://shop?order=CFED8B1C8B9F292500E2E837767900BF2448EE28"
}
The token request is used to create a new token.
/api/v1/token
POST
application/json
Name | Required | Method | Description |
---|---|---|---|
returnUrl | Yes | All | The URL to redirect the customer to after completion of the tokenization request (both success and failure scenarios) |
metadata | No | All | An arbitrary, max 255 long string that can be used to track tokenization requests |
description | No | All | A description to show the customer |
language | Yes | All | The language of the customer. Possible values: Languages |
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 |
tokenType | No | All | The type of token that is requested. Possible values: card or web . Default is card |
Example
{
"returnUrl" : "http://shop?order=436D2D8278789F4B2D618E301C875708B58F7A82",
"metadata" : "436D2D8278789F4B2D618E301C875708B58F7A82",
"description" : "API token description",
"language" : "eng",
"tokenType" : "card"
}
200
application/json
The token read request is used to read information of a given token.
/api/v1/token?reference={reference}
GET
reference
: The unique reference of the token request200
application/json
If you have a PCI compliant environment you can also choose to transmit the sensitive PAN or IBAN information directly to obtain a token. Either the PAN or the IBAN should be filled in and a token will be calculated accordingly.
/api/v1/token/pci
POST
application/json
Name | Required | Description |
---|---|---|
pan | No | The PAN, without spaces or any other separation characters, with a maximum of 19 characters |
iban | No | The IBAN, must be valid, without spaces or any other separation characters |
metadata | No | An arbitrary, max 255 long string that can be used to track token requests |
Example
curl https://api.psp.ccv.eu/api/v1/token/pci -u apikey:
{
"pan" : "6799998900000010062",
"metadata" : "436D2D8278789F4B2D618E301C875708B58F7A82"
}
200
application/json
{
"metadata": "436D2D8278789F4B2D618E301C875708B58F7A82",
"reference": "T1506161514118975.1",
"token": "995336783076747372",
"tokenMaskedInput" : "6799xxxxxxxxxxx0062"
}
Normally the payUrl is used to obtain the token data from the customer or token data is directly supplied via token 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/token/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 |
Example
{
"pan": "67032222222222227"
}
200
The vault resource can be used to store sensitive data in our vault. This data is stored in an encrypted form. When storing something in the vault, through a process called Vault Enrollment, a Vault Access Token will be returned. The Vault Access Token is used to retrieve the stored information, and allows actions to be performed with the stored information through the VPOS API.
A Vault Access Token is obtained by performing an initial vault enrollment process. The enrollment can be achieved in two ways:
storeInVault
field when performing a payment request (currently only supported for card
payments).The vault enrollment process creates two transactions: a parent vault transaction and a child transaction. The parent vault transaction contains the Vault Access Token and a reference to the child transaction (childReferenceId
). The child transaction is created to validate the sensitive information (e.g. for the card
vault data type the child transaction is used to validate the card and authenticate the cardholder).
A vault transaction can only have 1 child transaction. When the child transaction reaches a final transaction status such as success
or manualintervention
, the vault (parent) transaction will be updated with the same status.
The general vault enrollment request flow is:
We do not expose the status of the vault transaction or any of its details to the customer. It is up to you to verify the status of the vault transaction and act accordingly. Webhooks are provided to give you feedback, but this principle remains.
After obtaining a Vault Access Token, there are three actions that can be taken in the system.
Name | Description |
---|---|
status | Possible values: Transaction Status |
merchantOrderReference | A reference, maximum 255 characters, of the order associated with this vault transaction |
description | A description to show the customer |
language | The language of the customer. Possible values: Languages |
method | Fixed value vault |
brand | The brand of the card that was entered by the user. Only included when the dataType is card |
metadata | An arbitrary string, maximum 255 characters, that can be used to track vault transactions |
payUrl | To complete the vault request the customer should be redirected to this URL. |
returnUrl | After vault data storage is completed (successfully or otherwise) the customer is redirected to this URL |
reference | A unique reference for the vault transaction |
created | The local server datetime the vault transaction was created, epoch timestamp |
lastUpdate | The local server datetime the vault transaction was updated, epoch timestamp |
statusFinalDate | The local server datetime the vault transaction reached a final status, epoch timestamp |
failureCode | An error code indication what caused the failure. Possible values: Failure Codes |
details | An optional object listing specific vault details: Vault Details |
notificationRequests | An object which is used to request Notifications for specific events related to this vault transaction. |
Example
{
"status" : "success",
"merchantOrderReference" : "8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
"description" : "API Vault description",
"language" : "eng",
"method" : "vault",
"brand" : "bcmc",
"metadata" : "my custom metadata",
"reference" : "V1505181754007360.1",
"created" : 1431964440770,
"lastUpdate" : 1431964458858,
"statusFinalDate" : 1431964458858,
"payUrl" : "https://onlinepayments.ccv.eu/vault/card.html?reference=C1505181754007360.1",
"returnUrl" : "http://shop/?order=8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
"details" : {
"expirationDuration" : "P0Y2M1DT0H0M0.000S",
"vaultAccessToken" : "5C810B0AD0B1BC0926EBEA53"
}
}
The expiration of the vault token is configurable by account. By default this is set to 30 days. In some scenarios you want the default expiration set to the card expiry date. This is also configurable by account.
Name | Description |
---|---|
expirationDuration | The time after which the vault access token expires in ISO 8601 Duration |
expirationTimestamp | The datetime on which the vault access token will be expired after epoch timestamp |
vaultAccessToken | The Vault Access Token |
dataType | The data type that is stored in the vault for this Vault Access Token. At this moment only card is supported |
maskedPan | The masked primary account number. Only included when the dataType is card |
expiryDate | The expiry date of the card in format MMYY. Only included when the dataType is card |
scaToken | 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. Only included when the dataType is card |
brand | The brand of the card. |
Example
{
"dataType" : "card",
"expirationDuration" : "P0Y2M1DT0H0M0.000S",
"expirationTimestamp" : 1420106400000,
"vaultAccessToken" : "5C810B0AD0B1BC0926EBEA53",
"maskedPan": "xxxxxxxxxxxx4242",
"expiryDate": "0424",
"scaToken": false,
"brand": "visa"
}
Name | Sensitive | Description |
---|---|---|
token | no | The Vault Access Token |
eraseTimestamp | no | The date that this token will be erased from the database, epoch timestamp |
referenceId | no | A unique reference for the vault transaction |
merchantOrderReference | no | An arbitrary string, maximum 255 characters, that can be used to track vault transactions |
pan | yes | The primary account number |
maskedPan | no | The masked primary account number |
expiryDate | no | The expiry date |
cardholderFirstName | no | The first name of the cardholder |
cardholderLastName | no | The last name of the cardholder |
created | no | The local server datetime the vault transaction was created, epoch timestamp |
The vault initiate request is used to create a new vault access token.
/api/v1/vault/initiate
POST
application/json
Name | Required | Description |
---|---|---|
dataType | Yes | The data type that should be requested from the customer. At this moment only card is supported |
brand | No | The card brand selected by the customer. Possible values: Supported Brands |
returnUrl | Yes | After the payment is completed (successfully or otherwise) the customer is redirected to this URL. |
language | Yes | The language of the customer. Defines the language to be used in the payment screens the customer will see. Possible values: Languages |
metadata | No | An arbitrary string, maximum of 255 characters, that can be used to track payments |
merchantOrderReference | No | A reference, maximum of 255 characters, of the order associated with this payment |
description | No | A description to show the customer |
webhookUrl | No | The webhook URL invoked for transaction changes. This overrides the merchant webhook if one is present. We do not validate this url |
scaReady | No | Indicates that the vault request 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 |
billingAddress | Conditional | The billing street address.{BR}{BR}Required when scaReady is set to yes . |
billingCity | Conditional | The billing city of the customer.{BR}{BR}Required when scaReady is set to yes . |
billingState | Conditional | 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. |
billingPostalCode | Conditional | The billing postal (zip) code of the customer.{BR}{BR}Required when scaReady is set to yes . |
billingCountry | Conditional | The billing country of the customer, an ISO 3166 alpha-2 code. See for more info: Country Codes - ISO 3166.{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. |
billingEmail | Conditional | The billing email of the customer.{BR}{BR}Required when scaReady is set to yes . Must be a valid email address if present. |
billingPhoneNumber | Conditional | 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. |
billingPhoneCountry | Conditional | 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. |
billingFirstName | No | The billing first name of the customer |
billingLastName | No | The billing last name of the customer |
billingHouseNumber | No | The billing house number of the customer |
billingHouseExtension | No | The billing house extension of the customer |
shippingAddress | Conditional | The shipping street address.{BR}{BR}Required when shipping provided* if scaReady is set to yes . |
shippingCity | Conditional | The shipping address city.{BR}{BR}Required when shipping provided* if scaReady is set to yes . |
shippingState | Conditional | The shipping address region/state, an ISO 3166-2 country subdivision code.{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. |
shippingPostalCode | Conditional | The shipping address postal (zip) code.{BR}{BR}Required when shipping provided* if scaReady is set to yes . |
shippingCountry | Conditional | 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. |
shippingEmail | No | The shipping email of the custom. Must be a valid email address if present. |
shippingPhoneNumber | No | 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. |
shippingPhoneCountry | No | 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. |
shippingFirstName | No | The shipping first name of the customer |
shippingLastName | No | The shipping last name of the customer |
shippingHouseNumber | No | The shipping house number of the customer |
shippingHouseExtension | No | The shipping house extension of the customer |
notificationRequests | No | An object which is used to request Notifications for specific events related to this vault token initiation. |
!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
{
"dataType" : "card",
"returnUrl" : "http://shop/?order=8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
"metadata" : "my custom metadata",
"merchantOrderReference" : "8cdbb73f-6537-4b7f-a6de-6ddab6c283e1",
"description" : "API Vault description",
"language" : "eng"
}
200
application/json
Create a new vault request from a PCI compliant environment.
/api/v1/vault/token
POST
application/json
Name | Required | Description |
---|---|---|
merchantOrderReference | No | An arbitrary string, maximum 255 characters, that can be used to track vault transactions |
pan | Yes | The primary account number |
expiryDate | Yes | The expiry date |
cardholderFirstName | No | The first name of the cardholder |
cardholderLastName | No | The last name of the cardholder |
Example
{
"merchantOrderReference" : "abcddd",
"pan" : "6799998900000123456",
"expiryDate" : "1803"
}
200
application/json
Name | Description |
---|---|
token | The Vault Access Token |
eraseTimestamp | The date that this token will be erased from the database, in the format ISO 8601 DateTime |
referenceId | A unique reference for the vault transaction |
merchantOrderReference | An arbitrary string, maximum 255 characters, that can be used to track vault transactions |
created | The local server datetime the vault transaction was created, epoch timestamp |
lastUpdate | The local server datetime the vault transaction was updated, epoch timestamp |
statusFinalDate | The local server datetime the vault transaction reached a final status, epoch timestamp |
This operation retrieves the sensitive data that was stored in the vault and returns it in plain text. The sensitive data can only be retrieved in plain text when this is allowed for your account. Default this is turned off, and will only be turned on when requested by the account owner.
/api/v1/vault/token
GET
application/json
vaultToken
: The vault access token for which the data must be retrieved.200
application/json
Example of retrieval with non-sensitive data because not allowed by configuration
curl https://api.psp.ccv.eu/api/v1/vault/token?vaultToken=TOKEN1 -u apikey:
{
"eraseTimestamp" : 1543155649042,
"referenceId" : "V181026162049038CB87E190.1",
"merchantOrderReference" : "321",
"maskedPan" : "4111XXXXXXXX1111",
"expiryDate" : "1221",
"cardholderFirstName" : "John",
"cardholderLastName" : "Doe"
}
This operation explicitly erases the sensitive data from the vault.
/api/v1/vault/token
DELETE
Name | Required | Description |
---|---|---|
vaultToken | Conditional | The vault access token. If present, merchantOrderReference must not be present |
merchantOrderReference | Conditional | The merchant order reference. If present vaultToken must not be present. |
Example
# Delete the vault token using the merchant order reference 321
curl https://api.psp.ccv.eu/api/v1/vault/token?merchantOrderReference=321 -u apikey:
200
application/json
The mandate API resource can be used to acquire mandates from the customers to allow easy merchant initiated
transactions in the future. When creating a mandate, a mandateId
is returned. This mandateId
can later be used for all kinds of actions, including sending the mandateId
with a new payment request, to indicate it’s a new payment for that specific mandate.
A mandate is obtained by performing an initial mandate creation process. The creation can be achieved through a mandate create request:
The mandate creation process creates two entities: the mandate itself and a child transaction. The mandate contains the
mandate Id and a reference to the child transaction (childReferenceId
). The child transaction is created to gain the
actual mandate (e.g. for the SEPA_DIRECT_DEBIT
mandate type the child transaction is used to sign a mandate using an
external party Twikey).
A mandate entity can only have 1 child transaction. When the child transaction reaches a
final transaction status such as success
or manualintervention
, the mandate will be updated
with the same corresponding mandate status.
An optional amount can be added when creating a mandate and triggers the first payment of that mandate. The payment information is then used to sign the mandate. When no amount is specified, alternative ways to sign the mandate will be presented to the customer, eg. SMS, iDIN, itsme, …
The general mandate creation request flow is:
signUrl
from the response.returnUrl
provided in
the create a new mandate.only an active mandate can be used for payments.
We do not expose the status of the mandate or any of its details to the customer. It is up to you to verify the status of the mandate transaction and act accordingly. Webhooks and Notifications are provided to give you feedback, but this principle remains.
Name | Description |
---|---|
status | Possible values: Mandate Status |
merchantOrderReference | A reference, maximum 255 characters, of the merchant order reference associated with this mandate |
signUrl | To complete the mandate create request the customer should be redirected to this URL. |
returnUrl | After the mandate creation is completed (successfully or otherwise) the customer is redirected to this URL |
externalMandateReference | The unique reference of the mandate given by the external mandate party |
created | The local server datetime the mandate was created, epoch timestamp |
modified | The local server datetime the mandate was modified, epoch timestamp |
details | An optional object listing specific mandate details: Mandate Details |
signed | The local server datetime the mandate was signed, epoch timestamp |
mandateId | The Id of the mandate uniquely given by CCV. |
type | The Type of the mandate, possible values: Mandate Type |
amount | The amount used in the first payment of the current mandate. Specifying an amount will trigger the first payment automatically |
notificationRequests | An object which is used to request Notifications for specific events related to this mandate. |
Example
{
"status": "active",
"externalMandateReference": "CCV98",
"mandateId": "50d2f91c-9a4d-4205-b443-24ae24b316a3",
"signed": 1622705674332,
"type": "sepa_direct_debit",
"merchantOrderReference": "1234678",
"modified": 1622705674384,
"signUrl": "https://urlToSign",
"created": 1622705598302,
"returnUrl": "https://google.be",
"amount": 4.78,
"details": {
"customerCountry": "BEL",
"customerLanguage": "nld",
"customerFirstName": "Dirk",
"customerEmail": "d.teur@ccvlab.eu",
"sddDetails": "{\"Mndt\":{\"MndtId\":\"CCV98\",\"LclInstrm\":\"CORE\",\"Ocrncs\":{\"SeqTp\":\"RCUR\",\"Frqcy\":\"ADHO\",\"Drtn\":{\"FrDt\":\"2021-06-03\"}},\"CdtrSchmeId\":\"BE46ZZZ00000084920\",\"Cdtr\":{\"Nm\":\"CCV Belgium NV\",\"PstlAdr\":{\"AdrLine\":\"Ter Waarde 48\",\"PstCd\":\"8900\",\"TwnNm\":\"Ieper\",\"Ctry\":\"BE\"},\"Id\":\"BE0897971214\",\"CtryOfRes\":\"BE\",\"CtctDtls\":{\"EmailAdr\":\"xx\"}},\"Dbtr\":{\"Nm\":\"Dirk Teur\",\"PstlAdr\":{\"AdrLine\":\"XX\",\"PstCd\":\"3500\",\"TwnNm\":\"Hasselt\",\"Ctry\":\"BE\"},\"CtryOfRes\":\"BE\",\"CtctDtls\":{\"EmailAdr\":\"d.teur@ccvlab.eu\"}},\"DbtrAcct\":\"BE31798258915655\",\"DbtrAgt\":{\"FinInstnId\":{\"BICFI\":\"GKCCBEBB\",\"Nm\":\"BELFIUS BANK\"}},\"RfrdDoc\":\"TAR2014\",\"SplmtryData\":[{\"Key\":\"TRACKER\",\"Value\":\"53jz\"},{\"Key\":\"token\",\"Value\":\"SDD210603093318246CB87E192.1\"},{\"Key\":\"MandateName\",\"Value\":\"Mandate for direct debit terminal\"},{\"Key\":\"TemplateId\",\"Value\":330},{\"Key\":\"Terminal type\",\"Value\":null},{\"Key\":\"FirstName\",\"Value\":\"Dirk\"},{\"Key\":\"LastName\",\"Value\":\"Teur\"},{\"Key\":\"Language\",\"Value\":\"en\"},{\"Key\":\"SignerMethod#0\",\"Value\":\"mock\"},{\"Key\":\"Signer#0\",\"Value\":\"Twikey Mock Signer\"},{\"Key\":\"SignerPlace#0\",\"Value\":\"Genk\"},{\"Key\":\"SignerDate#0\",\"Value\":\"2021-06-03T07:34:28Z\"}]}}",
"customerLastName": "Teur"
}
}
Name | Description |
---|---|
SEPA_DIRECT_DEBIT | Create a mandate to use with payments using the method sdd . |
PAYPAL | Create a mandate to use with payments using the method paypal . |
Name | Description |
---|---|
PENDING | This mandate is still is the process of being signed. |
ACTIVE | This mandate is active and ready to be used. |
INACTIVE | This mandate is not active and cannot be used with a payment. |
For each given mandate-type, there are specific details. Besides these specific details, there are also general details that apply to all mandates.
Name | Description |
---|---|
customerFirstName | The first name of the customer |
customerLastName | The last name of the customer |
customerEmail | The email of the customer |
customerLanguage | The language of the customer |
customerCountry | The country code of the customer |
Example
{
"customerCountry": "BEL",
"customerLanguage": "nld",
"customerFirstName": "Dirk",
"customerEmail": "d.teur@ccvlab.eu",
"customerLastName": "Teur"
}
Contains the raw sdd details
Name | Description |
---|---|
sddDetails | Specific details of a SEPA_DIRECT_DEBIT mandate |
Example
{
"sddDetails": "{\"Mndt\":{\"MndtId\":\"CCV98\",\"LclInstrm\":\"CORE\",\"Ocrncs\":{\"SeqTp\":\"RCUR\",\"Frqcy\":\"ADHO\",\"Drtn\":{\"FrDt\":\"2021-06-03\"}},\"CdtrSchmeId\":\"BE46ZZZ00000084920\",\"Cdtr\":{\"Nm\":\"CCV Belgium NV\",\"PstlAdr\":{\"AdrLine\":\"Ter Waarde 48\",\"PstCd\":\"8900\",\"TwnNm\":\"Ieper\",\"Ctry\":\"BE\"},\"Id\":\"BE0897971214\",\"CtryOfRes\":\"BE\",\"CtctDtls\":{\"EmailAdr\":\"xx\"}},\"Dbtr\":{\"Nm\":\"Dirk Teur\",\"PstlAdr\":{\"AdrLine\":\"XX\",\"PstCd\":\"3500\",\"TwnNm\":\"Hasselt\",\"Ctry\":\"BE\"},\"CtryOfRes\":\"BE\",\"CtctDtls\":{\"EmailAdr\":\"d.teur@ccvlab.eu\"}},\"DbtrAcct\":\"BE31798258915655\",\"DbtrAgt\":{\"FinInstnId\":{\"BICFI\":\"GKCCBEBB\",\"Nm\":\"BELFIUS BANK\"}},\"RfrdDoc\":\"TAR2014\",\"SplmtryData\":[{\"Key\":\"TRACKER\",\"Value\":\"53jz\"},{\"Key\":\"token\",\"Value\":\"SDD210603093318246CB87E192.1\"},{\"Key\":\"MandateName\",\"Value\":\"Mandate for direct debit terminal\"},{\"Key\":\"TemplateId\",\"Value\":330},{\"Key\":\"Terminal type\",\"Value\":null},{\"Key\":\"FirstName\",\"Value\":\"Dirk\"},{\"Key\":\"LastName\",\"Value\":\"Teur\"},{\"Key\":\"Language\",\"Value\":\"en\"},{\"Key\":\"SignerMethod#0\",\"Value\":\"mock\"},{\"Key\":\"Signer#0\",\"Value\":\"Twikey Mock Signer\"},{\"Key\":\"SignerPlace#0\",\"Value\":\"Genk\"},{\"Key\":\"SignerDate#0\",\"Value\":\"2021-06-03T07:34:28Z\"}]}}"
}
/api/v1/mandate
POST
application/json
Name | Required | Description |
---|---|---|
merchantOrderReference | No | A reference, maximum of 255 characters, of the order associated with this mandate |
returnUrl | Yes | After the contract is completed (successfully or otherwise) the customer is redirected to this URL. |
type | Yes | The type of the mandate to be created. Possible values Mandate Types |
amount | No | An optional amount to start the first payment and to use that payment to sign the mandate. The amount can contain up to 12 digits in total, including a maximum of 2 decimal digits. |
details | No | Details specific for the type of mandate |
notificationRequests | No | An object which is used to request Notifications for specific events related to this mandate. |
Name | Required | Description |
---|---|---|
customerFirstName | Yes | The first name of the customer |
customerLastName | Yes | The last name of the customer |
customerEmail | Yes | The email of the customer to which the contract is mailed. |
customerLanguage | Yes | The language of the customer. Defines the language to be used in the payment screens the customer will see. Possible values: Languages |
customerCountry | Yes | The country of the customer, an ISO 3166 alpha-2 code. See for more info: Country Codes - ISO 3166. |
customerZip | No | The zip/postal code of the customer. Should be filled in if the other address fields are filled in. |
customerAddress | No | The address of the customer. Should be filled in if the other address fields are filled in. |
customerCity | No | The city of the customer. Should be filled in if the other address fields are filled in. |
Example
{
"details": {
"customerLanguage": "nld",
"customerFirstName": "Dirk",
"customerEmail": "d.teur@ccvlab.eu",
"customerLastName": "Teur",
"customerCountry": "BEL",
"customerZip": "8500",
"customerAddress": "Spinnerijstraat 99/Bus 12",
"customerCity": "Kortrijk"
},
"merchantOrderReference" : "1234678",
"type": "SEPA_DIRECT_DEBIT",
"returnUrl" : "https://google.be"
}
200
application/json
This operation returns all data from a given mandate.
/api/v1/mandate/{id}
GET
application/json
200
application/json
This operation returns all data from all mandates.
/api/v1/mandate
GET
application/json
200
application/json
This operation returns all transactions initiated using the given mandate.
/api/v1/mandate/{id}/transactions
GET
application/json
200
application/json
The mandate revoke process will adjust two entities: the mandate itself and the Twikey mandate. The mandate status is set to the inactive mandate status after a request is sent to Twikey to cancel the mandate.
The general mandate revoke request is a simple DELETE request.
/api/v1/mandate/{mandateId}
DELETE
Name | Required | Description |
---|---|---|
mandateId | Yes | The mandate id of the mandate that should be revoked |
200
200 if revoke is ok
/api/v1/mandate/{mandateId}
PUT
application/json
Name | Required | Description |
---|---|---|
mandateId | Yes | The mandate id of the mandate that should be updated |
Name | Required | Description |
---|---|---|
details | Yes | General Details and/or details specific for the type of mandate |
The details
parameter is required meaning that at least one of the below specified detail-fields should be present in the update request. Otherwise,
the request will return 400 - Bad Request
status code.
Updating general details can be done in combination with mandate-type specific details. There is no need to perform a separate update request to change these values. See our example in the update SDD details section below for more information.
Name | Required | Description |
---|---|---|
customerFirstName | No | The first name of the customer |
customerLastName | No | The last name of the customer |
customerEmail | No | The email of the customer to which the contract is mailed. |
customerLanguage | No | The language of the customer. Defines the language to be used in the payment screens the customer will see. Possible values: Languages |
customerCountry | No | The country of the customer, an ISO 3166 alpha-2 code. See for more info: Country Codes - ISO 3166. |
!INFO customerFirstName
& customerLastName
must be updated together, otherwise the request will return a 400 - Bad Request
status code.Only provide customerEmail
when it’s value has changed otherwise the request will return a 400 - Bad Request
status code.
Name | Required | Description |
---|---|---|
customerZip | No | The zipcode of the customer |
customerCity | No | The city of the customer |
customerAddress | No | The address of the customer (street & number) |
vatNumber | No | The enterprise number (can only be changed if companyName is changed) |
customerNumber | No | The customer number |
companyName | No | The company name on the mandate |
customerPhoneNumber | No | The customer phone number |
iban | No | The debtor IBAN |
bic | No | The debtor BIC code |
!INFO customerAddress
, customerCity
, customerZip
& customerCountry
should be updated together.
Example
{
"type": "SEPA_DIRECT_DEBIT",
"details": {
"customerFirstName": "Dirk",
"customerLastName": "Teur",
"customerEmail": "d.teur@ccvlab.eu",
"customerLanguage": "nld",
"customerCountry": "BEL",
"customerZip": "5800",
"customerCity": "Kortrijk",
"vatNumber": "1234",
"customerNumber": "23454",
"customerAddress": "Zr Idastraat 15",
"companyName": "CCV LAB",
"customerMobilePhoneNumber": "0474144545",
"iban": "BE68068897250734",
"bic": "GKCCBEBB"
}
}
200
application/json
Name | Type | Description |
---|---|---|
name | string | The merchant name. |
accountNumberFrom | string | The IBAN number from where the payout originated. |
accountNumberTo | string | The IBAN number to where the payout is paid out. |
unstructuredReference | string | The unstructured reference of this payout. |
amount | decimal | The amount paid out. |
payoutDate | string | The date using format year-month-day |
payoutFrequency | string | Possible values: DAILY , WEEKLY , TWO_WEEKLY , MONTHLY . |
payoutGrouping | string | Possible values: DAILY , TRANSACTION . |
payoutReference | string | The reference of this payout. |
transactionDate | string | The date the transaction was performed. Using format year-month-day |
status | string | Possible values: OPEN , PROCESSED , DONE . |
Name | Description |
---|---|
data | List of Payout object |
page | Page object |
Name | Type | Description |
---|---|---|
name | string | The merchant name. |
accountNumberFrom | string | The IBAN number from where the payout originated. |
accountNumberTo | string | The IBAN number to where the payout is paid out. |
unstructuredReference | string | The unstructured reference of this payout. |
amount | decimal | The amount paid out. |
payoutDate | string | The date using format year-month-day |
payoutFrequency | string | Possible values: DAILY , WEEKLY , TWO_WEEKLY , MONTHLY . |
payoutGrouping | string | Possible values: DAILY , TRANSACTION . |
payoutReference | string | The reference of this payout. |
Name | Type | Description |
---|---|---|
size | integer | The requested page size. |
number | integer | The number of the current page. (The first page has number 0) |
totalElements | integer | The total amount of elements over all pages. |
totalPages | integer | The total number of available pages. |
/api/v1/payout?payoutDateFrom={payoutDateFrom}&payoutDateTo={payoutDateTo}&page={page}&size={size}
GET
Name | Type | Format | Inclusion | Description |
---|---|---|---|---|
payoutDateFrom | date | yyyy-mm-dd | Required | The start date to include the requested payouts |
payoutDateTo | date | yyyy-mm-dd | Required | The end date to include the requested payouts |
page | int | Optional | The requested page of the payouts. First page = 0. (default = 0) | |
size | int | Optional | The number of payouts that is requested per page. (default = 25, maximum = 500) |
200
application/json
Example
{
"data": [
{
"accountNumberFrom": "BE31798258915655",
"accountNumberTo": "BE71096123456769",
"name": "MerchantName",
"description": "4wzTG6QEDXfGDJH8hHB0",
"amount": 10,
"payoutDate": "2021-07-05",
"payoutFrequency": "DAILY",
"payoutGrouping": "DAILY",
"payoutReference": "ref_1_3"
},
{
"accountNumberFrom": "BE31798258915655",
"accountNumberTo": "BE71096123456769",
"name": "MerchantName",
"description": "HCBJEztPB0MgfC3vXd2E",
"amount": 10,
"payoutDate": "2021-07-05",
"payoutFrequency": "DAILY",
"payoutGrouping": "DAILY",
"payoutReference": "ref_1_2"
}
],
"page": {
"size": 2,
"totalElements": 2,
"totalPages": 1,
"number": 0
}
}
/api/v1/payout/payoutReference
GET
200
application/json
Example
{
"accountNumberFrom": "BE31798258915655",
"accountNumberTo": "BE71096123456769",
"name": "MerchantName",
"description": "i06MknMQMd49a59dYd5X",
"amount": 10,
"payoutDate": "2020-12-25",
"payoutFrequency": "DAILY",
"payoutGrouping": "DAILY",
"payoutReference": "ref_1_1",
"transactionDate": "2021-12-06",
"status": "DONE"
}